将代理身份与 Vertex AI Agent Engine 搭配使用

本页面介绍了如何使用 Identity Access Management (IAM) 代理身份在 Vertex AI Agent Engine 运行时中使用代理时提供安全和访问管理功能。

概览

代理身份提供了每个代理的身份，可实现最低权限方法，并且与代理的生命周期相关联，因此代理身份比服务账号更安全。通过 IAM 实现的现有访问权限管理控制功能支持代理身份，从而实现严格的治理。

本页面涵盖以下主题：

创建具有代理身份的代理：创建代理，以便在部署到 Vertex AI Agent Engine 运行时时，该代理自动接收唯一身份。
使用代理身份授权对 Google Cloud API 的访问权限：使用已配置的代理身份授予或拒绝代理对 Google Cloud的第一方工具、API 和资源的访问权限。这还包括使用 Agent2Agent (A2A) Protocol 访问 Vertex AI Agent Engine 上托管的其他代理。
使用 OAuth 通过委托权限访问第三方服务：使用 OAuth 为第一方和第三方工具配置用户委托身份验证，以便代理可以代表您执行任务。
使用 API 密钥访问第三方服务：使用在运行时安全存储和可用的 API 密钥连接到第三方服务。
记录代理活动：查看 Google Cloud 服务中日志内的代理身份。对于用户委托流程，日志会同时显示用户身份和代理身份。
列出代理和代理身份：查看 Vertex AI Agent Engine 中代理的列表及其身份。

限制

在规划项目时，请考虑以下限制：

无法向代理身份授予 Cloud Storage 存储分区的旧版存储分区角色（storage.legacyBucketReader、storage.legacyBucketWriter 或 storage.legacyBucketOwner）。
我们建议仅在测试环境中使用代理身份。

创建具有代理身份的代理

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

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

创建 Agent Engine 实例，但不部署代理代码：如果您想在部署代理之前设置 IAM 政策，可以创建代理身份，但不部署代理代码。为此，请创建一个仅包含 identity_type 字段的 Agent Engine 实例：
```
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={"identity_type": types.IdentityType.AGENT_IDENTITY}
)
```
使用代理身份创建 Agent Engine 实例后，您可以使用 agent_engine.update(...) 添加代理代码。

在部署代理代码时创建 Agent Engine 实例：如果您想在部署代理代码时预配代理身份，请使用 Vertex AI 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 Vertex AI 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 存储分区的名称。

Agent Engine 实例是使用只读的系统证明代理身份（即主账号标识符）创建的：

# 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：启用 Vertex AI 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 证书，以实现安全身份验证。

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

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

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

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

向代理授予访问权限

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

roles/aiplatform.expressUser：授予对正在运行的推理、会话和内存的访问权限。
roles/serviceusage.serviceUsageConsumer：授予代理使用项目配额和 Vertex AI 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：您的区域。请参阅 Vertex AI Agent Engine 的支持的区域。
AGENT_ENGINE_ID：Agent Engine 实例的资源 ID。
ROLE_NAME 是您要授予的角色的名称。例如 roles/vision.user。如需了解预定义角色的列表，请参阅了解角色。

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

向多位客服人员授予访问权限

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

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

如果您的项目属于某个组织，请执行以下操作：

# 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 Engine 代理授予角色，请执行以下操作：

# 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"
      ]
    }
  }
]
}

设置主账号访问权限边界，以限制代理可访问的资源，即使代理可能拥有其他权限也是如此：

// 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

使用 OAuth 通过委托权限访问第三方服务

通过与 Secret Manager 集成，代理身份可让代理代表您访问第三方服务。

如需设置与 Secret Manager 的集成，您首先需要按照以下步骤将用于访问第三方服务的辅助凭据（客户端 ID 或客户端密钥）存储到 Secret Manager 中（在代理生命周期受管理的消费方项目中）：

在 Secret Manager 中创建新容器。
从第三方应用提供商处获取客户端 ID 或客户端密钥。
向 Secret Manager 添加客户端 ID 或客户端密钥。

根据代理 ID（一种主账号标识符）限制对这些凭据的访问权限：

# Create the secret container
gcloud secrets create my-app-oauth-secret

# Add the actual client secret to Secret Manager
gcloud secrets versions add my-app-oauth-secret --data-file=oauth-secret

# Grant agent identity access to the secret
gcloud secrets add-iam-policy-binding my-app-oauth-secret \
--role='roles/secretmanager.secretAccessor' \
--member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID" \

密钥存储完毕后，代理可以在运行时使用其正文标识符和标准Google Cloud 身份验证库自动访问这些凭据，作为应用默认凭据的一部分。

# Example: Use agent identity to retrieve third party credentials from Secret Manager
# Use case: Using an agent, the user is trying to post a message on Slack,
# The developer first retrieves secret from Secret Manager using agent identity,
# and then uses it to login to Slack and post a message.

from google.cloud import secretmanager
from google.auth import default

def access_secret(project_id: str, secret_id: str, version_id: str = "latest") -> str:
  # Application default credential automatically gets token from MDS using agent identity
  agent_identity_credentials, _ = default()

  # Create the Secret Manager client.
  client = secretmanager.SecretManagerServiceClient(credentials=agent_identity_credentials)

  # Build the resource name of the secret version.
  name = f"projects/{project_id}/secrets/{secret_id}/versions/{version_id}"

  # Access the secret version.
  response = client.access_secret_version(request={"name": name})

  # Decode the payload to get the secret string.
  secret_value = response.payload.data.decode("UTF-8")
  return secret_value

有了客户端 ID 和客户端密钥，您现在可以构建工具并配置基于 OAuth 的身份验证。

以下示例使用智能体开发套件 (ADK) 开发的智能体。基于 OAuth 的身份验证已封装到 AuthCredential 和 OAuth2Auth 中，作为工具构建的一部分：

import os
import asyncio

from google.adk.auth.auth_schemes import OpenIdConnectWithConfig
from google.adk.auth.auth_credential import AuthCredential, AuthCredentialTypes, OAuth2Auth
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset
from google.adk.agents.llm_agent import LlmAgent

auth_scheme = OpenIdConnectWithConfig(
  authorization_endpoint="https://your-endpoint.slack.com/oauth2/v1/authorize",
  token_endpoint="https://your-token-endpoint.slack.com/oauth2/v1/token",
  scopes=['openid', 'profile', "email"]
)

auth_credential = AuthCredential(
  auth_type=AuthCredentialTypes.OPEN_ID_CONNECT,
  oauth2=OAuth2Auth(
    client_id=access_secret(project_id='foo', secret_id='slack_oauth_client_id'),
    client_secret=access_secret(project_id='foo', secret_id='slack_oauth_client_secret'),
  )
)

# --- Slack Toolset Configuration Based On OpenAPI Specification ---
with open(os.path.join(os.path.dirname(__file__), 'spec.yaml'), 'r') as f:
   spec_content = f.read()

slack_toolset = OpenAPIToolset(
  spec_str=spec_content,
  spec_str_type='yaml',

  # ** Crucially, associate the authentication scheme and credentials with these tools. **
  # This tells the ADK that the tools require the defined OIDC/OAuth2 flow.
  auth_scheme=auth_scheme,
  auth_credential=auth_credential,
)

# Configure and create the main LLM Agent.

root_agent = LlmAgent(
   model='gemini-2.5-flash',
   name='enterprise_assistant',
   instruction='Help user integrate with Slack and post messages to Slack.',
   tools=[slack_toolset],
)

在运行时，会发生以下情况（如果您通过 ADK Web 在本地使用 ADK，则这些步骤会在 ADK Web 和 ADK 后端中自动完成）：

您访问智能体，智能体决定需要调用工具（例如 Slack）。
ADK 中编程的工具（使用 auth_scheme 和 auth_credential）会向前端返回一个 authConfig 对象（包含重定向 URI 和客户端 ID）。
前端会解析 authConfig 对象，然后您会被重定向到第三方授权页面。登录后，您会被重定向到代理的前端，并且授权代码会发送到 ADK 后端。
后端使用授权代码获取第三方服务的访问令牌，并继续执行该工具。

如果您将 ADK 代理部署到 Vertex AI Agent Engine 运行时，则需要构建自定义前端，并将 ADK-web 身份验证或重定向代码迁移到前端，以执行相同的 OAuth 集成。

使用 API 密钥访问第三方服务

代理身份可让代理能够使用 API 密钥访问第三方服务并代表您执行操作。您首先需要将用于访问第三方服务的 API 密钥存储到 Secret Manager 中，然后从 Secret Manager 中检索这些凭据。

from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset

# Access secret is defined in the code blocks above
WEATHER_DOT_COM_API_KEY = access_secret(project_id='foo', secret_id='weather_dot_com_api_key')

auth_scheme, auth_credential = token_to_scheme_credential(
  "apikey", "query", "apikey", WEATHER_DOT_COM_API_KEY
)

sample_api_toolset = OpenAPIToolset(
  spec_str="...",
  spec_str_type="yaml",
  auth_scheme=auth_scheme,
  auth_credential=auth_credential,
)

记录代理活动

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

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

列出代理及其身份

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

控制台

在 Google Cloud 控制台中，前往 Vertex AI Agent Engine 页面。
前往 Agent Engine

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

REST API

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

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

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

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