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 deploy 部署具有代理身份的代理：使用 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" \

替换以下内容：

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 政策。强烈建议不要执行此操作，因为这会使代理容易遭受凭据盗窃。

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

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

后续步骤

指南

管理已部署的智能体

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

指南

使用代理

使用 Agent Platform Runtime 中的代理。