Utiliser BigQuery Agent Analytics

BigQuery Agent Analytics est une solution Open Source qui vous permet de capturer, d'analyser et de visualiser à grande échelle les données d'interaction des agents multimodaux en diffusant des interactions brutes (requêtes, réponses, appels d'outils et erreurs, par exemple) directement dans BigQuery. Cette solution vous permet d'effectuer des évaluations basées sur l'IA, d'optimiser les prompts 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 (version bêta).

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 à faible latence et à haut débit sans bloquer l'exécution des agents.

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

  1. Capture. Utilisez des plug-ins dans l'Agent Development Kit (ADK) ou des rappels dans LangGraph pour intercepter les événements d'interaction et capturer les événements des agents.
  2. Flux. 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. Analysez et évaluez 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'agent complexes multitours.

Diagramme montrant les données d'activité des agents provenant des frameworks d'orchestration et transférées dans BigQuery pour analyse.

Avantages d'Agent Analytics

  • Activez la journalisation complète avec une seule ligne de code et automatisez la gestion des schémas.
  • Enregistrez et analysez des données multimodales, telles que du texte, des images, des vidéos et de l'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.
  • Identifiez 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 avec des contrôles d'accès précis, le masquage des données et le chiffrement.

Méthodes de capture des données de journal des agents

Pour capturer la télémétrie d'interaction de votre agent (requêtes, réponses, appels d'outils et journaux d'erreurs) de manière native dans BigQuery, vous pouvez enregistrer 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, le BigQueryAgentAnalyticsPlugin de l'Agent Development Kit (ADK) se connecte à l'exécuteur d'agents pour intercepter, sérialiser et diffuser automatiquement les événements.
  • Gestionnaires de rappels de framework : intégrez des rappels standards dans des environnements d'agents courants. Par exemple, vous pouvez utiliser le gestionnaire BigQuery intégré à LangGraph et LangChain pour intercepter et transférer des traces.
  • Ingestion directe d'API : pour les frameworks personnalisés ou propriétaires, utilisez les Google Cloud bibliothèques clientes pour diffuser des événements structurés directement dans votre table d'événements à l'aide de l'API Storage Write (gRPC).

Quelle que soit la méthode, toutes les options de journalisation utilisent l'API BigQuery Storage Write (gRPC) à faible latence, à haut débit . Cette API fournit un point de terminaison de diffusion robuste qui met en mémoire tampon et sérialise les lignes (à l'aide du moteur PyArrow) de manière asynchrone avant de les valider. Cela 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 de journal des agents

Pour comprendre et optimiser les performances de votre agent, analysez et évaluez les journaux d'interaction de différentes manières :

  • 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 effectuer une analyse automatisée de la cause racine des 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 BigQuery Agent Analytics prédéfini (bloc Looker) à partir de Marketplace Looker.
  • Notebooks Jupyter : explorez et expérimentez avec les données de journal à l'aide des bibliothèques Python, pandas ou BigFrames dans des environnements interactifs.
  • SDK Python : interrogez, reconstruisez et auditez de manière programmatique les traces d'exécution des agents directement dans le code de votre application ou dans les pipelines d'évaluation automatisés.

Exemples d'utilisation des données de journal des agents

Voici quelques cas d'utilisation courants et exemples d'utilisation des données de journal des agents dans BigQuery.

Observabilité et métriques opérationnelles

  • Interrogez les données pour répartir les coûts par flux d’agents et déterminer si un agent spécifique, tel qu’un agent d’affinage, consomme une quantité disproportionnée de jetons par rapport à sa contribution aux réponses finales.
  • Utilisez l'agent d'analyse conversationnelle BigQuery pour effectuer une analyse de la cause racine basée sur l'IA en exécutant des requêtes avec la AI.GENERATE fonction. Par exemple : "Analyse ce journal de conversation et explique la cause racine 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 AI.SCORE fonction.
  • Identifiez les clusters de conversations dans lesquels l'agent n'a pas pu aider les utilisateurs en utilisant une requête SQL avec la recherche vectorielle, puis comparez-les à l'intention initiale de l'utilisateur. Cela vous permet d'identifier les lacunes dans les outils ou la base de connaissances de l'agent.

Insights et contextualisation pour l'entreprise

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

Pour obtenir d'autres exemples, consultez la section Requêtes d'analyse avancées.

Utiliser un notebook Jupyter pour travailler avec les journaux des agents

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

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 excellents 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 BigQuery Agent Analytics. Pour obtenir des exemples détaillés d'analyse des journaux, consultez le dépôt GitHub du SDK.

  • Reconstruction des traces : 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é des agents par rapport à des critères basés sur des règles, tels que la latence, le nombre de tours et les taux d'erreur, ainsi que des critères sémantiques, tels que l'exactitude, le sentiment et les hallucinations.
  • Correspondance des trajectoires : comparez les chemins d'exécution réels des agents 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 comportementale et détection des dérives : effectuez des analyses statistiques sur les sorties d’agents non déterministes, surveillez les distributions des requêtes des utilisateurs et détectez les régressions de production ou les dérives sémantiques.
  • Mémoire des agents à long terme : fournissez aux agents un contexte inter-session, 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.

Enregistrer et analyser l'activité des agents

L'intégration du SDK dans les workflows de vos agents implique généralement les étapes suivantes :

  1. Enregistrer les interactions : associez un plug-in de journalisation (tel que le BigQueryAgentAnalyticsPlugin dans ADK) ou un gestionnaire de rappels dans votre framework d'orchestration d'agents. Lorsque les utilisateurs interagissent avec votre agent, les journaux sont diffusés de manière asynchrone vers BigQuery à l'aide de l'API Storage Write (gRPC) à haut débit.

  2. Initialiser 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 Google Cloud projet contenant l'ensemble de données cible.
    • dataset_id : nom de l'ensemble de données BigQuery stockant les journaux.
    • table_id: table spécifique stockant les événements de télémétrie (agent_events par défaut).

  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_trace(
    session_id="YOUR_SESSION_ID"
)
trace.render()

    L'extrait utilise les composants suivants :

    • trace: objet Trace hydraté contenant l'arborescence DAG hiérarchique liée de manière causale de toutes les actions de l'utilisateur et de l'agent.
    • YOUR_SESSION_ID: ID 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 la régression par rapport à une suite de tests de référence :

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

    L'extrait utilise les composants suivants :

    • evaluator: logique compilée GraderPipeline structurée composant des métriques d'évaluation hétérogènes basées sur des règles et sémantiques.
    • session_ids: liste de chaînes d'ID de session pour exécuter des évaluations par lot dans BigQuery.
    • report: objet EvaluationReport résultant contenant les notes brutes des sessions, les résumés des métriques, les statistiques d'essai et les commentaires de l'évaluateur automatique.

Intégrer BigQuery Agent Analytics à votre workflow

Pour intégrer BigQuery Agent Analytics à votre workflow, consultez la documentation de votre framework :

Étape suivante