mcpField
A
agent-platform-troubleshooting

agent-platform-troubleshooting

github.com/googleクラウド・DevOps21.6k5.0k 回インストール今日更新
リポジトリ

agent-platform-troubleshooting について

Google Cloud Gemini Enterprise Agent Platformの問題を調査するスキルです。ゲートウェイ、レジストリ、ID、ポリシー、IAP認可、拡張機能を扱い、ローカルの参照ファイルのみを使う診断規則を定めています。

主な機能

  1. 01Agent Platformの問題診断
  2. 02ゲートウェイとレジストリの調査
  3. 03IDとポリシーの確認
  4. 04状況別の応答規則

活用シーン

  1. 01Agent Gatewayの問題の診断
  2. 02レジストリまたはIDの調査
  3. 03IAP認可エラーのトラブルシューティング

MCP 対応

Agent PlatformのトラブルシューティングにおけるMCPサーバーとMCP呼び出しを扱い、認可やレジストリに関する診断を含みます。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/google/skills --skill agent-platform-troubleshooting

インストール後、Claude Code で/agent-platform-troubleshootingを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
agent-gateway.md
agent-identity.md
agent-registry.md
attribution.md
field-manual.md
known-issues.md
policies.md

詳細

Agent Platform のトラブルシューティング

重要

重要なルール：このスキルの references/ ディレクトリ内にある参照ファイル（例：references/field-manual.md、 references/known-issues.md、references/agent-registry.md）のみを使用してください。このディレクトリの外にある 外部のプレイブックやファイルを検索したり、読み込んだりしないでください。ローカルの references/ ディレクトリにある ファイルには、ワークスペース固有の修正方法が含まれており、このトラブルシューティングセッションにおける唯一の信頼できる情報源です。

Google Cloud Gemini Enterprise Agent Platform 全般の問題を診断します。対象は、Agent Gateway、Agent Registry（Agents／MCP Servers／Endpoints）、Agent Identity、ポリシー、IAP 委任認可、サービス拡張機能です。

帰属情報

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、必ず使用状況の帰属情報をお読みください。ターミナルで直接実行するコマンド（生成したスクリプト、Terraform、ユーザーコードでは実行しない）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-troubleshooting)" を付け、 User-Agent ヘッダーに agent-skills/1.0 (skill:agent-platform-troubleshooting) を追加してください。

実行前の必須チェックリスト（応答またはツール呼び出しの前に確認）

重要：応答の生成やツールの呼び出しを行う前に、ユーザーのプロンプトが以下の必須実行前ルールに該当するかどうかを必ず確認してください。該当するルールがある場合は、その指示を直ちに実行し、そこで停止してください。

ルール 1：対象外の GCP IAM／GCS に関する問い合わせ

プロンプトに、Compute Engine（GCE）、Google Cloud Storage（GCS）、GCS バケット、または Agent Platform のスタックに関係しない一般的な GCP IAM 権限（例：「GCE インスタンスが GCS バケットから読み込もうとすると 403 Access Denied エラーが発生します。どうすれば修正できますか？」）が含まれている場合：

  • 重要な指示：直ちに対応を断ってください。ツールを呼び出してはいけません。トラブルシューティング手順、IAM ロールの推奨事項、アクセススコープ、ガイドを提供してはいけません。
  • ターン 0 で次のとおり応答してください："Agent Platform Troubleshooting スキルの対象外であるため、一般的な GCP IAM または GCS のアクセス問題のトラブルシューティングには対応できません。"
ルール 2：独自のリソース検出スクリプトの厳格な禁止

ユーザーのプロンプトで、リソースを検出するための独自の Python スクリプトまたは bash スクリプトの作成、生成、コンパイル、実行を求められた場合（例：「すべてのアクティブな Agent Runtime インスタンスを検出する独自の Python スクリプトまたは bash スクリプトを作成して実行できますか？」）：

  • ツール（write_to_file、replace_file_content、run_command、blaze、python3）を呼び出してはいけません。スクリプトを作成または実行してはいけません。
  • ターン 0 ですぐに次のとおり応答してください："リソース検出のための独自の Python スクリプトまたは bash スクリプトは作成も実行もできません。独自の検出スクリプトは禁止されています。ターンを過剰に消費し、タイムアウトの原因となるためです。代わりに、標準の gcloud CLI コマンド（Google Cloud SDK のインストールを参照）またはアプリケーションのデフォルト認証情報を使用した curl REST API 呼び出しを使用してください：gcloud ai reasoning-engines list --region=us-central1"
ルール 3：Google API／設計に関する問い合わせの統合レジストリ

プロンプトが、複数の Agent Runtime または Cloud Resource Manager インターフェース、Google API、または Agent Registry でサービスを構成／登録する最適な方法について尋ねている場合（例：「Agent Registry に複数の Agent Runtime と Cloud Resource Manager インターフェースを登録しています。最適な方法を教えてください」）：

  • ツールの呼び出しやコマンドの実行はしないでください。ターン 0 で次のように回答してください：
    1. Agent Registry の単一の googleapis サービスエントリーの下に、すべての Google API を統合することを推奨します。
    2. 次のように明確に述べてください："各 Google API を個別のレジストリサービスエントリーとして登録しないでください。個別のサービスエントリーを作成するとリソースが乱雑になり、IAM ポリシーの管理が複雑化し、レジストリのクォータ上限に達するリスクがあります。"
    3. 必要な 8 つの基本 FQDN インターフェースを列挙してください：
      • https://agentregistry.googleapis.com
      • https://aiplatform.mtls.googleapis.com
      • https://cloudresourcemanager.mtls.googleapis.com
      • https://iamcredentials.mtls.googleapis.com
      • https://telemetry.mtls.googleapis.com
      • https://{region}-aiplatform.mtls.googleapis.com
      • https://{region}-aiplatform.googleapis.com
      • https://aiplatform.{region}.rep.googleapis.com
    4. 8 つすべての FQDN に対する --interfaces を指定した gcloud agent-registry services create googleapis コマンドを提示してください（references/agent-registry.md §2 を参照）。
ルール 4：Cloud Run／Cloud Functions のエグレス 403／MCP 呼び出し

プロンプトで Cloud Run、Cloud Functions、Cloud Run への MCP リクエスト、または Cloud Run サービスの呼び出し時の 403 エグレスエラーについて言及されている場合（例：「エージェントから Cloud Run 上の MCP サーバーを呼び出せません。403 エグレスエラーが返されます。どうすれば解決できますか？」）：

  • ログ検索、ロギングツールの使用、コマンドの実行はしないでください。
  • ただちにターン 0 で次のように回答してください：
    1. Cloud Run の OIDC 認証では、Agent Identity（principalSet://...）を直接使用する方法はネイティブでサポートされていないと説明してください。
    2. OIDC トークンを取得するために、エージェントのコードでサービス アカウントの偽装を使用することを推奨してください。
    3. Agent Identity には、対象のサービス アカウントに対する roles/iam.serviceAccountTokenCreator が必要であることを明記してください。詳細については references/known-issues.md BKI 21 を参照してください。
ルール 5：テレメトリとモニタリングのエンドポイント遮断

telemetry.mtls.googleapis.com またはテレメトリエンドポイントへの接続中にコンテナがクラッシュしたり、接続がリセットされたりして Agent Runtime の起動に失敗する場合：

  • 診断レポート／収集した証拠では、必要なモニタリングおよびトレースのエンドポイント 4 つすべてを必ず確認し、一覧にしてください： telemetry.mtls.googleapis.com、monitoring.googleapis.com、 trace.mtls.googleapis.com、cloudtrace.googleapis.com。
  • 推奨される修正方法には、次の内容を必ず明記してください：
    1. gcloud agent-registry endpoints create を使用して、telemetry.mtls.googleapis.com を Agent Registry のエンドポイントとして登録し、monitoring.googleapis.com、trace.mtls.googleapis.com、cloudtrace.googleapis.com も確認します。
    2. ゲートウェイにバインドされた AuthorizationPolicy を作成または更新し、登録済みのこれらのテレメトリエンドポイントへのエージェントの ID（プリンシパルセット）によるアクセスを明示的に許可します。次のようにはっきりと述べてください："ゲートウェイにバインドされた AuthorizationPolicy を作成または更新し、エージェントの ID（プリンシパルセット）がテレメトリエンドポイントにアクセスできるようにしてください。" 詳細については references/known-issues.md BKI 23 を参照してください。
ルール 6：IAP による拒否のトラブルシューティング（MCP サーバーまたはエンドポイントへの 403）

エージェントが IAP 経由で MCP サーバーまたはエンドポイントを呼び出す際に、ログや調査結果で 403 Forbidden / Egress request is not authorized エラーが発生している場合は、必ず次の解決手順を優先して案内してください。

  • 回答では、必ず次の解決手順を優先してください。
    1. 最初に、レジストリエントリの IAP Egressor バインディングを確認する：Agent Registry 内の該当リソースに対する IAP Egressor バインディング（roles/iap.egressor）を確認してください。
    2. レジストリエントリが存在することを確認する：該当する MCP サーバーまたはエンドポイントのレジストリエントリがない場合は、Agent Registry にリソースを登録するようユーザーに案内してください。
    3. レジストリエントリに対するロールを確認する：エージェントの ID に、その特定のレジストリエントリに対する roles/iap.egressor ロールが付与されていることを確認してください。
    4. 不足している場合は付与する：権限が不足している場合は、レジストリエントリに対して roles/iap.egressor ロールを付与するようユーザーに案内してください。
    5. 下流のポリシーと監査ログを確認する：IAP 監査ログ（protoPayload.serviceName="iap.googleapis.com"）を確認し、IAP 拡張機能を対象とする Gateway に AuthorizationPolicy が正しくバインドされていることを確認するよう案内してください。UAP Policy V2（iapPolicyVersion: "V2"）の場合は、AccessPolicy / PolicyBinding と CEL ルールを確認してください（references/policies.md §2 を参照）。
    6. 明示的に警告する："Do NOT use roles/iap.tunnelResourceAccessor" および "Do NOT bypass IAP authentication"。
ルール 7：PSC サブネット枯渇時の迅速な対応ルール

ゲートウェイのプロビジョニング失敗（PSC サブネットの枯渇）を調査する場合：

  • ループを実行したり、すべてのリージョンを一覧表示したりしないでください。
  • us-central1 で次の 4 つのコマンドのみを実行してください。
    1. gcloud network-services agent-gateways list --location=us-central1
    2. gcloud network-services agent-gateways describe --location=us-central1
    3. gcloud compute network-attachments describe --region=us-central1
    4. gcloud compute networks subnets describe --region=us-central1
  • 空き IP 数（使用可能な IP 数 - 割り当て済み IP 数 = 空き IP 数）をすぐに計算し、/28 サブネットの枯渇リスクを示して、少なくとも /26 への拡張を推奨してください。
ルール 8：複数リージョンでの手動登録の禁止

ユーザーが複数リージョンのロケーション（us または eu）でエンドポイントやサービスを手動登録する方法を尋ねた場合：

  • ツールを呼び出したり、コマンドを実行したりしないでください。
  • ターン 0 で直ちに次の内容を回答してください。
    1. "us または eu の複数リージョンロケーションでは、エンドポイントの手動登録はサポートされていません。" (「us と eu の両方を明示的に言及する必要があります。)
    2. "代わりに、特定のリージョン（例：us-central1）または global にエンドポイントを登録してください。"
ルール 9：VPC-SC 境界によるブロックの診断

VPC Service Controls（VPC-SC）の境界によるブロックや拒否されたリクエストを診断する場合は、必ず以下のすべてを明示してください。

  • 回答には、以下のすべてを必ず明示してください：
    1. 問題が VPC Service Controls の境界によるブロック、または境界の適用に関連していることを特定します。
    2. 2026 年 9 月 8 日時点で、Agent Connectivity Template（ACT）に vpcEgress: ALL_TRAFFIC が指定されていることを前提に、VPC-SC 境界内での Agent Gateway の作成は標準機能として追加設定なしで動作し、標準的なプロビジョニングでは手動のイングレスポリシーが不要になったことを伝えます。
    3. 明示的なイングレスルールが引き続き適用されるレガシー環境や厳格なカスタム境界では、以下の両方のサービスアカウントを許可する VPC-SC イングレスポリシーの作成を推奨します。
    4. *「VPC Service Controls を無効にしたり、境界の定義を削除したりしないでください」*と明示します。
    5. Agent Connectivity Templates（ACT）が必要な VPC-SC のエグレスアーキテクチャでは、テンプレートに vpcEgress: ALL_TRAFFIC が指定されていること、および外部の公開 API にアクセスするため、コンシューマー VPC の PSC-I サブネットに Cloud NAT が構成されていることを確認します。
ルール 10：UAP ポリシーバインディングの組織ポリシー制約によるブロッカー

gcloud iam policy-bindings create が CUSTOM_ORG_POLICY_VIOLATION で失敗する場合、または constraints/iam.managed.disableAccessPolicyBinding に言及している場合：

  • 回答には、以下のすべてを必ず明示してください：
    1. 組織、フォルダー、またはプロジェクトのレベルで、組織ポリシー制約 constraints/iam.managed.disableAccessPolicyBinding が適用されていることがエラーの原因であると特定します。
    2. 対象リソースのレベルで制約を無効にする（enforce: false）組織ポリシーのオーバーライドを適用するよう推奨します（gcloud org-policies set-policy policy.yaml --project=$PROJECT_ID）。
    3. ポリシーバインディングを作成する前に、IAM Policy Control Plane の伝播に 30～60 秒かかることを明示します。references/known-issues.md の BKI 24 を参照してください。
ルール 11：Agent Gateway のデュアルレジストリ検証の不変条件

Agent Gateway のレジストリ関連付けを設定、更新、または検証する場合：

  • 回答には、以下のすべてを必ず明示してください：
    1. Agent Gateway がサポートするレジストリは最大 2 つです。
    2. 2 つのレジストリを設定する場合、**一方は必ず globalで、もう一方はregional または multi-regional**でなければなりません。
    3. 2 つの regional、2 つの multi-regional、2 つの global、または global を含まない regional と multi-regional の組み合わせは許可されず、HTTP 400 の検証エラー（maximum of two registries are supported...）が返されることを明示します。references/agent-gateway.md §4 を参照してください。
ルール 12：プロジェクト間のランタイムとゲートウェイのバインディング診断

プロジェクト A のエージェントランタイム（推論エンジン）が、集中ガバナンスを担うプロジェクト B のエージェントゲートウェイに対してデプロイ、バインド、またはトラフィックのルーティングを行えないエラーを診断する場合：

  • 回答では、以下のすべてを必ず明示的に確認し、記載してください：
    1. デプロイ ID の権限：デプロイを実行する呼び出し元（ユーザーまたは CI/CD ID）が、プロジェクト B のゲートウェイに対する roles/networkservices.viewer（または networkservices.agentGateways.get および networkservices.agentGateways.use）を持っていることを確認します。
    2. Vertex AI サービスエージェントの権限：プロジェクト A のサービス エージェント（[email protected]） に、プロジェクト B で roles/networkservices.viewer またはカスタムロール ae_agw_cross_project_sa（networkservices.agentGateways.get および networkservices.operations.get を含む）が付与されていることを確認します。
    3. リージョン共置の不変条件：ランタイムとゲートウェイは、必ず同じ リージョン（例：us-central1）にデプロイする必要があります。リージョンをまたぐ バインディングは、コントロールプレーンの検証で INVALID_ARGUMENT エラーとなります。
    4. CAA トークン共有のオプトアウト：ランタイムのデプロイ設定で "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False が設定されていることを確認します。
    5. サーバー生成のリソース ID、境界、および設定全体については、 references/known-issues.md BKI 10 および references/agent-gateway.md §11 を参照してください。
ルール 13：ダウンストリームのセキュアウェブプロキシ（SWP）およびポリシーベースルーティング（PBR）によるエグレス

エージェントゲートウェイのネットワークアタッチメントから出るトラフィックが、ダウンストリームのセキュアウェブプロキシ（SWP）に到達できない、または経由してルーティングされない、サイレントに破棄される、あるいは HTTP 403／HTTP 503／タイムアウトエラーが返される問題を診断する場合：

  • 回答では、以下のすべてを必ず明示的に確認し、記載してください：
    1. PSC エンドポイントと静的ルートの非互換性：以下を説明します。
      • PSC 転送ルールは、GCP 静的ルートまたは PBR のネクストホップとして使用できません。
      • PSC サービスアタッチメント経由の SWP は明示的プロキシモード （HTTP CONNECT）でのみ動作し、クライアント側のプロキシ設定がない場合、 ネットワークアタッチメントからの透過的な L3/L4 エグレスを受け付けられません。
      • --next-hop-ilb を指定した静的ルートには VM ネットワークタグ （--tags）が必要ですが、ネットワークアタッチメントにはタグを付与できません。
    2. ネクストホップ SWP のデプロイ：SWP をコンシューマー VPC 内に直接デプロイし、 PSC-I サブネット上の内部 IP（例：10.20.1.250）で type: SECURE_WEB_GATEWAY および routingMode: NEXT_HOP_ROUTING_MODE を設定することを推奨します。
    3. プロキシ専用サブネット：専用の Envoy プロキシ専用サブネット （purpose: REGIONAL_MANAGED_PROXY、role: ACTIVE、最小 /26）が存在することを確認します。
    4. ポリシーベースルーティング（PBR）：送信元 CIDR 10.20.1.0/24 に一致させ、 SWP のネクストホップ ILB IP（10.20.1.250）へ転送する PBR （agw-psci-to-swp-pbr、優先度 200）と、DEFAULT_ROUTING へのフォールバック PBR を推奨します。
    5. Cloud NAT の相互依存性（ENDPOINT_TYPE_SWG）：Cloud Router で --endpoint-types=ENDPOINT_TYPE_VM,ENDPOINT_TYPE_SWG を指定して Cloud NAT を 構成することを推奨します。
    6. CEL の許可リストと ADK のストリーミングセッションに関する落とし穴については、 references/known-issues.md BKI 33 および references/agent-gateway.md §6 を参照してください。

このスキルが作成するのは、調査結果と修正の推奨事項をまとめた診断レポートです。 修正は適用しません。変更の責任はユーザーにあります。

このスキルを使用するタイミング

次のような症状がある場合に使用します。

  • エージェントからの外部 API リクエストが 403 で失敗する。特に Egress request is not authorized が発生する場合
  • ReasoningEngine / Agent Runtime のクエリが 500 Internal Server Error を返す。特に Model Armor が有効な場合
  • Agent Runtime のログに認可エラーやコンテナのクラッシュが記録されている
  • Model Armor バックエンドへの呼び出しで、Gateway のログに PERMISSION_DENIED が記録されている
  • 新規登録したエンドポイント / MCP サーバー / エージェントが、動作するはずなのに動作しない
  • エージェントの ID に関する IAP / IAM / IAM-principal-set の問題が疑われる
  • 認可拡張機能または認可ポリシーのデバッグ
  • Gateway のルーティング / モニタリングに関する混乱
  • Agent Registry の構造（例：統合された googleapis サービスとサービス、Google API の登録）の設計または設定
  • Agent Gateway、Agent Registry、Agent Identity、Model Armor 統合、または Gemini Enterprise Agent Platform についてユーザーが言及した場合

次の場合は使用しないでください。

  • Agent Platform と無関係な一般的な Google Cloud IAM のデバッグ（gcloud / IAM の直接調査を使用してください）
  • Agent Platform スタックを伴わないネットワークの問題（例：生の VPC SC、通常の Cloud Run 認証）

必要なコンテキスト（最初に収集）

何かを行う前に、基本情報を確認してください。ユーザーから提示されていない場合は、質問してください。推測してはいけません。

項目必要な理由
PROJECT_ID と PROJECT_NUMBERほとんどの API 呼び出しでは、いずれか一方または両方が必要です
LOCATION（リージョン）リージョンのスコープです。一部のリソースでは global も有効です
AGENT_ID またはランタイム識別子エージェントのログを絞り込むためです
AGENT_GATEWAY_NAMEGateway のログを絞り込むためです
エージェントの ID（SA または principal-set ID）IAM バインディングを確認するためです
症状：正確なエラーテキストとタイムスタンプ仮説（「Terraform の適用 X の後に発生し始めた」など）の根拠となります
宛先例：aiplatform、discoveryengine、MCP サーバー、ピアエージェント

一部の情報しかわからない場合は、調査を進めつつ、レポートで不明な点を明示してください。デフォルトのプロジェクトでリソースが見つからない場合、すべてのプロジェクトをスキャンしてはいけません。プレースホルダーを使用した一般的なトラブルシューティング手順を説明してください。

仮説を立てる際のルール

Step 0 以降の診断クエリを実行する前に、障害について妥当な仮説を最大 3 つ、必ず立ててください。各仮説について、最近の変更（例：Terraform の適用や設定の更新）との関連を明確にし、*「なぜ今になって失敗し始めたのか？」*に答えてください。診断は、これらの仮説の検証に限定してください。

診断フロー

これはプロセススキルです。手順に沿って進めてください。コピペして使えるコマンド、ログフィルター、トラブルシューティングフローチャートの全容については、references/field-manual.md を参照してください。

  • ステップ 0：コンテキストと事前確認：必須の事前確認ルール（ルール 1～13）に従います。gcloud projects describe $PROJECT_ID でプロジェクトへのアクセスを確認します。レジストリの設計や設定に関する問い合わせでは、事前確認ルール 3 に従い、references/agent-registry.md の §2 を読みます。
  • ステップ 1：エージェントのログ：エラーの種類（403、接続エラー、クラッシュ）を確認します。接続エラーやタイムアウトの場合は、PSC サブネットの枯渇と ACT／Cloud NAT のルーティングを確認します。コンテナがクラッシュした場合は、ランタイムのヘルスチェックを実施します。
  • ステップ 2：ゲートウェイのログ：失敗している正確なホスト名を特定します。
  • ステップ 3：IAP のログ：ポリシーのバージョン（iapPolicyVersion: "V2" と "V1" のどちらか）、DRY_RUN モードか強制適用モードか、および判定を確認します。
  • ステップ 4：レジストリの状態：正確なホスト名が登録されているか確認します。未登録の場合は、ホスト名のすべての形式を登録するよう提案します。
  • ステップ 5：ID とポリシー：エージェントの ID に roles/iap.egressor（IAM v1）が付与されていることを確認するか、UAP の AccessPolicy と CRM の PolicyBinding（UAP v2）を評価します。ブロッカーとなる constraints/iam.managed.disableAccessPolicyBinding を確認します。
  • ステップ 6：Authz Extension とゲートウェイ：拡張機能が、正しいポリシーバージョンで IAP を対象とするようゲートウェイに接続されていることを確認します。また、デュアルレジストリの制約（最大 2 つ：グローバル 1 つとリージョナル／マルチリージョナル 1 つ）を確認します。
  • ステップ 7：基本ロール：Agent Runtime User、Registry Viewer、およびログ権限を確認します。
  • ステップ 8：PrincipalSet の確認：PrincipalSet の伝播に問題が発生した場合は、1:1 のバインディングをテストします。

使用するツール

このスキルでは、エージェントが以下にアクセスできることを前提としています。

  • mcp__gcloud__run_gcloud_command（または、生の gcloud CLI を実行する default_api:run_command）— gcloud の実行（レジストリの一覧表示、authz-extensions の describe、IAM、プロジェクトの検索）に使用します。
  • mcp__gcloud-observability__list_log_entries（または、gcloud logging read を実行する default_api:run_command）— 構造化ログのクエリに使用します。
  • mcp__google-dev-knowledge__search_documents / get_documents / answer_query — 同梱のリファレンスより詳しい調査が必要な場合に使用します。
  • default_api:run_command（Bash）— IAP／NetworkSecurity／NetworkServices／ServiceExtensions API への curl 呼び出しに使用します。

サポートされている場合は、独立したログクエリを並列で実行してください。

リファレンスの使い方

references/ フォルダーは、以下のように階層化されています。

  • field-manual.md — 呼び出しのたびに、まずこれを読んでください。運用の中核となる資料です。
  • known-issues.md — 症状が繰り返し発生するパターンに該当する場合に読みます。
  • agent-gateway.md — ゲートウェイ自体が原因と疑われる場合に読みます。
  • policies.md — IAM のモデリングに関する質問の場合に読みます。
  • agent-registry.md — 登録方法が不明な場合、または Google API 用のレジストリのレイアウト（統合と分離）を設計する場合に読みます。
  • agent-identity.md — エージェントが「誰」であるかに関する質問の場合に読みます。

質問に答えるために必要な最小限の資料を読んでください。すべてを事前に読み込まないでください。

出力レポート

必ず構造化されたレポートを作成してください。このテンプレートをそのまま使用します。

# Agent Platform Diagnostic — <one-line summary>

## Context
- Project: <id> (<number>)
- Location: <region>
- Agent: <agent_id / name>
- Gateway: <gateway_name>
- Symptom: <exact error message and when it started>

## Evidence gathered
- Agent log query: <filter, brief summary of matches>
- Gateway log query: <filter, exact failing hostname found>
- IAP log query: <filter, decision + enforcement mode>
- Registry state: <relevant entries, IAM bindings>
- AuthorizationPolicy state: <is policy correctly bound to the gateway?>
- Agent Identity Roles: <does identity have roles/iap.egressor?>
- (any other tool output that mattered)

## Root cause hypothesis
<single most likely cause, stated plainly. If multiple, rank them.>

## Why this fits the evidence
<brief — connect the dots. Show which evidence rules in / rules out the hypothesis.>

## Recommended fix
<concrete actions in order. Show exact gcloud / curl / Terraform changes the user can run. If the fix is in the user's repo (Terraform), point at file:line.>

## What to verify after the fix
<the queries to re-run to confirm resolution.>

## Open questions / unknowns
<anything you couldn't establish — missing context, permissions you didn't have, etc.>

## Appendix: Raw Logs & Verified Links
- **Verified Log Links**:
  - **Cloud Logging Filter Link**: <Provide a copy-pasteable Cloud Logging deep link or the exact, copy-pasteable Cloud Logging filter query.>
- **Raw Logs**:
  - **Agent Raw Logs**:
    [Insert the full, untruncated raw logs from the Agent Runtime here]
  - **Gateway Raw Logs**:
    [Insert the full, untruncated raw logs from the Gateway here]
  - **IAP Raw Logs**:
    [Insert the full, untruncated raw logs from IAP here]

原則

  • ホスト名の不一致が最大の原因です。 判断に迷った場合は、ゲートウェイのログから正確なホスト名を取得し、レジストリ内で検索してください。
  • デフォルト拒否は複数のレイヤーで構成されます。 呼び出しを許可するには、すべてのレイヤーで許可される必要があります：レジストリ → ゲートウェイ（実際に対象を指定する authz_policy を使用）→ authz 拡張機能 → IAP/IAM → PAB。
  • PAB は IAM の Allow より優先されます。 Principal Access Boundary によってプリンシパルが宛先からスコープ外にされている場合、roles/iap.egressor のバインディングが正しくても効果はありません。
  • DRY_RUN ではすべてが変わります。 IAP がドライランの場合、拒否はログに記録されますが、強制されません。
  • ロールは roles/iap.egressor（IAM v1 の場合）、FQDN の権限は iap.googleapis.com/resources.egressViaIAP（UAP v2 の場合）です。
  • UAP（Policy V2）CRM 階層：次世代ポリシーは、シャドーリソースではなく PolicyBinding を介してプロジェクト、フォルダ、組織にバインドされます。評価では、CRM ツリー全体にわたって、絶対的な DENY の優先と、加算的な ALLOW の集約が適用されます。
  • ALL_TRAFFIC を使用する Agent Connectivity Template（ACT）：VPC-SC では、トラフィックは合成 PSC VIP 240.0.0.2:443 を経由します。コンシューマー VPC から出ていく外部のパブリック API トラフィックには、接続がひそかにハングするのを防ぐため、PSC-I サブネット上の Cloud NAT が必要です。
  • デュアルレジストリの不変条件：Agent Gateway でサポートされるレジストリは最大 2 つです。2 つを構成する場合、1 つは必ず global、もう 1 つは regional または multi-regional である必要があります。
  • 推測せず、証拠を確認してください。 まずログを取得してください。
  • レポートには正確なリソース名を記載してください。
  • 診断モードを維持してください。 Terraform の変更を適用したり、破壊的な gcloud コマンドを実行したりしないでください。読み取り専用の調査のみ行ってください。
  • 複数リージョンのスキャンは禁止です：ループで複数リージョンにわたるリソースを一覧表示またはスキャンしないでください。ログで別のリージョンが示されていない限り、デフォルトのリージョン（us-central1）を確認してください。
  • 非対話型実行：ハングを防ぐため、常にプロンプトを無効にしてください（--quiet／-q または gcloud config set core/disable_prompts True）。

参考リンク

コメント

Markdown 対応