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 CodeBuildジョブを開始して Elastic Container Register にDockerイメージを生成します（ ECR）。
コマンド フラグ
エージェントイメージを作成するときは、次の任意フラグを使用できます。
Flag | 説明 |
|---|---|
| ビルド ラベル。デフォルトでは 、この値は |
| ビルドジョブを開始した後、ビルド ステータスをポーリングせずに返すよう CLI に指示します。 |
|
|
| （MongoDB のみ） ルート |
| （MongoDB のみ） すべてのワークスペースを順番にビルドします。 CLI はソース アーカイブを一度作成し、各ワークスペースに対してアップロードとビルドの手順を実行します。すべてのビルドが開始されると、ターミナルステータスに達するまで各ビルドをポーリングします。このフラグは、 |
| マシンが判読可能な単一のビルド結果を出力します。 |
| ビルドが開始される前に、 で宣言された各 を同じ名前の環境変数からアップロードします。ビルド間で期限切れとなる有効期間の短いレジストリ トークン用にオプトインします。詳細については、「 プライベート |
アーカイブの内容
エージェントソースをアップロードする前に、前のセクションで参照されている tar.gz アーカイブがビルドされます。このセクションでは、アーカイブ パッケージがどのディレクトリに保存されるか、また除外されるファイルについて説明します。
アーカイブルート
デフォルトでは 、agentengine build コマンドはエージェントディレクトリのみをパッケージ化します。ワークスペースまたは MongoDB構成ファイルにエージェントディレクトリがノードとしてリストされている場合は、代わりに ワークスペースまたは MongoDB ルートからの パッケージを使用します。次の表に示すように、リスティング要件はワークスペースのタイプによって異なります。
ワークスペース タイプ | メンバーシップ要件 |
|---|---|
rv ワークスペース | エージェントディレクトリは |
Monorepo | エージェントディレクトリは、ルート |
ワークスペースまたは MongoDB ルートを見つけるために、CLI は、エージェントディレクトリの親ディレクトリから上方向にルートをマークするファイルを検索します。検索は Git リポジトリのルートディレクトリで停止し、 ホームディレクトリには続行されないため、 コマンドはリポジトリ以外のファイルをパッケージできません。
エージェントディレクトリが Git サブモジュールまたはリンクされたワークツリーの場合、検索はその境界で停止しません。検索は親リポジトリまで続行され、前の表に記載されているメンバーシップ ルールによって、 コマンドがパッケージ化されるディレクトリが決定されます。
除外されたファイル
アーカイブ ルートにあるプロジェクトレベルの .agentengineignoreファイルは、CLI がアーカイブに圧縮するファイルを制御します。このファイルでは、グローバル、**、! 否定などの標準 .gitignore構文を使用します。 agentengine init コマンドは、次のデフォルトパターンでファイルを作成します。
.git.venv*__pycache__.pytest_cache.mypy_cache.ruff_cachenode_modulesdistbuild.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 ファイルは、この除外ファイルのセットには含まれません。プラットフォーム ビルドは、宣言されたプライベートnpmレジストリを解決するために.npmrc アーカイブから ファイルを読み取ります。このビルドでは、宣言されたプライベートpyproject.toml PyPI レジストリを解決するために も読み取られます。ビルドのためのプライベート レジストリ認証情報の構成方法については、「 プライベート アーティファクト リポジトリ 」を参照してください。
警告
ビルドには.npmrc pyproject.tomlファイルと ファイルが含まれるため、これらのファイルにレジストリ トークンや認証情報を保存しないでください。代わりに、artifact_repositories agent.yamlファイルで の認証情報を宣言します。詳細については、「 プライベート アーティファクト リポジトリ 」を参照してください。
プライベート アーティファクト リポジトリ
エージェントがAWS CodeAtlas などのプライベート アーティファクト リポジトリでホストされているパッケージに依存している場合は、agent.yamlファイルの artifact_repositories ブロックでそれらのリポジトリを宣言します。 Atlas Agent Engine は、ビルド時に各エントリに という名前の Atlas Agent Engine シークレットからレジストリ認証情報を解決し、それをビルド環境に挿入します。認証情報はソースファイルに保存されず、実行中のポッドに公開されません。リポジトリを宣言しない場合、Atlas Agent Engine は、既存のツール構成を変更せずに使用して、パブリック レジストリからの依存関係を解決します。
レジストリ URL は、agent.yaml ではなく、プロジェクトツールに存在します。 Pythonエージェントの場合は、pyproject.toml の [[tool.uv.index]] エントリで各プライベートインデックスを宣言します。 agent.yaml の nameフィールドはインデックス名と一致する必要があります。 TypeScript エージェントの場合は、.npmrcファイルで各プライベート スコープ レジストリを宣言します。 agent.yaml の npm_scope を、レジストリにマッピングするスコープに設定します。次の例は、各言語に一致するツールファイルと agent.yaml エントリを示しています。
[[tool.uv.index]] name = "corps-pypi" url = "https://<domain>-<account>.d.codeartifact.<region>.amazonaws.com/pypi/<repo>/simple/" explicit = true
artifact_repositories: - name: corps-pypi type: pypi secret: ARTIFACT_REPO_CORPS_PYPI_TOKEN username: aws scope: project
@acme:registry=https://npm.pkg.github.com/
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 シークレットに宣言されたスコープに存在する必要があります。ビルド間で期限切れになる有効期間の短いレジストリ トークンの場合は、--upload-build-secrets フラグを使用して同じ名前の環境変数から各シークレットをアップロードします。次の例では、 AWS Codeアーティファクト トークンを最小化し、1 回のビルドコマンドでアップロードします。
export ARTIFACT_REPO_CORPS_PYPI_TOKEN="$(aws codeartifact get-authorization-token \ --domain my-domain --query authorizationToken --output text)" agentengine build --upload-build-secrets
有効期間が長い認証情報の場合は、 を使用して各シークレットを 1 回設定し、agentengine secret set フラグなしでビルドします。シークレットのプロビジョニングの詳細については、「 クラウド シークレットのプロビジョニング 」を参照してください。
ビルド管理コマンド
次の表では、エージェントのビルドを監視および管理するために使用できるビルド管理コマンドについて説明しています。
コマンド | 説明 |
|---|---|
| 指定されたビルドのビルドログを |
| ワークスペースのすべてのビルドを テーブル形式で一覧表示します。この表には、ビルドID、ステータス、ラベル、作成時間が含まれます。 |
| 指定された実行中またはキューに入れられたビルドをキャンセルします。このコマンドは、ビルドがすでに成功しているか失敗している場合はエラーを返します。 |
| ソースからイメージを再ビルドせずに、成功したビルドイメージを別のワークスペースにプロモートします。詳細については、「 ビルドのプロモート 」を参照してください。 |
| 指定されたビルドの昇格のステータスを返します。出力には、引き上げが失敗した場合、ターゲット ビルドIDと失敗の理由が含まれます。 |
Tip
コマンド フラグ
各ビルド管理コマンドは、ワークスペースとプロジェクトを指定するために --workspace-id と --project-id フラグを受け入れます。指定しない場合、CLI は .agentengine/state.jsonファイルからこれらの値を読み取ります。
ビルドを推奨する
ビルドをプロモートすると、Atlas Agent Engine は、ソースからイメージを再ビルドせずに、あるワークスペースから別のワークスペースにテストされたビルドイメージをコピーします。昇格されたイメージはソース イメージとバイト的に同一であるため、ターゲット ワークスペースで実行されるエージェントは、ソース ワークスペースでテストしたエージェントと同じになります。
注意
プラットフォームUIビルドの詳細ページには、昇格されたビルドの Build Logs セクションが表示されません。これは、昇格では新しいビルドではなく既存のイメージが再利用されるためです。
デフォルトでは 、ソースビルドには少なくとも 1 つの配置が成功している必要があります。これにより、イメージが配置可能であることが確認されます。この要件をバイパスするには、--force フラグを使用します。
ビルドをプロモートするには、次の構文を使用します。
agentengine build promote <source_build_id> [--workspace <name>] [--workspace-id <id>] [--project-id <id>] [--context <name>] [--force] [--yes] [--json]
CLI は、ソース ビルドをIDによって識別し、現在の組織内で解決します。別の組織内のプロジェクトにビルドを推奨することはできません。
ビルドを推奨する場合は、次のフラグを使用できます。
Flag | 説明 |
|---|---|
| （MongoDB のみ） ルート |
| 宛先プラットフォーム ワークスペースID。 |
| 宛先プラットフォームプロジェクトID。 |
|
|
| 配置が成功する要件をバイパスします。このフラグには、ターゲットプロジェクトの |
| インタラクティブな確認プロンプトをスキップします。 CIパイプラインまたはその他の非対話型環境で コマンドを実行する場合は、このフラグを使用します。そうしないと、コマンドは インタラクティブターミナルの外部で失敗します。 |
| 昇格結果をJSONとして出力します。 |
警告
昇格がソース ワークスペースからランタイムまたはプロジェクト構成をコピーすることはありません。シークレット、Atlas 接続構成、および Egress ポリシーは、ターゲット ワークスペースに転送されません。昇格したビルドを配置する前に、ターゲットプロジェクトとワークスペースでこれらの設定を構成します。
昇格が成功したら、ターゲットのワークスペースに昇格されたビルドを配置します。ビルドを配置する方法については、「 ビルドの配置 」を参照してください。
例
次のコマンドは、ビルドステータスをポーリングせずにエージェントイメージをビルドし、ビルド情報を一覧表示します。
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
次のステップ
エージェントイメージを構築したら、そのエージェントを本番環境に配置できます。エージェントを配置する方法については、 「ビルドの配置」ガイドを参照してください。