Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

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

本文說明如何解決使用 Agent Identity 和 Agent Identity 驗證管理工具驗證代理程式時的常見錯誤。

如需設定驗證提供者的操作說明，請參閱「管理 Agent Identity 驗證提供者」。如需在外部服務中驗證 Agent Identity ID 權杖的操作說明，請參閱「使用代理程式自己的身分驗證外部服務」。

重新導向 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_ENABLE_RUNTIME_BOUND_TOKEN": "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 金鑰的限制不允許存取這項服務。

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

在 Google Cloud 控制台中，前往 「APIs & Services」(API 與服務) >「Library」(程式庫) 頁面，並確認已啟用目標 API。
依序前往「API 和服務」>「程式庫」
在 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 中有語法錯誤，或是環境變數設定錯誤。

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

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

ServiceNow 驗證迴圈或非預期範圍

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

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

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

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

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

GitHub 或 Microsoft 多個範圍錯誤

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

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

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

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

OpenID Connect 探索和 JWKS 端點錯誤

外部服務或信賴方可以查詢 Google Cloud安全權杖服務 OpenID Connect 探索 (/.well-known/openid-configuration) 或 JSON Web Key Set (/openid/jwks) 端點，驗證代理程式身分 ID 權杖。查詢這些端點時，要求可能會失敗，並顯示 HTTP 400、404、429 或 500 錯誤。

下表說明這些錯誤的原因和解決方法：

HTTP 狀態	原因	解析度
`400 Bad Request`	如果要求網址中的 workload identity pool 資源名稱無效，或是要求包含 `Authorization` HTTP 標頭，就會發生這項錯誤。	如要解決這項錯誤，請執行下列操作：確認 workload identity pool 資源名稱使用支援的代理程式信任網域格式 (`agents.global.org-ORGANIZATION_ID.system.id.goog` 或 `agents.global.proj-PROJECT_NUMBER.system.id.goog`)。從要求中移除任何 `Authorization` 或 OAuth 標頭。`/.well-known/openid-configuration` 和 `/openid/jwks` 端點是公開且未經驗證的端點；傳遞驗證標頭會導致要求失敗，並顯示 `HTTP 400` 錯誤。
`404 Not Found`	發生這項錯誤的原因是指定的組織 ID、專案編號或 workload identity pool 不存在，或是網址路徑有誤。	如要解決這個錯誤，請確認網址中的機構 ID、專案編號和信任網域 (工作負載身分集區 ID) 正確無誤。並確認網址路徑結尾為 `/.well-known/openid-configuration` 或 `/openid/jwks`。
`429 Too Many Requests`	如果驗證者查詢探索或 JWKS 端點時未快取回應，就會超過要求速率限制，導致發生這個錯誤。	如要解決這個錯誤，請根據 `Cache-Control: public, max-age=86400, must-revalidate` 回應標頭，將驗證器設定為快取探索文件和 JWKS 最多 24 小時。
`500 Internal Server Error`	伺服器在擷取公開簽署金鑰時發生暫時性內部問題，因此出現這個錯誤。	如要解決這項錯誤，請使用快取 JWKS (如有)，或以指數輪詢策略重試要求。

金鑰輪替後，權杖簽章驗證失敗

外部服務驗證代理商身分 ID 權杖時，即使來自同一代理商的先前權杖驗證成功，新核發的權杖可能仍會驗證簽章失敗。

發生這個問題的原因是， Google Cloud 會定期輪替工作負載身分集區的私密和公開簽署金鑰。因此，傳入權杖的 kid (金鑰 ID) 可能不在驗證者的本機金鑰快取中。

如要解決這個問題，請設定驗證器，讓驗證器在收到含有無法辨識 kid 的權杖時，先從 /openid/jwks 端點擷取新的 JWKS，再拒絕權杖。