Usa BigQuery agent analytics

BigQuery agent analytics 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 mediante la transmisión de interacciones de agentes sin procesar, como solicitudes, respuestas, llamadas a herramientas y errores, directamente a BigQuery. Esta solución te permite realizar evaluaciones basadas en IA, optimizar las instrucciones del agente y extraer la memoria a largo plazo para mejorar las interacciones futuras. BigQuery agent analytics es compatible con el Kit de desarrollo de agentes (ADK) y LangGraph (vista previa).

Arquitectura

BigQuery agent analytics transmite datos de actividad del agente a BigQuery con la API de BigQuery Storage Write, que proporciona transmisión de registros de alta capacidad y baja latencia sin bloquear la ejecución del agente.

El flujo de datos consta de las siguientes etapas:

  1. Capturar. Usa complementos en el Kit de desarrollo de agentes (ADK) o devoluciones de llamadas en LangGraph para interceptar eventos de interacción y capturar eventos del agente.
  2. Transmitir. Los eventos de interacción se envían a BigQuery a través de la API de Storage Write. Si no existe un esquema estandarizado, el agente crea uno automáticamente.
  3. Procesar compra de consumible. Analiza y evalúa los datos registrados del agente. Puedes consultar datos sin procesar con SQL, hacer un seguimiento de las métricas en paneles personalizados o usar el SDK de BigQuery agent analytics para reconstruir y evaluar seguimientos complejos de ejecución de agentes de varios turnos.

Diagrama que muestra el flujo de datos de actividad del agente desde los frameworks de orquestación hacia BigQuery para su análisis.

Beneficios de agent analytics

  • 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.
  • Haz un seguimiento de las métricas operativas, como el consumo de tokens y la latencia, dentro de un esquema sólido y predefinido.
  • Identifica oportunidades de optimización con las funciones de IA generativa y la búsqueda vectorial de BigQuery.
  • Protege los registros de agentes con controles de acceso detallados, enmascaramiento de datos y encriptación.

Formas de capturar datos de registro de agentes

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 datos de eventos de varias maneras:

  • Complementos del framework de organización: Usa complementos de registro estándar que proporciona tu kit de herramientas de organización de agentes. Por ejemplo, el BigQueryAgentAnalyticsPlugin del Kit de desarrollo de agentes (ADK) se conecta al ejecutor del agente para interceptar, serializar y transmitir eventos automáticamente.
  • Controladores de devolución de llamadas del framework: Integra devoluciones de llamadas estándar en entornos de agentes populares. Por ejemplo, puedes usar el controlador de BigQuery integrado en LangGraph y LangChain para interceptar y reenviar seguimientos.
  • Transferencia directa de la API: Para frameworks personalizados o propietarios, usa las Google Cloud bibliotecas cliente para transmitir eventos estructurados directamente a tu tabla de eventos con la API de Storage Write.

Independientemente del método, todas las opciones de registro usan la API de BigQuery Storage Write de baja latencia, 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 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 orientados al usuario.

Formas de analizar datos de registro de agentes

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

  • Consultas directas de SQL: 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 realizar análisis automatizados de causa raíz de errores o realizar uniones con tablas de la empresa 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 del agente, las tasas de error y las tendencias de uso a lo largo del tiempo.
  • Notebooks de Jupyter: Explora y experimenta con datos de registro con bibliotecas de Python, pandas o BigFrames en entornos interactivos.
  • SDK de Python: Consulta, reconstruye y audita de forma programática los seguimientos de ejecución del agente directamente en el código de tu aplicación o en las canalizaciones de evaluación automatizadas.

Ejemplos de cómo trabajar con datos de registro de agentes

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

Observabilidad y métricas operativas

  • Consulta datos para desglosar los costos por flujos de agentes y determinar si un agente específico, como un agente de refinamiento, 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 basados en IA ejecutando consultas con la AI.GENERATE función. 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 AI.SCORE función.
  • Identifica los clústeres de conversación en los que el agente no pudo ayudar a los usuarios con una consulta en SQL con la búsqueda vectorial y, luego, compáralos con la intención original del usuario. Esto te ayuda a identificar las brechas en las herramientas o la base de conocimientos del agente.

Estadísticas y contextualización de la empresa

Para contextualizar los datos del agente, une la tabla agent_events con otras tablas de la empresa . 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 ejemplo de notebook de Jupyter de Colab para consultar, visualizar y evaluar de forma interactiva los registros de agentes.

Usa el SDK de BigQuery agent analytics

El SDK de BigQuery agent analytics 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 notebooks son excelentes para la exploración ad hoc, y el SDK proporciona una forma de analizar y auditar sistemáticamente el comportamiento de los agentes a gran escala.

Qué puedes hacer con el SDK

Puedes realizar las siguientes tareas con el SDK de BigQuery agent analytics. Para obtener ejemplos detallados del análisis de registros, consulta el repositorio de GitHub del 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 determinista 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 precisión, el sentimiento y la alucinación.
  • Coincidencia de trayectoria: Compara las rutas de ejecución reales del agente con las trayectorias doradas 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 desvíos: Realiza análisis estadísticos sobre resultados de agentes no deterministas, supervisa las distribuciones de solicitudes de usuarios y detecta regresiones de producción o desvíos semánticos.
  • Memoria de agentes de largo alcance: Proporciona a los agentes contexto entre sesiones, recuperación semántica de perfiles de usuario y memoria episódica con reconocimiento de presupuesto de tokens almacenada de forma nativa en BigQuery.

Registra y analiza la actividad del agente

Por lo general, la integración del SDK en los flujos de trabajo de tu agente implica los siguientes pasos:

  1. Registra interacciones: Adjunta un complemento de registrador (como BigQueryAgentAnalyticsPlugin en 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 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 Client superior que enruta consultas de forma programática y administra las conexiones de bases de datos activas.
    • project_id: Es el Google Cloud ID del proyecto 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 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_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 intervalo DAG jerárquico reconstruido y vinculado causalmente 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 la sesión o verifica la regresión en comparación con un paquete de pruebas dorado:

    from bigquery_agent_analytics.evaluators import CodeEvaluator, LLMAsJudge
from bigquery_agent_analytics.grader_pipeline import GraderPipeline

# Create a grader pipeline with deterministic and semantic metrics
evaluator = GraderPipeline(
    graders=[
        CodeEvaluator.latency(threshold_ms=5000),
        LLMAsJudge.correctness(),
    ]
)
report = client.evaluate(evaluator, session_ids=["session_1", "session_2"])
print(f"Evaluation Pass Rate: {report.pass_rate:.2%}")

    El fragmento usa los siguientes componentes:

    • evaluator: Es la lógica compilada GraderPipeline estructurada que compone métricas de evaluación semánticas y basadas en reglas heterogéneas.
    • session_ids: Es la lista de cadenas de ID de sesión para ejecutar evaluaciones por lotes en BigQuery.
    • report: Es el objeto EvaluationReport resultante que contiene calificaciones de sesiones sin procesar, resúmenes de métricas, estadísticas de prueba y comentarios del evaluador automático.

Integra BigQuery agent analytics en tu flujo de trabajo

Para integrar BigQuery agent analytics en tu flujo de trabajo, consulta la documentación de tu framework:

¿Qué sigue?