Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

重新導向 URI 不符

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

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

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

缺少使用者角色

如果代理程式無法使用驗證供應商，請確認代理程式身分在驗證供應商資源上具有 roles/iamconnectors.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 金鑰的限制不允許存取這項服務。

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

在 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 金鑰字串，且未包含開頭或結尾的空白字元。

無法擷取憑證，權限遭拒 (`iamconnectors.connectors.retrieveCredentials`)

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

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

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

如要解決這項錯誤，請將「連結器使用者」 (roles/iamconnectors.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 中有語法錯誤，或是環境變數設定錯誤。