从您自己的 CI/CD 管道构建

Overview

在本指南中，您可以学习；了解如何从自己的 CI/CD 系统中构建和部署代理。您可以使用此方法代替Atlas Agent Engine GitHub Webhook管道。

您可以从任何可以发送带标头的 HTTPS请求的 CI/CD 系统部署，包括 Drone、GitHub Actions、GitLab CI 和 Jenkins。

Atlas Agent Engine 不需要特定于供应商的集成或 agentengine CLI来构建和部署.通过使用项目范围的API密钥作为其档案，您的管道实现与CLI相同的构建和部署序列。

提示

要从CLI构建和部署代理，请参阅构建代理映像和部署构建版本。

网关主机

本指南中的大多数端点均按项目和工作区划分范围，格式如下：

https://<gateway-host>/api/v1/projects/<project-id>/workspaces/<workspace-id>/...

将 <gateway-host> 替换为您环境的托管。下表列出了每个环境的网关主机：

environment	网关托管
开发中	`agentengine-dev.mongodb.com`
QA	`agentengine-qa.mongodb.com`
生产	`agentengine.mongodb.com`

开始之前

您的管道将代理源作为存档上传，这需要源类型为 archive 的工作区。连接 GitHub 的工作区拒绝序列中的第一个调用，并显示 409 UNSUPPORTED_SOURCE_TYPE 错误。推送会触发该工作区的构建，而不是上传的存档。

要创建存档源工作区，请从代理的目录运行以下命令：

agentengine init --org-id <org-id> --project-id <project-id>

agentengine init 命令注册一个新的工作区并搭建本地开发工具。使用在本指南中每个端点的路径中打印的工作区ID 。要学习；了解有关此命令的更多信息，请参阅注册代理。

如果代理已有连接 GitHub 的工作区，则无需迁移。您有以下选择：

继续使用该工作区的 Webhook管道。
为同一代理创建第二个存档源工作区，并从管道中将其作为目标。您可以同时维护这两个工作区。

设置管道档案

本指南中的每个请求（存档上传除外）都使用项目范围的API密钥进行身份验证。按以下格式将密钥包含在每个请求的 Authorization 标头中：

Authorization: Bearer <api-key>

将 <api-key> 占位符替换为您的API密钥。 API密钥是不记名令牌，因此您无需将其交换为单独的档案。

要创建API密钥，运行以下命令：

agentengine api-key create --project-id <project-id> --description "CI pipeline" --expires-in 90

您可以使用 --expires-in 标志来指定密钥的生命周期。为避免 CI/CD 系统中出现长期档案，您可以按照自己定义的安排轮换密钥。要学习；了解有关此命令及其标志的更多信息，请参阅管理API密钥和服务帐户。

重要

该命令仅显示一次明文密钥。您无法再次检索它。如果丢失密钥，请将其撤销并创建一个新密钥。

将密钥作为密钥存储在 CI/CD 系统中，例如 Drone 密钥或 GitHub Actions存储库密钥。请勿写入密钥内联写入管道文件或将其提交到源代码管理。

轮换管道档案

Atlas Agent Engine 不会自动轮换API密钥，也没有命令会续订现有密钥。要轮换管道使用的密钥，请创建一个新密钥并在 CI/CD 系统中更新密钥。确认新密钥有效后，撤销旧密钥。

在切换期间保持两个键处于活动状态。否则，您的管道在撤销和更新之间没有有效的密钥。

示例管道

无论您的 CI/CD 系统如何，管道都具有以下形状。您可以使用 curl 和 jq 来实现每个步骤：

check out your repository
  -> archive your agent directory
  -> POST builds/archive-init      (save build_id and upload_url)
  -> PUT upload_url                (the archive)
  -> POST builds/<build-id>/start
  -> GET builds/<build-id>         (until the status is terminal)
  -> POST deployments              (with build_id)

构建和部署序列

构建和部署序列包括以下步骤：

签出并存档代理源代码
初始化构建存档
上传代理源代码
开始构建
轮询构建状态
部署构建

在本节中，您可以学习；了解如何实现管道中的每个请求。

查看并存档您的代理源代码。

签出要构建的提交或分支，然后创建代理目录的 tar.gz 存档。 Atlas Agent Engine 会准确构建您上传的存档，因此此步骤决定了构建包含的内容。

以下示例使用 tar 命令创建名为 agent.tar.gz 的存档。该示例从存档中排除本地开发工件，包括 .venv、__pycache__ 和 .agentengine 目录以及 .env文件。

tar --exclude='.venv' --exclude='__pycache__' \
  --exclude='.agentengine' --exclude='.env' \
  -czf agent.tar.gz -C <agent-directory> .

初始化构建存档。

在运行以下命令之前，请在 CI/CD作业中设立这些环境变量：

export PROJECT_ID="<project-id>"
export WORKSPACE_ID="<workspace-id>"
export GATEWAY_HOST="agentengine-qa.mongodb.com"
export API_KEY="$CI_API_KEY"
export COMMIT_SHA="<commit-sha>"

使用Atlas Agent Engine项目的项目ID 。使用 agentengine init 返回的工作区ID 。将 GATEWAY_HOST 设置为您环境的托管，如上表所列。将API密钥存储在 CI/CD 系统的密钥存储中，并将其公开为 CI_API_KEY。将 COMMIT_SHA 设置为您在 git_info.commit_sha 中传递的提交。

要创建构建记录并获取源上传的预签名URL ，请通过运行以下 curl 命令向 builds/archive-init 端点发送 POST请求：

curl -s -X POST \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/builds/archive-init" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "label": "my-ci-build-123",
        "git_info": {
          "commit_sha": "<commit-sha>",
          "branch": "<branch-name>",
          "dirty": false
        },
        "build_target": { "subdirectory": "" },
        "auto_deploy": false
      }'

请求正文中的所有字段都是可选的。为了使构建具有可重复性，请始终传递 git_info.commit_sha属性。如果没有它， Atlas助手引擎会将生成的图像标记为 build-<random-id>，而不是 sha-<commit-sha>。

要成功构建部署自身并跳过最后一步，请将 auto_deploy设立为 true。

如果请求成功，端点将返回类似于以下内容的 201 Created 响应：

{
  "build_id": "bld_01ABC...",
  "upload_url": "https://<presigned-s3-url>",
  "upload_expires_at": "2026-01-01T00:05:00Z",
  "source_type": "archive"
}

上传代理源。

要上传代理目录，请通过运行以下 curl 命令，将包含存档作为 tar.gz文件的PUT请求发送到上一步返回的 upload_url 值：

curl -s -X PUT \
  --upload-file agent.tar.gz \
  -H "Content-Type: application/gzip" \
  "$UPLOAD_URL"

不要在此请求中发送 Authorization 标头。预签名URL就是凭证，它会在 archive-init 返回的 upload_expires_at 值指定的时间过期。如果上传URL在使用前过期，请再次调用 archive-init 以获取新的上传URL。

如果上传成功，端点将返回 200 OK 响应。

开始构建。

要确认上传内容已到达并对构建作业进行排队，请将不带正文的 POST请求发送到 builds/<build-id>/start 端点，然后运行以下 curl 命令来保存响应：

RESPONSE=$(curl -s -X POST \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/builds/$BUILD_ID/start" \
  -H "Authorization: Bearer $API_KEY")
echo "$RESPONSE"

如果请求成功，端点将返回类似于以下内容的 202 Accepted 响应：

{ "build_id": "bld_01ABC...", "status": "accepted" }

如果同一提交的构建版本已在运行，则此端点将返回 409 BUILD_ALREADY_ACTIVE 错误。该错误是重复的构建保护，而不是暂时性故障。

如果可用，响应会在 details对象中包含活动构建的ID和状态：

{
  "success": false,
  "code": "BUILD_ALREADY_ACTIVE",
  "details": {
    "existing_build_id": "bld_01ABC...",
    "existing_status": "in_progress"
  }
}

将 BUILD_ID 设置为 details.existing_build_id 值并轮询该构建，而不是初始化另一个构建存档：

BUILD_ID=$(printf '%s' "$RESPONSE" |
  jq -r '.details.existing_build_id // empty')

如果响应不包含 existing_build_id，则列出工作区版本并为同一提交选择活动构建：

BUILD_ID=$(curl -s \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/builds?limit=100" \
  -H "Authorization: Bearer $API_KEY" |
  jq -r --arg commit "$COMMIT_SHA" '
    .builds[]
    | select(.commit_sha == $commit)
    | select(
        .status == "queued" or
        .status == "in_progress" or
        .status == "waiting"
      )
    | .build_id' |
  head -n 1)

轮询构建状态。

要等待构建完成，请定期轮询 builds/<build-id> 端点，直到构建达到终端状态。以下示例每五秒进行一次轮询，并在 30 分钟后使管道失败，因此卡在 queued 或 waiting 状态的构建无法让 CI/CD作业无限期地运行：

TIMEOUT_SECONDS=1800
INTERVAL_SECONDS=5
ELAPSED=0
while true; do
  STATUS=$(curl -s \
    "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/builds/$BUILD_ID" \
    -H "Authorization: Bearer $API_KEY" \
    | jq -r '.status')
  if [ "$STATUS" = "succeeded" ]; then
    break
  elif [ "$STATUS" = "failed" ] || [ "$STATUS" = "cancelled" ]; then
    echo "Build $BUILD_ID ended with status: $STATUS" >&2
    exit 1
  elif [ "$ELAPSED" -ge "$TIMEOUT_SECONDS" ]; then
    echo "Timed out after ${TIMEOUT_SECONDS}s waiting for build $BUILD_ID" >&2
    exit 1
  fi
  sleep "$INTERVAL_SECONDS"
  ELAPSED=$((ELAPSED + INTERVAL_SECONDS))
done

当构建达到 succeeded 时，循环退出，管道继续执行下一步。当它达到 failed 或 cancelled 时，或者超时时，该示例将以非零状态退出，因此管道失败。调整 TIMEOUT_SECONDS 和 INTERVAL_SECONDS 以匹配构建持续时间和 CI/CD 系统对API调用的容忍度。

在构建过程中，端点会返回类似于以下内容的响应：

{
  "build_id": "bld_01ABC...",
  "status": "in_progress",
  "executor_type": "vm",
  "image_uri": null,
  "lockfile_mode": null,
  "error_message": null
}

下表描述了 status 值：

状态	说明
`queued`	构建正在等待开始。继续轮询。
`in_progress`	构建正在运行。继续轮询。
`waiting`	另一个构建当前占用工作区构建槽。继续轮询。
`succeeded`	构建已完成，`image_uri` 包含该映像。继续下一步。
`failed`	构建未完成。 `error_message`字段标识Atlas Agent Engine 可以确定的根本原因，例如过期的锁文件。
`cancelled`	用户或Atlas Agent Engine 取消了构建。

lockfile_mode字段报告Atlas助手引擎是否遵守提交的锁文件。要学习；了解更多信息，请参阅管理依赖项。

部署构建版本。

要部署此构建生成的映像，请通过运行以下 curl 命令向 deployments 端点发送 POST请求：

curl -s -X POST \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/deployments" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "build_id": "'"$BUILD_ID"'" }'

build_id字段是可选的。如果省略， Atlas助手引擎将在工作区中部署最近成功的构建。

如果请求成功，端点将返回类似于以下内容的 202 Accepted 响应：

{ "deployment_id": "deploy-abc123" }

响应仅确认Atlas Agent Engine 已接受部署。要确认部署正常运行，请轮询 deployments/current 端点，如以下示例所示：

curl -s \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/deployments/current" \
  -H "Authorization: Bearer $API_KEY"

端点返回工作区的活动部署，包括其状态、部署运行的每个组件的准备情况以及部署的整体运行状况。以下响应被修剪为脚本化检查所需的字段：

{
  "deployment_id": "deploy-abc123",
  "status": "successful",
  "components": [
    {
      "name": "agent",
      "available": true,
      "replicas": 1,
      "ready_replicas": 1
    }
  ],
  "health": {
    "available": true,
    "checked_at": "2026-01-01T00:10:00Z"
  }
}

在健康部署中，status 是 successful，components大量中的每个条目都将 available设立为 true，其中 ready_replicas 等于 replicas，并且 health 对象的 available字段是 true。

平台如何使用 git_info

git_info对象存储描述您已签出的来源的元数据。它不会告诉Atlas助手引擎要构建什么。存档序列从不克隆或签出存储库，也不会联系GitHub。 Atlas Agent Engine 会准确构建您上传的存档。

在初始化构建存档之前，选择要构建的提交或分支完全在管道中进行。您的管道会检查目标引用，存档该工作目录，并将 commit_sha 和 branch 传递给生成的构建。这些值具有以下作用：

commit_sha 确定映像标签并启用构建启动请求应用的重复构建防护。
branch 被记录以供显示。

管理依赖项

如果您提交uv.lock文件， Atlas助手引擎将准确安装锁定的依赖设立，并且不会重新解析依赖项。构建响应将 lockfile_mode 报告为 honored。如果锁文件已过期或无法执行，则构建会失败并显示可操作的 error_message 值，而不是默默地安装不同版本。要解决此故障，请在本地运行uv lock，提交更新的锁文件，然后再次构建。

如果您不提交锁文件， Atlas助手引擎会解析每个构建的依赖项，并将 lockfile_mode 报告为 re-resolved。这种行为不是错误。

注意

锁定文件限制

Atlas助手引擎尚不支持针对 VM 优化的执行程序构建的提交锁文件。无论提交的锁文件如何，这些构建始终会重新解析依赖项。要检查此限制是否适用于您的构建，请检查构建状态响应中的 executor_type字段。值为 vm 表示针对 VM 优化的执行程序构建。值为 container 表示容器执行程序。

请勿声明 SDK 包

请勿在 pyproject.toml文件中将Atlas Agent Engine SDK 包列为依赖项，包括以下包：

agentengine-langgraph
agentengine-core
runner-shared
agentengine-memory

这些包不会发布到包索引。声明一个会导致 uv lock 失败并出现 not found in the package registry 错误。无论 pyproject.toml文件声明什么内容， Atlas助手引擎始终会在单独的步骤中将这些包作为预构建轮子安装到助手的环境中。您的代理可以在运行时导入它们，而无需声明它们。仅声明代理自身的依赖项。

故障排除

下表描述了从自己的管道构建和部署时可能遇到的错误：

错误	可能的原因
`409 UNSUPPORTED_SOURCE_TYPE` 在 `archive-init`	工作区与 GitHub 连接，而不是与存档源连接。创建存档源工作区。
`409 BUILD_ALREADY_ACTIVE` 在 `start`	此提交的构建已在运行。使用错误响应中的 `details.existing_build_id` 作为 `BUILD_ID`。如果响应不包含该字段，则列出工作区构建并为同一提交选择活动构建。轮询该构建，而不是再次调用 `archive-init`。
`403` 在每个写入请求	创建API密钥的帐户对该项目没有足够的权限。使用具有部署管理权限的帐户创建密钥。
`403` 具有项目不匹配原因	API密钥的项目与请求路径中的项目ID不匹配。
`400 INVALID_BUILD_STATE` 在 `deployments`	引用的构建未成功或不存在。
`409 DEPLOY_IN_PROGRESS` 在 `deployments`	此工作区的部署已在进行中。
`403` 或存档上传时出现URL过期错误	预签名URL已过期。再次调用 `archive-init` 以获取新的URL。
构建失败，报告 `uv.lock`文件已过时	在本地运行 `uv lock`，提交更新的锁文件，然后再次构建。
`agent-engine-sdk-langgraph was not found in the package registry`	从 `pyproject.toml`文件的依赖项中删除 SDK包。

后续步骤

部署代理后，您可以监控其性能和活动。要学习；了解如何监控代理，请参阅监控指南。