Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

BigQuery-Agentenanalyse verwenden

Die BigQuery-Agentenanalyse ist eine Open-Source-Lösung, mit der Sie multimodale Agenteninteraktionsdaten im großen Maßstab erfassen, analysieren und visualisieren können. Dazu werden Rohdaten von 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 das Langzeitgedächtnis extrahieren, um zukünftige Interaktionen zu verbessern. Die BigQuery-Agentenanalyse wird im Agent Development Kit (ADK) und LangGraph (Vorschau) unterstützt.

Architektur

Die BigQuery-Agentenanalyse streamt Aktivitätsdaten zu Agenten zu BigQuery mit der BigQuery Storage Write API (gRPC). 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:

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

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

Vorteile der Agentenanalyse

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.
Mithilfe von generativen KI-Funktionen und der Vektorsuche von BigQuery Optimierungsmöglichkeiten 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 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 (gRPC) direkt in Ihre Ereignistabelle zu streamen.

Unabhängig von der Methode verwenden alle Protokollierungsoptionen die niedrige Latenz, den hohen Durchsatz BigQuery Storage Write API (gRPC). 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 sichergestellt, dass Aufgaben der Beobachtbarkeitspipeline die Ausführung des nutzerorientierten Agenten nicht 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 den Zustand des Agenten, Fehlerraten und Nutzungstrends im Zeitverlauf zu verfolgen. Looker-Kunden können auch eine vordefinierte BigQuery Agent Analytics-Dashboardvorlage (Looker Block) aus dem Looker Marketplace verwenden.
Jupyter-Notebooks: Interaktive Umgebungen zum Analysieren und Experimentieren mit Log daten mithilfe von Python-Bibliotheken, pandas oder BigFrames.
Python SDK: programmatically Ausführungstraces von Agenten direkt in Ihrem Anwendungscode oder in automatisierten Bewertungspipelines abfragen, rekonstruieren und prüfen.

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 Betriebsbezogene Messwerte

Daten abfragen um Kosten nach Agentenflüssen aufzuschlüsseln und zu ermitteln, ob ein bestimmter Agent, z. B. ein Verfeinerungsagent, im Vergleich zu seinem Beitrag zu endgültigen Antworten eine unverhältnismäßig große 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

Konversationen mit der AI.SCORE Funktion einstufen und den Agentenrang im Zeitverlauf messen.
Konversationscluster identifizieren, in denen der Agent Nutzern nicht helfen konnte, indem Sie eine SQL-Abfrage mit der Vektorsucheverwenden und sie dann mit der ursprünglichen Absicht des Nutzers vergleichen. 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 zum Arbeiten mit Agentenlogs verwenden

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

BigQuery-Agentenanalyse-SDK verwenden

Das BigQuery-Agentenanalyse-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-Agentenanalyse-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 Golden Traces, um die Effizienz der einzelnen Schritte zu überprüfen und festzustellen, ob die Tools in der richtigen Reihenfolge verwendet wurden.
Verhaltensmonitoring und Drift-Erkennung: Führen Sie statistische Analysen für nicht deterministische Agentenausgaben durch, beobachten Sie die Verteilungen von Nutzeranfragen und erkennen Sie Produktionsregressionen oder semantische Abweichungen.
Langzeitgedächtnis des Agenten: Stellen Sie Agenten sitzungsübergreifenden Kontext, semantischen Abruf von Nutzerprofilen und ein Token-Budget-basiertes episodisches Gedächtnis zur Verfügung, das nativ in BigQuery gespeichert ist.

Agentenaktivität protokollieren und analysieren

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

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 (gRPC) mit hohem Durchsatz in BigQuery gestreamt.
Client initialisieren: Stellen Sie eine Verbindung zu Ihrem Log-Dataset über das Python SDK 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 (standardmäßig agent_events).
Sitzungstrace rekonstruieren: Rufen Sie eine bestimmte Konversationssitzung 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.
Automatisierte Bewertungen ausführen: Sitzungsabläufe programmatisch bewerten oder auf Regressionen anhand einer Golden Test Suite prüfen:
```
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-kompilierte Logik, die heterogene regelbasierte und semantische Bewertungsmetriken 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, Messwertzusammenfassungen, Teststatistiken und Feedback vom automatischen Bewerter.

BigQuery-Agentenanalyse in Ihren Workflow einbinden

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

Leitfaden zum ADK-Plug-in für BigQuery Analytics
BigQuery-Callback-Handler Integration (LangChain und LangGraph)

Nächste Schritte

Codelab ansehen.