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

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

リダイレクト URI の不一致

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

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

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

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

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

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

発行元エンドポイントに関する問題

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

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

401 UNAUTHENTICATED エラー

エージェントを認証できない場合は、次のエラーが発生することがあります。通常、このエラーは、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 など）が Google Cloud プロジェクトで有効になっていないか、API キーの制限によりこのサービスへのアクセスが許可されていない場合に発生します。

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

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

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

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

    [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 キー文字列をコピーし、先頭または末尾に空白が含まれていないことを確認します。

認証情報の取得が拒否されました（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 ユーザー（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 コンソールを開き、[ログ エクスプローラ] ページに移動します。
  2. 一時的なデプロイ コンテナのログ（maps_mcp_agent_tmp...、bigquery_mcp_agent_tmp... など）を検索します。
  3. Python のトレースバックを調べて、構文エラーを特定したり、欠落しているパッケージをトレースしたりします。
  4. requirements.txt ファイルに、必要なパッケージがすべて記載されていることを確認します。

次のステップ