构建代理映像

Overview

在本指南中，您可以学习；了解如何从CLI构建代理映像。构建进程会将代理源代码上传到云存储，并启动生成Docker映像的远程构建作业。

构建命令事务语法和选项

使用以下语法构建代理映像：

agentengine build [--label <str>] [--no-wait] [--context <name>] [--workspace <name>] [--all] [--json] [--upload-build-secrets]

此命令将代理源打包为 tar.gz文件，通过预签名URL将其上传到 Simple Storage Service (S3) 存储桶，然后启动 AWS Docker作业以在 Elastic 容器注册表 ( ECR）。

命令标志

构建代理映像时，可以使用以下可选标志：

标记	说明
`--label`	构建标签。默认下，会以 `branch@sha12` 格式从本地 git存储库读取此值。
`--no-wait`	指示CLI在启动构建作业后立即返回，而不轮询构建状态。
`--context`	`.agentengine/state.json`文件中的命名本地上下文。
`--workspace`	（仅限 Monorepo）按名称构建特定工作区，如根 `agent.yaml` 中所定义。该标志与 `--all` 互斥。
`--all`	（仅限 Monorepo）按顺序构建所有工作区。 CLI创建源存档一次，然后为每个工作区运行上传和构建步骤。所有构建开始后，它会轮询每个构建，直到达到终端状态。该标志与 `--workspace` 互斥。
`--json`	输出单个机器可读的构建结果。
`--upload-build-secrets`	在构建开始之前，上传同名环境变量中在 `agent.yaml` 中声明的每个 `artifact_repositories[].secret`。选择在构建之间过期的短期注册表令牌。要学习；了解更多信息，请参阅私有工件存储库。

存档内容

在上传代理源代码之前， CLI会构建上一节中引用的 tar.gz 存档。本节介绍存档打包到哪个目录以及排除哪些文件。

存档根目录

默认下，agentengine build 命令仅打包代理目录。如果工作区或单一存储库配置文件将代理目录列为成员，则该命令会改为从工作区或单一存储库根目录打包。列出要求取决于工作区类型，如下表所述：

工作区类型	成员资格要求
uv 工作空间	代理目录必须与 `[tool.uv.workspace].members`模式匹配，不得从工作区中排除，并且必须有自己的 `pyproject.toml`文件。在成员模式中，`` 匹配单个目录级别，`` 不受支持。显式列出更深层次的成员，例如 `agents/` 和 `agents//`。
Monorepo	代理目录的显示必须与根 `agent.yaml`文件中的 `agents[].path` 列表中的内容完全相同。嵌套在所列路径下的目录不是成员。

要查找工作区或单一存储库根， CLI会在代理目录的父目录中向上搜索，以查找标记根的文件。搜索会在 git 存储库的根目录停止，而从不继续进入主目录，因此该命令无法包存储库外部的文件。

如果代理目录是 git 子模块或链接的工作树，则搜索不会在该边界停止。搜索将继续到父存储库，上表中描述的成员资格规则确定命令从哪个目录打包。

已排除的文件

存档根目录下的项目级 .agentengineignore文件控制着CLI将哪些文件打包到存档中。此文件使用标准 .gitignore 语法，包括 glob、** 和 ! 否定。 agentengine init 命令使用以下默认模式创建文件：

.git
.venv*
__pycache__
.pytest_cache
.mypy_cache
.ruff_cache
node_modules
dist
build
.agentengine
*.pyc
.env
.env.*
.DS_Store
*.pem
*.key

如果该文件不存在， CLI将使用与 agentengine init 命令相同的默认模式。

以下文件始终被排除在外，并且您不能在 .agentengineignore文件中使用 ! 否定词来覆盖该文件：

.env 和 .env.* 文件
*.pem 和 *.key 文件
常见 OpenSSH 私钥：id_rsa、id_dsa、id_ecdsa、id_ed25519 和 id_ed448
.git 目录
云和工具凭证存储：.aws、.kube、.ssh、.netrc、.git-credentials、.azure、.config/gh、.docker/config.json 和 .config/gcloud

项目级 .npmrc文件不是这设立已排除文件的一部分。平台构建会从存档中读取 .npmrc文件，以解析声明的私有npm注册表。该构建还会读取 pyproject.toml 来解析声明的私有 PyPI 注册表。要学习；了解如何为构建构建私有注册表凭证，请参阅私有工件存储库。

警告

由于此构建包含 .npmrc 和 pyproject.toml 文件，因此请勿在这些文件中存储注册表令牌或凭证。相反，请在 agent.yaml文件的 artifact_repositories 中凭证档案。要学习；了解更多信息，请参阅私有工件存储库。

私有工件存储库

如果您的代理依赖于托管在私有项目存储库（例如 AWS CodeArtifact）中的包，请在 agent.yaml文件的 artifact_repositories区块中声明这些存储库。 Atlas Agent Engine 在构建时从每个条目中指定的Atlas Agent Engine 密钥解析注册表凭证，并将其注入到构建环境中。凭证不会存储在源文件中，也不会暴露给运行的Pod。如果您未声明任何存储库， Atlas Agent Engine 将使用现有工具配置解析公共注册表中的依赖项，无需更改。

注册表 URL 存在于项目工具中，而不是在 agent.yaml 中。对于Python代理，请在 pyproject.toml 中的 [[tool.uv.index]] 条目中声明每个私有索引。 agent.yaml 中的 name字段必须与索引名称匹配。对于 TypeScript 代理，请在 .npmrc文件中声明每个私有作用域的注册表。将 agent.yaml 中的 npm_scope 设置为映射到注册表的范围。以下示例显示了每种语言的匹配工具文件和 agent.yaml 条目：

pyproject.toml

[[tool.uv.index]]
name = "corps-pypi"
url = "https://<domain>-<account>.d.codeartifact.<region>.amazonaws.com/pypi/<repo>/simple/"
explicit = true

agent.yaml

artifact_repositories:
  - name: corps-pypi
    type: pypi
    secret: ARTIFACT_REPO_CORPS_PYPI_TOKEN
    username: aws
    scope: project

.npmrc

@acme:registry=https://npm.pkg.github.com/

agent.yaml

artifact_repositories:
  - name: corp-npm
    type: npm
    secret: ARTIFACT_REPO_CORP_NPM_TOKEN
    npm_scope: "@acme"
    scope: project

要学习；了解完整的 artifact_repositories模式，请参阅代理 YAML 模式。

在构建开始之前， Atlas Agent Engine 会根据项目工具验证已声明的存储库。如果验证失败，则构建会停止，并出现可操作错误。要在构建之前发现问题，请在本地运行agentengine agent validate。要学习；了解更多信息，请参阅验证配置。

在构建开始之前，每个声明的 artifact_repositories[].secret 都必须存在于Atlas Agent Engine 密钥中声明的范围内。对于在构建之间过期的短期注册表令牌，请使用 --upload-build-secrets 标志从同名的环境变量中上传每个密钥。以下示例将创建一个 AWS CodeArtifact 令牌并在一个构建命令中将其上传：

export ARTIFACT_REPO_CORPS_PYPI_TOKEN="$(aws codeartifact get-authorization-token \
  --domain my-domain --query authorizationToken --output text)"
agentengine build --upload-build-secrets

对于长期凭证，请使用 agentengine secret set 将每个密钥设立一次，并在不带该标志的情况下构建。要学习；了解有关预配密钥的更多信息，请参阅预配 Cloud 密钥。

构建管理命令

下表描述了可用于监控和管理代理构建的构建管理命令：

命令	说明
`agentengine build logs <build_id>`	将指定构建的构建日志流式传输到 `stdout`。
`agentengine build list`	以表格格式列出工作区的所有构建。该表包含构建ID、状态、标签和创建时间。
`agentengine build cancel <build_id>`	取消指定的运行或排队的构建。如果构建已成功或失败，此命令将返回错误。
`agentengine build promote <source_build_id>`	将成功的构建映像提升到另一个工作区，而无需从源重建映像。要学习；了解更多信息，请参阅升级构建。
`agentengine build promote get <promotion_id>`	返回指定构建升级的状态。如果升级失败，输出包括目标构建ID和失败原因。

提示

命令标志

每个构建管理命令都接受 --workspace-id 和 --project-id 标志来指定工作区和项目。如果未提供， CLI将从 .agentengine/state.json文件中读取这些值。

升级构建

当您升级构建时， Atlas Agent Engine 会将经过测试的构建映像从一个工作区复制到另一个工作区，而无需从源重建映像。由于升级后的映像与源映像字节相同，因此在目标工作区中运行的代理与您在源工作区中测试的代理相同。

注意

平台用户界面构建详细信息页面不显示升级构建的 Build Logs 部分，因为升级会重复使用现有映像，而不是运行新构建。

默认下，源构建必须至少有一个成功的部署，这确认该映像是可部署的。要绕过此要求，请使用 --force 标志。

使用以下语法来升级构建：

agentengine build promote <source_build_id> [--workspace <name>] [--workspace-id <id>] [--project-id <id>] [--context <name>] [--force] [--yes] [--json]

CLI通过ID识别源构建，并在当前组织内进行解析。您不能将构建为不同组织中的项目。

升级构建时，可以使用以下标志：

标记	说明
`--workspace`	（仅限 Monorepo）目标工作区名称，如根 `agent.yaml`文件中所定义。
`--workspace-id`	目标平台工作区ID。
`--project-id`	目标平台项目ID。
`--context`	`.agentengine/state.json`文件中的命名本地上下文。
`--force`	绕过成功部署要求。此标志需要目标项目中的 `PROJECT_OWNER`角色。
`--yes`	跳过交互式确认提示。在 CI管道或其他非交互式环境中运行命令时，请使用此标志。如果没有它，命令在交互式终端之外将失败。
`--json`	以JSON输出升级结果。

警告

升级不会从源工作区复制运行时或项目配置。密钥、 Atlas连接配置和出口策略不会传输到目标工作区。在部署升级的构建之前，请在目标项目和工作区上配置这些设置。

升级成功后，在目标工作区中部署升级后的构建。要学习；了解如何部署构建，请参阅部署构建版本。

例子

以下命令会在不轮询构建状态的情况下构建代理映像，然后列出构建信息：

agentengine build --no-wait && agentengine build list

如果构建成功，命令输出将类似于以下示例：

Initialising build...
build_id: <build_id>
Creating archive...
Uploading archive...
Starting build...
✓ Build started (build_id: ...)
URL: https://agentengine.mongodb.com/api/v1/workspaces/<workspace_id>/builds/<build_id>
BUILD_ID                              STATUS   LABEL              CREATED_AT
<build_id>                            running  main@abc123def456  2026-04-01T10:30:00Z

后续步骤

构建代理映像后，您可以将代理部署到生产环境中。要学习；了解如何部署代理，请参阅“部署您的构建指南。