设置 Agent Registry

如需在 Agent Registry 中注册和发现 AI 智能体、Model Context Protocol (MCP) 服务器、独立技能和端点，您必须在 Google Cloud 项目中启用 Agent Registry API。您在其中启用 Agent Registry 的项目将用作治理项目。

您可以在单个治理项目中设置 Agent Registry，也可以通过配置管理边界在多个项目中设置 Agent Registry，其中中央管理项目充当治理项目。

准备工作

在单个项目中或跨多个项目配置 Agent Registry：

所需的角色

如需获得设置 Agent Registry 所需的权限，请让您的管理员为您授予 Google Cloud 项目的以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

设置 Google Cloud CLI 环境

如果您计划使用 gcloud CLI for Agent Registry，请按以下步骤操作：

  1. 在 Google Cloud 控制台中，激活 Cloud Shell。

    激活 Cloud Shell

    Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

  2. 使用 gcloud components update 命令将 gcloud CLI 更新到最新版本：

    gcloud components update

  3. 如果您计划使用预览版功能，请使用 gcloud components install 命令安装 alpha 组件：

    gcloud components install alpha

启用 Agent Registry API

  • 对于单个项目：在治理项目中启用 Agent Registry API。启用 API 并授予权限后，您就可以开始在该项目中注册和发现代理。您无需配置管理边界。
  • 对于多个项目（管理边界）：在用于运行配置命令的项目上启用 Resource Manager API。当您为多个项目配置管理边界并创建功能配置时，Resource Manager 会自动在管理项目中启用 Agent Registry API。

使用您的项目 ID 启用 API：

控制台

对于单个项目，请在项目中启用 Agent Registry API：

启用 API 所需的角色

如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

启用 API

对于多个项目（管理边界），请在用于配置的项目上启用 Resource Manager API：

启用 API 所需的角色

如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

启用 API

gcloud

  • 对于单个项目，请使用 gcloud services enable 命令在项目中启用 Agent Registry API：

    gcloud services enable agentregistry.googleapis.com \
    --project=PROJECT_ID

  • 对于多个项目（管理边界），请在用于配置的项目上启用 Resource Manager API：

    gcloud services enable cloudresourcemanager.googleapis.com \
    --project=PROJECT_ID

将 PROJECT_ID 替换为独立治理项目的项目 ID，或要用作管理边界的管理项目的项目 ID。

为多个项目配置管理边界

如需跨多个 Google Cloud 项目使用 Agent Registry，请配置管理边界。管理边界会将一个或多个 Google Cloud 成员项目分组到一个中央管理项目中，该项目充当您的治理项目，以便您跨项目发现和治理 AI 智能体、MCP 服务器和工具。

您可以在 Resource Manager 中定义管理边界。如需了解分步说明，请参阅 Resource Manager 文档中的配置管理边界。

如需了解 BoundaryConfig、Boundary 和 CapabilityConfig 资源如何协同工作的架构概览，请参阅跨项目边界。

当您使用 agent-management 创建 CapabilityConfig 资源时，Resource Manager 会自动在管理项目中启用 agentregistry.googleapis.com。建立管理边界后：

  1. 如果需要在各个成员项目中进行本地操作，请在这些成员项目中启用 Agent Registry API。
  2. 向管理项目中的用户和服务账号授予所需的角色和权限。

当您在管理项目中的某个位置列出或搜索代理或 MCP 服务器时，Agent Registry 会汇总并返回该位置中来自边界内所有成员项目的自动发现资源，以及直接在管理项目中的该位置创建的所有已注册 Service 资源。每个返回的资源名称都会保留组件的 ID，并使用请求中指定的项目。

授予权限

如需在 Agent Registry 中查看和管理资源，您必须向用户授予适当的 Identity and Access Management (IAM) 权限。

向您的用户授予以下一个或多个 Agent Registry 角色：

  • Agent Registry API Viewer (roles/agentregistry.viewer)：查看和搜索智能体、MCP 服务器、工具、独立技能、技能修订版本、发布商、端点和绑定。
  • Agent Registry API Editor (roles/agentregistry.editor)：查看和修改 Agent Registry 资源，包括注册、更新和删除智能体、MCP 服务器、工具、端点、独立技能和技能修订版本。
  • Agent Registry API Admin (roles/agentregistry.admin)：对 Agent Registry 资源执行所有操作，包括注册和管理智能体、MCP 服务器、工具、端点、独立技能、技能修订版本、绑定和技能 IAM 政策。
  • Agent Registry User (roles/agentregistry.user)：查看所有 Agent Registry 资源，以及创建、更新和删除独立技能和技能修订版本，而无需对代理、MCP 服务器或端点拥有编辑权限。

如需了解如何授予对项目的 IAM 角色，请参阅管理对项目、文件夹和组织的访问权限。

更改 Agent Registry 项目

如果您想更改使用 Agent Registry 的项目并移除对旧项目的依赖项，请在旧项目中停用 Agent Registry API。在旧项目中停用 Agent Registry API 后，您可以在其他项目中启用该 API。您的数据不会迁移，您必须在此新项目中重新创建资源。

停用 Agent Registry API

如果您不想再使用 Agent Registry，请在项目中停用 Agent Registry API：

控制台

  1. 在 Google Cloud 控制台中，前往 Agent Registry API 管理页面：

    前往 Agent Registry API

  2. 在项目选择器中，选择您设置了 Agent Registry 的 Google Cloud 项目。

  3. 点击停用 API。

  4. 在确认对话框中，点击停用。

gcloud

使用 gcloud services disable 命令在项目中停用 Agent Registry API：

gcloud services disable agentregistry.googleapis.com \
    --project=PROJECT_ID

将 PROJECT_ID 替换为项目的 ID。

后续步骤