安装和身份验证

Overview

本教程向您展示如何安装MongoDB Atlas Agent Engine 并使用其对帐户进行身份验证。您将验证系统依赖项，安装 agentengine CLI，验证 runner-base 映像，并根据Atlas Agent Engine API网关对您的帐户进行身份验证。

先决条件

在开始本教程之前，请确保已安装并配置以下组件：

先决条件	注意
支持的操作系统	支持以下操作系统：基于 Apple Silicon 或 Intel 的 macOS arm64 或 x86_64 上的Linux Windows到适用于Linux的Windows子系统 (WSL)。在 WSL 上，使用 WSL 发行版中的Linux二进制文件。
容器引擎	将Docker Desktop 或Docker Engine 与计算机上运行的Docker Compose v2 结合使用。 Atlas Agent Engine 尽最大努力支持 Podman，并且CLI在检测到 `podman-compose` 工具时会打印兼容性通知。
Python	使用 3.11 或更高版本。
MongoDB 集群	已部署的代理使用此集群，因此您必须检索其连接字符串。本地测试会启动自己的MongoDB容器。
网络接入	您的网络必须允许对以下主机进行出站访问权限： `https://agentengine.mongodb.com`， Atlas Agent Engine API网关 MongoDB 的私有Amazon ECR 注册表，提供代理运行时映像 `docker.io`，提供本地MongoDB容器当您运行`agentengine dev up` 命令时， CLI会打印容器注册表托管。如果您必须将主机名添加到防火墙允许列表中，您的MongoDB代表可以提供托管名。对于气隙或出口受限的网络，您可以从您控制的主机获取CLI二进制文件和代理运行时映像。要学习；了解如何配置自定义工件源，请参阅使用自定义工件源。

使用自定义工件源

您可以配置 agentengine CLI ，从自己的主机而不是MongoDB托管的注册表下载二进制文件和拉取代理运行时映像。运行 agentengine agent source setup 以生成 source.yaml文件，或运行agentengine agent source template 以写入可编辑的带注释模板。安装 agentengine CLI后运行这些命令。

默认下， CLI会从 ~/.agentengine/source.yaml 读取 source.yaml。要使用其他位置，请将 AGENTENGINE_IMAGE_SOURCE_FILE 环境变量设立为文件路径。

导出 AGENTENGINE_IMAGE_SOURCE=custom 以将 agentengine dev up 路由，并将 agentengine self-update 路由到您的自定义托管。以下示例source.yaml 同时镜像CLI二进制文件和代理运行时映像：

base: internal
release:
  type: static
  url: https://artifactory.example.com/agentic-cli/manifest.json
registry:
  prefix: artifactory.example.com/acme-docker

release区块将CLI二进制文件下载到您的托管，registry.prefix区块将代理运行时映像拉取到您的注册表。如果仅镜像其中之一，则CLI将 base 源（默认为 internal）用于另一个。

对于 type: static，release.url 的清单必须与以下结构匹配，每个操作系统和架构在 assets 中都有一个条目。否则，agentengine self-update 会失败， CLI不会显示更新通知。

{
  "releases": [
    {
      "version": "1.4.2",
      "assets": [
        {
          "os": "darwin",
          "arch": "arm64",
          "url": "https://artifactory.example.com/acme-generic/agentic-cli/1.4.2/agentic_darwin_arm64",
          "sha256": "9f2b...e1"
        }
      ]
    }
  ]
}

要从 GitHub Enterprise 版本API而不是清单读取版本，请将 release.type设立为 github，并将 release.url 设置为API端点，例如 https://ghe.example.internal/api/v3/repos/acme/agentic-cli/releases。

如果您的映像注册表需要身份验证，请在运行agentengine dev up 之前登录。示例，运行docker login <registry>，或者对于Amazon ECR，运行以下命令：

aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <aws_account_id>.dkr.ecr.<region>.amazonaws.com

安装 `agentengine` CLI

agentengine CLI是使用MongoDB Atlas Agent Engine 进行本地开发的主节点 (primary node in the replica set)工具。它生成在本地运行代理的三项服务所需的Docker Compose 配置。

以下步骤描述了如何从Atlas Agent Engine 用户用户界面下载CLI 。

打开“安装CLI”页面。

登录Atlas Agent Engine，然后从CLI下载页面下载CLI 。

该页面会显示一个 Version 下拉列表，其中预填充了最新的CLI版本。它还显示一个 Platform 下拉列表，其中预填充了检测到的操作系统。要更改这些默认值，请从下拉选择器中选择不同的版本或平台。

下载二进制文件。

选择版本和平台后，单击 Download for <your platform> 按钮。保存页面显示的 SHA-256校验和值，以在以下步骤中使用。

验证下载。

在终端中，导航到您的 downloads目录。选择与操作系统对应的标签页并运行以下命令：

shasum -a 256 agentengine

certutil -hashfile agentengine.exe SHA256

输出必须与保存的 SHA-256 值匹配。如果值不匹配，删除二进制文件并重新下载。

将二进制文件标记为可执行文件。

选择与操作系统相对应的标签页，然后运行以下命令，将二进制文件标记为可执行文件：

chmod +x agentengine

Windows二进制文件下载后可执行。跳过此步骤。

将二进制文件添加到 `PATH`。

选择与操作系统对应的标签页，查看将二进制文件添加到 PATH 的说明。

从下载目录运行以下命令：

mkdir -p ~/.local/bin
mv agentengine ~/.local/bin/agentengine

确认 ~/.local/bin 在您的 PATH 上。通过在用户可写入的目录中安装二进制文件，您可以在不使用 sudo 命令的情况下运行agentengine self-update 命令。

将 .exe文件移至 PATH 上已有的目录，或将其目录添加到 System Properties -> Environment Variables-> Path（在Windows GUI 中）。

要使用 agentengine 命令，请将二进制文件重命名为 agentengine.exe。

验证安装。

通过检查 CLI 版本来确认已安装CLI ：

agentengine version

输出类似于以下内容：

0.1.94-alpha (commit: <hash>)
image registry: ECR
runner-base: <registry-host>/runner-base:0.1.94-alpha
runner-base-typescript-langgraph: <registry-host>/runner-base-typescript-langgraph:0.1.94-alpha
playground-ui: <registry-host>/playground-ui:0.1.94-alpha
orchestrator: <registry-host>/orchestration-engine:<version>
memory-server: <registry-host>/memory-server:<version>

要学习；了解如何将已安装的CLI更新到较新版本，请参阅更新CLI。

验证运行器基础映像

runner-base 映像是Atlas Agent Engine 用于在本地运行代理的三项服务的容器映像。如果在您首次运行代理时Docker无法拉取此映像，则您的代理将无法启动。通过验证Docker基础映像，您可以在运行代理项目之前发现并修复任何网络问题。验证运行器基础映像是可选项，但建议执行。

本地开发从 MongoDB 的容器映像注册表中提取 Runner-Base 映像。您不需要 GitHub访问权限或单独的注册表登录。 CLI使用 agentengine auth login 会话检索映像，并在您运行agentengine dev up 命令时打印注册表托管。

获取基于运行者的图像引用。

运行 agentengine version 命令以检索默认的Runner-Base 映像：

agentengine version

复制输出中的 runner-base: 值。

向平台映像注册表进行身份验证。

运行以下命令，将本地Docker安装日志到平台映像注册表中：

agentengine dev login

agentengine dev up 命令会自动运行此流程，因此仅当您直接拉取映像时才需要执行此步骤。

拉取 Runner-Base 映像。

运行以下命令以拉取 Runner-Base 映像，并将 <runner-base-image> 替换为从 agentengine version 输出中复制的值：

docker pull <runner-base-image>

成功拉取以 Status: 行结束，其中 Downloaded newer image 或 Image is up to date。

验证您的帐户

agentengine auth login 命令针对Atlas Agent Engine API网关启动基于浏览器的 OIDC 登录流程，并为将来的CLI命令保存本地身份验证状态。

注意

Atlas OAuth 委派

当您登录Atlas Agent Engine 时，该平台会自动从Atlas检索您的角色分配，并确定您可以访问权限哪些组织和项目。该平台使用Atlas OAuth 2.1 App Connections服务器授权对Atlas的访问权限。

登录到Atlas助手引擎。

从终端运行以下命令：

agentengine auth login

默认默认下，这会打开针对 https://agentengine.mongodb.com 生产API网关的浏览器。您可以将 --base-url 传递给命令以定位不同的网关，或传递 --no-browser 以打印登录URL，而无需打开浏览器。以下代码显示了该命令的格式：

agentengine auth login [--base-url <url>] [--no-browser] [--timeout <duration>]

完成登录后， CLI会从API读取您的项目成员身份，并保留所选项目ID project_id 以及身份验证令牌。

选择一个项目。

如果您的帐户属于单个项目，系统会自动选择该项目。如果您的帐户属于多个项目， CLI会提示您以交互方式选择一个项目。如果没有偏好，请选择默认项目。 CLI会将您的选择保存为默认，您可以使用 --project-id 标志覆盖该默认值。

验证您的身份验证状态。

要检查身份验证是否成功，运行以下命令：

agentengine auth status

此命令会打印当前的本地身份验证上下文，而无需联系平台，其输出会反映磁盘上保存的登录状态。您可以将 --json 标志传递给命令，以输出具有单独 auth、command_defaults 和 directory_context 字段的JSON对象。

在您通过运行agentengine init 命令注册代理目录之前，Directory context字段将报告 none found。登录成功后仍会显示您的帐户、基本URL以及默认组织和项目。

提示

如果您的身份验证令牌过期，日志并重新日志以刷新令牌：

agentengine auth logout
agentengine auth login

后续步骤

安装并使用MongoDB Atlas Agent Engine 验证您的帐户后，您可以创建一个项目。要学习；了解如何执行后续步骤，请参阅创建项目指南。

来年

创建项目