Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

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

認証プロバイダの構成手順については、Agent Identity 認証プロバイダを管理するをご覧ください。

リダイレクト 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 キーの制限によりこのサービスへのアクセスが許可されていない場合に発生します。

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

Google Cloud コンソールで、[API とサービス>ライブラリ] ページに移動し、ターゲット API が有効になっていることを確認します。
[API とサービス] > [ライブラリ] に移動
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 の構文エラー、環境変数の構成ミスが原因で発生します。

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

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

ServiceNow 認証ループまたは予期しないスコープ

エージェントが 3-legged OAuth を使用して ServiceNow に対して認証を行うと、認証フローが失敗したり、エージェントがリクエストループに入ったりする可能性があります。

この問題は、ServiceNow がエージェントによってリクエストされたスコープではなく、アプリケーションレベルで付与されたスコープを判断するために発生します。管理者が ServiceNow アプリケーションで特定のスコープ（useraccount など）を構成すると、エージェントが別のスコープ（mcp_server など）をリクエストした場合でも、ServiceNow は構成されたスコープのみを含むトークンを返します。エージェントがリクエストされたスコープを厳密に想定または検証する場合、受信したトークンを拒否し、ループで認証情報を再リクエストする可能性があります。

この問題を解決するには、次の操作を行います。

管理者として ServiceNow インスタンスにログインします。
ServiceNow の OAuth アプリケーションの構成に移動します。
エージェントに必要なすべてのスコープが、アプリケーションの許可されたスコープのリストに明示的に追加されていることを確認します。
ServiceNow で有効になっているスコープのみをリクエストするようにエージェントを構成します。

詳細については、サポートされているサードパーティサービスをご覧ください。

GitHub または Microsoft の複数スコープエラー

GitHub または Microsoft の認証プロバイダを構成するときに、複数の OAuth スコープをリクエストすると、認証が失敗します。

認証マネージャーは、GitHub と Microsoft の単一スコープ統合をサポートしています。認証マネージャーは、複数のスコープを同時にリクエストすることをサポートしていません。

この問題を解決するには、統合に必要な単一のスコープのみをリクエストするようにエージェントまたは認証プロバイダを構成します。