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

Cloud Run エージェントからのアウトバウンド リクエストが失敗するか、Agent Gateway をバイパスする場合は、次のチェックを使用してリクエストパスをトレースするか、一般的な問題と解決策をご覧ください。設定手順については、Agent Gateway でエージェントを管理するをご覧ください。

トラフィックが Agent Gateway に到達する前に、Cloud Run Envoy サイドカーが Traffic Director API からルーティングと証明書の構成を取得します。サイドカーは、mTLS CONNECT トンネルを介して Secure Web Proxy にアウトバウンド トラフィックを送信します。

Envoy サイドカー アクセスログでアウトバウンド ルーティングを確認する

Cloud Run Envoy サイドカーがアウトバウンド TCP 接続をインターセプトすると、jsonPayload.upstream_host フィールドを含む JSON アクセスログ エントリが run.googleapis.com%2Fvar%2Flog%2Fenvoy_sidecar_log に書き込まれます。

Cloud Run サービスからアウトバウンド リクエストをトリガーし、サイドカー アクセスログをクエリします。

gcloud logging read \
    'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND jsonPayload.upstream_host:*' \
    --project=PROJECT_ID \
    --freshness=7d \
    --limit=20 \
    --format="table(timestamp, jsonPayload.sni, jsonPayload.upstream_host, jsonPayload.response_flags, jsonPayload.bytes_sent, jsonPayload.bytes_received, jsonPayload.duration)"

次のように置き換えます。

  • SERVICE_NAME: Cloud Run エージェント サービスの名前。
  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。

ゲートウェイを介した正常な接続では、次のような出力が返されます。

TIMESTAMP                     SNI          UPSTREAM_HOST                      RESPONSE_FLAGS  BYTES_SENT  BYTES_RECEIVED  DURATION
2026-10-09T05:07:48.340693Z   example.com  envoy://tunnel_internal_listener/  -               4101        2899            489

UPSTREAM_HOST と RESPONSE_FLAGS の値を確認します。

  • UPSTREAM_HOST が envoy://tunnel_internal_listener/ で、RESPONSE_FLAGS が - の場合、接続は正常です。Envoy サイドカーが EgressRouting ポリシーと一致し、接続を Agent Gateway に転送しました。
  • UPSTREAM_HOST が宛先 IP アドレスとポート（93.184.216.34:443 など）の場合、Traffic Director API は EgressRouting ポリシーを照合できなかったか、ターゲット ゲートウェイを解決できませんでした。Envoy は ORIGINAL_DST パススルーを使用し、Agent Gateway をバイパスしました。EgressRouting と AgentGateway のリソース URI を監査するをご覧ください。
  • UPSTREAM_HOST が envoy://tunnel_internal_listener/ で、RESPONSE_FLAGS が UF または UH、または BYTES_RECEIVED が 0 の場合、Envoy は Secure Web Proxy への CONNECT トンネルを開くことができませんでした。Virtual Private Cloud（VPC）サブネットの接続を確認するか、Secure Web Proxy ゲートウェイを更新すると Envoy トンネリングが中断するをご覧ください。
  • 行が表示されない場合は、run.googleapis.com%2Frequests を確認して、リクエストが Cloud Run コンテナに到達したことを確認します。アクティブなリビジョンで --ambient-networking が有効になっていることを確認します。それでも行が表示されない場合は、Envoy サイドカーの xDS と接続ログを確認するをご覧ください。

Envoy サイドカーの xDS と接続ログを確認する

Envoy サイドカーのアクセスログにエントリが返されないか、接続エラーが表示される場合は、サイドカーの xDS ログとアップストリーム接続ログを調べます。

  1. Traffic Director API の xDS ストリーム エラーまたは起動ステータスを確認します。

    gcloud logging read \
   'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND (severity>=INFO OR textPayload:"DeltaAggregatedResources")' \
   --project=PROJECT_ID \
   --freshness=7d \
   --limit=30 \
   --format="table(timestamp, severity, textPayload, jsonPayload.message)"

  2. ambient-swp-connect-cluster へのアップストリーム トンネル接続の試行を確認します。

    gcloud logging read \
   'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND (textPayload:"ambient-swp-connect-cluster" OR jsonPayload.message:"ambient-swp-connect-cluster" OR jsonPayload.message:"tunnel_internal_listener")' \
   --project=PROJECT_ID \
   --freshness=7d \
   --limit=30 \
   --format="table(timestamp, severity, textPayload, jsonPayload.message)"

    次のように置き換えます。

    • SERVICE_NAME: Cloud Run エージェント サービスの名前。
    • PROJECT_ID: 実際の Google Cloud プロジェクト ID。

ログメッセージを確認します。

  • ログに DeltaAggregatedResources gRPC config stream と The caller does not have permission が含まれている場合、サービス ID に roles/trafficdirector.client がありません。Envoy サイドカーが xDS 構成を受信できないをご覧ください。
  • ログに Creating connection to cluster ambient-swp-connect-cluster が含まれている場合、Envoy は EgressRouting 構成を受信し、Secure Web Proxy への接続を試みています。

EgressRouting と AgentGateway のリソース URI を監査する

gcloud alpha network-services egress-routings create または gcloud beta network-services agent-gateways import を実行すると、API はターゲット リソースが存在するかどうかを確認せずに URI 構文を検証します。リソース名またはリージョンに誤字があると、Traffic Director API は EgressRouting 変換をスキップし、Envoy はパススルー ルーティングを使用します。

保存されている URI を検査し、デプロイされたリソースと比較します。

  1. EgressRouting リソースを検査します。出力では、プロジェクト ID がプロジェクト番号に正規化されます。

    gcloud alpha network-services egress-routings describe EGRESS_ROUTING_NAME \
   --location=REGION \
   --project=PROJECT_ID

  2. リージョン内のすべての EgressRouting リソースを一覧表示して、同じサービスをターゲットとする重複するポリシーがないことを確認します。

    gcloud alpha network-services egress-routings list \
   --location=REGION \
   --project=PROJECT_ID

  3. ターゲットの Secure Web Proxy ゲートウェイが EgressRouting.gateway と AgentGateway.selfManaged.resourceUris の URI と一致していることを確認します。

    gcloud network-services gateways describe SWP_NAME \
   --location=REGION \
   --project=PROJECT_ID

    次のように置き換えます。

    • EGRESS_ROUTING_NAME: EgressRouting リソースの名前。
    • REGION: デプロイのリージョン。
    • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
    • SWP_NAME: Secure Web Proxy ゲートウェイの名前。

3 つの URI がすべて、プロジェクト ID または番号、リージョン、リソース名と一致していることを確認します。

  • EgressRouting.sources[].workloadUri:
    • サービス スコープ: //run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME
    • プロジェクト スコープ: //run.googleapis.com/projects/PROJECT_ID または //run.googleapis.com/projects/PROJECT_NUMBER
  • EgressRouting.gateway: //networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME
  • AgentGateway.selfManaged.resourceUris[]: projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME

Secure Web Proxy のトランザクション ログを確認する

Envoy サイドカーがトラフィックを Secure Web Proxy に転送してもリクエストが失敗する場合は、プロキシ トランザクション ログを表示するの説明に従ってプロキシログを調べます。

  • プロキシログにトラフィックが表示されない場合、リクエストは Secure Web Proxy に到達していません。EgressRouting と AgentGateway のリソース URI を監査すると一般的な問題と解決策で EgressRouting の構成を確認します。
  • 予期しない DENY または ALLOW の決定が表示された場合は、ログエントリの jsonPayload.authzPolicyInfo と jsonPayload.agentGatewayInfo を確認して、一致した AuthzPolicy と宛先メタデータを検査し、Agent Gateway リソースに接続されている ExtensionBinding ルールを確認します。ExtensionBinding リソースを作成または更新した後、構成の変更がゲートウェイに反映されるまでに最大 5 分かかることがあります。

一般的な問題と解決策

以降のセクションでは、一般的な問題とその解決方法について説明します。

リソース URI の不一致により、アウトバウンド トラフィックが Agent Gateway をバイパスする

Cloud Run からのアウトバウンド トラフィックが Agent Gateway をバイパスするか、egress-routings create の成功後にタイムアウトします。envoy_sidecar_log では、jsonPayload.upstream_host に envoy://tunnel_internal_listener/ ではなく宛先 IP アドレスとポートが表示されます。

EgressRouting または AgentGateway リソース URI のいずれかが、存在しないリソース名または一致しないリージョンを参照しています。Traffic Director API が Cloud Run サービスから Secure Web Proxy へのチェーンを解決できない場合、トンネル変換をスキップして ORIGINAL_DST を提供します。

EgressRouting リソース URI と AgentGateway リソース URI を監査するのコマンドを実行して、一致しない URI を見つけます。一致するリソース名とリージョンで構成を更新し、AgentGateway リソースまたは EgressRouting リソースを再作成します。

Envoy サイドカーが xDS 構成を受信できない

Cloud Run コンテナからのアウトバウンド リクエストがタイムアウトするか失敗し、envoy_sidecar_log に次のエラーが含まれます。

DeltaAggregatedResources gRPC config stream to trafficdirector.REGION.rep.googleapis.com:443 closed: 7, The caller does not have permission

Cloud Run ランタイム サービス ID に roles/trafficdirector.client がありません。デフォルトでは、--functional-type=agent と --identity-type=agent-identity を使用してサービスをデプロイすると、roles/run.agentDefaultAccess が付与されます。これには roles/trafficdirector.client と roles/cloudtrace.agent が含まれます。サービス ID にこれらの権限がない場合は、ロールを付与します。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME" \
    --role="roles/trafficdirector.client"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME" \
    --role="roles/cloudtrace.agent"

次のように置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • ORGANIZATION_ID: 実際の Google Cloud 組織 ID。
  • PROJECT_NUMBER: Google Cloud プロジェクト番号。
  • REGION: サービスのリージョン。
  • SERVICE_NAME: Cloud Run エージェント サービスの名前。サービスが Agent Identity ではなくサービス アカウントを使用する場合は、--member を serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com に設定します。

Cloud Run サービス エージェントが VPC ネットワークにアクセスできることを確認します。デフォルトでは、roles/run.serviceAgent にはこれらの権限が含まれています。サービス エージェントの権限を変更した場合は、roles/compute.networkUser を付与します。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com" \
    --role="roles/compute.networkUser"

Secure Web Proxy ゲートウェイを更新すると、Envoy トンネリングが中断される

既存の Secure Web Proxy ゲートウェイの ServerTlsPolicy、証明書、IP アドレス、ポートを更新すると、アウトバウンド リクエストが 502、503、504 エラーで失敗するか、envoy_sidecar_log が RESPONSE_FLAGS: UF を報告します。

Secure Web Proxy ゲートウェイの作成後に addresses または ports を変更することはできません。また、既存の Secure Web Proxy ゲートウェイの serverTlsPolicy または certificateUrls の更新は、Traffic Director API の EgressRouting エンドポイントに反映されません。

ワークロードのダウンタイムなしでこれらの Secure Web Proxy フィールドを変更するには、次の操作を行います。

  1. 別のリソース名と更新された構成で、代替の Secure Web Proxy ゲートウェイを作成します。
  2. AgentGateway リソースの selfManaged.resourceUris を更新して、代替の Secure Web Proxy ゲートウェイ URI を参照します。
  3. 置換用の Secure Web Proxy ゲートウェイを指すように EgressRouting リソースを再作成します。
  4. 交換用ゲートウェイがトラフィックをルーティングしたら、AgentGateway リソースから古い Secure Web Proxy ゲートウェイを削除し、古い Secure Web Proxy ゲートウェイを削除します。

Secure Web Proxy がすべてのアウトバウンド トラフィックを拒否する

EgressRouting ポリシーを作成するか、ExtensionBinding をアタッチすると、Cloud Run エージェントからのすべてのアウトバウンド リクエストが 403 エラーで失敗します。

Secure Web Proxy は、Agent Gateway リソースの ALLOW AuthzPolicy で許可されるまで、デフォルトですべてのトラフィックを拒否します。ExtensionBinding を接続しても、ALLOW AuthzPolicy のないトラフィックは許可されません。基盤となる Secure Web Proxy Gateway リソースに接続されたポリシーは無視されます。

承認されたトラフィックを許可するには、Agent Gateway リソースをターゲットとする ALLOW AuthzPolicy を接続します。手順については、ベースラインの下り（外向き）トラフィックと MCP トラフィックを許可するをご覧ください。

アウトバウンド モデル リクエストが 403 エラーで失敗する

Agent Gateway でポリシーを構成した後、Cloud Run エージェントから REGION-aiplatform.googleapis.com の Vertex AI などのモデル エンドポイントへの発信呼び出しが 403 Forbidden エラーで失敗する。

--vpc-egress=all はすべての送信コンテナ トラフィックを Secure Web Proxy 経由でルーティングするため、ALLOW AuthzPolicy が Model Context Protocol（MCP）メソッドのみに一致する場合、または Identity-Aware Proxy（IAP）ExtensionBinding が Identity and Access Management（IAM）統合アクセス ポリシーに許可ルールがない非 MCP ホストに一致する場合、モデル リクエストは失敗します。

アウトバウンド モデル呼び出しを許可するには、Agent Gateway リソースの ALLOW AuthzPolicy でモデル エンドポイントを許可します。また、IAP ExtensionBinding の matchConditions を prefix: "urn:mcp" にスコープ設定するか、IAM 統合アクセス ポリシーに destination.unregistered.host 許可ルールを追加します。手順については、ベースラインの下り（外向き）トラフィックと MCP トラフィックを許可すると IAP 下り（外向き）ポリシーを構成するをご覧ください。

Secure Web Proxy が GatewaySecurityPolicyRules を無視する

GatewaySecurityPolicyRules を作成したか、Secure Web Proxy Gateway リソースに AuthzPolicy を接続しましたが、アウトバウンド エージェント トラフィックには影響しません。

Secure Web Proxy が AgentGateway リソースに関連付けられている場合、Secure Web Proxy は AgentGateway リソースに接続されている認可ポリシーと拡張機能バインディングのみを適用します。基盤となる Secure Web Proxy Gateway に接続されている GatewaySecurityPolicyRules リソースまたは AuthzPolicy リソースは無視されます。

代わりに、AuthzPolicy リソースと ExtensionBinding リソースを Agent Gateway リソースに接続します。手順については、Agent Gateway でポリシーを構成するをご覧ください。

送信リクエストが TLS 検査に失敗する

Cloud Run エージェントからのアウトバウンド リクエストが、すべての接続で TLS エラーで失敗する。

Secure Web Proxy サービス アカウントに、Certificate Authority Service プールの roles/privateca.certificateManager がありません。

CA プールに対する roles/privateca.certificateManager を Secure Web Proxy サービス アカウントに付与します。手順については、サービス アカウントを作成するをご覧ください。

アウトバウンド TLS 検査接続が SSLV3_ALERT_HANDSHAKE_FAILURE または RemoteDisconnected で失敗する

エージェントからのアウトバウンド リクエストが、SSLV3_ALERT_HANDSHAKE_FAILURE を使用した宛先ホストへの最初の接続で失敗するか、RemoteDisconnected で失敗する。

宛先ホストへの最初の TLS 検査接続で、Secure Web Proxy は CA Service からリーフ証明書をミントしてキャッシュに保存します。これにより、一時的な handshake エラーが発生する可能性があります。urllib.request.urlopen など、デフォルトで Connection: close を送信する HTTP クライアントは、TLS インターセプト中に RemoteDisconnected で失敗することがあります。

エージェント コードでこれらのエラーを防止するには:

  • 永続的な接続を再利用する HTTP クライアント（httpx.AsyncClient、requests.Session() など）を使用します。
  • httpx.AsyncHTTPTransport(retries=2) や urllib3.util.Retry などの HTTP クライアントで、接続とハンドシェイクの再試行を構成します。

次のステップ