本页面介绍了如何使用 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标志：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( agent=app, config={ "identity_type": types.IdentityType.AGENT_IDENTITY, "requirements": ["google-cloud-aiplatform[adk,agent_engines]"], "staging_bucket": f"gs://"BUCKET _NAME", }, )其中，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 的权限。
创建 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 资源执行身份验证。
拒绝访问代理
如需拒绝代理访问资源，您可以使用 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 或客户端密钥。
将客户端 ID 或客户端密钥添加到 Secret Manager。
根据代理 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 "gcp-client-secret-1a2b3c4d" # 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
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 的身份验证已封装到 authenticationScheme 和 authCredential 方法中，作为工具构建的一部分：
import os
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.0-flash',
name='enterprise_assistant',
instruction='Help user integrate with Slack and post messages to Slack.',
tools=userinfo_toolset.get_tools(),
)
在运行时，会发生以下情况（如果您通过 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
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 页面。
属于所选项目的已部署代理会显示在列表中。您可以使用过滤字段按指定列过滤列表。
对于每个代理，代理身份都列在身份列下。
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 实例关联的服务代理或服务账号名称。