Soluciona problemas de Agent Gateway

Cuando una solicitud saliente de tu agente de Cloud Run falla o omite Agent Gateway, sigue la ruta de la solicitud con las siguientes verificaciones o consulta Problemas comunes y soluciones. Para obtener instrucciones de configuración, consulta Administra agentes con Agent Gateway.

Antes de que el tráfico llegue a Agent Gateway, el sidecar de Envoy de Cloud Run recupera la configuración de enrutamiento y certificados de la API de Traffic Director. El sidecar envía tráfico saliente a través de un túnel mTLS CONNECT al Secure Web Proxy.

Verifica el enrutamiento de salida en los registros de acceso del sidecar de Envoy

Cuando el archivo adicional de Envoy de Cloud Run intercepta una conexión TCP saliente, escribe una entrada de registro de acceso JSON en run.googleapis.com%2Fvar%2Flog%2Fenvoy_sidecar_log con el campo jsonPayload.upstream_host.

Activa una solicitud saliente desde tu servicio de Cloud Run y consulta los registros de acceso del archivo adicional:

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

Reemplaza lo siguiente:

  • SERVICE_NAME: Es el nombre de tu servicio de agente de Cloud Run.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .

Una conexión en buen estado a través de la puerta de enlace devuelve un resultado similar al siguiente:

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

Verifica los valores de UPSTREAM_HOST y RESPONSE_FLAGS:

  • Si UPSTREAM_HOST es envoy://tunnel_internal_listener/ y RESPONSE_FLAGS es -, la conexión está en buen estado. El sidecar de Envoy coincidió con tu política de EgressRouting y reenvió la conexión a Agent Gateway.
  • Si UPSTREAM_HOST es una dirección IP y un puerto de destino, como 93.184.216.34:443, la API de Traffic Director no pudo coincidir con tu política de EgressRouting ni resolver la puerta de enlace de destino. Envoy usó el paso de ORIGINAL_DST y omitió Agent Gateway. Consulta Audita los URIs de recursos de EgressRouting y AgentGateway.
  • Si UPSTREAM_HOST es envoy://tunnel_internal_listener/ y RESPONSE_FLAGS es UF o UH, o BYTES_RECEIVED es 0, Envoy no pudo abrir el túnel CONNECT a Secure Web Proxy. Verifica la conectividad de la subred de la nube privada virtual (VPC) o consulta La actualización de la puerta de enlace de Secure Web Proxy interrumpe la tunelización de Envoy.
  • Si no aparece ninguna fila, verifica run.googleapis.com%2Frequests para confirmar que la solicitud llegó a tu contenedor de Cloud Run. Verifica que tu revisión activa habilite --ambient-networking. Si las filas aún no aparecen, consulta Verifica los registros de conexión y xDS del archivo adicional de Envoy.

Verifica los registros de conexión y xDS del archivo adicional de Envoy

Si los registros de acceso del sidecar de Envoy no devuelven entradas o muestran una falla de conexión, inspecciona los registros de conexión de xDS y upstream del sidecar:

  1. Verifica si hay errores de transmisión de xDS de la API de Traffic Director o el estado de inicio:

    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. Verifica los intentos de conexión del túnel ascendente a 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)"

    Reemplaza lo siguiente:

    • SERVICE_NAME: Es el nombre de tu servicio de agente de Cloud Run.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .

Verifica los mensajes de registro:

  • Si los registros contienen DeltaAggregatedResources gRPC config stream y The caller does not have permission, a la identidad del servicio le falta roles/trafficdirector.client. Consulta El archivo adicional de Envoy no puede recibir la configuración de xDS.
  • Si los registros contienen Creating connection to cluster ambient-swp-connect-cluster, Envoy recibió la configuración de EgressRouting y trató de conectarse a Secure Web Proxy.

Audita los URIs de recursos de EgressRouting y AgentGateway

Cuando ejecutas gcloud alpha network-services egress-routings create o gcloud beta network-services agent-gateways import, la API valida la sintaxis del URI sin verificar si existen los recursos objetivo. Un error tipográfico en un nombre de recurso o región hace que la API de Traffic Director omita la traducción de EgressRouting, y Envoy usa el enrutamiento de transferencia.

Inspecciona los URI almacenados y compáralos con tus recursos implementados:

  1. Inspecciona el recurso EgressRouting. En el resultado, se normalizan los IDs de los proyectos en números de proyectos:

    gcloud alpha network-services egress-routings describe EGRESS_ROUTING_NAME \
       --location=REGION \
       --project=PROJECT_ID
  2. Enumera todos los recursos EgressRouting de la región para confirmar que ninguna política duplicada se oriente al mismo servicio:

    gcloud alpha network-services egress-routings list \
       --location=REGION \
       --project=PROJECT_ID
  3. Verifica que la puerta de enlace de Secure Web Proxy de destino coincida con el URI en EgressRouting.gateway y AgentGateway.selfManaged.resourceUris:

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

    Reemplaza lo siguiente:

    • EGRESS_ROUTING_NAME: Es el nombre de tu recurso EgressRouting.
    • REGION: Es la región de tu implementación.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • SWP_NAME: Es el nombre de tu puerta de enlace de Secure Web Proxy.

Verifica que los tres URIs coincidan con el ID del proyecto o número, la región y el nombre del recurso:

  • EgressRouting.sources[].workloadUri:
    • Permisos con alcance de servicio: //run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME
    • Con alcance de proyecto: //run.googleapis.com/projects/PROJECT_ID o //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

Verifica los registros de transacciones de Secure Web Proxy

Si el sidecar de Envoy reenvía el tráfico a Secure Web Proxy, pero las solicitudes fallan, inspecciona los registros del proxy como se describe en Visualiza los registros de transacciones del proxy:

  • Si no aparece tráfico en los registros del proxy, las solicitudes no llegan a Secure Web Proxy. Verifica la configuración de EgressRouting en Audita los URI de recursos de EgressRouting y AgentGateway y Problemas y soluciones habituales.
  • Si ves decisiones DENY o ALLOW inesperadas, verifica jsonPayload.authzPolicyInfo y jsonPayload.agentGatewayInfo en la entrada de registro para inspeccionar los metadatos de destino y AuthzPolicy coincidentes, y verifica las reglas de ExtensionBinding adjuntas a tu recurso de Agent Gateway. Después de crear o actualizar un recurso ExtensionBinding, los cambios de configuración pueden tardar hasta cinco minutos en propagarse a la puerta de enlace.

Problemas comunes y soluciones

En las siguientes secciones, se describen los problemas habituales y cómo resolverlos.

El tráfico saliente omite Agent Gateway debido a un URI de recurso que no coincide

El tráfico saliente de Cloud Run omite Agent Gateway o se agota el tiempo de espera después de que se realiza correctamente egress-routings create. En envoy_sidecar_log, jsonPayload.upstream_host muestra la dirección IP y el puerto de destino en lugar de envoy://tunnel_internal_listener/.

Uno de los URI de recursos EgressRouting o AgentGateway hace referencia a un nombre de recurso inexistente o a una región que no coincide. Cuando la API de Traffic Director no puede resolver la cadena desde el servicio de Cloud Run hasta Secure Web Proxy, omite la traducción del túnel y entrega ORIGINAL_DST.

Ejecuta los comandos en Audita los URI de recursos de EgressRouting y AgentGateway para encontrar el URI que no coincide. Actualiza la configuración con el nombre y la región del recurso coincidentes, y vuelve a crear el recurso AgentGateway o EgressRouting.

El sidecar de Envoy no puede recibir la configuración de xDS

Las solicitudes salientes del contenedor de Cloud Run agotan el tiempo de espera o fallan, y envoy_sidecar_log contiene el siguiente error:

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

La identidad del servicio del entorno de ejecución de Cloud Run no tiene roles/trafficdirector.client. De forma predeterminada, implementar un servicio con --functional-type=agent y --identity-type=agent-identity otorga roles/run.agentDefaultAccess, que incluye roles/trafficdirector.client y roles/cloudtrace.agent. Si a tu identidad de servicio le faltan estos permisos, otorga los roles:

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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • ORGANIZATION_ID: Es el ID de la organización de Google Cloud .
  • PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
  • REGION: Es la región de tu servicio.
  • SERVICE_NAME: Es el nombre de tu servicio de agente de Cloud Run. Si tu servicio usa una cuenta de servicio en lugar de la identidad del agente, establece --member en serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com.

Confirma que el agente de servicio de Cloud Run pueda acceder a tu red de VPC. De forma predeterminada, roles/run.serviceAgent incluye estos permisos. Si modificaste los permisos del agente de servicio, otorga 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"

La actualización de la puerta de enlace de Secure Web Proxy interrumpe la tunelización de Envoy

Después de actualizar el ServerTlsPolicy, el certificado, la dirección IP o el puerto de una puerta de enlace de Secure Web Proxy existente, las solicitudes salientes fallan con errores 502, 503 o 504, o envoy_sidecar_log informa RESPONSE_FLAGS: UF.

No puedes cambiar addresses ni ports después de crear una puerta de enlace de Secure Web Proxy. Además, las actualizaciones de serverTlsPolicy o certificateUrls en una puerta de enlace de Secure Web Proxy existente no se propagan a los extremos de EgressRouting en la API de Traffic Director.

Para cambiar estos campos de Secure Web Proxy sin tiempo de inactividad de la carga de trabajo, completa los siguientes pasos:

  1. Crea una puerta de enlace de Secure Web Proxy de reemplazo con un nombre de recurso diferente y la configuración actualizada.
  2. Actualiza selfManaged.resourceUris en el recurso AgentGateway para hacer referencia al URI de la puerta de enlace de Secure Web Proxy de reemplazo.
  3. Vuelve a crear tu recurso EgressRouting para que apunte a la puerta de enlace de Secure Web Proxy de reemplazo.
  4. Después de que la puerta de enlace de reemplazo enrute el tráfico, quita la puerta de enlace de Secure Web Proxy antigua del recurso AgentGateway y bórrala.

Las solicitudes salientes fallan con errores 403

Las solicitudes salientes de tu agente de Cloud Run, incluidas las llamadas a los extremos del modelo, como Vertex AI en REGION-aiplatform.googleapis.com o aiplatform.googleapis.com, fallan con errores 403 Forbidden después de configurar las políticas en Agent Gateway.

Debido a que --vpc-egress=all enruta todo el tráfico saliente del contenedor a través de Secure Web Proxy, las solicitudes fallan por uno de los siguientes motivos:

  • Tu Identity-Aware Proxy (IAP) ExtensionBinding omite matchConditions (o coincide con hosts fuera de los servidores del protocolo de contexto del modelo [MCP]) sin una regla de permiso para el destino en tu política de acceso unificado de Identity and Access Management (IAM).
  • Se adjunta una ALLOW AuthzPolicy a tu recurso de Agent Gateway (o al Secure Web Proxy Gateway subyacente), y las solicitudes salientes no coinciden con sus reglas de ALLOW.

Para solucionar este problema, sigue estos pasos:

  • Limita el alcance de matchConditions en tu ExtensionBinding de IAP a prefix: "urn:mcp" para los servidores de MCP (y, de forma opcional, prefix: "urn:agent" para el tráfico de agente a agente) de modo que las llamadas de modelos y otros destinos que no sean de MCP omitan la evaluación de IAP, o bien agrega una regla de permiso destination.unregistered.host para tu destino (como REGION-aiplatform.googleapis.com o aiplatform.googleapis.com) en tu política de acceso unificado de IAM. Para obtener instrucciones, consulta Configura políticas de salida de IAP.
  • Si adjuntaste un AuthzPolicy de ALLOW, agrega reglas de ALLOW para tus destinos obligatorios o quita el AuthzPolicy si controlas el tráfico solo con recursos de ExtensionBinding.

Secure Web Proxy ignora las GatewaySecurityPolicyRules

Creaste recursos GatewaySecurityPolicyRule en el Secure Web Proxy Gateway, pero no tienen efecto en el tráfico saliente del agente.

Cuando Secure Web Proxy se asocia con un recurso AgentGateway, Secure Web Proxy ignora todos los recursos GatewaySecurityPolicyRule en la Gateway subyacente (su TlsInspectionPolicy permanece activa).

En su lugar, adjunta recursos ExtensionBinding a tu recurso de Agent Gateway. Si usas recursos AuthzPolicy, adjúntalos solo a tu recurso de Agent Gateway. Si adjuntas recursos AuthzPolicy tanto a AgentGateway como al Secure Web Proxy Gateway subyacente, se produce un conflicto de configuración. Para obtener instrucciones, consulta Configura políticas en Agent Gateway.

Las solicitudes de salida fallan en la inspección de TLS

Las solicitudes salientes de tu agente de Cloud Run fallan con errores de TLS en cada conexión.

A la cuenta de servicio de Secure Web Proxy le falta roles/privateca.certificateManager en tu grupo de Certificate Authority Service.

Otorga roles/privateca.certificateManager en el grupo de AC a tu cuenta de servicio de Secure Web Proxy. Para obtener instrucciones, consulta Crea una cuenta de servicio.

Las conexiones salientes con inspección de TLS fallan con SSLV3_ALERT_HANDSHAKE_FAILURE o RemoteDisconnected

Las solicitudes salientes de tu agente fallan en la primera conexión a un host de destino con SSLV3_ALERT_HANDSHAKE_FAILURE o con RemoteDisconnected.

En la primera conexión con inspección de TLS a un host de destino, Secure Web Proxy crea y almacena en caché un certificado de hoja del Servicio de CA, lo que puede provocar un error de protocolo de enlace transitorio. Los clientes HTTP que envían Connection: close de forma predeterminada, como urllib.request.urlopen, pueden fallar con RemoteDisconnected durante la intercepción de TLS.

Para evitar estos errores en el código de tu agente, haz lo siguiente:

  • Usa clientes HTTP que reutilicen conexiones persistentes, como httpx.AsyncClient o requests.Session().
  • Configura los reintentos de conexión y de protocolo de enlace en tu cliente HTTP, como httpx.AsyncHTTPTransport(retries=2) o urllib3.util.Retry.

¿Qué sigue?