开始使用Atlas助手引擎

Overview

在本教程中，您将在MongoDB Atlas助手引擎上创建并部署Hello World代理。您可以安装 agentengine CLI并从入门模板中搭建项目。然后，在本地运行代理、注册代理、构建并将其部署到Atlas代理引擎。

本教程使用 Anthropic 作为大语言模型 (LLM)提供商，使用 macOS 作为操作系统。

先决条件

开始之前，请确保您具备以下先决条件：

macOS 计算机。要查看Windows和Linux设置说明，请参阅《安装和身份验证》指南。
Git
在您的计算机上运行的Docker Desktop
Python 3.11 或更高版本
可访问权限至少一个Atlas组织的Atlas帐户
您所选的 LLM提供商的API密钥。本教程使用 Anthropic，但您可以使用任何提供商。

步骤

完成以下步骤以安装 agentengine CLI、搭建 Hello World代理、在本地运行它，并将其部署到Atlas助手引擎。

安装 `agentengine` CLI。

登录Atlas Agent Engine，然后从CLI下载页面下载CLI 。 Version 下拉列表预填充最新的CLI版本，Platform 下拉列表预填充检测到的操作系统。

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

完成CLI安装。

在终端中，导航到下载目录并运行以下命令：

shasum -a 256 agentengine

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

运行以下命令将二进制文件标记为可执行文件并将其移动到 ~/.local/bin目录：

chmod +x ./agentengine
mkdir -p ~/.local/bin
mv ./agentengine ~/.local/bin/agentengine

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

要学习；了解更多信息，请参阅安装 agentengine CLI。

登录Atlas助手引擎。

运行以下命令对CLI进行身份验证：

agentengine auth login

按照基于浏览器的登录流程完成身份验证。

创建代理项目。

运行以下命令以搭建 Hello World代理项目：

agentengine create

当CLI提示时，选择以下值：

模板：Hello World 代理
法学硕士提供商：Anthropic Claude
API密钥：您的 Anthropic API密钥
启用内存：否

该命令会创建一个项目根目录，其中包含一个 project-config.yaml 配置文件和一个 agents/目录。代理的文件（包括 agent.yaml 配置文件、带有API密钥的 .env文件和 pyproject.toml文件）位于 agents/ 的子目录中。以下示例显示了该命令创建的结构：

my-project/
├── project-config.yaml
└── agents/
    └── my-agent/
        ├── agent.yaml
        ├── pyproject.toml
        ├── .env
        └── src/

从代理目录（在本示例中为 my-agent/）运行所有后续 agentengine 命令。

在本地运行代理。

本地开发需要访问权限托管在 MongoDB容器映像注册表中的基于 Runner 的映像。 CLI使用您的 agentengine auth login 会话拉取映像，因此您无需单独登录注册表。

导航到代理目录并运行以下命令以启动本地开发环境：

agentengine dev up

CLI构建Docker映像并启动完整的代理堆栈。当堆栈成功启动时，命令输出如下所示：

◆ Workspace  <your organization>  /  Default Project  /  <your project>
✓ Created .agentengine/docker-compose.dev.yml
✓ Created .agentengine/Dockerfile.dev
✓ Created .agentengine/Dockerfile.dev.dockerignore
✓ Created .agentengine/dev-entrypoint.py
✓ Created .agentengine/entrypoint.py
✓ Created .devcontainer/devcontainer.json
✓ Reused existing .agentengineignore
[+] Building 1.6s (17/17) FINISHED
[+] up 5/5
 ✔ Container <your-project>-mongodb-1  Healthy
 ✔ Container <your-project>-oe-1       Healthy
 ✔ Container <your-project>-app-1      Started
✓ Stack running (hot-reload)
  oe       http://localhost:51331
  mongo    mongodb://localhost:51333
  ui       http://localhost:3000
  Invoke:  curl -X POST 'http://localhost:3000/invoke' \
             -H 'Content-Type: application/json' \
             -d '{"message": "Hello"}'
  Next:    Open VS Code and run "Dev Containers: Reopen in Container"
           for editing and debugging inside the running app container
  Restart: from this workspace dir, run
           agentengine dev restart
  Logs:    agentengine dev logs
  Stop:    agentengine dev stop
  Clean:   agentengine dev clean

当所有服务准备就绪后，在浏览器中打开 http://localhost:3000 URL以与代理聊天。

注意

用户界面可能会在默认端口 3000 以外的端口上运行。要查看URL，请检查 agentengine dev up 命令输出中的 ui字段。

以下示例显示了与代理的成功交换：

点击放大

要停止本地环境，运行以下命令：
```
agentengine dev stop
```

在平台上注册。

在部署项目之前，运行以下命令以将项目注册到Atlas Agent Engine：

agentengine init

此命令将本地项目链接到Atlas Agent Engine，并为代理创建工作区。

设置Atlas资源。

Atlas助手引擎需要Atlas 集群来存储执行状态、检查点和历史记录。 CLI仅支持Atlas服务帐户凭证。不支持Atlas 用户帐户登录和旧版Atlas API公钥和私钥。

重要

Atlas空调

在此步骤中，您可以选择现有的Atlas 集群，也可以创建新的 Atlas 集群。如果您创建新集群， CLI默认会预配付费的Atlas Flex集群。 Atlas向您收取集群操作费用，直到您终止集群。要清理本教程中创建的资源，请参阅清理资源。

在Atlas用户界面中，创建或选择一个服务帐户：
1. 打开要使用的Atlas项目。
2. Go项目 Identity & 中的应用程序访问菜单并创建或选择服务帐户。
3. 授予服务帐户“项目所有者”权限。要学习；了解为什么需要此角色，请参阅Atlas项目管理角色。
运行以下命令以设立和预配集群：
```
agentengine atlas setup
```
出现提示时，输入Atlas服务帐户客户端ID和密钥。 CLI预配集群、配置网络访问权限并将 MONGODB_URI 存储为平台密钥。要学习；了解有关Atlas资源的更多信息，请参阅设置Atlas资源。

设置云密钥。

您部署的代理需要密钥才能调用 LLM 并连接到Atlas。

运行以下命令以设立Anthropic API密钥。 CLI会提示您输入值。

agentengine secret set ANTHROPIC_API_KEY

要学习；了解有关管理密钥的更多信息，请参阅预配 Cloud 密钥。

构建并部署代理。

运行以下命令以构建代理映像并一步部署：

agentengine deploy --auto

该命令会捆绑代理代码，启动远程构建作业，并监控构建触发的部署。构建需要 5 到 10 分钟，部署又需要 5 到 10 分钟。部署期间，输出可能会显示 Agent Sandbox: waiting 和 Tool Sandbox: waiting 几分钟。部署成功后，命令输出如下所示：

Waiting for auto-deploy to start...
✓ Auto-deploy started (deployment_id: <deployment-id>)
✓ Deployment succeeded
  version: v0.1.0
  components:
    Orchestration Engine      ready (2 replicas)
    Agent Sandbox             ready (3 replicas)
    Tool Sandbox              ready (4 replicas)
  url: https://agentengine.mongodb.com/project/<project-id>/deployments/<deployment-id>

您的代理现在正在MongoDB Atlas代理引擎上运行。

--auto 标志仅适用于单代理项目。要分步进行构建和部署，或者部署特定的构建，运行agentengine build，然后运行 agentengine deploy。要学习；了解更多信息，请参阅开始部署。

对失败的部署进行故障排除

部署失败的最常见原因是：

配置错误的密钥
Atlas 集群，其IP访问列表未配置为允许来自Atlas助手引擎的流量

要调试失败的部署，运行以下命令以查看Atlas助手引擎日志：

# View deployment logs
agentengine deploy logs
# View deployed agent workspace logs
agentengine logs

有关每个命令的详细信息，请参阅“View 部署事件日志”和“使用CLI”指南。

清理资源

本教程预配的资源在您删除之前会持续存在。当您不再需要这些资源时，请通过以下方式将其删除：

Atlas 集群：要终止集群，请打开Atlas项目的 Clusters 页面，单击集群旁边的省略号 (...)，然后单击 Terminate。如果您选择了现有集群，则本教程不会创建新集群，因此您可以保持不变。
工作区：agentengine init 命令在Atlas助手引擎上创建一个工作区，其中包含已部署的代理。要查找工作区ID，运行以下命令：
agentengine workspace list
然后，运行以下命令删除工作区：
agentengine workspace delete <workspace-id> --yes
数据库用户：设置流程会创建一个数据库用户，代理使用该用户连接到Atlas。在Atlas 用户界面中，打开 Database & Network Access 并单击数据库用户旁边的删除图标。
Voyage AI API密钥：设置流程将创建一个 Voyage AI API密钥来支持代理的内存功能。在Atlas 用户界面中，打开 AI Model APIs 并单击API密钥旁边的删除图标。
平台密钥：设置流程会询问是否将 MONGODB_URI 和 VOYAGE_API_KEY 值存储为平台密钥。如果您选择存储这些密钥，则可以按照删除密钥中的说明将其删除。