使用有范围的凭证限制代理权限

当编排器智能体调用远程 Agent2Agent (A2A) 智能体时，限定凭据范围有助于确保远程智能体仅获得该请求所需的权限。在 Agent Registry 中发现代理后，您可以使用 Agent Identity 身份验证管理器以及受限 OAuth 范围或 Cloud Storage 的凭据访问边界，添加用户的凭据或生成限定范围的令牌。

准备工作

在通过 A2A 调用的限定范围凭据限制代理权限之前，请完成以下步骤：

  1. 设置 Agent Registry。

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

  3. 如果您想限制 Cloud Storage 令牌，请在项目中启用 Security Token Service API (sts.googleapis.com)。

  4. 安装 google-auth 和 requests Python 库：

    pip install --upgrade google-auth requests

  5. 为本地开发配置应用默认凭证 (ADC)。否则，请附加服务账号或工作负载身份联合凭证配置：

    gcloud auth application-default login

所需的角色

您可以使用用户账号进行本地开发，也可以使用服务账号或智能体主体，让编排器智能体发现已注册的智能体并调用目标 A2A 智能体。用户账号、服务账号或智能体主体必须具有适当的角色才能完成这些任务。

为确保您的用户账号、服务账号或智能体主体拥有在智能体注册表中发现 A2A 智能体并调用目标 A2A 智能体所需的权限，请让您的管理员为您的用户账号、服务账号或智能体主体授予以下 IAM 角色：

  • 如需在 Agent Registry 中发现代理，请在启用了 Agent Registry 的治理项目中拥有 Agent Registry API Viewer (roles/agentregistry.viewer) 角色
  • 在运行时调用目标 A2A 智能体： 托管目标智能体的服务的运行时或网关角色，调用该智能体时需要此角色。例如，如果目标智能体在 Cloud Run 上运行，则账号或主账号必须具有 Cloud Run Invoker 角色 (roles/run.invoker)。

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

您的管理员还可以通过自定义角色或其他预定义角色向您的用户账号、服务账号或智能体主体授予所需的权限。

凭证如何在智能体之间传递

当 A2A 客户端或编排器代理向远程代理发送消息时，下游服务会根据请求的身份验证方式检查权限：

  • 代表用户：用户登录您的编排器智能体，该智能体将用户授权的 OAuth 2.0 令牌或由身份验证管理器管理的令牌传递给远程 A2A 智能体。 Google Cloud API 会验证令牌并检查用户的 Identity and Access Management (IAM) 权限，以便远程智能体无法访问用户无权访问的资源。
  • 使用智能体自己的身份：当编排器智能体在没有登录用户的情况下运行时，它会使用自己的智能体身份或服务账号进行身份验证。下游服务会检查授予该代理的主账号 (principal://)、匹配的主账号集 (principalSet://) 或其服务账号的角色。
  • 从外部或跨云工作负载：在Google Cloud 外部运行的智能体通过工作负载身份联合交换来自外部身份提供方的令牌，以在调用目标 Agent Endpoint 之前获取联合 Google Cloud 访问令牌。

如需限制令牌授予远程智能体的权限，您可以使用绑定限制 OAuth 令牌的范围，以用于第三方或 SaaS A2A 智能体。

您还可以使用凭据访问边界限制 Cloud Storage 令牌，以将 Google Cloud 访问令牌限制为特定的 Cloud Storage 存储桶或对象。凭据访问边界仅支持 Cloud Storage (storage.googleapis.com) 权限。对于其他 Google Cloud API 和 A2A 智能体调用，请通过身份验证管理器绑定、具有 IAM 允许和拒绝政策的最小权限智能体身份或 Agent Gateway 来限定访问权限范围。

如果这些选项不适合您的使用场景，并且您的编排器代理使用服务账号进行身份验证，您还可以使用服务账号模拟为仅具有特定任务所需角色的专用服务账号请求短期有效令牌。

使用绑定限定 OAuth 令牌的范围

调用使用 2 足式或 3 足式 OAuth 2.0 的第三方或 SaaS A2A 智能体时，请在身份验证管理器中创建一个身份验证提供方，并在 Agent Registry 中附加一个 Binding 资源，其中仅列出远程智能体所需的 OAuth scopes。当智能体开发套件 (ADK) 使用 get_remote_a2a_agent() 检索远程智能体时，它会请求仅限于该绑定范围的令牌。如需了解设置步骤，请参阅向工具和资源进行身份验证和管理绑定。

限制 Cloud Storage 令牌

如果您的编排器代理将 OAuth 2.0 访问令牌传递给读取或写入 Cloud Storage 数据的代理或工具，您可以降低令牌的权限，使其仅允许访问特定存储桶或对象前缀。在发送请求之前，使用 Security Token Service 应用凭据访问边界：

import google.auth
from google.auth import downscoped
from google.auth.transport.requests import Request

source_creds, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)

access_boundary_rule = downscoped.AccessBoundaryRule(
    available_resource=(
        "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME"
    ),
    available_permissions=["inRole:roles/storage.objectViewer"],
)
cab = downscoped.CredentialAccessBoundary(rules=[access_boundary_rule])

downscoped_creds = downscoped.Credentials(
    source_credentials=source_creds,
    credential_access_boundary=cab,
)
downscoped_creds.refresh(Request())

将 BUCKET_NAME 替换为远程代理可以读取的 Cloud Storage 存储桶名称。

其他安全控制措施

您可以将凭证范围限定与网络政策和提示检查结合使用：

后续步骤