Fehlerbehebung für Agent Gateway

Wenn eine ausgehende Anfrage von Ihrem Cloud Run-Agenten fehlschlägt oder das Agent Gateway umgeht, können Sie den Anfragepfad mit den folgenden Prüfungen verfolgen oder sich die häufigen Probleme und Lösungen ansehen. Eine Anleitung zur Einrichtung finden Sie unter Agenten mit Agent Gateway verwalten.

Bevor der Traffic das Agent Gateway erreicht, ruft der Cloud Run Envoy-Sidecar die Routing- und Zertifikatskonfiguration von der Traffic Director API ab. Der Sidecar-Proxy sendet ausgehenden Traffic über einen mTLS-CONNECT-Tunnel an Secure Web Proxy.

Ausgehendes Routing in den Envoy-Sidecar-Zugriffslogs prüfen

Wenn der Cloud Run Envoy-Sidecar eine ausgehende TCP-Verbindung abfängt, schreibt er einen JSON-Zugriffslogeintrag mit dem Feld jsonPayload.upstream_host in run.googleapis.com%2Fvar%2Flog%2Fenvoy_sidecar_log.

Lösen Sie eine ausgehende Anfrage von Ihrem Cloud Run-Dienst aus und fragen Sie die Sidecar-Zugriffslogs ab:

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)"

Ersetzen Sie Folgendes:

  • SERVICE_NAME: der Name Ihres Cloud Run-Agentendienstes.
  • PROJECT_ID: Projekt-ID in Google Cloud .

Eine fehlerfreie Verbindung über das Gateway gibt eine Ausgabe ähnlich der folgenden zurück:

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

Prüfen Sie die Werte UPSTREAM_HOST und RESPONSE_FLAGS:

  • Wenn UPSTREAM_HOST den Wert envoy://tunnel_internal_listener/ und RESPONSE_FLAGS den Wert - hat, ist die Verbindung fehlerfrei. Der Envoy-Sidecar hat Ihre EgressRouting-Richtlinie abgeglichen und die Verbindung an das Agent Gateway weitergeleitet.
  • Wenn UPSTREAM_HOST eine Ziel-IP-Adresse und ein Port wie 93.184.216.34:443 ist, konnte die Traffic Director API Ihre EgressRouting-Richtlinie nicht abgleichen oder das Ziel-Gateway nicht auflösen. Envoy hat ORIGINAL_DST-Passthrough verwendet und das Agent Gateway umgangen. Weitere Informationen finden Sie unter Ressourcen-URIs für EgressRouting und AgentGateway prüfen.
  • Wenn UPSTREAM_HOST den Wert envoy://tunnel_internal_listener/ hat und RESPONSE_FLAGS den Wert UF oder UH hat oder BYTES_RECEIVED den Wert 0 hat, konnte Envoy den CONNECT-Tunnel zu Secure Web Proxy nicht öffnen. Prüfen Sie die Subnetzverbindung Ihrer Virtual Private Cloud (VPC) oder lesen Sie den Abschnitt Aktualisierung des Secure Web Proxy-Gateways unterbricht Envoy-Tunneling.
  • Wenn keine Zeilen angezeigt werden, prüfen Sie run.googleapis.com%2Frequests, ob die Anfrage Ihren Cloud Run-Container erreicht hat. Prüfen Sie, ob die aktive Überarbeitung --ambient-networking aktiviert. Wenn immer noch keine Zeilen angezeigt werden, lesen Sie den Abschnitt Envoy-Sidecar-xDS- und Verbindungslogs prüfen.

Envoy-Sidecar-xDS- und Verbindungsprotokolle prüfen

Wenn die Envoy-Sidecar-Zugriffslogs keine Einträge zurückgeben oder einen Verbindungsfehler anzeigen, prüfen Sie die Sidecar-xDS- und Upstream-Verbindungslogs:

  1. Prüfen Sie, ob xDS-Streamfehler der Traffic Director API oder Startstatusfehler vorliegen:

    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. Prüfen Sie die Versuche, eine Upstream-Tunnelverbindung zu ambient-swp-connect-cluster herzustellen:

    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)"

    Ersetzen Sie Folgendes:

    • SERVICE_NAME: der Name Ihres Cloud Run-Agentendienstes.
    • PROJECT_ID: Projekt-ID in Google Cloud .

Prüfen Sie die Logeinträge:

  • Wenn die Logs DeltaAggregatedResources gRPC config stream und The caller does not have permission enthalten, fehlt der Dienstidentität roles/trafficdirector.client. Weitere Informationen finden Sie unter Envoy-Sidecar kann keine xDS-Konfiguration empfangen.
  • Wenn die Logs Creating connection to cluster ambient-swp-connect-cluster enthalten, hat Envoy die EgressRouting-Konfiguration empfangen und versucht, eine Verbindung zum Secure Web Proxy herzustellen.

Ressourcen-URIs für EgressRouting und AgentGateway prüfen

Wenn Sie gcloud alpha network-services egress-routings create oder gcloud beta network-services agent-gateways import ausführen, validiert die API die URI-Syntax, ohne zu prüfen, ob die Zielressourcen vorhanden sind. Ein Tippfehler in einem Ressourcennamen oder einer Region führt dazu, dass die Traffic Director API die EgressRouting-Übersetzung überspringt und Envoy Passthrough-Routing verwendet.

Prüfen Sie die gespeicherten URIs und vergleichen Sie sie mit Ihren bereitgestellten Ressourcen:

  1. Prüfen Sie die Ressource EgressRouting. In der Ausgabe werden Projekt-IDs in Projektnummern normalisiert:

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

  2. Listen Sie alle EgressRouting-Ressourcen in der Region auf, um zu prüfen, ob keine doppelte Richtlinie auf denselben Dienst abzielt:

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

  3. Prüfen Sie, ob das Secure Web Proxy-Zielgateway mit dem URI in EgressRouting.gateway und AgentGateway.selfManaged.resourceUris übereinstimmt:

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

    Ersetzen Sie Folgendes:

    • EGRESS_ROUTING_NAME: der Name Ihrer EgressRouting-Ressource.
    • REGION: die Region Ihrer Bereitstellung.
    • PROJECT_ID: Projekt-ID in Google Cloud .
    • SWP_NAME: der Name Ihres Secure Web Proxy-Gateways.

Prüfen Sie, ob alle drei URIs mit Ihrer Projekt-ID oder -nummer, der Region und dem Ressourcennamen übereinstimmen:

  • EgressRouting.sources[].workloadUri:
    • Dienstbezogen: //run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME
    • Projektbezogen: //run.googleapis.com/projects/PROJECT_ID oder //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-Transaktionslogs prüfen

Wenn der Envoy-Sidecar Traffic an Secure Web Proxy weiterleitet, die Anfragen aber fehlschlagen, prüfen Sie die Proxy-Logs wie unter Proxy-Transaktionslogs ansehen beschrieben:

  • Wenn in den Proxy-Logs kein Traffic angezeigt wird, erreichen die Anfragen den Secure Web Proxy nicht. Prüfen Sie Ihre EgressRouting-Konfiguration unter Ressourcen-URIs für EgressRouting und AgentGateway prüfen und Häufige Probleme und Lösungen.
  • Wenn Sie unerwartete DENY- oder ALLOW-Entscheidungen sehen, prüfen Sie jsonPayload.authzPolicyInfo und jsonPayload.agentGatewayInfo im Logeintrag, um die übereinstimmenden AuthzPolicy- und Zielmetadaten zu untersuchen, und prüfen Sie alle ExtensionBinding-Regeln, die an Ihre Agent Gateway-Ressource angehängt sind. Nachdem Sie eine ExtensionBinding-Ressource erstellt oder aktualisiert haben, kann es bis zu fünf Minuten dauern, bis Konfigurationsänderungen an das Gateway weitergegeben werden.

Häufige Probleme und Lösungen

In den folgenden Abschnitten werden häufige Probleme und deren Behebung beschrieben.

Ausgehender Traffic umgeht das Agent Gateway aufgrund eines nicht übereinstimmenden Ressourcen-URI

Ausgehender Traffic von Cloud Run umgeht das Agent-Gateway oder es kommt zu einer Zeitüberschreitung, nachdem egress-routings create erfolgreich war. In envoy_sidecar_log zeigt jsonPayload.upstream_host die Ziel-IP-Adresse und den Port anstelle von envoy://tunnel_internal_listener/ an.

Einer der Ressourcen-URIs EgressRouting oder AgentGateway verweist auf einen nicht vorhandenen Ressourcennamen oder eine nicht übereinstimmende Region. Wenn die Traffic Director API die Kette vom Cloud Run-Dienst zum Secure Web Proxy nicht auflösen kann, wird die Tunnelübersetzung übersprungen und ORIGINAL_DST bereitgestellt.

Führen Sie die Befehle unter Ressourcen-URIs für EgressRouting und AgentGateway prüfen aus, um den nicht übereinstimmenden URI zu finden. Aktualisieren Sie die Konfiguration mit dem entsprechenden Ressourcennamen und der Region und erstellen Sie die Ressource AgentGateway oder EgressRouting neu.

Envoy-Sidecar kann keine xDS-Konfiguration empfangen

Ausgehende Anfragen vom Cloud Run-Container werden abgebrochen oder schlagen fehl und envoy_sidecar_log enthält den folgenden Fehler:

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

Die Cloud Run-Laufzeitdienstidentität hat nicht die Berechtigung roles/trafficdirector.client. Wenn Sie einen Dienst mit --functional-type=agent und --identity-type=agent-identity bereitstellen, wird standardmäßig roles/run.agentDefaultAccess gewährt, einschließlich roles/trafficdirector.client und roles/cloudtrace.agent. Wenn Ihrer Dienstidentität diese Berechtigungen fehlen, weisen Sie die Rollen zu:

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"

Ersetzen Sie Folgendes:

  • PROJECT_ID: Projekt-ID in Google Cloud .
  • ORGANIZATION_ID: Ihre Google Cloud Organisations-ID.
  • PROJECT_NUMBER: Ihre Google Cloud -Projektnummer.
  • REGION: die Region Ihres Dienstes.
  • SERVICE_NAME: der Name Ihres Cloud Run-Agentendienstes. Wenn Ihr Dienst ein Dienstkonto anstelle der Agent-Identität verwendet, setzen Sie --member auf serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID..

Prüfen Sie, ob der Cloud Run-Dienst-Agent auf Ihr VPC-Netzwerk zugreifen kann. Standardmäßig enthält roles/run.serviceAgent diese Berechtigungen. Wenn Sie die Berechtigungen des Dienst-Agents geändert haben, weisen Sie roles/compute.networkUser zu:

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

Durch das Aktualisieren des Secure Web Proxy-Gateways wird das Envoy-Tunneling unterbrochen.

Nachdem Sie die ServerTlsPolicy, das Zertifikat, die IP-Adresse oder den Port eines vorhandenen Secure Web Proxy-Gateways aktualisiert haben, schlagen ausgehende Anfragen mit den Fehlern 502, 503 oder 504 fehl oder envoy_sidecar_log meldet RESPONSE_FLAGS: UF.

Sie können addresses oder ports nach dem Erstellen eines Secure Web Proxy-Gateways nicht mehr ändern. Darüber hinaus werden Aktualisierungen von serverTlsPolicy oder certificateUrls auf einem vorhandenen Secure Web Proxy-Gateway nicht an EgressRouting-Endpunkte in der Traffic Director API weitergegeben.

So ändern Sie diese Secure Web Proxy-Felder ohne Ausfallzeit der Arbeitslast:

  1. Erstellen Sie ein Secure Web Proxy-Ersatz-Gateway mit einem anderen Ressourcennamen und der aktualisierten Konfiguration.
  2. Aktualisieren Sie selfManaged.resourceUris in der Ressource AgentGateway, um auf den Ersatz-URI des Secure Web Proxy-Gateways zu verweisen.
  3. Erstellen Sie die EgressRouting-Ressource neu, sodass sie auf das Ersatz-Secure Web Proxy-Gateway verweist.
  4. Nachdem das Ersatz-Gateway Traffic weitergeleitet hat, entfernen Sie das alte Secure Web Proxy-Gateway aus der AgentGateway-Ressource und löschen Sie das alte Secure Web Proxy-Gateway.

Ausgehende Anfragen schlagen mit 403-Fehlern fehl

Ausgehende Anfragen von Ihrem Cloud Run-Agenten, einschließlich Aufrufen von Modellendpunkten wie Vertex AI unter REGION-aiplatform.googleapis.com oder aiplatform.googleapis.com, schlagen mit 403 Forbidden-Fehlern fehl, nachdem Sie Richtlinien im Agent Gateway konfiguriert haben.

Da --vpc-egress=all den gesamten ausgehenden Container-Traffic über Secure Web Proxy weiterleitet, schlagen Anfragen aus einem der folgenden Gründe fehl:

  • Ihr Identity-Aware Proxy (IAP) ExtensionBinding lässt matchConditions aus (oder stimmt mit Hosts außerhalb von MCP-Servern (Model Context Protocol) überein), ohne dass eine Zulassungsregel für das Ziel in Ihrer Unified Access Policy für Identity and Access Management (IAM) vorhanden ist.
  • An Ihre Agent Gateway-Ressource (oder an den zugrunde liegenden Secure Web Proxy Gateway) ist eine ALLOW-AuthzPolicy angehängt und die ausgehenden Anfragen entsprechen nicht den ALLOW-Regeln.

So lösen Sie dieses Problem:

  • Beschränken Sie den Bereich matchConditions in Ihrer IAP-ExtensionBinding auf prefix: "urn:mcp" für MCP-Server (und optional prefix: "urn:agent" für den Traffic zwischen KI-Agenten), damit Modellaufrufe und andere Nicht-MCP-Ziele die IAP-Prüfung umgehen, oder fügen Sie eine destination.unregistered.host-Zulassungsregel für Ihr Ziel (z. B. REGION-aiplatform.googleapis.com oder aiplatform.googleapis.com) in Ihrer IAM Unified Access Policy hinzu. Eine Anleitung finden Sie unter IAP-Richtlinien für ausgehenden Traffic konfigurieren.
  • Wenn Sie eine AuthzPolicy vom Typ ALLOW angehängt haben, fügen Sie ALLOW-Regeln für die erforderlichen Ziele hinzu oder entfernen Sie die AuthzPolicy, wenn Sie den Traffic nur mit ExtensionBinding-Ressourcen steuern.

Secure Web Proxy ignoriert GatewaySecurityPolicyRules

Sie haben GatewaySecurityPolicyRule-Ressourcen auf dem Secure Web Proxy Gateway erstellt, diese haben jedoch keine Auswirkungen auf den ausgehenden Agent-Traffic.

Wenn Secure Web Proxy mit einer AgentGateway-Ressource verknüpft ist, ignoriert Secure Web Proxy alle GatewaySecurityPolicyRule-Ressourcen auf der zugrunde liegenden Gateway (die TlsInspectionPolicy bleibt aktiv).

Hängen Sie stattdessen ExtensionBinding-Ressourcen an Ihre Agent Gateway-Ressource an. Wenn Sie AuthzPolicy-Ressourcen verwenden, hängen Sie sie nur an Ihre Agent Gateway-Ressource an. Wenn Sie AuthzPolicy-Ressourcen sowohl an das AgentGateway als auch an das zugrunde liegende Secure Web Proxy-Gateway anhängen, führt dies zu einem Konfigurationskonflikt. Eine Anleitung finden Sie unter Richtlinien auf dem Agent-Gateway konfigurieren.

Ausgehende Anfragen bestehen die TLS-Prüfung nicht

Ausgehende Anfragen von Ihrem Cloud Run-Agenten schlagen bei jeder Verbindung mit TLS-Fehlern fehl.

Das Secure Web Proxy-Dienstkonto hat nicht die Berechtigung roles/privateca.certificateManager für Ihren Certificate Authority Service-Pool.

Gewähren Sie Ihrem Secure Web Proxy-Dienstkonto die Berechtigung roles/privateca.certificateManager für den CA-Pool. Informationen dazu finden Sie im Artikel Dienstkonto erstellen.

Ausgehende TLS-geprüfte Verbindungen schlagen mit SSLV3_ALERT_HANDSHAKE_FAILURE oder RemoteDisconnected fehl

Ausgehende Anfragen von Ihrem Agenten schlagen bei der ersten Verbindung zu einem Zielhost mit SSLV3_ALERT_HANDSHAKE_FAILURE oder mit RemoteDisconnected fehl.

Bei der ersten TLS-geprüften Verbindung zu einem Zielhost erstellt Secure Web Proxy ein untergeordnetes Zertifikat vom CA-Dienst und speichert es im Cache. Dies kann zu einem vorübergehenden Handshake-Fehler führen. HTTP-Clients, die standardmäßig Connection: close senden, z. B. urllib.request.urlopen, können während der TLS-Prüfung mit RemoteDisconnected fehlschlagen.

So vermeiden Sie diese Fehler in Ihrem KI-Agenten-Code:

  • Verwenden Sie HTTP-Clients, die persistente Verbindungen wiederverwenden, z. B. httpx.AsyncClient oder requests.Session().
  • Konfigurieren Sie Wiederholungsversuche für Verbindungen und Handshakes auf Ihrem HTTP-Client, z. B. httpx.AsyncHTTPTransport(retries=2) oder urllib3.util.Retry.

Nächste Schritte