BigQuery-Agentenanalysen verwenden

BigQuery-Agentenanalysen sind eine Open-Source-Lösung, mit der Sie multimodale Agenteninteraktionsdaten im großen Maßstab erfassen, analysieren und visualisieren können. Dazu werden Rohdaten zu Agenteninteraktionen wie Anfragen, Antworten, Toolaufrufe und Fehler direkt in BigQuery gestreamt. Mit dieser Lösung können Sie KI-gestützte Bewertungen durchführen, Agenten-Prompts optimieren und langfristige Erinnerungen extrahieren, um zukünftige Interaktionen zu verbessern. BigQuery-Agentenanalysen werden im Agent Development Kit (ADK) und LangGraph (Vorschau) unterstützt.

Architektur

BigQuery-Agentenanalysen streamen Aktivitätsdaten zu Agenten mit der BigQuery Storage Write APIin BigQuery. Diese API bietet einen Log-Streaming mit hohem Durchsatz und niedriger Latenz, ohne die Ausführung des Agenten zu blockieren.

Der Datenfluss besteht aus folgenden Phasen:

1. Erfassung Mit Plug-ins im Agent Development Kit (ADK) oder Callbacks in LangGraph werden Interaktionsereignisse abgefangen, um Agentenereignisse zu erfassen.
2. Streaming Interaktionsereignisse werden über die Storage Write API an BigQuery gesendet. Wenn kein standardisiertes Schema vorhanden ist, wird automatisch eines vom Agenten erstellt.
3. Aufnehmen Protokollierte Agentendaten analysieren und bewerten. Sie können Rohdaten mit SQL abfragen, Messwerte auf benutzerdefinierten Dashboards verfolgen oder das BigQuery-Agentenanalysen SDK verwenden, um komplexe mehrstufige Ausführungstraces von Agenten zu rekonstruieren und zu bewerten.

Vorteile von Agentenanalysen

• Umfassende Protokollierung mit einer einzigen Codezeile aktivieren und Schemas automatisch verwalten.
• Multimodale Daten wie Text, Bilder, Videos und Audio mithilfe von Objekttabellen protokollieren und analysieren.
• Betriebsbezogene Messwerte wie Tokenverbrauch und Latenz in einem robusten, vordefinierten Schema verfolgen.
• Optimierungsmöglichkeiten mithilfe von generativen KI-Funktionen und der Vektorsuche von BigQuery ermitteln.
• Agentenlogs mit detaillierten Zugriffssteuerungen, Datenmaskierung und Verschlüsselung schützen.

Möglichkeiten zum Erfassen von Agentenlogdaten

Wenn Sie die Interaktionstelemetrie Ihres Agenten (Anfragen, Antworten, Toolaufrufe und Fehlerlogs) nativ in BigQuery erfassen möchten, können Sie Ereignisdaten auf verschiedene Arten protokollieren:

• Plug-ins für das Orchestrierungsframework: Verwenden Sie Standard-Logging-Plug-ins, die von Ihrem Agenten-Orchestrierungstoolkit bereitgestellt werden. Das Plug-in BigQueryAgentAnalyticsPlugin im Agent Development Kit (ADK) wird beispielsweise in den Agenten-Runner eingebunden, um Ereignisse automatisch abzufangen, zu serialisieren und zu streamen.
• Framework-Callback-Handler: Integrieren Sie Standard-Callbacks in gängige Agentenumgebungen. Sie können beispielsweise den integrierten BigQuery-Handler in LangGraph und LangChain verwenden, um Traces abzufangen und weiterzuleiten.
• Direkte API-Aufnahme: Verwenden Sie für benutzerdefinierte oder proprietäre Frameworks die Google Cloud Clientbibliotheken, um strukturierte Ereignisse mit der Storage Write API direkt in Ihre Ereignistabelle zu streamen.

Unabhängig von der Methode verwenden alle Logging-Optionen die BigQuery Storage Write API mit niedriger Latenz, hohem Durchsatz . Diese API bietet einen robusten Streaming-Endpunkt, der Zeilen asynchron im Arbeitsspeicher puffert und serialisiert (mit der PyArrow-Engine), bevor sie übernommen werden. So wird verhindert, dass Aufgaben der Beobachtbarkeitspipeline die Ausführung von Agenten für Nutzer blockieren.

Möglichkeiten zum Analysieren von Agentenlogdaten

Um die Leistung Ihres Agenten zu verstehen und zu optimieren, können Sie Interaktionslogs auf folgende Arten analysieren und bewerten:

• Direkte SQL-Abfragen: Führen Sie benutzerdefinierte Abfragen in BigQuery aus, um Messwerte wie Tokenverbrauch und Ausführungslatenz zu berechnen. Sie können auch verwenden AI.GENERATE für die automatisierte Ursachenanalyse von Fehlern oder Joins mit Geschäftstabellen ausführen, um die geschäftlichen Auswirkungen zu messen.
• Interaktive Dashboards: Verbinden Sie Visualisierungstools wie Data Studio mit vordefinierten oder benutzerdefinierten BigQuery-Ansichten, um die Agentenleistung, Fehlerraten und Nutzungstrends im Zeitverlauf zu verfolgen. Looker-Kunden können auch eine vordefinierte BigQuery-Agenten analysen-Dashboardvorlage (Looker Block) aus dem Looker Marketplace verwenden.
• Jupyter-Notebooks: Untersuchen und testen Sie Log daten in interaktiven Umgebungen mit Python-Bibliotheken, pandas oder BigFrames.
• Python SDK: Führen Sie programmatisch Abfragen aus, rekonstruieren und prüfen Sie Ausführungstraces von Agenten direkt in Ihrem Anwendungscode oder in automatisierten Bewertungspipelines.

Beispiele für die Arbeit mit Agentenlogdaten

Im Folgenden finden Sie häufige Anwendungsfälle und Beispiele für die Arbeit mit Agentenlogdaten in BigQuery.

Beobachtbarkeit und Betriebsdaten

• Fragen Sie Daten ab um die Kosten nach Agentenflüssen aufzuschlüsseln und zu ermitteln, ob ein bestimmter Agent, z. B. ein Verfeinerungsagent, im Vergleich zu seinem Beitrag zu den endgültigen Antworten eine unverhältnismäßig hohe Anzahl von Tokens verbraucht.
• Verwenden Sie den BigQuery-Agenten für Konversationsanalysen für die KI-gestützte Ursachenanalyse, indem Sie Abfragen mit der AI.GENERATE Funktionausführen. Beispiel: „Analysiere dieses Konversationslog und erkläre die Ursache des Fehlers.“

Agentenbewertung und Qualitätsanalyse

• Bewerten Sie Unterhaltungen und messen Sie die Agentenbewertung im Zeitverlauf mit der AI.SCORE Funktion.
• Ermitteln Sie Unterhaltungscluster, in denen der Agent Nutzern nicht helfen konnte, indem Sie eine SQL-Abfrage mit der Vektorsucheverwenden, und vergleichen Sie sie dann mit der ursprünglichen Absicht des Nutzers. So können Sie Lücken in den Tools oder der Wissensdatenbank des Agenten erkennen.

Geschäftliche Statistiken und Kontextualisierung

Um Agentendaten zu kontextualisieren, verknüpfen Sie die Tabelle agent_events mit anderen Geschäftstabellen . Sie können beispielsweise den durchschnittlichen Bestellwert für Kunden anzeigen, die mit dem KI-Agenten interagiert haben, im Vergleich zu Kunden, die die Suchleiste verwendet haben.

Weitere Beispiele finden Sie unter Erweiterte Analyseabfragen.

Jupyter-Notebook für die Arbeit mit Agentenlogs verwenden

In diesem Beispiel für ein Colab-Jupyter-Notebook können Sie interaktiv Abfragen an Agentenlogs senden, sie visualisieren und bewerten.

BigQuery-Agentenanalysen-SDK verwenden

Das BigQuery-Agentenanalysen-SDK ist eine Open-Source- Python-Bibliothek, die eine Verbrauchs- und Bewertungsebene für die langfristige Beobachtbarkeit von Agenten bietet. Dashboards und Notebooks eignen sich hervorragend für Ad-hoc-Analysen. Mit dem SDK können Sie das Agentenverhalten im großen Maßstab systematisch analysieren und prüfen.

Funktionen des SDK

Mit dem BigQuery-Agentenanalysen-SDK können Sie die folgenden Aufgaben ausführen. Detaillierte Beispiele für die Loganalyse finden Sie im GitHub-Repository für das SDK.

• Trace-Rekonstruktion: Rekonstruieren Sie polymorphe Ereignislogs in kausale Ereignisketten, um Sitzungen über mehrere Runden hinweg zu debuggen, einschließlich verschachtelter Tool- und LLM-Aufrufe.
• Deterministische und semantische Bewertung: Bewerten Sie die Agentenqualität anhand regelbasierter Kriterien wie Latenz, Anzahl der Runden und Fehlerraten sowie semantischer Kriterien wie Korrektheit, Stimmung und Halluzinationen.
• Abgleich von Abläufen: Vergleichen Sie die tatsächlichen Ausführungspfade des Agenten mit erwarteten optimalen Abläufen, um die Effizienz der einzelnen Schritte zu überprüfen und festzustellen, ob die Tools in der richtigen Reihenfolge verwendet wurden.
• Verhaltensüberwachung und Abweichungserkennung: Führen Sie statistische Analysen für nicht deterministische Agentenausgaben durch, überwachen Sie die Verteilung von Nutzeranfragen und erkennen Sie Produktionsregressionen oder semantische Abweichungen.
• Langfristiger Agentenspeicher: Stellen Sie Agenten sitzungsübergreifenden Kontext, semantische Abrufe von Nutzerprofilen und episodische Erinnerungen zur Verfügung, die unter Berücksichtigung des Tokenbudgets nativ in BigQuery gespeichert werden.

Agentenaktivitäten protokollieren und analysieren

Die Einbindung des SDK in Ihre Agentenworkflows umfasst in der Regel die folgenden Schritte:

1. Interaktionen protokollieren: Fügen Sie ein Logger-Plug-in (z. B. das BigQueryAgentAnalyticsPlugin im ADK) oder einen Callback-Handler in Ihr Agenten Orchestrierungsframework ein. Wenn Nutzer mit Ihrem Agenten interagieren, werden die Logs asynchron mit der Storage Write API mit hohem Durchsatz in BigQuery gestreamt.

2. Client initialisieren: Stellen Sie über das Python SDK eine Verbindung zu Ihrem Log-Dataset her:

   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",
   )
   

   Das Snippet verwendet die folgenden Komponenten:

   • client: Die übergeordnete Client-Instanz, die Abfragen programmatisch weiterleitet und aktive Datenbankverbindungen verwaltet.
   • project_id: Die Google Cloud Projekt-ID des Ziel-Datasets.
   • dataset_id: Der Name des BigQuery-Datasets, in dem Logs gespeichert werden.
   • table_id: Die spezifische Tabelle, in der Telemetrieereignisse gespeichert werden (agent_events standardmäßig).

3. Sitzungstrace rekonstruieren: Rufen Sie eine bestimmte Unterhaltungssitzung ab, um die genaue Reihenfolge der Ereignisse zu visualisieren und zu überprüfen:

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

   Das Snippet verwendet die folgenden Komponenten:

   • trace: Das hydrierte Trace-Objekt, das den rekonstruierten kausal verknüpften hierarchischen DAG-Span-Baum aller Nutzer- und Agentenaktionen enthält.
   • YOUR_SESSION_ID: Die eindeutige ID der Sitzung, die Sie untersuchen möchten.

4. Automatisierte Bewertungen ausführen: Bewerten Sie Sitzungsabläufe programmatisch oder prüfen Sie Regressionen anhand einer optimalen Testsuite:

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

   Das Snippet verwendet die folgenden Komponenten:

   • evaluator: Die strukturierte GraderPipeline-Kompilierungslogik, die heterogene regelbasierte und semantische Bewertungsdaten zusammensetzt.
   • session_ids: Die Liste der Sitzungs-ID-Strings, für die Batchbewertungen in BigQuery ausgeführt werden sollen.
   • report: Das resultierende EvaluationReport-Objekt mit Rohbewertungen für Sitzungen, Messwertzusammenfassungen, Teststatistiken und Feedback vom automatischen Bewerter.

BigQuery-Agentenanalysen in Ihren Workflow einbinden

Informationen zum Einbinden von BigQuery-Agentenanalysen in Ihren Workflow finden Sie in der Dokumentation für Ihr Framework:

• Leitfaden zum ADK-Plug-in für BigQuery-Analysen
• Einbindung von BigQuery-Callback-Handlern (LangChain und LangGraph)

Nächste Schritte

• Codelab ansehen.