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 API in BigQuery. Diese API bietet einen hohen Durchsatz und eine geringe Latenz beim Logstreaming, 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ührungsprotokolle von Agenten zu rekonstruieren und zu bewerten.

Diagramm, das zeigt, wie Agent-Aktivitätsdaten aus Orchestrierungs-Frameworks zur Analyse in BigQuery übertragen werden.

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.
  • Agentenprotokolle mit detaillierten Zugriffssteuerungen, Datenmaskierung und Verschlüsselung schützen.

Möglichkeiten zum Erfassen von Agentenprotokolldaten

Wenn Sie die Interaktionstelemetrie Ihres Agenten (Anfragen, Antworten, Toolaufrufe und Fehlerprotokolle) 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.
  • Callback-Handler für das Framework: 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 Cloud de Confiance by S3NS 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 geringer 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 Agentenprotokolldaten

Um die Leistung Ihres Agenten zu verstehen und zu optimieren, können Sie Interaktionsprotokolle 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 vorgefertigten oder benutzerdefinierten BigQuery-Ansichten, um den Zustand des Agenten, Fehlerraten und Nutzungstrends im Zeitverlauf zu verfolgen.
  • Jupyter-Notebooks: Untersuchen und testen Sie Protokoll daten in interaktiven Umgebungen mit Python-Bibliotheken, pandas oder BigFrames.
  • Python SDK: Führen Sie programmatisch Abfragen aus, rekonstruieren und prüfen Sie Ausführungsprotokolle von Agenten direkt in Ihrem Anwendungscode oder in automatisierten Bewertungspipelines.

Beispiele für die Arbeit mit Agentenprotokolldaten

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

Beobachtbarkeit und Betriebsstatistiken

  • 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: „Analysieren Sie dieses Konversationsprotokoll und erklären Sie die Ursache des Fehlers.“

Agentenbewertung und Qualitätsanalyse

  • Bewerten Sie Unterhaltungen und messen Sie den Agentenrang 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 Erkenntnisse 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 Agentenprotokollen verwenden

In diesem Beispiel für ein Colab-Jupyter-Notebook können Sie Agentenprotokolle interaktiv abfragen, 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 Verhalten von Agenten 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 Protokollanalyse finden Sie im GitHub-Repository für das SDK.

  • Trace-Rekonstruktion: Rekonstruieren Sie polymorphe Ereignisprotokolle 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 Qualität des Agenten 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 prüfen und festzustellen, ob die Tools in der richtigen Reihenfolge verwendet wurden.
  • Verhaltensüberwachung und Drift-Erkennung: Führen Sie statistische Analysen für nicht deterministische Agentenausgaben durch, überwachen Sie die Verteilung von Nutzeranfragen und erkennen Sie Produktionsregressionen oder semantische Abweichungen.
  • Langfristiges Agentengedächtnis: 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 Protokolle 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 Protokolldataset 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 Cloud de Confiance by S3NS Projekt-ID des Ziel-Datasets.
    • dataset_id: der Name des BigQuery-Datasets, in dem Protokolle gespeichert werden.
    • table_id: die spezifische Tabelle, in der Telemetrieereignisse gespeichert werden (standardmäßig agent_events).

  3. Sitzungsprotokoll 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-Logik, die heterogene regelbasierte und semantische Bewertungsstatistiken umfasst.
    • 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, Zusammenfassungen von Messwerten, Teststatistiken und Feedback von automatischen Bewertern.

BigQuery-Agentenanalysen in Ihren Workflow einbinden

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

Nächste Schritte