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.iam.gserviceaccount.com.

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.iam.gserviceaccount.com" \
    --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.

Secure Web Proxy lehnt den gesamten ausgehenden Traffic ab

Alle ausgehenden Anfragen von Ihrem Cloud Run-Agenten schlagen mit 403-Fehlern fehl, nachdem Sie eine EgressRouting-Richtlinie erstellt oder eine ExtensionBinding angehängt haben.

Secure Web Proxy lehnt standardmäßig den gesamten Traffic ab, bis eine ALLOW-AuthzPolicy für Ihre Agent Gateway-Ressource ihn zulässt. Wenn Sie eine ExtensionBinding anhängen, wird Traffic ohne ALLOW-AuthzPolicy nicht zugelassen. Richtlinien, die an die zugrunde liegende Secure Web Proxy-Gateway-Ressource angehängt sind, werden ignoriert.

Wenn Sie autorisierten Traffic zulassen möchten, hängen Sie eine ALLOW-AuthzPolicy an, die auf Ihre Agent Gateway-Ressource ausgerichtet ist. Eine Anleitung finden Sie unter Ausgehenden Baseline- und MCP-Traffic zulassen.

Ausgehende Modellanfragen schlagen mit 403-Fehlern fehl

Ausgehende Aufrufe von Ihrem Cloud Run-Agenten an Modellendpunkte wie Vertex AI unter REGION-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 Modellanfragen fehl, wenn Ihre ALLOW-AuthzPolicy nur mit MCP-Methoden (Model Context Protocol) übereinstimmt oder wenn Ihre IAP-ExtensionBinding (Identity-Aware Proxy) mit Nicht-MCP-Hosts ohne Zulassungsregel in Ihrer Unified Access Policy von Identity and Access Management (IAM) übereinstimmt.

Wenn Sie ausgehende Modellaufrufe zulassen möchten, müssen Sie Ihre Modellendpunkte in einer ALLOW-AuthzPolicy für Ihre Agent Gateway-Ressource zulassen. Außerdem müssen Sie entweder den Bereich matchConditions in Ihrer IAP-ExtensionBinding auf prefix: "urn:mcp" festlegen oder eine destination.unregistered.host-Zulassungsregel in Ihrer IAM Unified Access Policy hinzufügen. Eine Anleitung finden Sie unter Ausgehenden Baseline-Traffic und MCP-Traffic zulassen und IAP-Richtlinien für ausgehenden Traffic konfigurieren.

Secure Web Proxy ignoriert GatewaySecurityPolicyRules

Sie haben GatewaySecurityPolicyRules erstellt oder eine AuthzPolicy an die Secure Web Proxy-Ressource Gateway angehängt, aber diese haben keine Auswirkungen auf den ausgehenden Agent-Traffic.

Wenn Secure Web Proxy mit einer AgentGateway-Ressource verknüpft ist, erzwingt Secure Web Proxy nur die Autorisierungsrichtlinien und Erweiterungsbindungen, die an die AgentGateway-Ressource angehängt sind. Alle GatewaySecurityPolicyRules- oder AuthzPolicy-Ressourcen, die an den zugrunde liegenden Secure Web Proxy Gateway angehängt sind, werden ignoriert.

Hängen Sie stattdessen Ihre AuthzPolicy- und ExtensionBinding-Ressourcen an Ihre Agent Gateway-Ressource an. 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