排解代理程式身分驗證問題

本文說明如何解決使用 Agent Identity 驗證管理員時的常見錯誤。

如需設定驗證提供者的操作說明，請參閱「管理 Agent Identity 驗證提供者」。

重新導向 URI 不符

如果在 OAuth 流程中收到第三方應用程式的 redirect URI mismatch 錯誤，請確認在第三方開發人員入口網站中註冊的重新導向 URI，與驗證管理工具產生的 URI 完全相符。

如要解決這個問題，請在 Google Cloud 控制台中查看驗證供應商詳細資料，或執行下列 gcloud 指令，找出產生的重新導向 URI：

gcloud alpha agent-identity authProviders describe AUTH_PROVIDER_NAME \
    --location="LOCATION"

缺少使用者角色

如果代理程式無法使用驗證供應商，請確認代理程式身分在驗證供應商資源上具有 roles/agentidentity.user 角色。

如要解決這個問題，請使用 Google Cloud 控制台授予角色，或執行 add-iam-policy-binding 指令。

發卡機構端點問題

如果是 OIDC 供應商，請確認發行者端點可公開存取，且支援 .well-known/openid-configuration 探索文件。

如果 Google Cloud 無法擷取 OIDC 中繼資料或 JWKS，請確認端點是否位於防火牆或受限網路後方。

401 UNAUTHENTICATED 錯誤

如果服務專員無法通過驗證，可能會發生下列錯誤。這項錯誤通常是由 Google 管理的情境感知存取權政策所致，該政策會強制執行 mTLS 繫結和 DPoP 加密證明：

{
  "error": {
    "code": 401,
    "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
    "status": "UNAUTHENTICATED"
  }
}

如要解決這項錯誤，您可以選擇退出預設情境感知存取權政策，前提是您有特定的權杖共用需求，或是必須直接在標頭中插入權杖。如要停用，請在部署代理程式時設定下列環境變數：

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

API 金鑰服務已封鎖 (API_KEY_SERVICE_BLOCKED)

驗證 API 金鑰時，可能會發生下列錯誤。這項錯誤表示服務遭到封鎖：

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_SERVICE_BLOCKED",
    "domain": "googleapis.com",
    "metadata": {
      "methodName": "google.cloud.translate.v2.TranslateService.TranslateText",
      "service": "translate.googleapis.com",
      "consumer": "projects/PROJECT_NUMBER",
      "apiName": "translate"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "Requests to this API translate method google.cloud.translate.v2.TranslateService.TranslateText are blocked."
  }
]

發生這項錯誤的原因是目標 API 服務 (例如 Cloud Translation API) 尚未在 Google Cloud 專案中啟用，或是 API 金鑰的限制不允許存取這項服務。

如要解決這項錯誤，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中，前往「APIs & Services」(API 和服務)>「Library」(程式庫) 頁面，並確認已啟用目標 API。

    依序前往「APIs & Services」(API 和服務) >「Library」(程式庫)

  2. 在 Google Cloud 控制台中，前往「APIs & Services」(API 和服務) >「Credentials」(憑證) 頁面，編輯 API 金鑰，並確認 API 限制允許存取服務。

    依序前往「APIs & Services」(API 和服務)>「Credentials」(憑證)

API 金鑰無效 (API_KEY_INVALID)

向第三方服務傳送要求時，可能會發生下列錯誤。這項錯誤表示 API 金鑰無效：

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_INVALID",
    "domain": "googleapis.com",
    "metadata": {
      "service": "translate.googleapis.com"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "API key not valid. Please pass a valid API key."
  }
]

這個錯誤是因為要求標頭中傳遞的 API 金鑰字串不正確、格式錯誤，或不存在於專案憑證中。

如要解決這個錯誤，請確認您已從 Google Cloud 控制台的「憑證」頁面複製正確的 API 金鑰字串，且未包含開頭或結尾的空白字元。

無法擷取憑證，權限遭拒 (agentidentity.authProviders.retrieveCredentials)

在本機執行 adk web 或與已部署的代理程式互動時，可能會發生下列 403 Forbidden 錯誤：

google.api_core.exceptions.Forbidden: 403 POST https://agentidentitycredentials.mtls.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME/credentials:retrieve?%24alt=json%3Benum-encoding%3Dint: Permission 'agentidentity.authProviders.retrieveCredentials' denied on resource '//agentidentity.googleapis.com/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME' (or it may not exist).

發生這個錯誤的原因是，嘗試叫用驗證提供者的主體沒有擷取憑證所需的 IAM 權限。

如要解決這項錯誤，請將「Agent Identity User」(代理程式身分使用者) (roles/agentidentity.user) 角色授予主體：

  • 如果在本機開發期間 (uv run adk web 或 uvicorn) 發生這個錯誤，請確認您已將角色授予個人使用者帳戶 (user:USER_EMAIL)。
  • 如果在與已部署的代理程式互動時發生這項錯誤，請確認您已將角色授予代理程式的 SPIFFE ID 主體 (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID)。

一般部署作業失敗

使用 uv run adk deploy 部署代理程式時，指令可能會失敗並顯示一般錯誤訊息。

發生這個錯誤的原因是缺少 Python 依附元件、agent.py 中有語法錯誤，或是環境變數設定錯誤。

如要解決這項錯誤，請按照下列步驟操作：

  1. 開啟 Google Cloud 控制台，然後前往「Logs Explorer」頁面。
  2. 搜尋臨時部署容器記錄 (例如 maps_mcp_agent_tmp... 或 bigquery_mcp_agent_tmp...)。
  3. 檢查 Python 回溯，找出語法錯誤或追蹤缺少的套件。
  4. 確認 requirements.txt 檔案中列出所有必要套件。

ServiceNow 驗證迴圈或非預期範圍

如果服務專員使用三足式 OAuth 向 ServiceNow 進行驗證，驗證流程可能會失敗，或服務專員可能會進入要求迴圈。

發生這個問題的原因是，ServiceNow 是在應用程式層級決定授予的範圍，而不是根據代理程式要求的範圍。如果管理員在 ServiceNow 應用程式上設定特定範圍 (例如 useraccount)，即使代理程式要求不同的範圍 (例如 mcp_server)，ServiceNow 傳回的權杖也只會包含這些設定的範圍。如果代理程式嚴格預期或驗證要求的範圍，就會拒絕收到的權杖，並可能在迴圈中重新要求憑證。

如要解決這個問題，請按照下列步驟操作：

  1. 以管理員身分登入 ServiceNow 執行個體。
  2. 前往 ServiceNow OAuth 應用程式設定。
  3. 請確保代理程式所需的所有範圍都已明確加入應用程式的允許範圍清單。
  4. 將代理程式設為只要求在 ServiceNow 中啟用的範圍。

詳情請參閱「支援的第三方服務」。

GitHub 或 Microsoft 多個範圍錯誤

為 GitHub 或 Microsoft 設定驗證供應器時，如果要求多個 OAuth 範圍，驗證就會失敗。

驗證管理員支援 GitHub 和 Microsoft 的單一範圍整合。驗證管理工具不支援同時要求多個範圍。

如要解決這個問題，請將代理程式或驗證供應商設定為只要求整合所需的單一範圍。

詳情請參閱「支援的第三方服務」。

後續步驟