Overview
このガイドでは、 MongoDB Atlas Agent の組織、プロジェクト、ワークスペースを管理する方法を学習できます。このガイドでは、次のマネジメントコマンドについて説明します。
エージェントエンジン ワークスペース: 配置されたエージェントのワークスペースを作成および管理します。
エージェントエンジン サービスアカウント:プロジェクトまたは組織のサービスアカウントを作成および管理します 。
前提条件
開始する前に、agentengine CLI をインストールと認証していることを確認してください。詳細については、 「インストールと認証のガイド」を参照してください。
組織の表示
組織は、 MongoDB Atlas Agent Engine 上のチームとリソースの最上位のグループです。 agentengine CLI で組織を一覧表示して表示することはできますが、変更することはできません。 Atlas ベースの組織 を変更するには、 MongoDB Atlasを使用します。
MongoDB Atlasを使用していない組織では、Atlas Agent Engine UI を使用して組織を変更 します。
すべての組織を一覧表示
アカウントが属するすべての組織を一覧表示するには、次のコマンドを実行します。
agentengine organization list
組織の詳細の取得
特定の組織の詳細を検索するには、次のコマンドを実行します。 <org-id> を組織IDに置き換えます。
agentengine organization get <org-id>
プロジェクトを見る
プロジェクトは組織内に存在し、特定のエージェントまたはチームのリソースをグループ化します。 agentengine CLI でプロジェクトを一覧表示して表示できますが、変更することはできません。 Atlas ベースのプロジェクト を変更するには、 MongoDB Atlasを使用します。
プロジェクトがMongoDB Atlasベースでない場合は、Atlas Agent Engine UIを使用してプロジェクトを変更 します。
すべてのプロジェクトを一覧表示
組織内のすべてのプロジェクト を一覧表示するには、次のコマンドを実行します。
agentengine project list [--org-id <org-id>]
組織ID を指定するには、--org-id フラグを使用します。デフォルトでは 、CLI はローカルに保存された認証状態からこの値を読み取ります。
プロジェクト詳細の取得
特定のプロジェクトの詳細を検索するには、次のコマンドを実行します。 <project-id> をプロジェクトIDに置き換えます。
agentengine project get <project-id>
ワークスペースの管理
ワークスペース とは、プロジェクト内に配置されたエージェントのランタイム環境です。ワークスペースの作成と管理には、次のコマンドを使用します。このセクションの例では、<workspace-id> プレースホルダーを使用します。このプレースホルダーをワークスペースIDに置き換えます。
すべてのワークスペースを一覧表示する
プロジェクト内のすべてのワークスペースを一覧表示するには、次のコマンドを実行します。
agentengine workspace list [--project-id <id>] [--org-id <id>] [--base-url <url>] [--json]
次の表では、使用可能なフラグについて説明しています。
Flag | 説明 |
|---|---|
|
|
|
|
|
|
| 人間が判読できるテーブルではなく、未加工のJSONを出力します |
ワークスペースの詳細の取得
特定のワークスペースの詳細を取得するには、agentengine workspace get コマンドを実行します。
agentengine workspace get <workspace-id> [--project-id <id>] [--org-id <id>] [--base-url <url>] [--json]
次の表では、使用可能なフラグについて説明しています。
Flag | 説明 |
|---|---|
|
|
|
|
|
|
| 人間が判読できるキーと値のペアではなく、未加工のJSONを出力します |
ワークスペースの作成
agentengine workspace create コマンドはプラットフォームに新しいワークスペースを作成します。 name フィールドと entrypoint フィールドを含む agent.yamlファイルを含むエージェントディレクトリから次のコマンドを実行します。
コマンドは、agent.yaml から description、framework、features、agent_card を自動的に読み取り、ローカル Gitリポジトリから GitOps フィールドを自動削除します（存在する場合）。 agent.yaml の値を上書きするには、--description と --framework フラグを使用します。
プロジェクトのワークスペースがすでに存在する場合 、コマンドは既存のワークスペースIDを出力し、正常に終了します。
agentengine workspace create [--description <desc>] [--framework <fw>] [--project-id <id>] [--org-id <id>] [--base-url <url>] [--json]
次の表では、使用可能なフラグについて説明しています。
Flag | 説明 |
|---|---|
| ワークスペースの説明。 |
| エージェントフレームワーク（例: 、 |
|
|
|
|
|
|
|
|
ワークスペースの更新
agentengine workspace update コマンドは既存のワークスペースを部分的にアップデートします。更新リクエストには、明示的に指定されたフラグのみが含まれます。
agentengine workspace update <workspace-id> [flags]
次の表では、使用可能なフラグについて説明しています。
Flag | 説明 |
|---|---|
| ワークスペースの表示名 |
| ワークスペースの説明 |
| エージェントフレームワーク |
| LVM モデル名 |
| 有効なツール（コンマ区切り） |
| 保護ルールの有効化または無効化（ |
| メモリの有効化または無効化（ |
| エージェント カードの概要テキスト |
| エージェント カードの機能（コンマ区切り） |
| GitOps プロバイダー |
| GitOpsリポジトリURL |
| GitOps ブランチ |
| GitOps マニフェスト パス |
| GitOps 接続参照 |
|
|
|
|
|
|
APIを使用したワークスペースの管理
ワークスペース コマンドは Atlas Agent Engine APIを呼び出します。プログラムでワークスペースを管理するには、これらのエンドポイントを直接呼び出します。
各ワークスペース エンドポイントの範囲は 1 つのプロジェクトに限定されます。複数のプロジェクトでエンドポイントを呼び出す場合は、リクエストにプロジェクトIDを含めます。
次の表では、利用可能なエンドポイントについて説明しています。 {project-id} をプロジェクトIDに置き換え、{workspace-id} をワークスペースIDに置き換えます。
エンドポイント | 説明 |
|---|---|
| プロジェクト内の ワークスペース を一覧表示します。 |
| プロジェクトにワークスペースを作成します。 |
| 1 つのワークスペースの詳細を返します。 |
| リクエスト本文に含めるフィールドを更新します。 |
| ワークスペースを削除します。 |
サービス アカウントの管理
サービス アカウントは、個人ではなくプロジェクトまたは組織に属するプログラムによる ID です。サービス アカウントの作成、一覧表示、ローテーション、および削除を行うには、次のコマンドを使用します。
サービスアカウントアクセストークンを検索するには、POST エンドポイントへの/api/v1/oauth/token リクエストでクライアントIDとシークレットを渡します。詳細については、「 エージェントの呼び出し 」を参照してください。
このセクションの例では、次のプレースホルダーを使用します。
<name>: サービス アカウント名。<role>: サービス アカウントを付与するロール。プロジェクトアカウントには、PROJECT_OWNERまたはPROJECT_READ_ONLYを使用します。組織アカウントには、ORG_GROUP_CREATORまたはORG_READ_ONLYを使用します。<client-id>: サービス アカウントのクライアントID。
サービス アカウントの作成
新しいサービス アカウントを作成するには、次のコマンドを実行します。
agentengine service-account create <name> --role <role> [--org-id <id> | --project-id <id>] [--description <text>] [--secret-expires-in <duration>] [--ip-access-list <ip-or-cidr>,...] [--json]
このコマンドは、次の例に示すように、プレーンテキストのクライアントシークレットとサービス アカウントの詳細を出力します。
Client Secret: agp_sa_sk_... Client ID: agp_sa_id_... Name: ci-pipeline ...
重要
クライアントシークレットが表示されたら保存します。 1 回だけ表示されます。
次の表では、使用可能なフラグについて説明しています。
Flag | 説明 |
|---|---|
| 必須。サービス アカウントに付与されたロールです。 |
| 組織範囲内のアカウントの組織ID 。 |
| プロジェクト スコープ アカウントのプロジェクトID 。デフォルト: ローカルに保存された認証状態から取得された値。 |
| 人間が判読できる説明。 |
| シークレット有効期間（単位は時間）（ など）。デフォルト: |
| 認証情報の使用が許可されたIPアドレスまたは CIDR ブロック。デフォルト: |
| 作成されたサービス アカウント、1 回限りのクライアントシークレット、解決されたコンテキストをJSONとして出力します。警告は stdout に表示されません。 |
サービス アカウントの一覧表示
現在のプロジェクトまたは組織のすべてのサービス アカウントを一覧表示するには、次のコマンドを実行します。
agentengine service-account list [--org-id <id>] [--project-id <id>] [--limit <n>]
このコマンドは、クライアントID、名前、ロール、アクティブなステータス、シークレット有効期限、シークレット最終使用日、各サービス アカウントの説明を含む表を表示します。
デフォルトでは 、コマンドはローカルに保存された認証状態のプロジェクトのサービス アカウントを一覧表示します。別の組織またはプロジェクトのサービス アカウントを一覧表示するには、--org-id または --project-id フラグを使用します。
サービス アカウント シークレットのローテーション
サービス アカウントの新しいクライアントシークレットを発行するには、次のコマンドを実行します。
agentengine service-account rotate <client-id> [--org-id <id>] [--project-id <id>] [--secret-expires-in <duration>]
コマンドは、新しいプレーンテキストクライアントシークレットを出力します。以前のシークレットは、最大 7 日間、または独自の有効期限が切れるまで有効のままです。
Tip
前のシークレットをすぐに取り消すには、シークレットを 2 回目にローテーションするか、サービス アカウントを削除します。
サービス アカウントの削除
サービス アカウントを完全に削除するには、次のコマンドを実行します。
agentengine service-account delete <client-id> [--org-id <id>] [--project-id <id>]
サービス アカウントを削除すると、そのサービスはアクセス トークンをリクエストできなくなり、すでに保持しているトークンは次回の使用で失敗します。
CLI バージョンの管理
このセクションでは、CLI バージョンを取得して更新するために使用できるコマンドについて説明します。
CLI バージョンの確認
agentengine version コマンドは、CLI リリース バージョン、バイナリがビルドされた Git コミット、および ローカル開発スタックで使用されるデフォルトのコンテナイメージ タグを出力します。
CLI のバージョンを検索するには、次のコマンドを実行します。
agentengine version [--json]
Tip
デフォルトでは 、このコマンドは人間が判読できるプレーンテキスト string を出力します。 --json フラグを渡すと、schema_version、status、version、git_commit、build、埋め込み images フィールドを含む安定したマシン読み取り可能なJSONオブジェクトが出力されます。
出力は次のようになります。
0.1.94-alpha (commit: <hash>) image registry: ECR runner-base: <registry>/runner-base:0.1.94-alpha runner-base-typescript-langgraph: <registry>/runner-base-typescript-langgraph:0.1.94-alpha playground-ui: <registry>/playground-ui:0.1.94-alpha orchestrator: <registry>/orchestration-engine:<version> memory-server: <registry>/memory-server:<version>
CLI を更新する
agentengine self-update コマンドは、現在の OS とアーキテクチャに一致する最新のリリースアセットをダウンロードし、そのアセットの SHA-256チェックサム値を検証して、現在のインストール パスにある既存のバイナリを置き換えます。
Atlas Agent Engine にログインすると、CLI はプラットフォームAPI Gateway から利用可能なリリースのリストを検索します。
注意
agentengine self-update コマンドは、現在のバイナリを保持しているディレクトリに新しいバイナリをダウンロードするため、そのディレクトリへの書込み (write) アクセス権が必要です。書込み (write) アクセス権がない場合は、 コマンドの前に sudo を付けるか、CLI を別のディレクトリに再インストールします 。
CLI を更新するには、次のコマンドを実行します。
agentengine self-update [--force] [--auto[=true|false]]
次の表では、使用可能なフラグについて説明しています。
Flag | 説明 |
|---|---|
| 現在の CLI がすでに最新になっている場合でも、最新リリースをダウンロードしてインストールしてください。 |
| ほとんどの コマンドが実行される前に、自動更新を有効にします。自動更新をオフにするには、 |
ほとんどの agentengine コマンドを実行すると、新しいリリースが利用可能な場合、CLI は stderr に 1 行の通知を出力します。 CLI は 24 時間ごとに更新チェックを実行します。チェックを完全に無効にするには、 シェルで AGENTENGINE_NO_UPDATE_CHECK=1 環境変数を設定します。
注意
Windowsでは、実行中のagentengine.exe はその場で置き換えができないため、agentengine self-update コマンドは更新されたバイナリをダウンロードし 手動置き換えます 。
リソースの制限
各組織は最大 100 の組織サービス アカウントを持つことができます。この制限を超えると、リクエストは400 Bad Request エラーと RESOURCE_LIMIT_EXCEEDED メッセージを返します。
次の表は、各プロジェクトのリソース制限を示しています。
Resource | Limit |
|---|---|
ワークスペース | 25 |
API キー | 100 |
認証情報プロバイダ | 100 |
プロジェクト サービス アカウント | 100 |
リソース制限を超えると、リクエストはRESOURCE_LIMIT_EXCEEDED メッセージとともに 400 Bad Request エラーを返します。
パブリック プレビュー中に適用されるすべての制限を確認するには、 「 MongoDB Atlas Agent の制限 」を参照してください。
次のステップ
組織、プロジェクト、ワークスペースを設定したら、エージェントをローカルで構築して実行できます。その方法については、「 ローカル環境を構築する 」を参照してください。