不同的访问模式有不同的身份验证方法：
| 使用场景 | 身份验证方法 | 此身份验证方法简介 |
|---|---|---|
| 直接从代理中访问数据源。 | 服务账号 | 已部署的代理可以访问其服务账号有权访问的所有资源。 |
| 在代理中，使用 API 密钥向端点发送请求。 | API 密钥 | 在使用此身份验证方法之前，请确定您要使用的 API 支持 API 密钥。 |
| 处理代理最终用户的用户账号、注册、登录或授权。 | OAuth 客户端 ID | 要求代理向用户请求并获得用户同意。 |
角色
您在 Vertex AI Agent Engine 上部署的代理使用 AI Platform Reasoning Engine Service Agent 或您的自定义服务账号运行。如需了解详情，请参阅为代理设置身份和权限。
AI Platform Reasoning Engine Service Agent
AI Platform Reasoning Engine Service Agent 服务账号采用 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 格式。
该服务账号具有 Vertex AI Reasoning Engine Service Agent 角色 (roles/aiplatform.reasoningEngineServiceAgent)，该角色可授予部署的代理所需的默认权限。您可以在 IAM 文档中查看默认权限的完整列表。
列出已部署代理的角色
控制台
gcloud
首先，安装并初始化 gcloud CLI。然后运行以下命令：
gcloud projects get-iam-policy PROJECT_ID_OR_NUMBER \
--flatten="bindings[].members" \
--filter="bindings.members:serviceAccount:PRINCIPAL" \
--format="value(bindings.role)"其中
PROJECT_ID_OR_NUMBER是您的项目 ID 或编号，PRINCIPAL基于将代理部署到 Vertex AI Agent Engine 时所用的服务账号。
Python
首先，运行以下命令来安装客户端库
pip install google-api-python-client然后进行身份验证，并运行以下命令以列出已部署代理的角色：
from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2
project_id = "PROJECT_ID"
principal = "PRINCIPAL"
crm_service = resourcemanager_v3.ProjectsClient()
policy = crm_service.get_iam_policy(iam_policy_pb2.GetIamPolicyRequest(
resource=f"projects/{project_id}"
))
for binding in policy.bindings:
for member in binding.members:
if principal in member:
print(binding.role)
其中，PRINCIPAL 基于在 Vertex AI Agent Engine 上部署代理时使用的服务账号。
为已部署的代理授予角色
控制台（推荐）
gcloud
首先，安装并初始化 gcloud CLI。然后运行以下命令：
gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME其中
Python
我们不建议您编写自己的 Python 代码来为已部署的代理授予或撤消角色。我们建议您使用 Google Cloud 控制台或 gcloud 进行一次性操作，或使用 Terraform 以编程方式管理 IAM 访问权限控制。如果您希望或需要使用 Python 执行此操作，请参阅 IAM 客户端库的文档。
撤消已部署代理的角色
控制台（推荐）
gcloud
首先，安装并初始化 gcloud CLI。然后运行以下命令：
gcloud projects remove-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME其中
Python
我们不建议您自行编写 Python 代码来为已部署的代理授予或撤消角色。我们建议您使用 Google Cloud 控制台或 gcloud 进行一次性操作，或使用 Terraform 以编程方式管理 IAM 访问权限控制。如果您希望或需要使用 Python 执行此操作，请参阅 IAM 客户端库的文档。
Secret
密文包含一个或多个密文版本，以及标签和复制信息等元数据。密文的实际载荷存储在密文版本中。Secret 在项目级层进行管理（通过 Secret Manager），并且可以在已部署的代理之间共享。如需列出 Secret Manager 中与代理对应的 Secret，您可以添加标签并使用这些标签进行过滤。
创建 Secret
控制台
前往 Secret Manager 页面。
在 Secret Manager 页面上，点击创建密钥。
在名称字段中，输入密文的名称（例如
my-secret）。可选：如需在创建初始密文时也添加密文版本，请在密文值字段中输入密文的值（例如
abcd1234）。前往标签，然后点击添加标签。
输入键及其对应的值以创建标签。
点击创建密钥。
gcloud
首先，安装并初始化 gcloud CLI。然后运行以下命令：
gcloud secrets create SECRET_ID --replication-policy="automatic"gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"
其中
SECRET_ID是相应 Secret 的 ID 或完全限定标识符。FILE_PATH是包含版本详细信息的文件（包括文件名）的完整路径。
如需了解详情，请参阅 Secret Manager 文档，了解如何创建 Secret 和 Secret 版本；或者参阅 CLI 参考文档，了解如何创建 Secret 和 Secret 版本。
Python
首先，运行以下命令来安装客户端库
pip install google-cloud-secret-manager然后进行身份验证，并运行以下命令
from google.cloud import secretmanager
import google_crc32c
client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
"parent": "projects/PROJECT_ID",
"secret_id": "SECRET_ID",
"secret": { # google.cloud.secretmanager_v1.types.Secret
# Required. The replication policy cannot be changed after the Secret has been created.
"replication": {"automatic": {}},
# Optional. Labels to associate with the secret.
"labels": {"type": "api_key", "provider": "anthropic"},
# Optional. The secret's time-to-live in seconds with format (e.g.,
# "900s" for 15 minutes). If specified, the secret versions will be
# automatically deleted upon reaching the end of the TTL period.
"ttl": "TTL",
},
})
anthropic_api_key = "API_KEY" # The secret to be stored.
payload_bytes = anthropic_api_key.encode("UTF-8")
# Optional. Calculate payload checksum.
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)
version = client.add_secret_version(request={
"parent": secret.name,
"payload": {
"data": payload_bytes,
"data_crc32c": int(crc32c.hexdigest(), 16), # Optional.
},
})
print(f"Added secret version: {version.name}")
获取密钥
控制台
前往 Secret Manager 页面。
在 Secret Manager 页面上，点击要描述的 Secret 的名称。
Secret 详细信息页面列出了有关 Secret 的信息。
gcloud
首先，安装并初始化 gcloud CLI。然后运行以下命令：
gcloud secrets versions describe VERSION_ID --secret=SECRET_ID其中
VERSION_ID是相应 Secret 版本的 ID，SECRET_ID是相应 Secret 的 ID 或完全限定标识符。
如需了解详情，请访问 Secret Manager 文档或 CLI 参考文档。
Python
首先，运行以下命令来安装客户端库
pip install google-cloud-secret-manager然后进行身份验证，并运行以下命令
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.get_secret(request={"name": name})
列出 Secret
控制台
前往 Secret Manager 页面。
在“密钥”表格中，点击过滤条件字段。
选择过滤条件属性及其对应的值，例如
Location:asia-east1。系统会根据输入的值自动过滤表格。
（可选）如需过滤 Secret 版本：选择一个 Secret 以访问其版本，然后使用版本表中的过滤条件选项。
gcloud
如需列出项目的所有密文，请运行以下命令：
gcloud secrets list --filter="FILTER"其中，FILTER 是字符串（例如 name:asecret OR name:bsecret）或正则表达式（例如 name ~ "secret_ab.*"）。
如需列出某个 Secret 的所有版本，请运行以下命令：
gcloud secrets versions list SECRET_ID其中，SECRET_ID 是相应 Secret 的 ID 或完全限定标识符。
如需了解详情，请参阅 Secret Manager 文档，了解如何过滤 secret 和列出 secret 版本，或参阅 CLI 参考文档，了解如何列出 secret 和密文版本。
Python
首先，运行以下命令来安装客户端库
pip install google-cloud-secret-manager然后进行身份验证，并运行以下命令
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
for secret in client.list_secrets(request={
"parent": "projects/PROJECT_ID",
"filter": "FILTER", # e.g. "labels.provider=anthropic"
}):
print(f"Found secret: {secret.name}")
更新密钥
控制台
前往 Secret Manager 页面。
在 Secret Manager 页面上，点击 Secret 名称旁边的复选框。
如果信息面板已关闭，请点击显示信息面板以显示信息。
在信息面板中，选择标签标签页。
点击添加标签，然后输入标签的键和值。
点击保存。
gcloud
首先，安装并初始化 gcloud CLI。然后运行以下命令：
gcloud secrets update SECRET_ID --update-labels=KEY=VALUE其中
SECRET_ID是相应 Secret 的 ID 或完全限定标识符，KEY是标签键，VALUE是相应标签的值。
如需了解详情，请参阅 Secret Manager 文档或 CLI 参考文档。
Python
首先，运行以下命令来安装客户端库
pip install google-cloud-secret-manager然后进行身份验证，并运行以下命令
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.update_secret(request={
"secret": {
"name": name,
"labels": {"type": "api_key", "provider": "anthropic"}, # updated labels
},
"update_mask": {"paths": ["labels"]},
})
print(f"Updated secret: {response.name}")
删除密钥
控制台
前往 Secret Manager 页面。
在 Secret Manager 页面上的操作列中，点击查看更多。
在菜单中选择删除。
在删除密文对话框中，输入密文的名称。
点击删除密文按钮。
gcloud
如需删除 Secret 版本，请运行以下命令：
gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID其中
VERSION_ID是相应 Secret 版本的资源名称，SECRET_ID是相应 Secret 的 ID 或完全限定标识符。
如需删除某个密文及其所有版本，请运行以下命令：
gcloud secrets delete SECRET_ID其中，SECRET_ID 是相应 Secret 的 ID 或完全限定标识符
如需了解详情，请参阅 Secret Manager 文档，了解如何删除 Secret 和销毁 Secret 版本，或参阅 CLI 参考文档，了解如何删除 Secret 和销毁 Secret 版本。
Python
首先，运行以下命令来安装客户端库
pip install google-cloud-secret-manager然后进行身份验证，并运行以下命令
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
client.delete_secret(request={"name": name})
OAuth 客户端和凭据
客户端 ID 用于向 Google 的 OAuth 服务器标识单个代理。如果您的代理在多个平台上运行，那么每个平台都需要有自己的客户端 ID。概括来讲，如需集成基于 OAuth 的代理，您需要执行以下操作：
创建 OAuth 客户端凭据
在 Google Cloud 控制台中，前往 Google Auth Platform > 客户端页面。
（如果需要）如果屏幕显示“Google Auth Platform not configured yet”（尚未配置 Google Auth Platform），请点击 Get Started（开始使用），然后填写项目配置。（以后可以更新这些信息。）如需详细了解生产环境就绪情况，请访问 OAuth 2.0 政策合规性。
点击创建客户端。
将应用类型设置为
Web application。将 OAuth 客户端的名称设置为
OAUTH_CLIENT_DISPLAY_NAME。在已获授权的重定向 URI 下，添加
REDIRECT_URI的 URI。在“客户端密钥”下，点击“下载 JSON”按钮。系统将下载一个包含以下内容的
client_secret.json文件：
{'web': {
'client_id': "CLIENT_ID",
'client_secret': "CLIENT_SECRET",
'project_id': "PROJECT_ID",
'redirect_uris': [REDIRECT_URIs],
'auth_uri': 'https://accounts.google.com/o/oauth2/auth',
'token_uri': 'https://www.googleapis.com/oauth2/v3/token',
'auth_provider_x509_cert_url': 'https://www.googleapis.com/oauth2/v1/certs',
'javascript_origins': "JAVASCRIPT_ORIGINS", # Optional.
}}
- 将客户端 ID 和密钥存储在 Secret Manager 中，例如：
from google.cloud import secretmanager
import google_crc32c
import json
client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
"parent": "projects/PROJECT_ID",
"secret_id": "OAUTH_SECRET_ID", # e.g. "oauth-client-demo"
"secret": {
"labels": {"type": "oauth_client"},
"replication": {"automatic": {}},
},
})
payload_bytes = json.dumps(cred).encode("UTF-8")
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)
client.add_secret_version(request={
"parent": secret.name,
"payload": {
"data": payload_bytes,
"data_crc32c": int(crc32c.hexdigest(), 16),
},
})
列出 OAuth 客户端
在 Google Cloud 控制台中，前往 Google Auth Platform > 客户端页面。
系统会列出您拥有的 OAuth 客户端凭据。
删除 OAuth 客户端
在 Google Cloud 控制台中，前往 Google Auth Platform > 客户端页面。
选择要删除的 OAuth 客户端凭据，然后点击“删除”。
客户管理的加密密钥 (CMEK)
默认情况下， Google Cloud 会使用 Google 管理的加密密钥自动加密静态数据。如果您对保护数据的密钥有特定的合规性或监管要求，则可以将客户管理的加密密钥 (CMEK) 用于已部署的代理。
如需了解有关将 CMEK 与 Vertex AI 搭配使用的常规要求和指南，请参阅 Vertex AI 的 CMEK 文档，其中包含以下信息：
- 项目设置（结算和已启用的 API）
- 创建密钥环和密钥
- 所需的权限授予
如需为代理启用 CMEK，您需要在创建 Agent Engine 实例时指定 encryption_spec 并提供 Cloud KMS 密钥。如需查看代码示例，请参阅配置客户管理的加密密钥。
限制
将 CMEK 与 Vertex AI Agent Engine 搭配使用时，存在以下限制：
不允许使用多区域密钥：仅支持单区域密钥。密钥环和密钥的区域必须与 Agent Engine 实例的区域相同。
已部署的 CMEK 实例无法更新：如果代理部署时使用了 CMEK 密钥，则该部署的实例无法更新或更改。如需使用其他 Agent Engine 规范（用于新密钥或其他配置），您必须部署新的 Agent Engine 实例。
某些元数据和运营数据未加密：CMEK 会加密代理的静态核心数据。不过，某些元数据和运行时操作数据不会加密。其中包括：
- 客服人员元数据：
- 显示名
- 说明
- 运行时运营数据：
- 服务账号电子邮件地址
- 代理对象类方法名称
- 环境变量
- 客服人员元数据：