Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

将代理身份与 Agent Runtime 搭配使用

在 Agent Runtime 上使用代理身份可提供安全的代理专属身份，从而实现最小权限访问权限管理方法。本文档介绍了如何使用代理身份创建代理、授权访问 Google Cloud API 以及管理第三方服务的凭据。

概览

代理身份提供代理专属身份，可实现最小权限方法，并且与代理的生命周期相关联，因此代理身份比服务账号更安全。通过 IAM 进行的现有访问权限管理控制支持代理身份，从而实现强大的治理。

默认情况下，代理身份凭据通过 Google 管理的情境感知访问权限 (CAA) 政策进行保护。此政策强制执行 mTLS 绑定，以确保代理的凭据（以证书绑定令牌的形式）只能从其预期的可信运行时环境（例如 Cloud Run 容器）中使用。这种安全基准可防止被盗凭据重放，从而防范凭据盗窃和账号接管攻击 (ATO)。

本页涵盖以下主题：

使用代理身份创建代理：创建代理，以便在您部署到 Agent Runtime 时，代理自动接收唯一身份。
使用代理身份 Google Cloud 授权访问 API：使用预配的代理身份向代理授予或拒绝访问 Google Cloud'的第一方工具、API 和资源。这还包括使用 Agent2Agent (A2A) 协议访问托管在 Agent Runtime 上的其他代理。
记录代理活动：在各项服务 Google Cloud 中查看日志中的代理身份。对于用户委托的流程，日志会显示用户身份和代理身份。
列出代理和代理身份：在 Agent Runtime 中查看代理及其身份的列表。
选择停用情境感知访问权限 （不推荐）：选择停用默认的情境感知访问权限 (CAA) 政策。

限制

无法在 Cloud Storage 存储分区上向代理身份授予旧版存储分区角色（storage.legacyBucketReader、storage.legacyBucketWriter 或 storage.legacyBucketOwner）。

使用代理身份创建代理

创建 Agent Runtime 实例后，您可以为部署到 Agent Runtime 的代理预配唯一身份。该身份与 Agent Runtime 的代理资源 ID 相关联，并且与您用于开发代理的代理框架无关。

创建代理身份时，您有以下选项：

创建 Agent Runtime 实例而不部署代理代码：如果您想在部署代理之前设置 IAM 政策，可以创建代理身份而不部署代理代码。为此，请仅使用 identity_type 字段创建 Agent Runtime 实例：

import vertexai
from vertexai import agent_engines
from vertexai import types

client = vertexai.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)
remote_app = client.agent_engines.create(
  config={
    "display_name": "identity-for-agent",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
  },
)

使用代理身份创建 Agent Runtime 实例后，您可以使用 agent_engine.update(...)添加代理代码。

在部署代理代码时创建 Agent Runtime 实例：如果您想在部署代理代码时预配代理身份，请使用 Agent Platform SDK for Python 和 identity_type=AGENT_IDENTITY 标志。

在您首选的框架中定义代理：

from google.adk.agents import Agent

agent = Agent(
    model="gemini-2.5-flash",
    name="minimal_agent",
    instruction="You are a helpful assistant.",
)

然后，部署它：

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Agent Platform client with v1beta1 API for agent identity support
client = vertexai.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity
remote_app = client.agent_engines.create(
  agent=app,
  config={
    "display_name": "running-agent-with-identity",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
    "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
    "staging_bucket": f"gs://"BUCKET_NAME",
  },
)

print(f"Effective Identity: {remote_app.api_resource.spec.effective_identity}")

其中 BUCKET_NAME 是 Cloud Storage 存储桶的名称。

使用 Agents CLI 部署代理： Agents CLI 非常适合学习者、原型设计和快速测试，因为它提供了一个快速部署解决方案，其中包含用于监控的基础资源。以下命令会部署您的代理：
```
agents-cli deploy --agent-identity
```

使用 ADK 部署代理和代理身份：使用 ADK 设置代理。在运行 adk deploy 之前，请在代理的文件夹中运行以下命令，以添加包含代理身份的配置文件。

# Create the file
$ touch .agent_engine_config.json

# Update the file to specify that you're using Agent Identity
$ echo '{ "identity_type": "AGENT_IDENTITY" }' > .agent_engine_config.json

创建的 Agent Runtime 实例具有只读的系统证明代理身份（主账号标识符）：

# Agent identity Format
principal://TRUST_DOMAIN/NAMESPACE/AGENT_NAME

# Example agent identity
principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID

以下部分会自动预配给您，作为代理身份的一部分：

TRUST_DOMAIN：启用 Agent Platform API 后，系统会为您预配信任网域：
- 如果您有组织，则信任网域是在组织级层创建的，格式为 agents.global.org-ORGANIZATION_ID.system.id.goog。
- 如果您的项目没有组织，则信任网域是在项目级层创建的，格式为 agents.global.project-PROJECT_NUMBER.system.id.goog。
NAMESPACE：代理的不可变资源路径。
AGENT_NAME：不可变的 agent-reasoning-engine-id。

代理身份基于 SPIFFE。我们还会自动预配和管理代理上具有相同身份的 x509 证书，以实现安全身份验证。默认情况下，代理可以访问自己的日志记录、指标、模型访问权限、会话、记忆库和沙盒（预览版）。

代理身份附带默认的 roles/aiplatform.agentContextEditor 和 roles/aiplatform.agentDefaultAccess 角色，以便代理拥有执行操作的基本权限。

您可以通过查看身份通过 Agent Runtime Google Cloud 控制台和 API。

使用代理身份访问 Google Cloud API 和服务

使用代理身份创建代理后，您可以使用以下 IAM 政策向代理授予或拒绝访问 Google Cloud API 和服务：

允许政策：向代理授予对 Google Cloud 资源的访问权限。
拒绝政策：拒绝代理访问 Google Cloud 资源。

授予代理访问权限

向代理身份授予 IAM 权限。我们建议使用以下角色：

roles/aiplatform.expressUser：授予运行推理、会话和记忆库的访问权限。
roles/serviceusage.serviceUsageConsumer：授予代理使用项目的配额和 Agent Platform SDK 的权限。
roles/browser：授予对基本 Google Cloud 功能的访问权限。

如果您使用日志记录、指标和 Cloud API 注册表，并且对于您想向代理公开的任何其他资源，可能需要其他权限。如需更多示例，请参阅下文。

创建 IAM 允许政策以向代理授予 IAM 角色：

  # Example: Grant the agent access to vision API.
  gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
  --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID" \
  --role="ROLE_NAME" \

替换以下内容：

RESOURCE_TYPE：资源类型（例如 projects 或 organizations）。
RESOURCE_ID：您要授予访问权限的资源的 ID。
ORGANIZATION_ID：组织的 ID。
PROJECT_NUMBER：您的项目编号。
LOCATION：您的区域。请参阅 Runtime 支持的区域。
AGENT_ENGINE_ID：Agent Runtime 实例的资源 ID。
ROLE_NAME 是您要授予的角色的名称。例如，roles/vision.user。如需了解预定义角色的列表，请参阅了解角色。

配置 IAM 后，Agent Platform SDK 的应用默认凭据会自动使用代理身份对 Google Cloud 资源执行身份验证。

授予多个代理访问权限

您可以向特定项目中的所有 Agent Runtime 代理或整个组织中的所有 Agent Runtime 代理授予 IAM 角色。

如需向项目中的所有 Agent Runtime 代理授予角色，请使用以下命令之一。

如果您的项目属于组织：

# Grant all agents in a project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

如果您的项目不属于组织：

# Grant all agents in an orgless project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.project-PROJECT_NUMBER.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

向项目中的所有代理授予常见权限（例如配额、日志记录或对模型的访问权限）可以更轻松地简化部署。然后，向各个代理授予特定的狭窄权限，以用于更敏感的权限（例如对数据的访问权限）。在组织或项目中首次使用代理身份功能后，您可以随时授予此类权限，因此可以在部署代理之前执行此操作。

例如，以下命令会向项目中的所有代理授予基本角色：

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/serviceusage.serviceUsageConsumer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/browser

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/aiplatform.expressUser

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/cloudapiregistry.viewer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/logging.logWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/monitoring.metricWriter

如需向整个组织中的所有 Agent Runtime 代理授予角色：

# Grant all agents in an organization the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platform/aiplatform" \
--role="ROLE_NAME"

拒绝代理访问权限

如需拒绝代理访问资源，您可以使用 IAM 拒绝政策或设置主账号访问权限边界政策。

使用 IAM 拒绝政策拒绝代理访问某些资源。

// Deny policy (deny all agents across the org from ability to create or delete buckets)

{
"displayName": "Deny access to bucket for all agent identities in the org",
"rules": [
  {
    "denyRule": {
      "deniedPrincipals": [
        "principalSet://<org.id>.global.agent.id.goog/*"
      ],
      "deniedPermissions": [
        "iam.googleapis.com/roles.create",
        "storage.googleapis.com/buckets.delete"
      ]
    }
  }
]
}

设置 Principal Access Boundary，以限制代理可以访问的资源，即使代理可能拥有其他权限也是如此：

// PAB Policy (Only allow agents to operate within resource boundary)

{
    "name":"organizations/ORGANIZATION_ID/locations/global/principalAccessBoundaryPolicies/example-policy",
    "details": {
    "rules": [
      {
        "description": "Restrict agent identity inside a folder",
        "resources": [
          "//cloudresourcemanager.googleapis.com/folder/0123456789012"
        ],
        "effect": "ALLOW"
      }
    ],
  }
}

// Bind PAB policy to all identities in the organization (incl agent id)

gcloud iam principal-access-boundary-policies bindings create example-pab-binding \
      --organization=organizations/ORGANIZATION_ID \
      --policy=example-policy \ --target-principal-set=cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_ID

记录代理活动

如果您启用 Cloud Logging，则可以查看哪些代理和用户访问了 Google Cloud 资源的日志。

当代理代表用户执行操作时，日志会显示代理和用户的身份。
当代理自行执行操作时，日志仅显示代理的身份。

列出代理及其身份

您可以使用 Google Cloud 控制台和命令行在 Agent Runtime 中查看代理身份的列表。

控制台

在 Google Cloud 控制台中，前往 Agent Platform 部署页面。

前往“部署”页面

属于所选项目的已部署代理会显示在列表中。您可以使用过滤条件 字段按指定的列过滤列表。
对于每个代理，代理身份都会列在身份列下。

REST API

使用 REST API 获取 Agent Runtime 实例时，您可以检索代理身份。

响应包含以下格式的代理身份：

{
  ...
  spec: {
    "effectiveIdentity": "agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID"
  }
  ...
}

对于未使用代理身份的 Agent Runtime 实例，effectiveIdentity 字段包含与 Agent Runtime 实例关联的服务代理或服务帐号名称。

选择停用情境感知访问权限 (CAA)

默认情况下，尝试在预期 Agent Runtime 运行时之外使用访问令牌会导致以下错误：

Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"

对于特殊情况（例如代理之间有特定的令牌共享要求），您可以选择停用默认的 CAA 政策。强烈建议您不要执行此操作，因为这会让代理容易受到凭据盗窃的攻击。

如需选择停用默认的情境感知访问权限 (CAA) 政策，请在创建 Agent Runtime 实例时设置以下环境变量：

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

后续步骤

指南

管理已部署的代理

了解如何管理已部署到 Agent Platform 托管运行时的代理。

指南

使用代理

使用 Agent Platform Runtime 中的代理。