改用 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) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

啟用 API

啟用 Agent Identity API 後，控制台中的 Agent Registry 頁面會切換至新的 API，以讀取及寫入資源：Google Cloud

  • 您不需要重新建立驗證提供者。新的 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 資源上，將「連結器使用者」(roles/iamconnectors.user) 角色授予代理程式的 SPIFFE ID，請在新版 authProviders/AUTH_PROVIDER_NAME 資源上授予「代理程式身分使用者」 (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 在本機測試代理程式，請將 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/v1alpha。此外，請從傳入的要求中讀取 auth_provider_name，並將其設為 FinalizeCredentials 要求主體中的 auth_provider 欄位。

停用舊版 API

更新 IAM 允許政策並部署代理程式碼後，請確認代理程式會使用新版 API 進行驗證及擷取憑證。

遷移所有有效工作流程後，請在專案中停用舊版服務：

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

後續步驟