Observabilidad para desarrolladores de agentes de IA

Si desarrollas agentes de IA, puedes instrumentar tus aplicaciones con OpenTelemetry para observar cómo razonan, llaman a herramientas y responden a instrucciones. En esta guía, se explica cómo capturar la telemetría de los agentes con frameworks como LangGraph y el Kit de desarrollo de agentes (ADK), y cómo analizar las instrucciones y respuestas multimodales en Cloud Trace.

Instrumentar agentes para comprender su comportamiento

Cuando desarrollas o administras aplicaciones de IA generativa, los datos de telemetría capturan los pasos de razonamiento, las llamadas a herramientas y las interacciones externas de tus agentes autónomos. Estos datos son útiles por los siguientes motivos:

  • Comprende el comportamiento no determinístico: Debido a que el proceso de razonamiento de un agente no es determinístico, la telemetría es la única forma confiable de inspeccionar las decisiones que toma un agente y las herramientas que selecciona.
  • Soluciona problemas y diagnostica errores: Los seguimientos te ayudan a identificar solicitudes a la API con errores, bucles de ejecución infinitos y cuellos de botella de latencia en los flujos de trabajo de agentes distribuidos.
  • Apoya la administración y valida el tráfico: La telemetría te permite visualizar los flujos de comunicación, como en la topología de la aplicación, para verificar que tus agentes se comuniquen solo con agentes autorizados, servidores de MCP y extremos externos.
  • Evalúa la calidad y el costo de los resultados: Recopilar instrucciones, respuestas y el uso de tokens te ayuda a evaluar la exactitud del modelo, detectar alucinaciones y optimizar el consumo de recursos.

Cómo puedes instrumentar tus aplicaciones de IA generativa

Instrumentar tu aplicación implica generar telemetría y enviarla a un destino en el que se puedan almacenar, consultar y analizar los datos. Por ejemplo, cuando tu instrumentación envía telemetría a tu proyecto de Google Cloud , puedes usar Google Cloud Observability para ver y analizar esos datos.

Cloud Trace extrae automáticamente eventos de los intervalos escritos por aplicaciones de IA generativa cuando esos intervalos se ajustan a las convenciones semánticas para intervalos y eventos. Para obtener información sobre esas convenciones, consulta los siguientes documentos:

Cloud Trace también puede mostrar instrucciones y respuestas multimodales. En esta situación, tus instrucciones y respuestas no se adjuntan a tus datos de seguimiento. En su lugar, se almacenan en un bucket de Cloud Storage. Para obtener más información sobre esta configuración, consulta Recopila y visualiza instrucciones y respuestas multimodales.

Prácticas recomendadas

Te recomendamos que instrumentes tu aplicación con OpenTelemetry, que es un proyecto de código abierto que proporciona un framework unificado para la instrumentación de aplicaciones. Las muestras de instrumentación que se indican en este documento usan OpenTelemetry.

También te recomendamos que almacenes tus instrucciones y respuestas en un bucket de Cloud Storage en lugar de en una entrada de registro:

  • Tienes un control detallado sobre el contenido del bucket de Cloud Storage. Por ejemplo, puedes borrar conversaciones individuales almacenadas en un bucket. Sin embargo, no puedes borrar entradas de registro individuales.

  • Los buckets de Cloud Storage pueden almacenar objetos que son mucho más grandes que el tamaño máximo de una entrada de registro, que se limita a 256 KiB. Cloud Logging responde con un error INVALID_ARGUMENT y descarta los datos si los datos recibidos superan el tamaño máximo de la entrada de registro. Si el comando se completa sin errores, pero los campos individuales superan sus límites de tamaño, Cloud Logging trunca esos datos.

Para obtener información sobre OpenTelemetry, consulta ¿Qué es OpenTelemetry?.

Ejemplos de instrumentación

Para comenzar con la instrumentación de agentes, consulta las siguientes guías y aplicaciones de ejemplo:

  • En Recopila y visualiza instrucciones y respuestas multimodales, se describe cómo configurar un agente de ReAct de LangGraph o un agente de IA generativa creado con ADK para recopilar instrucciones y respuestas multimodales. También se describe cómo hacer lo siguiente:

    • Almacena instrucciones y respuestas en un bucket de Cloud Storage.
    • Consulta las instrucciones y las respuestas con la página Explorador de seguimiento.
    • Analiza instrucciones y respuestas con BigQuery.
    • Evalúa las instrucciones y las respuestas con el SDK de Vertex AI para Python.

  • En Instrumenta un agente de ReAct de LangGraph con OpenTelemetry, se describe cómo usar OpenTelemetry para instrumentar una aplicación de IA generativa que use el framework de LangChain o LangGraph. También se vincula a una aplicación de ejemplo que puedes descargar y ejecutar. La aplicación de ejemplo recopila instrucciones de texto y respuestas.

  • En Instrumenta aplicaciones de ADK con OpenTelemetry, se describe cómo habilitar la instrumentación integrada que recopila telemetría de las acciones clave del agente. La telemetría incluye instrucciones de texto y respuestas del agente. También se vincula a una aplicación de ejemplo que puedes descargar y ejecutar. La aplicación de ejemplo recopila instrucciones de texto y respuestas.

  • En Investiga las llamadas de MCP con Trace, se describe cómo configurar tu aplicación para pasar el contexto de seguimiento a los servidores de MCP remotos de Google Cloud, lo que permite que esos servidores adjunten intervalos a un seguimiento.