迁移到 Agent Identity API

本文档将介绍如何将已部署的代理和身份验证提供程序从旧版 IAM Connectors API (iamconnectors.googleapis.com) 迁移到新的 Agent Identity API (agentidentity.googleapis.com)。

在预览版迁移期间，这两个 API 会并行运行，让您能够迁移工作负载，而不会中断现有的代理对话。

迁移工作流包括以下任务：

  1. 启用 Agent Identity API
  2. 更新 IAM 允许政策
  3. 更新代理代码和 SDK
  4. 停用旧版 API

启用 Agent Identity API

如需开始迁移，请在项目中启用新的 Agent Identity API。

启用 Agent Identity API（如果尚未启用）。

启用 API 所需的角色

如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获取此权限。 了解如何授予角色。

启用 API

启用 Agent Identity API 后，Google Cloud 控制台中的“代理注册表”页面会切换到新 API 来读取和写入资源：

  • 您无需重新创建身份验证提供方。新 API 将每个旧版身份验证提供方（例如 projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME）镜像为 authProviders 资源 (projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME)。

  • 使用 Google Cloud 控制台或 gcloud CLI 新创建的身份验证提供方会显示为 authProviders/ 资源，并且在旧版 API 中不可见。

  • 在迁移期间，使用旧版 connectors/ 字符串的有效代理会继续工作。

更新 IAM 允许政策

向镜像的身份验证提供方资源授予新的 IAM 角色，以便代理可以从新的 API 端点检索凭据。

例如，如果您在旧版 connectors/AUTH_PROVIDER_NAME 资源上向代理的 SPIFFE ID 授予了 Connector User (roles/iamconnectors.user) 角色，请在新版 authProviders/AUTH_PROVIDER_NAME 资源上授予 Agent Identity User (roles/agentidentity.user) 角色：

gcloud agent-identity auth-providers add-iam-policy-binding \
    AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

如果您使用 adk web 在本地测试代理，请向您的个人用户账号 (user:USER_EMAIL) 授予 roles/agentidentity.user。

更新代理代码和 SDK

更新代理代码，以引用新的 authProviders/ 资源层次结构和端点：

  1. 将代理代码中的 ADK 版本更新为 2.3.0 或更高版本。

  2. 在您的代理代码（例如 agent.py）中，将 GcpAuthProviderScheme 资源字符串中的 connectors/ 替换为 authProviders/。

    旧版配置： 

    auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME"
)

    新配置： 

    auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

  3. 仅限三方模式 OAuth：如果您的代理直接调用 REST API，请将端点主机名从 iamconnectorcredentials.googleapis.com 更新为 agentidentitycredentials.googleapis.com，并将请求路径中的 connectors/ 替换为 authProviders/。

  4. 仅限三方模式 OAuth：在前端验证服务器（例如 main.py）中，将 FinalizeCredentials 端点网址更新为 https://agentidentitycredentials.googleapis.com/v1。此外，从传入请求中读取 auth_provider_name，并将其设置为 FinalizeCredentials 请求正文中的 auth_provider 字段。

停用旧版 API

更新 IAM 允许政策并部署代理代码后，请验证您的代理是否使用新 API 进行身份验证并检索凭据。

迁移所有有效工作流后，请在项目中停用旧版服务：

gcloud services disable iamconnectors.googleapis.com \
    --project="PROJECT_ID"

后续步骤