Schema für Unterhaltungsprotokolle

In diesem Dokument werden das Tabellenlayout, die Spalten, die Ereignistypen, die Felder für die Nutzeridentität und die JSON-Nutzlaststruktur für das Logging von Unterhaltungen für die konversationelle Analyse in BigQuery beschrieben. Eine Übersicht über die Funktionsweise des Loggings von Unterhaltungen finden Sie unter Logging von Unterhaltungen – Übersicht.

Tabellenlayout und automatisches Erstellen

Erstellen Sie das Ziel-Dataset im selben Projekt wie den Daten-Agenten, bevor Sie das Logging aktivieren. Der Dienst-Agent der Conversational Analytics API erstellt die Tabelle am Standort des Datasets beim ersten protokollierten Turn (oder fügt fehlende Schemaspalten zu einer vorhandenen kompatiblen Tabelle hinzu). Die automatisch erstellte Tabelle wird nach Tag auf timestamp partitioniert (wobei alle Standardpartitionen im Dataset übernommen werden) und auf event_type, agent und user_id geclustert. Filtern Sie beim Abfragen der Tabelle immer nach timestamp.

Spalten

In der folgenden Tabelle werden die Spalten in der Zieltabelle für das Unterhaltungs-Logging beschrieben.

Spalte Typ Modus Inhalt
timestamp TIMESTAMP REQUIRED UTC-Zeit des Ereignisses. Partitionierungsspalte.
event_id STRING NULLABLE Eindeutige ID für das Ereignis. Sie bleibt gleich, wenn ein Schreibvorgang wiederholt wird, sodass Sie sie zum Entfernen von Duplikaten verwenden können.
event_type STRING NULLABLE Art des Ereignisses. Weitere Informationen finden Sie unter Ereignistypen.
agent STRING NULLABLE Der Agententyp, nicht der Name oder die ID Ihres KI-Agenten (z. B. ConversationalAnalyticsAgent). Verwenden Sie die KI-Datenagenten-ID, um KI-Agenten voneinander zu unterscheiden (siehe Felder in attributes).
session_id STRING NULLABLE Eine einzelne Frage, keine ganze Unterhaltung. Alle Ereignisse für eine Frage und die zugehörige Antwort haben dieselbe session_id. Wenn Sie die Gesprächsbeiträge in Unterhaltungen gruppieren möchten, verwenden Sie die Unterhaltungs-ID in attributes.
invocation_id STRING NULLABLE Eine Ausführung innerhalb einer Runde.
user_id STRING NULLABLE Der Anrufer, der die Frage gestellt hat. Weitere Informationen finden Sie unter Nutzeridentität.
trace_id STRING NULLABLE OpenTelemetry-Trace-ID (32 hexadezimale Zeichen).
span_id STRING NULLABLE ID dieses Vorgangs im Ausführungsbaum des Turns.
parent_span_id STRING NULLABLE ID des übergeordneten Vorgangs.
content JSON NULLABLE Ereignisnutzlast. Die Form hängt von event_type ab.
content_parts RECORD REPEATED Mehrteiliger Inhalt mit einem Element pro Teil (z. B. mime_type, uri, object_ref, text, part_index, part_attributes und storage_mode).
attributes JSON NULLABLE Metadaten: Daten-Agent-ID, Konversations-ID, interner Nutzerschlüssel, Modellversion und detaillierte Tokennutzung.
latency_ms JSON NULLABLE Latenzmessungen wie total_ms und time_to_first_token_ms.
status STRING NULLABLE OK oder ERROR.
error_message STRING NULLABLE Fehlerdetails. Sie kann auch für OK-LLM_RESPONSE-Zeilen festgelegt werden, wenn das Modell aus einem anderen Grund als einem normalen Stopp beendet wird (z. B. wenn das maximale Tokenlimit erreicht ist).
is_truncated BOOLEAN NULLABLE true, wenn ein Textwert im Ereignis 512.000 Zeichen (500 * 1,024) überschritten hat und abgeschnitten wurde. Die Grenzwerte enden mit ...[TRUNCATED]. Der entfernte Teil kann nicht wiederhergestellt werden.

Ereignistypen

In der folgenden Tabelle werden die Werte beschrieben, die in der Spalte event_type angezeigt werden können, sowie die Spalten oder JSON-Felder, in denen die Daten für jedes Ereignis gespeichert werden.

event_type Wert Beschreibung Ausgefüllte Spalten und JSON-Felder
INVOCATION_STARTING Beginn eines Zuges. Keine
USER_MESSAGE_RECEIVED Die Frage des Nutzers. content.text_summary
AGENT_RESPONSE Die Antwort des KI-Agenten als strukturiertes Objekt. content.text_summary (Nur-Text) und content.response (siehe Struktur von AGENT_RESPONSE)
LLM_RESPONSE Eine Zeile für jeden Modellaufruf, einschließlich Aufrufen, die ein Tool angefordert haben (nicht geschrieben, wenn eine Runde direkt aus einer verifizierten Abfrage beantwortet wird, wobei attributes.fast_path den Wert true hat). Die Ausgabe des Modells wird nicht gespeichert. Tokens: content.usage.prompt, content.usage.completion, content.usage.total. Modell: attributes.model_version. Grund für Beendigung: attributes.finish_reason. Detaillierte Nutzung: attributes.usage_metadata (z. B. cached_content_token_count und thoughts_token_count).
INVOCATION_COMPLETED Ende einer Runde, mit Latenz pro Runde. content ist leer. latency_ms.total_ms
EMBEDDING_SUGGESTION Vorschläge für den Agent-Inhaber zu Spalten, die von Einbettungen profitieren könnten. Sie wird nur für einige Agenten angezeigt. content.reason, content.suggested_columns
INVOCATION_ERROR, AGENT_ERROR, LLM_ERROR Fehlgeschlagener Zug. status ist ERROR und content ist NULL. error_message (einzeilige Zusammenfassung mit SQL-Anweisungen und entfernten Tabellennamen)

Nutzeridentität

Die Spalte user_id enthält die E-Mail-Adresse des Aufrufers: die E-Mail-Adresse des Nutzers, die E-Mail-Adresse eines Dienstkontos, wenn sich ein API-Aufrufer mit einem Dienstkonto authentifiziert, oder NULL, wenn der Aufrufer keine E-Mail-Adresse hat (z. B. einige Workforce Identity Federation-Identitäten). In jeder Zeile wird außerdem ein interner Nutzerschlüssel in attributes.session_metadata.user_id aufgezeichnet, sodass Sie mit internal_user_key eindeutige Nutzer zählen können (siehe Ansicht für agentenübergreifende Ereignisse erstellen).

Wenn Sie die API über ein Dienstkonto aufrufen, müssen Sie die Nutzerzuordnung in Ihrer Anwendung aufzeichnen, um die Turns Ihren eigenen Endnutzern zuzuordnen. Die API akzeptiert keine Endnutzer-ID für das Logging.

Felder in attributes

In der folgenden Tabelle sind die GoogleSQL-Ausdrücke aufgeführt, mit denen Metadatenfelder aus der JSON-Spalte attributes extrahiert werden.

Voraussetzungen GoogleSQL-Ausdruck
Daten-Agent-ID JSON_VALUE(attributes, '$.session_metadata.state."data-agent-id"')
Vollständiger Ressourcenname des KI-Datenagenten JSON_VALUE(attributes, '$.adk.app_name')
Unterhaltungs-ID JSON_VALUE(attributes, '$.session_metadata.state."conversation-id"')
Interner Nutzerschlüssel JSON_VALUE(attributes, '$.session_metadata.user_id')
Modellversion (in LLM_RESPONSE Zeilen) JSON_VALUE(attributes, '$.model_version')

Struktur von AGENT_RESPONSE

Wenn Sie die Antwort des KI-Agenten als Nur-Text lesen möchten, verwenden Sie JSON_VALUE(content, '$.text_summary'). Dabei werden die Markdown-, Annahme- und Insight-Teile der Antwort sowie alle klärenden Fragen kombiniert. In AGENT_RESPONSE-Zeilen ist content.response ein JSON-Objekt, kein String. Daher gibt JSON_VALUE(content, '$.response') den Wert NULL zurück.

In der folgenden Tabelle werden die Pfade unter content.response beschrieben.

Pfad unter content.response Typ Inhalt
parts ARRAY<JSON> Die Antwort in Teilen.
parts[].markdown STRING Antworttext (Markdown).
parts[].insight STRING Eine aus den Daten gewonnene Erkenntnis.
parts[].assumption STRING Eine Annahme, die der KI-Agent getroffen hat.
parts[].data_result_artifact_name STRING Name eines Datenergebnisses.
parts[].chart_artifact_name STRING Name eines Diagramms.
followup_questions ARRAY<STRING> Vorgeschlagene weiterführende Fragen.
clarifying_question STRING Wird festgelegt, wenn der KI-Agent dem Nutzer eine klärende Frage gestellt hat, anstatt zu antworten.
citation_sources JSON In der Antwort zitierte Quellen.

Nächste Schritte