Supervisa el tráfico a través de Agent Gateway

Usa esta página para aprender a ver registros, supervisar solicitudes y hacer un seguimiento de los seguimientos distribuidos del tráfico enrutado a través de tu implementación de Agent Gateway.

Cloud Logging

Los registros de Agent Gateway se generan con el recurso supervisado networkservices.googleapis.com/Gateway.

Puedes usar estos registros para supervisar las solicitudes de acceso a la puerta de enlace. Esto incluye los registros que se crean cuando se implementa Agent Gateway en el modo de ejecución de prueba. Para consultar los registros de incumplimientos de ejecución de prueba en las políticas de acceso unificado (UAP) de Identity-Aware Proxy (IAP), las políticas de gobernanza semántica, Model Armor y los Controles del servicio de VPC, y generar un informe consolidado de "se habría bloqueado", consulta Audita los incumplimientos de las políticas de ejecución de prueba en los controles.

Visualiza los registros de una puerta de enlace específica

Para ver los registros de una puerta de enlace específica, completa los siguientes pasos.

Consulta en la consola

  1. En la consola de Google Cloud , accede a la página Explorador de registros.

    Ir a Explorador de registros

  2. Haz clic en el botón de activar o desactivar Mostrar consulta.

  3. Pega lo siguiente en el campo de la consulta.

    resource.type="networkservices.googleapis.com/Gateway"
    resource.labels.location="REGION"
    resource.labels.gateway_name="AGENT_GATEWAY_NAME"
    

    Reemplaza lo siguiente:

    • REGION: Es la región de tu puerta de enlace.
    • AGENT_GATEWAY_NAME: Es el nombre de tu puerta de enlace.
  4. Haz clic en Ejecutar consulta.

Nombres de los registros de Agent Platform

Para consultar tipos específicos de entradas de registro en el Explorador de registros, puedes filtrar tu consulta por nombre de registro con el campo logName. En la siguiente tabla, se describen los nombres de los registros principales que generan el Agent Gateway y las operaciones del lado del agente:

Nombre del registro Descripción
projects/PROJECT_ID/logs/networkservices.googleapis.com%2Fgateway_requests Registros de las decisiones de permitir y denegar de la puerta de enlace.
projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access Registros de auditoría de Cloud para las decisiones de AuthorizeUser de IAP.
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr Errores de inicio y ejecución del agente (motor de razonamiento stderr).
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout Salida estándar del agente (motor de razonamiento stdout).

Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud .

Si usas Model Armor para la limpieza de contenido, esos registros se emiten por separado. Para obtener instrucciones sobre cómo consultar los registros de Model Armor, consulta Visualiza los registros de seguridad de contenido sin procesar en el Explorador de registros.

¿Qué se registra?

Las entradas de registro de Agent Gateway contienen información útil para supervisar y depurar el tráfico que entra y sale de tu puerta de enlace.

Campo Formato del campo Tipo del campo: opcional u obligatorio Descripción
severity
insertID
timestamp
receiveTimestamp
trace
traceSampled
logName
LogEntry Obligatorio Los campos generales, como se describe en una entrada de registro.
httpRequest HttpRequest Obligatorio Un protocolo común para registrar solicitudes HTTP.
resource MonitoredResource Obligatorio

MonitoredResource es el tipo de recurso asociado con una entrada de registro. El tipo de recurso para Agent Gateway es networkservices.googleapis.com/Gateway.

jsonPayload objeto (formato de struct) Obligatorio

Indica la carga útil de la entrada de registro que se expresa como un objeto JSON. El objeto JSON contiene los siguientes campos de Agent Gateway:

  • agentGatewayInfo: Incluye información sobre las solicitudes de Agent Gateway.

    • mcpInfo: Incluye información sobre el método de MCP de la solicitud (por ejemplo, "tools/list" o "tools/call") y el parámetro principal asociado con el método, si lo hay. Por ejemplo, en el caso del método "tools/call", el parámetro es el nombre de la herramienta.
    • agentRegistryResource: Es el nombre del recurso de Agent Registry del servidor de MCP, el agente o el endpoint que coincidió con la solicitud.
  • También puedes inspeccionar los detalles del campo serviceExtensionsInfo para obtener información sobre la extensión de autorización (IAP, Model Armor o cualquier otra) que controló la solicitud.

Latencia de propagación de políticas y de transferencia de registros

Cuando actualices las reglas de acceso de la puerta de enlace o investigues eventos de seguridad, ten en cuenta las siguientes ventanas de propagación y transferencia:

  • Propagación de las políticas de acceso unificado (UAP): Las actualizaciones de las UAP que aplica Agent Gateway (como agregar una regla DENY o cambiar iamEnforcementMode de "DRY_RUN" a "ENFORCE") tienen coherencia eventual. Los cambios directos en las políticas suelen entrar en vigor en un plazo de 2 minutos, pero pueden tardar 7 minutos o más en propagarse de forma global (consulta Propagación de cambios de acceso). Los cambios de membresía en un principalSet pueden tardar varios minutos o incluso horas en sincronizarse.
  • Detención de tráfico de emergencia: Las reglas de UAP se evalúan en las nuevas verificaciones de autorización en Agent Gateway y no finalizan un contenedor de agente ni cierran de forma forzosa las conexiones de transmisión ya establecidas. Para detener de inmediato un agente comprometido o que se comporta de forma inadecuada durante un incidente activo, borra el entorno de ejecución del agente o vuelve a enrutar el tráfico de su revisión, además de aplicar una regla de denegación de puerta de enlace. Para obtener instrucciones, consulta Detención de emergencia y revocación de acceso.
  • Latencia de registros, seguimientos y hallazgos: Agent Gateway evalúa las políticas de IAP y Model Armor de forma síncrona en la ruta de la solicitud y escribe entradas de registro de networkservices.googleapis.com/gateway_requests y cloudaudit.googleapis.com/data_access (AuthorizeUser) casi en tiempo real (por lo general, se pueden buscar en el Explorador de registros en cuestión de segundos). Los intervalos de seguimiento distribuido exportados a Trace también aparecen en cuestión de segundos después de que se completa el intervalo, mientras que las detecciones de amenazas fuera de banda de la Detección de anomalías en agentes se evalúan de forma asíncrona (consulta Latencia de los hallazgos de telemetría y seguridad).

Retén y exporta los registros de auditoría de la puerta de enlace a una SIEM

Para conservar las decisiones de acceso de Agent Gateway como evidencia de cumplimiento a prueba de manipulaciones y centralizar la supervisión de amenazas, puedes bloquear tus buckets de Logging y transmitir los registros de la puerta de enlace a una plataforma de administración de información y eventos de seguridad (SIEM):

  • Retención a prueba de manipulaciones (buckets de registros bloqueados): Enruta los registros de networkservices.googleapis.com/gateway_requests y cloudaudit.googleapis.com/data_access a un bucket de Logging personalizado con un período de retención configurado (--retention-days) y bloquea el bucket de forma permanente (gcloud logging buckets update BUCKET_ID --location=LOCATION --locked) para aplicar el almacenamiento de cumplimiento de escritura única y lecturas múltiples (WORM). Para obtener instrucciones paso a paso, consulta Retención con evidencia de alteración para los registros de auditoría.
  • Exportación de SIEM: Crea un receptor de registros de Logging (o un receptor agregado a nivel de la organización) con un filtro de inclusión para logName:("networkservices.googleapis.com%2Fgateway_requests" OR "cloudaudit.googleapis.com%2Fdata_access") para exportar de forma continua las decisiones de permitir y denegar de la puerta de enlace a Google Security Operations (Google SecOps), Pub/Sub (para la transferencia de SIEM de terceros), BigQuery o Cloud Storage. Para obtener ejemplos de filtros y comandos de creación de receptores de gcloud CLI, consulta Exporta registros de auditoría a un SIEM.

Cloud Monitoring

Agent Gateway exporta algunas métricas de Service Extensions a Monitoring. Si delegas la autorización a las extensiones de servicio, puedes usar estas métricas para supervisar el tráfico hacia y desde tu extensión. Para obtener más detalles, consulta Registro y supervisión de las llamadas de Cloud Load Balancing.

Panel de observabilidad

Agent Gateway proporciona un panel de observabilidad que te permite supervisar, auditar y depurar el tráfico enrutado a través de tus puertas de enlace:

  • Tarjetas de puntuación: Realiza un seguimiento de la cantidad total de intentos de autorización, fallas de autorización y solicitudes por segundo.
  • Gráficos: Visualiza los porcentajes de fallas de autorización (%) y las solicitudes por segundo a lo largo del tiempo.
  • Registros de tráfico de salida: Revisa los registros detallados de las consultas de salida, incluidos los rechazos de 403, el tráfico a extremos no registrados y las tendencias generales del tráfico.

Sigue estos pasos para acceder al panel de observabilidad de una puerta de enlace en la consola de Google Cloud :

  1. En la consola de Google Cloud , ve a la página Agent Gateway.

    Ir a Agent Gateway

  2. Haz clic en el nombre de la puerta de enlace que quieres supervisar.

  3. Haz clic en la pestaña Observabilidad.

Requisitos de datos del panel

El panel de observabilidad de Agent Gateway usa Estadísticas de observabilidad para mostrar datos. Si el panel no carga datos, asegúrate de actualizar el bucket de registros _Default para usar Estadísticas de observabilidad. El panel recupera datos de la vista _AllLogs del bucket _Default.

Usa Cloud Trace

Agent Gateway se integra en Cloud Trace para proporcionar observabilidad de extremo a extremo de las solicitudes para las cargas de trabajo de los agentes. Debido a que Agent Gateway funciona como el punto de control central para los agentes de IA, habilitar Trace te brinda visibilidad sobre cómo viajan las solicitudes desde tus agentes a través de la puerta de enlace y por varios servicios, herramientas, agentes y servidores de MCP de Google Cloud . Con el seguimiento de los flujos de solicitudes en estos límites de servicio, Trace ofrece un seguimiento distribuido completo para tus arquitecturas de agentes.

Con Trace, puedes hacer lo siguiente:

  • Depura las interacciones de los agentes con precisión: Realiza un seguimiento del recorrido completo de una solicitud a través de los límites de los servicios para aislar los cuellos de botella de latencia y las llamadas de backend con errores.
  • Respeta las decisiones de muestreo ascendente: Usa el muestreo basado en el elemento superior para mantener la continuidad de los seguimientos de extremo a extremo cuando los agentes o clientes ascendentes inicien el seguimiento, lo que garantiza que las solicitudes de alta prioridad se capturen por completo sin aumentar las tasas de muestreo del modelo de referencia para el tráfico de rutina.
  • Unifica la observabilidad con estándares abiertos: Basados en los estándares de OpenTelemetry y TraceContext de W3C, los seguimientos propagan el contexto sin problemas en tus agentes de IA, Agent Gateway, servidores de MCP de destino y plataformas de supervisión de terceros.
  • Acelera el análisis de la causa raíz: Correlaciona los intervalos de seguimiento directamente con los registros y las métricas de solicitudes de la puerta de enlace con trace_id para solucionar problemas de producción con mayor rapidez.

Para obtener más información sobre Trace, consulta la descripción general de Cloud Trace.

Roles obligatorios

Debes tener los siguientes roles de Identity and Access Management (IAM) en tu proyecto:

  • Para configurar y actualizar una política de seguimiento: Administrador de red de Compute (roles/compute.networkAdmin) o Administrador de Compute (roles/compute.admin)
  • Para ver seguimientos en la consola de Google Cloud : Usuario de Cloud Trace (roles/cloudtrace.user)

Además, para permitir que Agent Gateway escriba intervalos de seguimiento en Trace, debes otorgar el rol de agente de Cloud Trace (roles/cloudtrace.agent) a las siguientes cuentas de servicio:

  • Agente de servicio de Compute Engine: service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com
  • Agente de servicio de seguridad de redes: service-PROJECT_NUMBER@gcp-sa-networksecurity.iam.gserviceaccount.com
  • Agente de servicio de Agent Gateway: service-PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com
  • Cuenta de servicio de carga de trabajo del agente o del cliente: Si el agente de IA o la carga de trabajo del cliente que realiza la llamada inicia el seguimiento y exporta sus propios intervalos superiores a Trace, también se debe otorgar el rol roles/cloudtrace.agent en el proyecto a la cuenta de servicio de la carga de trabajo o a la cuenta de servicio personalizada adjunta al agente. De lo contrario, solo se escribe el intervalo secundario de Agent Gateway y faltará el intervalo principal en Trace.

Reemplaza PROJECT_NUMBER por el número del proyecto de Google Cloud .

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Habilita el seguimiento

Para habilitar el seguimiento de Agent Gateway, crea un archivo YAML de política de observabilidad y, luego, impórtalo con gcloud CLI.

  1. Crea un archivo de configuración llamado tracing-policy.yaml:

    name: "projects/PROJECT_ID/locations/REGION/telemetryPolicies/POLICY_NAME"
    telemetryTarget:
      resources: # You can attach a policy to multiple gateways
      - "//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME"
    displayName: "Tracing policy for Agent Gateway traffic"
    tracingConfiguration:
      samplingRate: SAMPLING_RATE
      parentBasedSampling:
        enabled: ENABLE_PARENT_BASED_SAMPLING
        samplingRate: PARENT_BASED_SAMPLING_RATE
    

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • REGION: Es la región de tu puerta de enlace (por ejemplo, europe-west1).
    • POLICY_NAME: Es un nombre para la política de observabilidad (por ejemplo, my-agw-tracing-policy).
    • AGENT_GATEWAY_NAME: Es el nombre de tu puerta de enlace.
    • SAMPLING_RATE: Es la fracción de solicitudes que se deben rastrear. Establece un valor de 0.0 a 1.0. Para entornos de producción con mucho tráfico, recomendamos una tasa del 1% (0.01) o del 0.1% (0.001) para equilibrar los costos de observabilidad y de transferencia.
    • ENABLE_PARENT_BASED_SAMPLING: Controla si se debe respetar el bit de muestreo en los encabezados traceparent entrantes de los emisores upstream. Se establece en true o false.
    • PARENT_BASED_SAMPLING_RATE: Es la fracción de solicitudes previamente muestreadas que se deben rastrear. Establece un valor de 0.0 a 1.0. Por ejemplo, 1.0 realiza un seguimiento del 100% de las solicitudes previamente muestreadas.
  2. Importa la política de observabilidad:

    gcloud beta network-services telemetry-policies import POLICY_NAME \
       --source=tracing-policy.yaml \
       --location=REGION
    

Ver seguimientos

Después de habilitar el seguimiento distribuido y enviar tráfico a través de la puerta de enlace, puedes ver los detalles del seguimiento en la consola de Google Cloud :

  1. En la consola de Google Cloud , ve a la página Explorador de seguimiento:

    Ve al Explorador de seguimiento

    También puedes usar la barra de búsqueda para encontrar esta página.

  2. En la barra Filtro, ingresa una expresión de filtro de seguimiento (por ejemplo, para filtrar por umbral de latencia, código de estado HTTP o URI de solicitud) o busca por el ID de seguimiento específico.

    Para obtener más información sobre cómo usar la IU del Explorador de seguimiento, consulta Busca y explora seguimientos.

    Explorador de seguimiento

    Vista del Explorador de seguimiento en Trace
    Vista del Explorador de seguimiento en Trace

    Vista de línea de tiempo de seguimiento

    Vista de línea de tiempo en Trace
    Vista de línea de tiempo en Trace

    Vista de gráfico de seguimiento

    Vista de gráfico en Trace
    Vista de gráfico en Trace

Correlaciona seguimientos con registros y métricas

Agent Gateway proporciona una correlación fluida entre los seguimientos, los registros y las métricas:

  • Correlación de registro y seguimiento: Cada entrada de registro de solicitud de puerta de enlace escrita en Logging contiene un campo trace con el formato projects/PROJECT_ID/traces/TRACE_ID.

    • En el Explorador de registros, haz clic en la entrada de registro y, luego, selecciona Ver detalles del seguimiento para navegar directamente al intervalo correspondiente en Trace.
    • En Trace, haz clic en Mostrar registros en el panel Detalles del seguimiento para ver todos los registros de solicitudes de puerta de enlace asociados con esa solicitud.
  • Correlación de métricas: Compara los picos de latencia observados en las métricas de Monitoring, como networkservices.googleapis.com/agentgateway/total_latencies, con los desgloses de intervalos de seguimiento para identificar si se produjo un pico de latencia dentro de la puerta de enlace o en la herramienta o el servidor de destino.

Soluciona problemas

En esta sección, se describen los problemas comunes y sus soluciones.

  • Los seguimientos no aparecen en Cloud Trace:

    1. Verifica que la API de Cloud Trace (cloudtrace.googleapis.com) esté habilitada en tu proyecto:

      gcloud services enable cloudtrace.googleapis.com --project=PROJECT_ID
      
    2. Verifica que se hayan otorgado los roles de IAM de agente de Cloud Trace (roles/cloudtrace.agent) necesarios a todas las cuentas de servicio requeridas.

    3. Verifica que la política de observabilidad exista en la región correcta y que haga referencia a la puerta de enlace de Agent Gateway adecuada:

      gcloud beta network-services telemetry-policies describe POLICY_NAME \
          --location=REGION
      
    4. Verifica el samplingRate configurado. Si el volumen de tráfico es bajo o la tasa de muestreo es baja, es posible que los seguimientos no se capturen de inmediato. Para confirmar que el seguimiento funciona, puedes actualizar de forma temporal tu política para usar un muestreo del 100% (samplingRate: 1.00). Restablece tu tasa de producción cuando termines de realizar las pruebas.

  • Intervalos de seguimiento incompletos:

    Si los intervalos de seguimiento aparecen como seguimientos raíz independientes o desconectados en lugar de intervalos secundarios de las solicitudes de tu aplicación, haz lo siguiente:

    1. Verifica que parentBasedSampling esté habilitado (establecido en true) en tu política de observabilidad.
    2. Verifica que a la cuenta de servicio del agente de IA o de la carga de trabajo que realiza la llamada se le haya otorgado el rol de agente de Cloud Trace (roles/cloudtrace.agent) en el proyecto para que los intervalos superiores se puedan exportar a Trace.
    3. Verifica que tu aplicación use un SDK de OpenTelemetry que tenga habilitada la propagación del contexto de seguimiento distribuido para que el encabezado traceparent de W3C se propague entre los límites del servicio. Para obtener más información, consulta la documentación del propagador TraceContext de OpenTelemetry.

¿Qué sigue?

Codelab

Aprende a controlar las cargas de trabajo de agentes con Agent Gateway en Gemini Enterprise Agent Platform.

Solución de problemas

Obtén información para solucionar problemas de conectividad de Agent Gateway.