Usa el análisis de agentes de BigQuery

El análisis de agentes de BigQuery es una solución de código abierto que te permite capturar, analizar y visualizar datos de interacción de agentes multimodales a gran escala a través de la transmisión de interacciones sin procesar de los agentes, como solicitudes, respuestas, llamadas a herramientas y errores, directamente a BigQuery. Esta solución te permite realizar evaluaciones potenciadas por IA, optimizar las instrucciones de los agentes y extraer la memoria a largo plazo para mejorar las interacciones futuras. El análisis de agentes de BigQuery es compatible con el Kit de desarrollo de agentes (ADK) y LangGraph (versión preliminar).

Arquitectura

El análisis de agentes de BigQuery transmite datos de actividad de los agentes a BigQuery con la API de BigQuery Storage Write (gRPC), que proporciona transmisión de registros de alta capacidad de procesamiento y baja latencia sin bloquear la ejecución de los agentes.

El flujo de datos consta de las siguientes etapas:

  1. Captura. Usa un complemento de registro en ADK o un controlador de devolución de llamada en LangGraph para interceptar y capturar eventos de interacción del agente.
  2. Transmitir. Los eventos de interacción se envían a BigQuery a través de la API de Storage Write (gRPC). Si no existe un esquema estandarizado, el agente crea uno automáticamente.
  3. Consume. Analizar y evaluar los datos registrados de los agentes Puedes consultar datos sin procesar con SQL, hacer un seguimiento de las métricas en paneles personalizados o usar el SDK de análisis de agentes de BigQuery para reconstruir y evaluar seguimientos complejos de ejecución de agentes de varios turnos.

Diagrama que muestra los datos de actividad de los agentes que fluyen desde los frameworks de organización hacia BigQuery para su análisis.

Beneficios de las estadísticas de agentes

  • Habilita el registro integral con una sola línea de código y automatiza la administración de esquemas.
  • Registra y analiza datos multimodales, como texto, imágenes, video y audio, con tablas de objetos.
  • Realiza un seguimiento de las métricas operativas, como el consumo de tokens y la latencia, dentro de un esquema sólido y predefinido.
  • Identificar oportunidades de optimización con las funciones de IA generativa y la búsqueda de vectores de BigQuery
  • Protege los registros del agente con controles de acceso detallados, enmascaramiento de datos y encriptación.

Elige una biblioteca para cada etapa del flujo de trabajo

El análisis de agentes de BigQuery tiene dos integraciones de registro y un SDK de análisis. Las integraciones de registro y el SDK de análisis se usan en diferentes etapas de tu flujo de trabajo:

  • Registra eventos del agente: Usa la integración de registro para tu framework de agente, ya sea el complemento de ADK o el controlador de devolución de llamada de LangGraph y LangChain. Solo necesitas una integración de registro y no necesitas el SDK de análisis para registrar eventos. Para otros frameworks o para habilitar el registro de conversaciones integrado para los agentes de datos de Conversational Analytics, consulta Formas de capturar datos de registro de agentes.
  • Analiza los eventos del agente: Usa el SDK de análisis de agentes de BigQuery para consultar, reconstruir y evaluar los eventos registrados. También puedes analizar los eventos con consultas en SQL y paneles.

En el siguiente diagrama, se muestra qué biblioteca usar en cada etapa del flujo de trabajo:

El complemento de ADK o el controlador de devolución de llamada de LangGraph y LangChain transmiten eventos de agentes a una tabla de eventos de BigQuery que analizas con el SDK de análisis de agentes de BigQuery, consultas en SQL o paneles.

En la siguiente tabla, se describe cada integración de registro y el SDK de análisis:

Etapa del flujo de trabajo Integración o SDK Paquete y punto de entrada Cuándo se utiliza
Registra eventos de agentes Complemento de análisis de agentes de BigQuery para ADK

Paquete de Python de google-adk[bigquery-analytics]

Clase BigQueryAgentAnalyticsPlugin

Para otros lenguajes, como Java, consulta la guía del complemento de ADK.

 Úsala en un agente de ADK para transmitir solicitudes de LLM, llamadas a herramientas y eventos de flujo de trabajo a BigQuery.
Registra eventos de agentes Controlador de devolución de llamada de LangGraph y LangChain para BigQuery (versión preliminar)

Paquete de Python de langchain-google-community[bigquery]

Clase BigQueryCallbackHandler

 Úsala en una aplicación de LangGraph o LangChain para transmitir eventos de ejecución de agentes a BigQuery.
Analiza los eventos del agente SDK de análisis de agentes de BigQuery

Paquete de Python de bigquery-agent-analytics

Clases Client y GraderPipeline

 Úsala en canalizaciones de evaluación, notebooks o servicios de auditoría para leer la tabla de eventos en la que escribe tu integración de registro, reconstruir sesiones de varios turnos y ejecutar evaluaciones automatizadas.

Formas de capturar los datos de registro del agente

Para capturar la telemetría de interacción de tu agente (solicitudes, respuestas, llamadas a herramientas y registros de errores) de forma nativa en BigQuery, puedes registrar los datos de eventos de varias maneras:

  • Complementos del framework de organización: Usa los complementos de registro estándar que proporciona tu kit de herramientas de organización de agentes. Por ejemplo, el BigQueryAgentAnalyticsPlugin en el ADK se conecta al ejecutor del agente para interceptar, serializar y transmitir eventos automáticamente.
  • Controladores de devolución de llamada del framework: Integra devoluciones de llamada estándar en entornos de agentes populares. Por ejemplo, puedes usar BigQueryCallbackHandler del paquete langchain-google-community en LangGraph y LangChain para interceptar y reenviar seguimientos a BigQuery.
  • Transferencia directa de la API: Para los frameworks personalizados o de propiedad, usa las bibliotecas cliente deGoogle Cloud para transmitir eventos estructurados directamente a tu tabla de eventos con la API de Storage Write (gRPC).
  • Agentes de datos de estadísticas conversacionales: Habilita el registro de conversaciones integrado cuando establezcas la configuración de un agente de datos de BigQuery en BigQuery Studio o a través de la API de Conversational Analytics para transmitir automáticamente eventos de conversación a una tabla de BigQuery de destino y analizar los registros de conversación.

Independientemente del método, todas las opciones de registro usan la API de BigQuery Storage Write (gRPC) de baja latencia y alta capacidad de procesamiento. Esta API proporciona un extremo de transmisión sólido que almacena en búfer y serializa filas (con el motor de PyArrow) de forma asíncrona en la memoria antes de confirmarlas, lo que garantiza que las tareas de la canalización de observabilidad no bloqueen los turnos de ejecución del agente para el usuario.

Formas de analizar los datos de registro del agente

Para comprender y optimizar el rendimiento de tu agente, analiza y evalúa los registros de interacción de las siguientes maneras:

  • Consultas en SQL directas: Ejecuta consultas personalizadas en BigQuery para calcular métricas como el consumo de tokens y la latencia de ejecución. También puedes usar AI.GENERATE para el análisis automatizado de la causa raíz de los errores o realizar uniones con tablas empresariales para medir el impacto empresarial.
  • Paneles interactivos: Conecta herramientas de visualización, como Data Studio, a vistas de BigQuery precompiladas o personalizadas para hacer un seguimiento del estado de los agentes, los porcentajes de errores y las tendencias de uso a lo largo del tiempo. Los clientes de Looker también pueden usar una plantilla de panel de análisis de agentes de BigQuery precompilada (bloque de Looker) de Looker Marketplace.
  • Notebooks de Jupyter: Explora y experimenta con datos de registro usando bibliotecas de Python, pandas o BigFrames en entornos interactivos.
  • SDK de Python: Consulta, reconstruye y audita de manera programática los seguimientos de ejecución de agentes directamente en el código de tu aplicación o en las canalizaciones de evaluación automatizadas.

Ejemplos de trabajo con datos de registro de agentes

A continuación, se muestran casos de uso y ejemplos comunes para trabajar con datos de registros de agentes en BigQuery.

Observabilidad y métricas operativas

  • Consulta los datos para desglosar los costos por flujos de agentes y determinar si un agente específico, como un agente de perfeccionamiento, consume una cantidad desproporcionada de tokens en comparación con su contribución a las respuestas finales.
  • Usa el agente de análisis conversacional de BigQuery para realizar análisis de causa raíz potenciados por IA ejecutando consultas con la función AI.GENERATE. Por ejemplo, "Analiza este registro de conversación y explica la causa raíz de la falla".

Evaluación de agentes y análisis de calidad

  • Clasifica las conversaciones y mide la clasificación de los agentes a lo largo del tiempo con la función AI.SCORE.
  • Identifica los clústeres de conversación en los que el agente no pudo ayudar a los usuarios con una consulta en SQL con Vector Search y, luego, compáralos con la intención original del usuario. Esto te ayuda a identificar brechas en las herramientas o la base de conocimiento del agente.

Estadísticas empresariales y contextualización

Para contextualizar los datos de los agentes, une la tabla agent_events con otras tablas empresariales. Por ejemplo, muestra el valor promedio del pedido (AOV) de los clientes que interactuaron con el agente de IA en comparación con los clientes que usaron la barra de búsqueda.

Para obtener más ejemplos, consulta las recetas de consultas.

Usa un notebook de Jupyter para trabajar con registros de agentes

Usa este notebook de Jupyter de Colab de ejemplo para consultar, visualizar y evaluar los registros de agentes de forma interactiva.

Usa el SDK de análisis de agentes de BigQuery

El SDK de análisis de agentes de BigQuery es una biblioteca de Python de código abierto que proporciona una capa de consumo y evaluación para la observabilidad de agentes a largo plazo. Los paneles y los notebooks son excelentes para la exploración ad hoc, y el SDK proporciona una forma de analizar y auditar de forma sistemática el comportamiento de los agentes a gran escala.

Qué puedes hacer con el SDK

Puedes realizar las siguientes tareas con el SDK de análisis de agentes de BigQuery. Para ver ejemplos detallados de análisis de registros, consulta el repositorio de GitHub para el SDK.

  • Reconstrucción de seguimientos: Reconstruye registros de eventos polimórficos en cadenas causales de eventos para depurar sesiones en varios turnos, incluidas las llamadas anidadas a herramientas y LLM.
  • Evaluación determinística y semántica: Evalúa la calidad del agente en función de criterios basados en reglas, como la latencia, los recuentos de turnos y las tasas de error, así como criterios semánticos, como la corrección, el sentimiento y las alucinaciones.
  • Coincidencia de trayectoria: Compara las rutas de ejecución reales del agente con las trayectorias de referencia esperadas para verificar la eficiencia de los pasos y si las herramientas se usaron en el orden correcto.
  • Supervisión del comportamiento y detección de desviaciones: Realiza análisis estadísticos sobre los resultados no determinísticos de los agentes, supervisa las distribuciones de las solicitudes de los usuarios y detecta regresiones de producción o desviaciones semánticas.
  • Memoria de agentes de largo horizonte: Proporciona a los agentes contexto entre sesiones, recuperación semántica de perfiles de usuario y memoria episódica que tiene en cuenta el presupuesto de tokens almacenada de forma nativa en BigQuery.

Registra y analiza la actividad del agente

El SDK lee y evalúa los eventos que escribe una integración de registro. Un flujo de trabajo típico incluye los siguientes pasos:

  1. Registra las interacciones: En tu framework de organización de agentes, adjunta una integración de registro, como BigQueryAgentAnalyticsPlugin en ADK o BigQueryCallbackHandler en LangGraph. Cuando los usuarios interactúan con tu agente, la integración transmite los eventos de forma asíncrona a BigQuery con la API de Storage Write (gRPC) de alta capacidad de procesamiento. Este paso no requiere el SDK.

  2. Inicializa el cliente: Conéctate a tu conjunto de datos de registro desde el SDK de Python:

    from google.cloud import bigquery
from bigquery_agent_analytics import Client

client = Client(
    project_id="YOUR_PROJECT_ID",
    dataset_id="YOUR_DATASET_ID",
    table_id="agent_events",
)

    El fragmento usa los siguientes componentes:

    • client: Es la instancia superior de Client que enruta de manera programática las consultas y administra las conexiones activas de la base de datos.
    • project_id: Es el ID del proyecto de Google Cloud que aloja el conjunto de datos de destino.
    • dataset_id: Es el nombre del conjunto de datos de BigQuery que almacena los registros.
    • table_id: Es la tabla que almacena los eventos registrados (agent_events de forma predeterminada). Este valor debe coincidir con la tabla en la que escribe tu integración de registro. Por ejemplo, BigQueryCallbackHandler en la versión 4.0.0 y anteriores de langchain-google-community escribe en agent_events_v2 de forma predeterminada.

  3. Reconstruye un seguimiento de sesión: recupera una sesión de conversación específica para visualizar y revisar la secuencia exacta de eventos:

    trace = client.get_session_trace(
    session_id="YOUR_SESSION_ID"
)
trace.render()

    El fragmento usa los siguientes componentes:

    • trace: Es el objeto Trace hidratado que aloja el árbol de intervalos de DAG jerárquico vinculado causalmente y reconstruido de todas las acciones del usuario y del agente.
    • YOUR_SESSION_ID: Es el ID único de la sesión que deseas inspeccionar.

  4. Ejecuta evaluaciones automatizadas: Califica de forma programática las trayectorias de las sesiones o verifica si hay regresiones en un paquete de pruebas de referencia:

    from bigquery_agent_analytics import (
    LLMAsJudge,
    TraceFilter,
)

# Run semantic evaluations across target sessions
evaluator = LLMAsJudge.correctness()
filters = TraceFilter(session_ids=["session_1", "session_2"])

report = client.evaluate(evaluator, filters=filters)
print(f"Evaluation Pass Rate: {report.pass_rate:.2%}")

    El fragmento usa los siguientes componentes:

    • evaluator: Es el evaluador semántico (LLMAsJudge) que se usa para calificar las sesiones (también puedes ejecutar verificaciones de SystemEvaluator basadas en reglas o combinar evaluadores en un GraderPipeline ponderado).
    • filters: Es la instancia de TraceFilter que especifica la lista de session_ids (o el período y los filtros de agentes) con la que se ejecutarán las evaluaciones por lotes en BigQuery.
    • report: Es el objeto EvaluationReport resultante que contiene las calificaciones sin procesar de la sesión, los resúmenes de las métricas y los comentarios del calificador automático.

Integra el análisis de agentes de BigQuery en tu flujo de trabajo

Para integrar el análisis de agentes de BigQuery en tu flujo de trabajo, haz lo siguiente:

  1. Configura la integración de registros para tu framework de agentes:

  2. Analiza los eventos registrados con el SDK de análisis de agentes de BigQuery, el notebook de Colab de ejemplo o las recetas de consultas en SQL.

¿Qué sigue?