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 complementos en el Kit de desarrollo de agentes (ADK) o devoluciones de llamada en LangGraph para interceptar eventos de interacción y capturar eventos de agentes.
  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.

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 Kit de desarrollo de agentes (ADK) se conecta al ejecutor de agentes 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 el controlador integrado de BigQuery en LangGraph y LangChain para interceptar y reenviar seguimientos.
  • 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 Consultas de análisis avanzadas.

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

La integración del SDK en los flujos de trabajo de tu agente suele implicar los siguientes pasos:

  1. Registra las interacciones: Adjunta un complemento de registrador (como el BigQueryAgentAnalyticsPlugin en el ADK) o un controlador de devolución de llamada en tu framework de organización de agentes. Cuando los usuarios interactúan con tu agente, los registros se transmiten de forma asíncrona a BigQuery con la API de Storage Write (gRPC) de alta capacidad de procesamiento.

  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 específica que almacena los eventos de telemetría (agent_events 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%}")

    En el fragmento, se usan 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, consulta la documentación de tu framework:

¿Qué sigue?