管理组织、项目和工作区

Overview

在本指南中，您可以学习；了解如何管理MongoDB Atlas Agent Engine 组织、项目和工作区。本指南介绍了以下管理命令：

Agentengine 组织：列出和查看组织。
agentengine 项目：列出和查看项目。
Agentengine 工作区：为已部署的代理创建和管理工作区。
AgentEngine Service-Account：为您的项目或组织创建和管理服务帐户。
Agentengine 版本：管理CLI版本。

先决条件

开始之前，请确保安装并验证 agentengine CLI。要学习；了解更多信息，请参阅《安装和身份验证指南》。

查看组织

组织是MongoDB Atlas助手引擎上团队和资源的顶级分组。 agentengine CLI可以列出和查看组织，但不能更改组织。要更改 Atlas 支持的组织，请使用MongoDB Atlas：

要创建、更新或删除组织，请参阅《管理组织》指南。
要添加、更新或删除组织用户，请参阅《管理组织用户》指南。

如果您的组织不是MongoDB Atlas支持的，请使用Atlas Agent Engine 用户用户界面更改您的组织。

列出所有组织

要列出您的帐户所属的所有组织，运行以下命令：

agentengine organization list

获取组织详细信息

要检索特定组织的详细信息，运行以下命令。将 <org-id> 替换为您的组织ID：

agentengine organization get <org-id>

查看项目

项目存在于组织中，并对特定代理或团队的资源群组。 agentengine CLI可以列出和查看项目，但无法更改项目。要更改 Atlas 支持的项目，请使用MongoDB Atlas：

要创建、更新或删除项目，请参阅“管理项目”指南。
要添加、更新或删除项目用户，请参阅《管理项目访问权限》指南。

如果您的项目不是MongoDB Atlas支持的，请使用Atlas Agent Engine 用户用户界面更改您的项目。

列出所有项目

要列出组织中的所有项目，运行以下命令：

agentengine project list [--org-id <org-id>]

您可以使用 --org-id 标志来指定组织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]

下表描述了可用标志：

标记	说明
`--project-id`	项目ID默认值：使用本地存储的身份验证状态中的项目。
`--org-id`	多组织路由的组织ID默认值：使用本地存储的身份验证状态中的项目。
`--base-url`	平台API基本URL默认值：使用本地存储的身份验证状态中的项目。
`--json`	输出原始JSON，而不是人类可读的表格

获取工作区详细信息

要检索特定工作区的详细信息，运行agentengine workspace get 命令：

agentengine workspace get <workspace-id> [--project-id <id>] [--org-id <id>] [--base-url <url>] [--json]

下表描述了可用标志：

标记	说明
`--project-id`	项目ID默认值：从本地存储的身份验证状态中获取的值。
`--org-id`	多组织路由的组织ID默认值：从本地存储的身份验证状态中获取的值。
`--base-url`	平台API基本URL默认值：从本地存储的身份验证状态中获取的值。
`--json`	输出原始JSON，而不是人类可读的键值对

创建工作区

agentengine workspace create 命令在平台上创建一个新的工作区。从包含 agent.yaml文件的代理目录运行此命令，其中包括 name 和 entrypoint 字段。

该命令会自动从 agent.yaml 读取 description、framework、features 和 agent_card，并自动检测本地 git存储库中的 GitOps 字段（如果存在）。使用 --description 和 --framework 标志覆盖 agent.yaml 中的值。

如果项目已存在工作区，则该命令将打印现有工作区ID并成功退出。

agentengine workspace create [--description <desc>] [--framework <fw>] [--project-id <id>] [--org-id <id>] [--base-url <url>] [--json]

下表描述了可用标志：

标记	说明
`--description`	工作区描述。覆盖 `agent.yaml` 中的值。
`--framework`	代理框架（示例`langgraph`）。覆盖 `agent.yaml` 中的值。
`--project-id`	项目ID默认值：从本地存储的身份验证状态中获取的值。
`--org-id`	多组织路由的组织ID默认值：从本地存储的身份验证状态中获取的值。
`--base-url`	平台API基本URL默认值：从本地存储的身份验证状态中获取的值。
`--json`	输出包含 `workspace_id` 和 `created` 字段的JSON

更新工作区

agentengine workspace update 命令部分更新现有工作区。只有明确提供的标志才会包含在更新请求中。

agentengine workspace update <workspace-id> [flags]

下表描述了可用标志：

标记	说明
`--name`	工作区显示名称
`--description`	工作区描述
`--framework`	代理框架
`--model`	LLM 模型名称
`--enabled-tools`	已启用的工具（以逗号分隔）
`--guardrails`	启用或禁用护栏（`--guardrails=true` 或 `--guardrails=false`）
`--memory`	启用或禁用内存（`--memory=true` 或 `--memory=false`）
`--agent-card-summary`	座席卡摘要文本
`--agent-card-capabilities`	座席卡功能（逗号分隔）
`--gitops-provider`	GitOps提供商
`--gitops-repo-url`	GitOps存储库URL
`--gitops-branch`	GitOps 分支
`--gitops-manifest-path`	GitOps 清单路径
`--gitops-connection-ref`	GitOps 连接参考
`--project-id`	项目ID默认值：从本地存储的身份验证状态中获取的值。
`--org-id`	多组织路由的组织ID默认值：从本地存储的身份验证状态中获取的值。
`--base-url`	平台API基本URL默认值：从本地存储的身份验证状态中获取的值。

使用API管理工作区

工作区命令调用Atlas Agent Engine API。要以编程方式管理工作区，请直接调用这些端点。

每个工作区端点的范围仅限于一个项目。如果您在多个项目中调用端点，请在请求中包含项目ID 。

下表描述了可用端点。将 {project-id} 替换为您的项目ID ，并将 {workspace-id} 替换为您的工作区ID：

端点	说明
`GET /api/v1/projects/{project-id}/workspaces`	列出项目中的工作区。
`POST /api/v1/projects/{project-id}/workspaces`	在项目中创建工作区。
`GET /api/v1/projects/{project-id}/workspaces/{workspace-id}`	返回单个工作区的详细信息。
`PATCH /api/v1/projects/{project-id}/workspaces/{workspace-id}`	更新请求正文中包含的字段。
`DELETE /api/v1/projects/{project-id}/workspaces/{workspace-id}`	删除工作区。

管理服务帐户

服务帐户是属于项目或组织而不是个人的编程身份。使用以下命令创建、列出、轮换和删除服务帐户。

要检索服务帐户访问权限令牌，请在 POST请求中将您的客户端ID和密钥传递给 /api/v1/oauth/token 端点。要学习；了解更多信息，请参阅调用代理。

本节中的示例使用以下占位符：

<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
...

重要

显示客户端密钥时将其保存。它只显示一次。

下表描述了可用标志：

标记	说明
`--role`	必需。授予服务帐户的角色。
`--org-id`	组织范围帐户的组织ID 。与 `--project-id` 标志互斥。
`--project-id`	项目范围帐户的项目ID 。默认值：从本地存储的身份验证状态中检索的值。与 `--org-id` 标志互斥。
`--description`	人类可读的描述。
`--secret-expires-in`	密钥有效期（以小时为单位），例如 `720h`。默认值：2160 小时（90 天）。最长：17520 小时（两年）。
`--ip-access-list`	允许使用该档案的IP地址或 CIDR 区块。默认：无限制。
`--json`	以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 天，或直到其过期为止，以先到者为准。

提示

要立即撤销之前的密钥，请再次轮换密钥或删除服务帐户。

删除服务帐户

要永久删除服务帐户，运行以下命令：

agentengine service-account delete <client-id> [--org-id <id>] [--project-id <id>]

删除服务帐户后，它就无法再请求访问权限令牌，并且它已经持有的任何令牌在下次使用时都会失败。

管理CLI版本

本部分介绍可用于检索和更新CLI版本的命令。

检查CLI版本

agentengine version 命令会打印CLI发布版本、构建二进制文件所依据的 git提交以及本地开发堆栈使用的默认容器映像标签。

要检索CLI版本，运行以下命令：

agentengine version [--json]

提示

默认下，此命令会打印人类可读的纯文本字符串。传递 --json 标志以打印稳定的机器可读JSON对象，其中包括 schema_version、status、version、git_commit、build 和嵌入式 images 字段。

输出类似于以下内容：

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 命令下载当前操作系统和架构的最新匹配发布资产，验证该资产的 SHA-256校验和，并替换当前安装路径中的现有二进制文件。

当您登录到Atlas Agent Engine 时， CLI会从平台API网关检索可用版本的列表。

注意

agentengine self-update 命令会将新的二进制文件下载到保存当前二进制文件的目录中，因此您必须对该目录具有写入访问权限。如果您没有写入访问权限，请在命令前加上 sudo 前缀，或将CLI重新安装到其他目录。

要更新CLI，运行以下命令：

agentengine self-update [--force] [--auto[=true|false]]

下表描述了可用标志：

标记	说明
`--force`	即使当前CLI已经是最新的，也请下载并安装最新版本。
`--auto`	在大多数命令运行之前启用自动自我更新。传递 `--auto=false` 标志以关闭自动更新。自动更新在Windows上不可用。

当您运行大多数 agentengine 命令时，如果有新发布可用， CLI会向 stderr 输出一行通知。 CLI每 24 小时运行一次更新检查。要完全禁用检查，请在Shell中设立AGENTENGINE_NO_UPDATE_CHECK=1 环境变量。

注意

在Windows上，agentengine self-update 命令会下载更新的二进制文件以进行手动替换，因为无法就地替换运行的agentengine.exe。

资源限制

每个组织最多可以有 100组织服务帐户。如果超过此限制，请求将返回 400 Bad Request 错误和 RESOURCE_LIMIT_EXCEEDED 消息。

下表列出了每个项目的资源限制：

Resource	Limit
工作区	25
API 密钥	100
凭证提供程序	100
项目服务帐户	100

如果超出资源限制，请求将返回 400 Bad Request 错误和 RESOURCE_LIMIT_EXCEEDED 消息。

要查看公开预览版期间应用的所有限制，请参阅MongoDB Atlas助手引擎限制。

后续步骤

设立组织、项目和工作区后，您可以在本地构建并运行代理。要学习；了解如何操作，请参阅构建本地环境。