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 transmettant les interactions brutes des agents (comme les requêtes, les réponses, les appels d'outils et les erreurs) directement à BigQuery. Cette solution vous permet d'effectuer des évaluations basées sur 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 Agent Development Kit (ADK) et LangGraph (version Preview).

Architecture

L'analyse des agents BigQuery diffuse les données d'activité des agents dans BigQuery à l'aide de l'API BigQuery Storage Write, qui fournit un flux 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 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 d'agent.
  2. Stream. Les événements d'interaction sont envoyés à BigQuery via l'API Storage Write. Si aucun schéma standardisé n'existe, l'agent en crée un automatiquement.
  3. Consommer Analyser et évaluer les données d'agent enregistrées Vous pouvez interroger des données brutes avec SQL, suivre des métriques dans des tableaux de bord personnalisés ou utiliser le SDK BigQuery Agent Analytics pour reconstruire et évaluer des traces d'exécution d'agents complexes en plusieurs tours.

Diagramme montrant les données d'activité des agents provenant des frameworks d'orchestration et transférées dans 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.
  • 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 robuste et prédéfini.
  • Identifier les opportunités d'optimisation à l'aide des fonctions d'IA générative et de 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.

Méthodes de capture des données de journaux d'agent

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 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 boîte à outils d'orchestration d'agents. Par exemple, BigQueryAgentAnalyticsPlugin dans l'Agent Development Kit (ADK) s'accroche au programme d'exécution de l'agent pour intercepter, sérialiser et diffuser automatiquement les événements.
  • Gestionnaires de rappel de framework : intègrent des rappels standards dans les environnements d'agent populaires. Par exemple, vous pouvez utiliser le gestionnaire BigQuery intégré à LangGraph et LangChain pour intercepter et transférer les traces.
  • Ingestion directe de l'API : pour les frameworks personnalisés ou propriétaires, utilisez les bibliothèques clientesCloud de Confiance by S3NS pour diffuser des événements structurés directement dans votre table d'événements à l'aide de l'API Storage Write.

Quelle que soit la méthode, toutes les options de journalisation utilisent l'API BigQuery Storage Write à 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. Cela permet de s'assurer que les tâches du pipeline d'observabilité ne bloquent pas les tours d'exécution de l'agent destinés aux utilisateurs.

Méthodes d'analyse des données de journaux 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 des causes profondes des erreurs ou effectuer des jointures avec des tables d'activité pour mesurer l'impact sur l'activité.
  • 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 des agents, les taux d'erreur et les tendances d'utilisation au fil du temps.
  • Notebooks Jupyter : explorez et expérimentez avec les données de journaux à l'aide des 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 des agents directement dans le code de votre application ou dans les pipelines d'évaluation automatisée.

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

Vous trouverez ci-dessous des exemples et des cas d'utilisation courants pour travailler avec les données de journaux d'agent dans BigQuery.

Observabilité et métriques opérationnelles

  • Interrogez les données pour répartir les coûts par flux d'agent 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 des causes premières basée sur l'IA en exécutant des requêtes avec la fonction AI.GENERATE. Par exemple, "Analyse ce journal de conversation et explique la cause première 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 conversations dans lesquels l'agent n'a pas réussi à aider les utilisateurs en utilisant une requête SQL avec Vector Search, 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 les entreprises

Pour contextualiser les données des agents, associez 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 Requêtes d'analyse avancée.

Utiliser un notebook Jupyter pour manipuler les journaux d'agent

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

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 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 la trace : reconstruisez les journaux d'événements polymorphes en chaînes d'événements causaux pour déboguer les sessions sur plusieurs tours, y compris les appels imbriqués d'outils et de LLM.
  • Évaluation déterministe et sémantique : évaluez la qualité de l'agent par rapport à des critères basés sur des règles (latence, nombre de tours et taux d'erreur, par exemple) et à des critères sémantiques (exactitude, sentiment et hallucination, par exemple).
  • Correspondance de la trajectoire : comparez les chemins d'exécution réels de l'agent aux trajectoires clés 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 de l'agent à long terme : fournit aux agents un contexte multisession, 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

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

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

  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 Cloud de Confiance by S3NS contenant l'ensemble de données cible.
    • dataset_id : nom de l'ensemble de données BigQuery dans lequel les journaux sont stockés.
    • table_id : table spécifique stockant les événements de télémétrie (agent_events par défaut).

  3. Reconstituer une trace de session : récupérez une session de conversation spécifique pour visualiser et examiner la séquence exacte d'é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'arbre de couverture DAG hiérarchique reconstruit et lié 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 recherchez les régressions 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 GraderPipeline structurée et compilée composant des métriques d'évaluation sémantiques et basées sur des règles hétérogènes.
    • session_ids : liste des chaînes d'ID de session pour lesquelles 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 des essais et les commentaires de l'évaluateur automatique.

Intégrer l'analyse des agents BigQuery à votre workflow

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

Étapes suivantes