迁移到 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 权限。如果您 创建了项目，则可能已通过 所有者角色 (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 alpha agent-identity authProviders 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/v1alpha。此外，请从传入请求中读取 auth_provider_name，并将其设置为 auth_provider请求正文中的FinalizeCredentials字段。

停用旧版 API

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

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

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

后续步骤