このガイドは、Gemini Enterprise Agent Platform の接続に関する問題のデバッグとトラブルシューティングに役立ちます。特に、Agent Gateway、エージェント ID、Identity and Access Management（IAM）ポリシー、Service Extensions を使用した委任認証を使用する場合に役立ちます。
Agent Platform Troubleshooting スキルを使用したトラブルシューティング
AI コーディング支援アシスタントとインタラクティブに接続性、認可、起動の問題を診断するには、 Cloud de Confiance by S3NS エージェント スキル リポジトリから agent-platform-troubleshooting スキルをインストールします。
このスキルにより、AI エージェントは、次のようなエージェント プラットフォーム スタック全体にわたるドメイン固有の診断プレイブック、ログフィルタ、解決手順を利用できるようになります。
- エージェント ゲートウェイの下り（外向き）拒否: ゲートウェイでインターセプトされた
403 Forbiddenエラーを診断し、IAP 認証の決定を検証します。 - Agent Runtime の起動の失敗: 欠落しているロール（
roles/browserやresourcemanager.projects.getなど）とブートストラップ例外を特定します。 - Agent Registry の宛先の問題: サービス エントリ、エンドポイント インターフェース、統合された Google API 構成を確認します。
- IAM アクセス ポリシー: 統合アクセス ポリシー（UAP）バインディング、条件式、プリンシパル アクセス境界（PAB）のスコープを検証します。
- コンテナの信頼: カスタム コンテナ（BYOC）またはプライベート認証局（CA）の TLS 証明書とハンドシェイク エラーを診断します。
エージェント環境にスキルをインストールするには、次のコマンドを実行します。
npx skills add https://github.com/google/skills --skill agent-platform-troubleshooting
下り（外向き）リクエスト フロー
Agent Platform は、すべての送信トラフィックに default-deny ポリシーを採用しています。エージェントが外部リソースに接続するには、ネットワーク レイヤと ID レイヤのそれぞれでアクセスを明示的に許可する必要があります。Agent Gateway が有効になっている場合、ゲートウェイはエージェントからのすべてのリクエストをインターセプトし、構成されたポリシーを適用します。
リクエストが成功するには、次の条件をすべて満たしている必要があります。
- IAM アクセス ポリシー: エージェントに割り当てられたエージェント ID に、宛先リソースに対する
iap.resources.egressViaIAP権限を直接またはプリンシパル セットを介して付与する必要があります。詳細については、IAM エージェント ポリシーを作成するをご覧ください。IAP ポリシーのトラブルシューティング方法を確認する。 - エージェント レジストリ: きめ細かいリソース単位のアクセス ポリシーとツールレベルの制御を適用するには、エージェント レジストリに宛先を登録することをおすすめします。エージェントが登録されていない宛先にアクセスしようとしている場合は、登録されていないエンドポイントのポリシーを構成して、エージェント ID に
iap.resources.egressViaIAP権限を付与する必要があります。 - Agent Gateway: ゲートウェイは、明示的にターゲットとする認可ポリシーに関連付けられている必要があります。デフォルトでは、ゲートウェイは IAP と Model Armor を使用してリクエストを保護します。
- Service Extensions を使用した委任認可: Service Extensions を使用して、認可の決定をカスタム認可エンジンに委任できます。構成された認可ポリシーに応じて、これらの認可エンジンの 1 つ以上がリクエストを許可または拒否します。
一般的な問題
Agent Gateway のトラブルシューティングを行う際は、これらの一般的な問題とその解決策を確認してください。
エージェント ランタイムの起動中のエラー
Agent Runtime インスタンスの起動またはデプロイに失敗した場合は、IAP が内部トラフィックをブロックしているか、エージェントに初期化に必要な基本ロールがない可能性があります。
IAP が内部サービスへの呼び出しをブロックしていないことを確認する
症状: 起動中に
403 Forbiddenエラーが発生する。原因: Agent Gateway は、すべてのトラフィックにデフォルト拒否ポリシーを使用します。したがって、IAP が自動適用モードの場合、内部サービス（
aiplatformやloggingなど）が登録されておらず、エージェントに必要な IAM 権限がない限り、内部サービスへの呼び出しもブロックされます。修正: IAP をドライラン モードに一時的に切り替えて、起動をブロックせずにどの接続が失敗しているかを確認するか、Cloud Logging をクエリしてブロックされているホスト名を特定します。ターゲット サービス ホスト名を特定したら、Agent Registry に登録し、エージェントに
iap.resources.egressViaIAP権限を付与します。Cloud Logging を使用してブロックされた特定のホスト名を見つけるには、ログ エクスプローラで次のクエリを実行します。
resource.type="networkservices.googleapis.com/Gateway" resource.labels.gateway_type="SECURE_WEB_GATEWAY" httpRequest.status=403
結果の
httpRequest.requestUrlフィールドまたはjsonPayload.authzPolicyInfoフィールドを調べて、宛先ホスト名を見つけます。起動時に登録が必要になる一般的な内部サービスには、次のようなものがあります。
- Agent Platform（推論エンジンとセッション）:
https://REGION-aiplatform.mtls.googleapis.com - Resource Manager:
https://cloudresourcemanager.mtls.googleapis.com、https://cloudresourcemanager.mtls.googleapis.com/ - Google Cloud Observability（有効な場合）:
https://telemetry.mtls.googleapis.com/ - Cloud Logging（有効な場合）:
https://logging.googleapis.com/ - Cloud Monitoring:
https://monitoring.googleapis.com/とhttps://monitoring.mtls.googleapis.com/ - Cloud Trace:
https://cloudtrace.googleapis.com/とhttps://cloudtrace.mtls.googleapis.com/ - Secret Manager:
https://secretmanager.googleapis.com/、https://secretmanager.mtls.googleapis.com/
- Agent Platform（推論エンジンとセッション）:
エージェント ID に必要な基本ロールがあることを確認する
症状:
aiplatform.googleapis.com/reasoning_engine_stderrログに、google.api_core.exceptions.Unknown: NoneやFailed to convert project number to project IDなどのエラーが表示されます。このエラーは、推論エンジンの起動時に表示されます。原因。エージェント ID に、初期化中にプロジェクト名を解決するために必要な
resourcemanager.projects.get権限がありません。修正。エージェント ID（またはそのプリンシパル セット）に、独自のランタイム構成を読み取るために必要な権限があることを確認します。次のロールが必要です。
roles/aiplatform.agentDefaultAccess: デフォルトのエージェント ロール。roles/aiplatform.user: エージェントの実行に必要です。roles/agentregistry.viewer: 登録済みリソースを表示するために必要です。roles/logging.logWriter、roles/monitoring.metricWriter: 可観測性で必要。roles/browser: SDK の初期化中にresourcemanager.projects.getを実行するために必要です。
エージェント ID に割り当てられたロールを確認するには、次のコマンドを実行します。
gcloud projects get-iam-policy PROJECT_ID \ --flatten="bindings[].members" \ --filter="bindings.members:AGENT_IDENTITY_PRINCIPAL"
次のように置き換えます。
PROJECT_ID: 実際の Cloud de Confiance プロジェクト ID。AGENT_IDENTITY_PRINCIPAL: エージェント ID プリンシパル。principal://TRUST_DOMAIN/resources/SERVICE/RESOURCE_PATHの形式を使用します。
ロールを付与する方法については、Agent Runtime で Agent Identity を使用するをご覧ください。
エラー 403 Forbidden 件
403 Forbidden エラーが発生した場合は、Agent Gateway の下り（外向き）に関連していることを確認します。下り（外向き）エラー メッセージの例を次に示します。
{"code": 403, "message": "403 Forbidden. {'message': 'Egress request is not authorized.', 'status': 'Forbidden'}"}
Logging でエージェント ログをクエリして、失敗した特定の呼び出しを見つけます。
resource.type="aiplatform.googleapis.com/ReasoningEngine" resource.labels.location="LOCATION" resource.labels.reasoning_engine_id="AGENT_ID" textPayload:"403"
次のように置き換えます。
LOCATION: エージェントがデプロイされているリージョン（us-central1など）。AGENT_ID: エージェント（Reasoning Engine）の ID。
ログエントリの textPayload で Egress request is not authorized メッセージを探します。403 エラーに異なるテキストが含まれている場合は、Agent Gateway ではなく、宛先サービスが呼び出しを直接拒否している可能性があります。
組み込みのオブザーバビリティ ダッシュボードを使用して、403 拒否などの下り（外向き）トラフィック ログを表示することもできます。
自己署名またはプライベート CA の宛先が接続に失敗する
- 現象: エージェントが、自己署名証明書またはプライベート CA 発行の証明書を提示する宛先に接続できない。
- 原因: デフォルトでは、Agent Gateway は公的に信頼できる CA によって発行された証明書のみを信頼します。プライベート CA または自己署名証明書を使用する宛先に接続するには、追加の構成が必要です。
- 軽減策: プライベート CA または自己署名証明書を使用して宛先に接続するには、エージェント接続テンプレートの
tlsConfig設定を使用してカスタム TLS 信頼アンカーを構成する必要があります。
カスタム コンテナ（BYOC）でデプロイされたエージェントが Agent Gateway に接続できない
- 症状: BYOC エージェントが Agent Gateway 経由でルーティングされると、接続を確立できません。ログに TLS handshake または証明書検証エラーが表示されることがあります。
- 原因: エージェントのカスタム コンテナが、エージェント ゲートウェイの認証局を信頼していません。
- 修正: エージェント ゲートウェイのルート証明書がコンテナの CA ストアに追加されていることを確認します。Agent Gateway 用のカスタム コンテナ（BYOC）エージェントを構成するをご覧ください。
ポリシー バインディングが失敗するか、ガバナンス拒否を模倣する
- 症状: ポリシー バインディングの構成が失敗する。ポリシーをバインドするときに
etagの入力を求められる。リクエストが失敗し、ガバナンスの拒否エラー（「unregistered destination correctly rejected」など）が返される。 - 原因: プロジェクトで Identity-Aware Proxy API（
iap.googleapis.com）が無効になっています。 - 修正: Identity-Aware Proxy API を有効にします。
Workforce Identity 連携で Agent Gateway を管理する際の失敗
この問題は、Cloud de Confiance コンソールで Agent Gateway を管理している場合や、Workforce Identity 連携（WIF）で認証されたときに gcloud CLI を使用している場合に発生することがあります。
コンソールに、次のような一般的な読み込みエラーまたは作成エラーが表示されます。
- 「読み込み中にエラーが発生しました。」
- 「サーバーはリクエストを実行できませんでした」
- 「エージェント ゲートウェイを作成できませんでした」
- 「読み込みに失敗しました」
また、gcloud コマンド（gcloud network-services agent-gateways import など）から error 13: an internal error has occurred などの内部エラーが返されることがあります。
この問題を解決するには、Cloud Identity または Google Workspace で管理されている標準の Google アカウントで認証します。このアカウントには、roles/networkservices.admin などの必要な権限が付与されている必要があります。
フェデレーション ID は、プレビュー版の Agent Platform Governance サービスと Gateway サービスで限定的にサポートされています。フェデレーション プリンシパルに広範な IAM ロールを付与しても、問題は解決しません。
デバッグ ワークフロー
下り（外向き）リクエスト フローのセクションで説明されている条件のいずれかが欠落している場合、リクエストがブロックされる可能性があります。
IAP の決定を確認する
ログ検索を IAP 下り（外向き）の決定に絞り込むには、Logging で次のクエリを実行します。
protoPayload.serviceName="iap.googleapis.com" protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP" protoPayload.metadata.mcp_attributes.base_protocol_method="true"
一致する IAP ログエントリがまったく表示されない場合は、IAP が評価する前にゲートウェイがリクエストを拒否した可能性があります。次のステップに進みます。
一致するログエントリが表示された場合は、次のフィールドを確認します。
protoPayload.authorizationInfo[].granted: リクエストが許可された（true）か拒否された（false）かを示します。protoPayload.authenticationInfo.principalSubject: 呼び出し元の SPIFFE ID またはprincipal://...ID。これがエージェントの ID と一致していることを確認します。protoPayload.authorizationInfo[].resource: 呼び出しが解決された登録済みの宛先リソース。labels."iap.googleapis.com/audited_resource_name": この値がunregisteredResourceの場合、宛先ホスト名は登録されていません。宛先ホスト名をエージェント レジストリに登録し、エージェントにこの宛先に対するiap.resources.egressViaIAP権限があることを確認します。- 適用モード: リクエストの適用モードを確認します。ドライラン リクエストをフィルタするには、クエリに
protoPayload.metadata.iamEnforcementMode="DRY_RUN"を追加します。DRY_RUNモードでは、IAP は拒否をログに記録しますが、適用しません。したがって、エージェントがドライラン モードで403エラーで失敗した場合、拒否はゲートウェイの下り（外向き）プロキシまたは宛先リソースのいずれかから発生している可能性があります。
Agent Gateway の決定を確認する
Agent Gateway がリクエストをどのように評価したかを確認するには、Logging でゲートウェイログをクエリします。この例では、403 エラーのみをログに記録しています。
resource.type="networkservices.googleapis.com/Gateway" resource.labels.gateway_type="SECURE_WEB_GATEWAY" resource.labels.location="REGION" resource.labels.gateway_name="AGENT_GATEWAY_NAME" httpRequest.status=403 -httpRequest.requestMethod="CONNECT"
一致するログエントリで次のフィールドを確認します。
jsonPayload.authzPolicyInfo.policies.result: 認可の全体的な結果（ALLOWEDまたはDENIED）。httpRequest.requestUrl: エージェントがアクセスしようとした正確なリンク先 URL をメモします。次のステップでは、宛先リソースで使用されているホスト名が Agent Registry に登録されているかどうかを確認します。
宛先の登録と IAM アクセス ポリシーの適用範囲を確認する
宛先にアクセスするには、エージェント ID に iap.resources.egressViaIAP 権限を付与する IAM 許可ポリシーが常に必要です。きめ細かいリソース単位のアクセス ポリシーを適用し、ホスト名が正確に一致するようにするには、エージェント レジストリに宛先を登録することをおすすめします。登録されていない宛先の場合は、登録されていないエンドポイントのポリシーによって、必要な権限がエージェント ID に付与されているかどうかを確認します。
リソースごとのポリシーを使用する場合は、エージェントが到達しようとするすべての宛先ホスト名とホスト名のバリエーションを Agent Registry に登録する必要があります。これは、aiplatform.googleapis.com などの Google API が、SDK バージョン、リージョン クライアント構成、mTLS の使用状況（us-central1-aiplatform.googleapis.com や us-central1-aiplatform.mtls.googleapis.com など）に応じて複数のホスト名を介して解決できるためです。
ゲートウェイはホスト名を完全に一致させるため、aiplatform.googleapis.com を登録してもエージェントが us-central1-aiplatform.googleapis.com を呼び出すと、ゲートウェイは登録されていないリソースとみなし、リクエストを拒否します。
次のサンプル スクリプトを実行して、リソースタイプに基づいてレジストリ エントリを一覧表示し、エージェントの呼び出しで使用される特定のホスト名のエントリを確認します。
HOSTNAME="HOSTNAME" PROJECT_ID="PROJECT_ID" LOCATION="REGION" echo "Checking Endpoints..." gcloud agent-registry endpoints list \ --project="$PROJECT_ID" \ --location="$LOCATION" | grep "$HOSTNAME" echo "Checking MCP Servers..." gcloud agent-registry mcp-servers list \ --project="$PROJECT_ID" \ --location="$LOCATION" | grep "$HOSTNAME" echo "Checking Agents..." gcloud agent-registry agents list \ --project="$PROJECT_ID" \ --location="$LOCATION" | grep "$HOSTNAME"
次のように置き換えます。
HOSTNAME: エージェントが到達しようとしている宛先ホスト名（例:us-central1-aiplatform.mtls.googleapis.com）。PROJECT_ID: 実際の Cloud de Confiance プロジェクト ID。REGION: Agent Registry リソースと Agent Gateway リソースのロケーション（例:us-central1）。
出力 1: ホスト名はすでに登録されています
ホスト名が Agent Registry エントリに存在する場合、次のような出力が表示されます。
Checking Endpoints... url: https://us-central1-aiplatform.mtls.googleapis.com Checking MCP Servers... Checking Agents...
宛先リソースの IAM バインディングを確認するに進み、リソース単位またはレジストリ全体のポリシーでエージェント ID へのアクセス権が付与されているかどうかを確認します。
出力 2: ホスト名がレジストリに存在しない
ホスト名がレジストリに存在しない場合は、次の例のような出力が表示されます。
Checking Endpoints... Checking MCP Servers... Checking Agents...
リソース単位またはレジストリ全体のポリシーを使用する場合は、まず Agent Registry に宛先を登録します。登録されていないエンドポイントにポリシーを使用する場合は、宛先リソースの IAM バインディングを確認するに進みます。
宛先リソースの IAM バインディングを確認する
エージェント ID またはそのプリンシパル セットに、宛先に対する iap.resources.egressViaIAP 権限があることを確認します。
ポリシー バインディングは、次の 3 つのスコープで構成できます。
- レジストリ全体: レジストリに登録されているすべてのエージェント、MCP サーバー、エンドポイントへのアクセス。
- リソースごと: アクセスを制限します。リソースごとのバインディングは、特定のリージョンに対するレジストリ全体のバインディングと統合されるのではなく、そのバインディングを置き換えます。
- 未登録のエンドポイントのポリシー: Agent Registry に登録されていない宛先へのアクセス。
次のいずれかの例を使用して、バインディングを確認します。
レジストリレベルの IAM ポリシー バインディングを確認するには、次のコマンドを実行します。
curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -d '{}' \ -X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry:getIamPolicy" \ -H "Content-Type: application/json"エンドポイントごとの IAM ポリシー バインディングを確認するには、次のコマンドを実行します。
export HOSTNAME=HOSTNAME ENDPOINT_ID=$(gcloud agent-registry endpoints list \ --project="PROJECT_ID" \ --location="REGION" \ --filter="interfaces.url:$HOSTNAME" \ --format="value(name.basename())") echo "ENDPOINT_ID=$ENDPOINT_ID" curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ -d '{}' \ -X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/endpoints/${ENDPOINT_ID}:getIamPolicy"
HOSTNAMEは、エージェントが到達しようとしている宛先のホスト名（us-central1-aiplatform.mtls.googleapis.comなど）に置き換えます。MCP サーバーごとの IAM ポリシー バインディングを確認するには、次のコマンドを実行します。
export MCP_SERVER=MCP_SERVER MCP_SERVER_ID=$(gcloud agent-registry mcp-servers list \ --project="PROJECT_ID" \ --location="REGION" \ --filter="interfaces.url:$MCP_SERVER" \ --format="value(name.basename())") echo "MCP_SERVER_ID=$MCP_SERVER_ID" curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ -d '{}' \ -X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/mcpServers/${MCP_SERVER_ID}:getIamPolicy"
MCP_SERVER は、MCP サーバーの URL（
https://example-abc12345-uc.a.run.app/mcpなど）に置き換えます。
返されたポリシー情報で、エージェントの ID またはプリンシパル セットに一致する iap.resources.egressViaIAP 権限を持つバインディングを探します。返された出力に "etag" フィールドが含まれていてもバインディングがない場合、IAM ポリシーが存在しないことを意味します。
バインディングが存在するが condition が含まれている場合は、Common Expression Language（CEL）式でエージェントが除外されていないことを確認します。エージェントにない属性でフィルタする条件により、エージェントが暗黙的に除外されている可能性があります。
ターゲットの宛先に、エージェント ID またはプリンシパル セットに iap.resources.egressViaIAP 権限を付与する一致するポリシー バインディングがない場合は、次のいずれかのポリシー オプションを使用して権限を付与します。
- レジストリ レベルのポリシー（推奨）: エージェントからレジストリへのポリシーを構成して、Agent Registry に登録されているすべてのリソースへのアクセス権を付与します。
- リソースごとのポリシー（MCP サーバーまたはエンドポイント）: Agent Registry に MCP サーバーを登録するか、エンドポイントを登録し、エージェントから MCP サーバーへのポリシーまたはエージェントからエンドポイントへのポリシーを作成します。
- 未登録のエンドポイントのポリシー: 未登録のエンドポイントのポリシーを構成して、リソースを登録せずにアクセスを許可します。
認可ポリシーと拡張機能を検査する
このセクションでは、エージェントに関連付けられた Agent Gateway を明示的にターゲットとする認可ポリシーがあることを確認します。
Gateway に関連付けられている認可拡張機能の詳細を取得し、使用している拡張機能が想定どおりに構成されていることを確認します。
gcloud service-extensions authz-extensions describe AUTHORIZATION_EXTENSION_NAME \ --location=LOCATION \ --project=PROJECT_ID
AUTHORIZATION_EXTENSION_NAME は、ゲートウェイに関連付けられている拡張機能の名前に置き換えます。拡張機能の名前がわからない場合は、 Cloud de Confiance Cloud de Confiance コンソールのゲートウェイの詳細ページに移動し、[Service Extensions] の [拡張機能名] フィールドの値をメモします。
認可ポリシーがゲートウェイ リソースを明示的にターゲットとし、同じ認可拡張機能にリンクしていることを確認します。 Cloud de Confiance Cloud de Confiance コンソールでゲートウェイの詳細ページに移動し、[サービス拡張機能] の [ポリシー名] フィールドの値を確認します。
ゲートウェイをターゲットとするポリシーがない場合、またはゲートウェイとポリシーのマッピングが正しくない場合、認可拡張機能は実行されません。
プリンシパル アクセス境界ポリシーを確認する
プリンシパル アクセス境界ポリシーは、IAM 許可ポリシーよりも優先されます。つまり、すべての IAM バインディングを正しく構成していても、宛先リソースをエージェントのスコープから除外するアクティブなプリンシパル アクセス境界ポリシーがある場合、リクエストは失敗します。
組織全体のポリシーを一覧表示するには、次のコマンドを実行します。
gcloud iam principal-access-boundary-policies list \ --organization="ORGANIZATION_ID" \ --location=global
エージェントのプリンシパル セットにバインドされているポリシーを確認するには、次のコマンドを実行します。
gcloud iam policy-bindings search-target-policy-bindings \ --project="PROJECT_ID" \ --target="PRINCIPAL_SET"
次のように置き換えます。
ORGANIZATION_ID: Cloud de Confiance 組織 ID。PROJECT_ID: 実際の Cloud de Confiance プロジェクト ID。PRINCIPAL_SET: エージェント ID のプリンシパル セット。
バインディングが存在する場合は、details.rules[].resources[] フィールドを調べて、宛先がエージェントのスコープ内にあることを確認します。
プリンシパルとプリンシパル セットのバインディングをテストする
権限が一貫して機能しない場合や、予期せず失敗する場合は、エージェントのグループ ID（プリンシパル セット）の構成方法に関連している可能性があります。プリンシパル セットベースの権限は、次の理由で失敗する可能性があります。
- 同期の遅延: セットに ID を追加すると、IAM が更新されて新しいメンバーが認識されるまでに数分かかることがあります。
- 属性が不足している: プリンシパル セットのメンバーシップに特定の属性が必要な場合、エージェントの ID にはそれらの属性（部門やチームのラベルなど）が正確に反映されている必要があります。ID にこれらの属性がない場合、エージェントはグループから自動的に除外されることがあります。
グループ メンバーシップが問題かどうかをテストするには、影響を受けるリソースに直接 principal:// バインディングを追加して、特定のエージェントに直接権限を付与します。エージェントが直接バインディングで正常に接続された場合、根本原因は属性の不一致か、プリンシパル セットとの同期遅延である可能性があります。この問題を解決するには、エージェントの ID 属性を確認して修正するか、直接 principal:// バインディングを使用します。
次のステップ
Codelab: Agent Platform でエージェント ワークロードを管理する
Gemini Enterprise Agent Platform の Agent Gateway でエージェント ワークロードを管理する方法について説明します。