管理绑定

在 Agent Registry 中，绑定可让编排器代理连接到下游代理、MCP 服务器和端点，而无需在代码中对连接或身份验证详细信息进行硬编码。您可以在 Agent Registry 中创建、查看、更新和删除绑定，以管理资源连接和委托权限。

准备工作

  1. 设置 Agent Registry。

  2. 对于单项目设置，请获取已启用 Agent Registry 的治理项目的项目 ID。如果您为多个项目配置了管理边界，请使用管理项目的 ID 进行边界范围内的发现和注册，或指定成员项目 ID 进行单项目操作。

  3. 注册来源和目标组件。如需了解详情，请参阅注册模型。

  4. 如果您想为委托权限配置绑定，请使用 Agent Identity 身份验证管理器创建身份验证提供方。如需了解详情，请参阅向工具和资源进行身份验证。

  5. 如需使用本文档中的 Google Cloud CLI 命令，请设置 gcloud CLI 环境。

所需的角色

如需获得在 Agent Registry 中管理绑定所需的权限，请让管理员向您授予已启用 Agent Registry 的治理项目的以下 IAM 角色：

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

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

绑定场景

您可以使用绑定来连接资源和委派权限。例如，您可以在以下场景中使用绑定：

  • 资源连接：将源智能体链接到目标资源，例如其他智能体、MCP 服务器或端点。在此场景中，您可以规划多智能体工作流，其中主编排器将任务分派给专门的子智能体或工具。
  • 委托权限：将代理与身份验证提供方相关联，以便代理使用自己的凭据或代表单个用户连接到外部目标或自定义工具。如果您的智能体需要使用 OAuth 令牌或 API 密钥向远程 MCP 服务器或工具进行身份验证，则必须进行此绑定。借助绑定，您无需在代码中手动定义身份验证提供方。如需查看详细说明，请参阅本文档中的创建身份验证提供方绑定。

创建绑定

创建绑定，将来源代理连接到目标资源：

gcloud

运行 gcloud agent-registry bindings create 命令：

gcloud agent-registry bindings create BINDING_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --source-identifier="SOURCE_ID" \
    --target-identifier="TARGET_ID"

替换以下内容：

Terraform

如需在来源代理和目标资源之间创建绑定，请配置 google_agent_registry_binding 资源。绑定需要 target 块：

resource "google_agent_registry_binding" "agent_binding" {
  location     = "REGION"
  binding_id   = "BINDING_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Connects a source agent to a target resource."

  source {
    identifier = "SOURCE_ID"
  }

  target {
    identifier = "TARGET_ID"
  }
}

替换以下内容：

  • REGION：注册表区域。
  • BINDING_NAME：您要为绑定指定的唯一名称。
  • DISPLAY_NAME：绑定的直观易懂的名称。
  • SOURCE_ID：URN 格式的源代理的代理标识符。
  • TARGET_ID：目标资源的注册表标识符，采用 URN 格式。

创建身份验证提供方绑定

您可以将代理与身份验证提供方相关联，以获得委托权限。 在创建此绑定之前，您必须先使用身份验证管理器创建身份验证提供方。如需了解详情，请参阅向工具和资源进行身份验证。

指定 --auth-provider-binding 资源名称时，您必须使用项目 ID：

gcloud

运行带有 --auth-provider-binding 标志的 gcloud agent-registry bindings create 命令：

gcloud agent-registry bindings create BINDING_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --source-identifier="SOURCE_ID" \
    --target-identifier="TARGET_ID" \
    --auth-provider-binding="projects/PROJECT_ID/locations/REGION/authProviders/AUTH_PROVIDER_ID"

替换以下内容：

  • BINDING_NAME：您要为绑定指定的唯一名称。
  • PROJECT_ID：项目 ID。
  • REGION：注册表区域。
  • DISPLAY_NAME：绑定的直观易懂的名称。
  • SOURCE_ID：URN 格式的源代理的代理标识符。
  • TARGET_ID：目标资源的注册表标识符，采用 URN 格式。
  • AUTH_PROVIDER_ID：身份验证提供方的 ID。

Terraform

如需在 Terraform 中配置身份验证提供方绑定，请指定 auth_provider_binding 块，其中包含身份验证提供方的资源名称、其范围和继续 URI：

resource "google_agent_registry_binding" "auth_binding" {
  location     = "REGION"
  binding_id   = "BINDING_NAME"
  display_name = "DISPLAY_NAME"

  source {
    identifier = "SOURCE_ID"
  }

  target {
    identifier = "TARGET_ID"
  }

  auth_provider_binding {
    auth_provider = "projects/PROJECT_ID/locations/REGION/authProviders/AUTH_PROVIDER_ID"
    scopes        = [SCOPES]
    continue_uri  = "CONTINUE_URI"
  }
}

替换以下内容：

  • REGION：注册表区域。
  • BINDING_NAME：您要为绑定指定的唯一名称。
  • DISPLAY_NAME：绑定的直观易懂的名称。
  • SOURCE_ID：URN 格式的源代理的代理标识符。
  • TARGET_ID：目标资源的注册表标识符，采用 URN 格式。
  • PROJECT_ID：项目 ID。
  • AUTH_PROVIDER_ID：身份验证提供方的 ID。
  • SCOPES：以英文逗号分隔的 OAuth 2.0 范围列表，例如 "https://www.googleapis.com/auth/cloud-platform"。
  • CONTINUE_URI：身份验证提供方的继续 URI，例如 https://example.com/continue。

如需查看如何在智能体代码中使用这些绑定的示例，请参阅在智能体开发套件 (ADK) 代码中解析绑定。

列出绑定

运行 gcloud agent-registry bindings list 命令，列出特定位置中的所有绑定：

gcloud agent-registry bindings list \
    --project=PROJECT_ID \
    --location=REGION

替换以下内容：

  • PROJECT_ID：项目 ID。
  • REGION：注册表区域。

查看绑定详情

通过运行 gcloud agent-registry bindings describe 命令检索单个绑定的详细信息：

gcloud agent-registry bindings describe BINDING_NAME \
    --project=PROJECT_ID \
    --location=REGION

替换以下内容：

  • BINDING_NAME：绑定的名称。
  • PROJECT_ID：项目 ID。
  • REGION：注册表区域。

更新绑定

更新现有绑定的参数，例如其显示名称或说明：

gcloud

运行 gcloud agent-registry bindings update 命令：

gcloud agent-registry bindings update BINDING_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="NEW_DISPLAY_NAME"

替换以下内容：

  • BINDING_NAME：您要更新的绑定的名称。
  • PROJECT_ID：项目 ID。
  • REGION：注册表区域。
  • NEW_DISPLAY_NAME：绑定的新人类可读名称。

Terraform

如需使用 Terraform 更新绑定的显示名称或说明，请修改配置中的现有 google_agent_registry_binding 资源，然后运行 terraform apply。

删除绑定

如需移除资源之间的连接，请删除绑定：

gcloud

运行 gcloud agent-registry bindings delete 命令：

gcloud agent-registry bindings delete BINDING_NAME \
    --project=PROJECT_ID \
    --location=REGION

替换以下内容：

  • BINDING_NAME：要删除的绑定的名称。
  • PROJECT_ID：项目 ID。
  • REGION：注册表区域。

Terraform

从 Terraform 配置中移除表示绑定的 google_agent_registry_binding 资源，然后运行 terraform apply。

后续步骤