Observabilidad para desarrolladores de agentes de IA

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

Instrumenta 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 de API fallidas, bucles de ejecución infinitos y cuellos de botella de latencia en los flujos de trabajo de agentes distribuidos.
  • Admite la gobernanza 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 MCP y extremos externos.
  • Evalúa la calidad y el costo del resultado: La recopilación de instrucciones, respuestas y uso de tokens te ayuda a evaluar la precisión del modelo, detectar alucinaciones y optimizar el consumo de recursos.

Cómo puedes instrumentar tus aplicaciones de IA generativa

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

Cloud Trace extrae automáticamente eventos de los intervalos escritos por las aplicaciones de IA generativa cuando esos intervalos cumplen con 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 este caso, tus instrucciones y respuestas no están adjuntas 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. En los ejemplos de instrumentación que se enumeran en este documento, se usa 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 está limitado 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 del agente, consulta las siguientes aplicaciones y guías de muestra:

  • En Recopila y visualiza instrucciones y respuestas multimodales , se describe cómo configurar un agente ReAct de LangGraph o un agente de IA generativa compilado 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.
    • Visualiza instrucciones y respuestas con la página del Explorador de Trace.
    • Analiza instrucciones y respuestas con BigQuery.
    • Evalúa instrucciones y respuestas con el SDK de Vertex AI para Python.

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

  • 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 muestra que puedes descargar y ejecutar. La aplicación de muestra recopila instrucciones y respuestas de texto.

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