改用 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 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「Service Usage 管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

啟用 API

啟用 Agent Identity API 後，Google Cloud 控制台中的「Agent Registry」頁面會切換至新的 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 或 REST API 建立的驗證提供者會顯示為authProviders/資源，且不會顯示在舊版 API 中。

  • 在遷移期間，使用舊版 connectors/ 字串的有效代理會繼續運作。

更新 IAM 允許政策

授予鏡像驗證提供者資源新的 IAM 角色，讓代理能從新的 API 端點擷取憑證。

舉例來說，如果您在舊版 connectors/AUTH_PROVIDER_NAME 資源上，將連接器使用者 (roles/iamconnectors.user) 角色授予代理的 SPIFFE ID，請在新版 authProviders/AUTH_PROVIDER_NAME 資源上授予代理身分使用者 (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 在本機測試代理，請將 roles/agentidentity.user 授予個人使用者帳戶 (user:USER_EMAIL)。

更新代理程式碼和 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"

後續步驟