Atlas リソースを設定する

プロファイル ファイル スキーマ

~/.agentengine/atlas.jsonファイルの構造は次のとおりです。

{
  "version": 1,
  "profiles": {
    "default": {
      "base_url": "https://cloud.mongodb.com",
      "client_id": "<service-account-client-id>",
      "client_secret": "<service-account-client-secret>"
    }
  }
}

複数の名前付きプロファイルを追加して、異なる Atlas 環境またはサービス アカウントで使用できます。デフォルト以外のプロファイルを使用するには、次の例に示すように --profile フラグを渡します。

agentengine atlas setup --profile <profile-name>

環境変数

プロファイルファイルを直接編集せずに、次の環境変数を使用して、認証情報を指定または上書きできます。

コマンドは、次の順序で認証情報を解決します。

1. MONGODB_ATLAS_ACCESS_TOKEN設定されている場合は

2. MONGODB_ATLAS_CLIENT_ID と MONGODB_ATLAS_CLIENT_SECRET（両方が設定されている場合）

3. 保存済みプロファイル ~/.agentengine/atlas.json

4. ターミナルが接続されている場合は、対話型プロンプト

コマンド フラグ

インタラクティブ フロー

agentengine atlas setup を実行すると、CLI は次の手順をガイドします。

1. 組織: 番号付きメニューで Atlas 組織を一覧表示します。既存の組織を選択するか、新しい組織を作成します。

2. プロジェクト: 選択した組織内のプロジェクトを一覧表示します。既存のプロジェクトを選択するか、新しいプロジェクトを作成します。新しいプロジェクトには、プロジェクト スコープのサービス アカウントが付与されます。

3. クラスター: 選択したプロジェクト内のクラスターを一覧表示します。既存のクラスターを選択するか、サービスアカウントにクラスター作成権限がある場合は、新しいクラスターを作成します。

4. データベースユーザー:エージェントがクラスターに接続するために使用する認証情報を持つデータベースユーザーを作成します。

5. 投票AI APIキー: エージェントのメモリ機能用の投票AI APIキーをプロビジョニングします。

6. シークレット: とMONGODB_URI VOYAGE_API_KEYを Atlas エージェント エンジンのシークレットとして保存し、配置されたエージェントが Atlas クラスターと 投票AIに接続できるようにします。

7. IP アクセス リスト: Atlas Agent Engine データ プレーンのIPアドレスをクラスターのIP アクセス リストに追加します。

フローが完了すると、CLI には各リソースのプロビジョニングステータスが表示されます。

自動設定

インタラクティブ プロンプトなしですべての Atlas リソースを自動的に作成するには、--yes フラグを agentengine atlas setup コマンドに渡します。ワークスペースが初期化されていない場合、agentengine atlas setup --yes コマンドは最初に agentengine init を実行し、その後はワークスペースIDに基づく名前を使用して次のリソースを作成します。

• Atlas cluster

• という名前のデータベースユーザー agent-engine-<workspace-id>

• という名前の投票APIキー agent-engine-<workspace-id>

生成された名前に一致する保存されたメタデータまたは既存の Atlas リソースが見つかると、自動セットアップは停止します。新しいリソースセットを作成するには、競合するリソースを削除し、--force を渡します。

自動設定は、存在する場合、保存された Atlasプロジェクトを使用します。それ以外の場合、プロンプトなしで続行するには、表示される Atlas組織が 1 つと表示される Atlasプロジェクトが1 つ必要です。

コマンドを実行中前に、次の環境変数を設定することで、デフォルトのクラスター構成を上書きできます。

ステータスを設定する

agentengine atlas setup コマンドは、各実行の終了時にすべてのリソースのプロビジョニングステータスを表示します。現在の状態を再確認するか、完全な設定フローを再実行するには、次のコマンドを実行します。

agentengine atlas setup --force

プロファイルの一覧表示

次のコマンドを使用して、~/.agentengine/atlas.jsonファイルから保存されたプロファイルを返します。

agentengine atlas profile list --json

次の例に、出力形式を示します。

{
  "schema_version": "1",
  "status": "ok",
  "profiles": [
    {"name": "default", "base_url": "https://cloud.mongodb.com"}
  ]
}

プロファイルの検証

次のコマンドを使用して、サービス アカウントの認証情報を検証し、アクセス可能な組織とプロジェクトを返します。

agentengine atlas profile verify --json --input -

- を --input フラグに渡して、stdin にJSONリクエストオブジェクトを渡します。このコマンドは、選択したプロファイル名、ベースURL、アクセス可能な組織とプロジェクトのリストを返します。出力にはアクセス トークンとシークレットは含まれません。

プロファイルの保存

次のコマンドを使用して、選択した Atlas組織とプロジェクトをワークスペースコンテキストに永続化します。

agentengine atlas profile save [--context <name>] [--workspace <name>] --json --input -

- を --input フラグに渡して、stdin にJSONリクエストオブジェクトを渡します。このコマンドは、Atlas の環境、プロファイル、組織、プロジェクトをワークスペースの .agentengine/state.jsonファイルに保存します。組織とプロジェクトの選択が変更されない場合、 コマンドは既存のクラスター、データベースユーザー、および 投票APIキーの選択を保持します。

クラスターの一覧表示

保存された Atlasプロジェクト内のクラスターを返すには、次のコマンドを使用します。

agentengine atlas cluster list [--context <name>] [--workspace <name>] --json

次の例に、出力形式を示します。

{
  "schema_version": "1",
  "status": "ok",
  "atlas_state": {},
  "clusters": [
    {
      "name": "my-cluster",
      "kind": "REPLICASET",
      "state_name": "IDLE",
      "is_flex": false
    }
  ],
  "create_defaults": {
    "name": "my-agent",
    "provider": "AWS",
    "region": "US_EAST_1",
    "tier": "FLEX",
    "label": "Flex"
  },
  "can_create": true,
  "warnings": []
}

create_defaultsオブジェクトは、新しいクラスターに推奨される構成を提供します。 can_createフィールドは、選択したプロジェクト内でクラスターを作成する権限があるかどうかを示します。

クラスターの保存

既存のクラスターを選択するか、新しいクラスターを作成するには、次のコマンドを使用します。

agentengine atlas cluster save [--context <name>] [--workspace <name>] --json --input -

- を --input フラグに渡して、stdin にJSONリクエストオブジェクトを渡します。既存のクラスターを選択するには:

{"mode": "existing", "name": "my-cluster"}

新しいクラスターを作成するには:

{
  "mode": "create",
  "name": "my-agent",
  "provider": "AWS",
  "region": "US_EAST_1",
  "tier": "FLEX"
}

作成モードで nameフィールドを省略すると、CLI はワークスペースIDから名前を生成します。クラスターを作成すると Atlas でのプロビジョニングがプロビジョニングされ、すぐに返されます。 Atlas がクラスターのプロビジョニングを完了するまでに数分かかる場合があります。

データベースユーザーの一覧表示

保存された Atlasプロジェクトのデータベースユーザーを返すには、次のコマンドを使用します。

agentengine atlas database-user list [--context <name>] [--workspace <name>] --json

次の例に、出力形式を示します。

{
  "schema_version": "1",
  "status": "ok",
  "atlas_state": {},
  "users": [
    {"username": "my-user", "database_name": "admin"}
  ],
  "create_defaults": {"username": "agent-engine-<workspace-id>"},
  "can_create": true,
  "warnings": []
}

コマンドは、名前がワークスペース用に生成されたデフォルトと一致する既存のユーザーを見つけると、そのユーザーを .agentengine/state.jsonファイルに自動的に保存します。これにより、現在のセッション外でリソースがプロビジョニングされたときにローカルの状態が最新に保たれます。

データベースユーザーの保存

既存のユーザーを選択するか、新しいユーザーを作成するには、次のコマンドを使用します。

agentengine atlas database-user save [--context <name>] [--workspace <name>] --json --input -

- を --input フラグに渡して、stdin にJSONリクエストオブジェクトを渡します。既存のユーザーを選択するには、次の例に示すようにパスワードを含めます。

{"mode": "existing", "username": "my-user", "password": "my-password"}

新しいユーザーを作成するには、次のオブジェクトを渡します。

{"mode": "create", "username": "my-user"}

作成モードで usernameフィールドを省略すると、CLI はワークスペースIDから名前を生成します。新規ユーザーの場合、CLI はパスワードを自動的に生成します。生成されたパスワードは、コマンド出力には含まれません。

保存後、コマンドは MONGODB_URI をプロジェクトスコープの Atlas Agent Engine シークレットとして書き込みます。ローカルファイルには書込みません。

投票APIキーを一覧表示する

次のコマンドを使用して、保存された Atlasプロジェクトの投票権APIキーを返します。

agentengine atlas voyage-api-key list [--context <name>] [--workspace <name>] --json

次の例に、出力形式を示します。

{
  "schema_version": "1",
  "status": "ok",
  "atlas_state": {},
  "keys": [
    {
      "id": "key-id",
      "name": "agent-engine-<workspace-id>",
      "masked_secret": "voy...xxxx"
    }
  ],
  "create_defaults": {"name": "agent-engine-<workspace-id>"},
  "can_create": true,
  "warnings": []
}

コマンドは、ワークスペース用に生成されたデフォルトと一致する既存のキーを見つけると、そのキーを .agentengine/state.jsonファイルに自動的に保存します。

投票APIキーの保存

既存のキーを選択するか、新しいキーを作成するには、次のコマンドを使用します。

agentengine atlas voyage-api-key save [--context <name>] [--workspace <name>] --json --input -

- を --input フラグに渡して、 JSONオブジェクトをstdin に渡します。既存のキーを選択するには、次の形式を使用します。

{"mode": "existing", "name": "my-key", "value": "<api-key-value>"}

新しいキーを作成するには、次の形式を使用します。

{"mode": "create", "name": "my-key"}

作成モードで nameフィールドを省略すると、CLI はワークスペースIDから名前を生成します。キーを作成すると、CLI は Atlas によって返されたシークレット値を直接使用します。

保存後、コマンドは VOYAGE_API_KEY をプロジェクトスコープの Atlas Agent Engine シークレットとして書き込みます。ローカルファイルには書込みません。下位の Atlas 環境の場合、 コマンドは VOYAGE_URL 変数も同じ方法で書込みます。