エージェント ID の認証に関する問題のトラブルシューティング

このドキュメントでは、認証マネージャーを使用したエージェント ID による認証で発生する一般的な エラーを解決する方法について説明します。

リダイレクト URI の不一致

OAuth フロー中にサードパーティ アプリケーションから redirect URI mismatch エラーが表示された場合は、サードパーティ デベロッパー ポータルに登録されているリダイレクト URI が、認証マネージャーによって生成された URI と完全に一致していることを確認してください。

この問題を解決するには、 コンソールで認証プロバイダ の詳細を表示して生成されたリダイレクト URI を確認するか、次の gcloud コマンドを実行します。 Google Cloud 

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

ユーザーロールが割り当てられていない

エージェントが認証プロバイダを使用できない場合は、エージェント ID に認証プロバイダ リソースに対する roles/iamconnectors.user ロールが付与されていることを確認します。

この問題を解決するには、 Google Cloud コンソールを使用してロールを付与するか、add-iam-policy-binding コマンドを実行します。

発行元エンドポイントの問題

OIDC プロバイダの場合は、発行元エンドポイントが一般公開されており、.well-known/openid-configuration 検出ドキュメントをサポートしていることを確認します。

が OIDC メタデータまたは JWKS を取得できない場合は、 エンドポイントがファイアウォールまたは制限付きネットワークの背後にないことを確認します。 Google Cloud

401「未認証」エラー

エージェントが認証できない場合は、次のエラーが発生することがあります。このエラーは通常、mTLS バインディングと DPoP 暗号証明を適用する Google マネージド コンテキストアウェア アクセス ポリシーが原因で発生します。

{
  "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 など）が プロジェクトで有効になっていないか、API キーの制限によりこのサービスへのアクセスが許可されていないために発生します。 Google Cloud

このエラーを解決するには、次の操作を行います。

  1. コンソールで、[API とサービス]>[ライブラリ] ページに移動し、ターゲット API が有効になっていることを確認します。 Google Cloud

    API とサービス>ライブラリに移動

  2. コンソールで、[API とサービス]>[認証情報] ページに移動し、API キーを編集して、API の制限でサービスへのアクセスが許可されていることを確認します。 Google Cloud

    API とサービス >認証情報に移動

無効な 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 に構文エラーがある、環境変数が正しく構成されていないことが原因で発生します。

このエラーを解決するには、次の手順を行います。

  1. Google Cloud コンソールを開き、[ログ エクスプローラ] ページに移動します。
  2. 一時的なデプロイ コンテナのログ（maps_mcp_agent_tmp... や bigquery_mcp_agent_tmp... など）を検索します。
  3. Python のトレースバックを確認して、構文エラーを特定するか、不足しているパッケージをトレースします。
  4. 必要なパッケージがすべて requirements.txt ファイルにリストされていることを確認します。

次のステップ