设置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. Voyage AI API密钥：为助手的内存功能预配 Voyage AI API密钥。

6. 密钥：将 MONGODB_URI 和 VOYAGE_API_KEY 保存为Atlas助手引擎密钥，以便部署的助手可以连接到Atlas 集群和 Voyage AI。

7. IP访问列表：将Atlas助手引擎数据平面IP地址添加到集群的IP访问列表。

流程完成后， CLI会显示每个资源的预配状态。

自动设置

要在没有交互式提示的情况下自动创建所有Atlas资源，请将 --yes 标志传递给 agentengine atlas setup 命令。当工作区尚未初始化时，agentengine atlas setup --yes 命令会先运行 agentengine init，然后使用基于工作区ID 的名称创建以下资源：

• Atlas cluster

• 数据库用户名为 agent-engine-<workspace-id>

• Voyage API密钥名为 agent-engine-<workspace-id>

当发现已保存的元数据或与这些生成的名称匹配的现有Atlas资源时，自动设置会停止。要创建一设立新的资源，删除冲突的资源并传递 --force。

自动设置会使用已保存的Atlas项目（如果存在）。否则，它需要一个可见的Atlas组织和一个可见的Atlas项目才能在没有提示的情况下继续。

您可以在运行命令之前设置以下环境变量来覆盖默认集群配置：

设置状态

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文件。如果组织和项目选择没有更改，该命令将保留任何现有的集群、数据库用户和 Voyage 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 密钥写入。它不会写入本地文件。

列出 Voyage API密钥

使用以下命令返回已保存Atlas项目中的 Voyage 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文件中。

保存 Voyage API密钥

使用以下命令选择现有密钥或创建新密钥：

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

通过将 - 传递给 --input 标志，从而通过 stdin 传递JSON对象。要选择现有密钥，请使用以下格式：

{"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 变量。