Utiliser BigQuery Agent Analytics

BigQuery Agent Analytics est une solution Open Source qui vous permet de capturer, d'analyser et de visualiser des données d'interaction d'agents multimodaux à grande échelle en diffusant les interactions brutes des agents (telles que les requêtes, les réponses, les appels d'outils et les erreurs) directement dans BigQuery. Cette solution vous permet d'effectuer des évaluations optimisées par l'IA, d'optimiser les requêtes des agents et d'extraire la mémoire à long terme pour améliorer les interactions futures. BigQuery Agent Analytics est compatible avec l'Agent Development Kit (ADK) et LangGraph (preview).

Architecture

BigQuery Agent Analytics diffuse les données d'activité des agents vers BigQuery à l'aide de l'API BigQuery Storage Write (gRPC), qui fournit une diffusion de journaux à haut débit et à faible latence sans bloquer l'exécution des agents.

Le flux de données comprend les étapes suivantes :

  1. Capture. Utilisez un plug-in de journalisation dans l'ADK ou un gestionnaire de rappels dans LangGraph pour intercepter et capturer les événements d'interaction de l'agent.
  2. Stream. Les événements d'interaction sont envoyés à BigQuery via l'API Storage Write (gRPC). Si aucun schéma standardisé n'existe, l'agent en crée un automatiquement.
  3. Consommation Analyser et évaluer les données d'agent enregistrées. Vous pouvez interroger des données brutes avec SQL, suivre des métriques sur des tableaux de bord personnalisés ou utiliser le SDK BigQuery Agent Analytics pour reconstruire et évaluer des traces d'exécution d'agents multitours complexes.

Schéma montrant les données d'activité des agents circulant des frameworks d'orchestration vers BigQuery pour analyse.

Avantages de l'analyse des agents

  • Activez la journalisation complète avec une seule ligne de code et automatisez la gestion des schémas.
  • Consignez et analysez des données multimodales, telles que du texte, des images, des vidéos et des contenus audio, à l'aide de tables d'objets.
  • Suivez les métriques opérationnelles, telles que la consommation de jetons et la latence, dans un schéma prédéfini robuste.
  • Identifier les opportunités d'optimisation à l'aide des fonctions d'IA générative et de la recherche vectorielle de BigQuery
  • Sécurisez les journaux des agents grâce à des contrôles d'accès précis, au masquage des données et au chiffrement.

Choisir une bibliothèque pour chaque étape du workflow

BigQuery Agent Analytics dispose de deux intégrations de journalisation et d'un SDK d'analyse. Les intégrations de journalisation et le SDK d'analyse servent à différentes étapes de votre workflow :

  • Consigner les événements de l'agent : utilisez l'intégration de journalisation pour votre framework d'agent, soit le plug-in ADK, soit le gestionnaire de rappels LangGraph et LangChain. Vous n'avez besoin que d'une seule intégration de journalisation, et vous n'avez pas besoin du SDK d'analyse pour consigner les événements. Pour les autres frameworks ou pour activer la journalisation des conversations intégrée pour les agents de données d'analyse conversationnelle, consultez Méthodes de capture des données de journal des agents.
  • Analyser les événements de l'agent : utilisez le SDK BigQuery Agent Analytics pour interroger, reconstruire et évaluer les événements consignés. Vous pouvez également analyser les événements à l'aide de requêtes SQL et de tableaux de bord.

Le schéma suivant indique la bibliothèque à utiliser à chaque étape du workflow :

Le plug-in ADK ou le gestionnaire de rappels LangGraph et LangChain transmet les événements de l'agent à une table d'événements BigQuery que vous analysez avec le SDK BigQuery Agent Analytics, des requêtes SQL ou des tableaux de bord.

Le tableau suivant décrit chaque intégration de journalisation et le SDK d'analyse :

Étape du workflow Intégration ou SDK Package et point d'entrée Quand utiliser cette fonctionnalité
Événements de l'agent Logging Plug-in BigQuery Agent Analytics pour ADK

Package Python google-adk[bigquery-analytics]

Classe BigQueryAgentAnalyticsPlugin

Pour les autres langages, comme Java, consultez le guide du plug-in ADK.

 Utilisez-le dans un agent ADK pour diffuser des requêtes LLM, des appels d'outils et des événements de workflow vers BigQuery.
Événements de l'agent Logging Gestionnaire de rappels BigQuery LangGraph et LangChain (preview)

Package Python langchain-google-community[bigquery]

Classe BigQueryCallbackHandler

 Utilisez-le dans une application LangGraph ou LangChain pour diffuser des événements d'exécution d'agent vers BigQuery.
Analyser les événements de l'agent SDK BigQuery Agent Analytics

Package Python bigquery-agent-analytics

Classes Client et GraderPipeline

 Utilisez-le dans des pipelines d'évaluation, des notebooks ou des services d'audit pour lire la table d'événements dans laquelle votre intégration de journalisation écrit, reconstruire des sessions multitours et exécuter des évaluations automatisées.

Méthodes pour capturer les données des journaux d'agent

Pour capturer la télémétrie des interactions de votre agent (requêtes, réponses, appels d'outils et journaux d'erreurs) de manière native dans BigQuery, vous pouvez consigner les données d'événement de plusieurs manières :

  • Plug-ins de framework d'orchestration : utilisez les plug-ins de journalisation standards fournis par votre kit d'outils d'orchestration d'agents. Par exemple, BigQueryAgentAnalyticsPlugin dans ADK se connecte à l'exécuteur d'agent pour intercepter, sérialiser et diffuser automatiquement les événements.
  • Gestionnaires de rappels de framework : intégrez des rappels standards dans les environnements d'agents populaires. Par exemple, vous pouvez utiliser BigQueryCallbackHandler du package langchain-google-community dans LangGraph et LangChain pour intercepter et transférer des traces vers BigQuery.
  • Ingestion directe via l'API : pour les frameworks personnalisés ou propriétaires, utilisez les bibliothèques clientesGoogle Cloud pour diffuser des événements structurés directement dans votre table d'événements à l'aide de l'API Storage Write (gRPC).
  • Agents de données d'analyse conversationnelle : activez la journalisation des conversations intégrée lorsque vous configurez les paramètres d'un agent de données BigQuery dans BigQuery Studio ou via l'API Conversational Analytics pour diffuser automatiquement les événements de conversation vers une table BigQuery de destination et analyser les journaux de conversation.

Quelle que soit la méthode, toutes les options de journalisation utilisent l'API BigQuery Storage Write (gRPC) à faible latence et à haut débit. Cette API fournit un point de terminaison de streaming robuste qui met en mémoire tampon et sérialise les lignes (à l'aide du moteur PyArrow) de manière asynchrone en mémoire avant de les valider, ce qui garantit que les tâches du pipeline d'observabilité ne bloquent pas les tours d'exécution de l'agent visibles par l'utilisateur.

Méthodes d'analyse des données des journaux d'agent

Pour comprendre et optimiser les performances de votre agent, analysez et évaluez les journaux d'interaction de l'une des manières suivantes :

  • Requêtes SQL directes : exécutez des requêtes personnalisées dans BigQuery pour calculer des métriques telles que la consommation de jetons et la latence d'exécution. Vous pouvez également utiliser AI.GENERATE pour l'analyse automatisée des causes principales d'erreurs, ou effectuer des jointures avec des tables d'entreprise pour mesurer l'impact sur l'entreprise.
  • Tableaux de bord interactifs : connectez des outils de visualisation tels que Data Studio à des vues BigQuery prédéfinies ou personnalisées pour suivre l'état de l'agent, les taux d'erreur et les tendances d'utilisation au fil du temps. Les clients Looker peuvent également utiliser un modèle de tableau de bord d'analyse des agents BigQuery prédéfini (bloc Looker) disponible sur Looker Marketplace.
  • Notebooks Jupyter : explorez et testez les données de journaux à l'aide de bibliothèques Python, de pandas ou de BigFrames dans des environnements interactifs.
  • SDK Python : interrogez, reconstruisez et auditez de manière programmatique les traces d'exécution de l'agent directement dans le code de votre application ou dans vos pipelines d'évaluation automatisés.

Exemples d'utilisation des données de journaux d'agent

Voici des cas d'utilisation courants et des exemples d'utilisation des données de journaux d'agent dans BigQuery.

Observabilité et métriques opérationnelles

  • Interrogez les données pour ventiler les coûts par flux d'agent et déterminer si un agent spécifique, tel qu'un agent d'affinement, consomme une quantité disproportionnée de jetons par rapport à sa contribution aux réponses finales.
  • Utilisez l'agent d'analyse conversationnelle BigQuery pour l'analyse des causes profondes optimisée par l'IA en exécutant des requêtes avec la fonction AI.GENERATE. Par exemple : "Analyse ce journal de conversation et explique la cause principale de l'échec."

Évaluation des agents et analyse de la qualité

  • Classez les conversations et mesurez le classement des agents au fil du temps à l'aide de la fonction AI.SCORE.
  • Identifiez les clusters de conversation où l'agent n'a pas réussi à aider les utilisateurs en utilisant une requête SQL avec Vector Search, puis comparez-les à l'intention d'origine de l'utilisateur. Cela vous aide à identifier les lacunes dans les outils ou la base de connaissances de l'agent.

Insights métier et contextualisation

Pour contextualiser les données de l'agent, associez la table agent_events à d'autres tables d'entreprise. Par exemple, affichez la valeur moyenne de la commande (AOV) pour les clients qui ont interagi avec l'agent IA par rapport aux clients qui ont utilisé la barre de recherche.

Pour obtenir d'autres exemples, consultez les recettes de requêtes.

Utiliser un notebook Jupyter pour travailler avec les journaux d'agent

Utilisez cet exemple de notebook Jupyter Colab pour interroger, visualiser et évaluer les journaux d'agent de manière interactive.

Utiliser le SDK BigQuery Agent Analytics

Le SDK BigQuery Agent Analytics est une bibliothèque Python Open Source qui fournit une couche de consommation et d'évaluation pour l'observabilité des agents à long terme. Les tableaux de bord et les notebooks sont d'excellents outils pour l'exploration ad hoc, et le SDK permet d'analyser et d'auditer systématiquement le comportement des agents à grande échelle.

Ce que vous pouvez faire avec le SDK

Vous pouvez effectuer les tâches suivantes à l'aide du SDK d'analyse de l'agent BigQuery. Pour obtenir des exemples détaillés d'analyse des journaux, consultez le dépôt GitHub du SDK.

  • Reconstruction de trace : reconstruisez les journaux d'événements polymorphes en chaînes d'événements causales pour déboguer les sessions sur plusieurs tours, y compris les appels d'outils et de LLM imbriqués.
  • Évaluation déterministe et sémantique : évaluez la qualité de l'agent en fonction de critères basés sur des règles, tels que la latence, le nombre de tours et les taux d'erreur, ainsi que de critères sémantiques, tels que l'exactitude, le sentiment et l'hallucination.
  • Correspondance de trajectoire : comparez les chemins d'exécution réels de l'agent aux trajectoires de référence attendues pour vérifier l'efficacité des étapes et si les outils ont été utilisés dans le bon ordre.
  • Surveillance du comportement et détection des dérives : effectuez des analyses statistiques sur les résultats non déterministes des agents, surveillez les distributions des requêtes utilisateur et détectez les régressions de production ou les dérives sémantiques.
  • Mémoire d'agent à long horizon : fournissez aux agents un contexte intersession, une récupération sémantique du profil utilisateur et une mémoire épisodique tenant compte du budget de jetons stockée de manière native dans BigQuery.

Journaliser et analyser l'activité des agents

Le SDK lit et évalue les événements écrits par une intégration de journalisation. Un workflow type comprend les étapes suivantes :

  1. Enregistrer les interactions : dans votre framework d'orchestration d'agents, associez une intégration de journalisation, telle que BigQueryAgentAnalyticsPlugin dans ADK ou BigQueryCallbackHandler dans LangGraph. Lorsque les utilisateurs interagissent avec votre agent, l'intégration diffuse les événements de manière asynchrone vers BigQuery à l'aide de l'API Storage Write (gRPC) à haut débit. Cette étape ne nécessite pas le SDK.

  2. Initialisez le client : connectez-vous à votre ensemble de données de journaux à partir du SDK 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",
)

    L'extrait utilise les composants suivants :

    • client : instance Client parente qui achemine les requêtes de manière programmatique et gère les connexions de base de données actives.
    • project_id : ID du projet Google Cloud hébergeant l'ensemble de données cible.
    • dataset_id : nom de l'ensemble de données BigQuery stockant les journaux.
    • table_id : table qui stocke les événements consignés (agent_events par défaut). Cette valeur doit correspondre à la table dans laquelle votre intégration de journalisation écrit. Par exemple, BigQueryCallbackHandler dans langchain-google-community version 4.0.0 et versions antérieures écrit par défaut dans agent_events_v2.

  3. Reconstruire une trace de session : récupérez une session de conversation spécifique pour visualiser et examiner la séquence exacte des événements :

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

    L'extrait utilise les composants suivants :

    • trace : objet Trace hydraté contenant l'arborescence de segments DAG hiérarchique reconstruite et liée de manière causale de toutes les actions de l'utilisateur et de l'agent.
    • YOUR_SESSION_ID : identifiant unique de la session que vous souhaitez inspecter.

  4. Exécuter des évaluations automatisées : évaluez de manière programmatique les trajectoires de session ou vérifiez l'absence de régression par rapport à une suite de tests de référence :

    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%}")

    L'extrait utilise les composants suivants :

    • evaluator : évaluateur sémantique (LLMAsJudge) utilisé pour évaluer les sessions (vous pouvez également exécuter des vérifications SystemEvaluator basées sur des règles ou combiner des évaluateurs dans un GraderPipeline pondéré).
    • filters : instance TraceFilter spécifiant la liste session_ids (ou la période et les filtres d'agent) sur laquelle exécuter les évaluations par lot dans BigQuery.
    • report : objet EvaluationReport obtenu contenant les notes brutes de la session, les résumés des métriques et les commentaires de l'évaluateur automatique.

Intégrer BigQuery Agent Analytics à votre workflow

Pour intégrer BigQuery Agent Analytics à votre workflow, procédez comme suit :

  1. Configurez l'intégration de la journalisation pour votre framework d'agent :

  2. Analysez les événements consignés à l'aide du SDK d'analyse de l'agent BigQuery, de l'exemple de notebook Colab ou des recettes de requêtes SQL.

Étapes suivantes