会話ログのスキーマ

このドキュメントでは、BigQuery での会話分析の会話ロギングのテーブル レイアウト、列、イベントタイプ、ユーザー ID フィールド、JSON ペイロード構造について説明します。会話ロギングの仕組みの概要については、会話ロギングの概要をご覧ください。

テーブル レイアウトと自動作成

ロギングを有効にする前に、データ エージェントと同じプロジェクトに宛先データセットを作成します。会話分析 API サービス エージェントは、最初のログに記録されたターンでデータセットのロケーションにテーブルを作成します（または、互換性のある既存のテーブルに欠落しているスキーマ列を追加します）。自動作成されたテーブルは、timestamp で日ごとにパーティション分割され（データセットのデフォルトのパーティション有効期限を継承）、event_type、agent、user_id でクラスタ化されます。テーブルをクエリするときは、常に timestamp でフィルタします。

列

次の表に、会話ロギングの宛先テーブルの列を示します。

列 種類 モード 目次
timestamp TIMESTAMP REQUIRED イベントの UTC 時刻。パーティショニング列。
event_id STRING NULLABLE イベントの一意の ID。書き込みが再試行されても同じままなので、重複を削除するために使用できます。
event_type STRING NULLABLE イベントの種類。イベントタイプをご覧ください。
agent STRING NULLABLE エージェントのタイプ。エージェントの名前や ID ではありません（例: ConversationalAnalyticsAgent）。エージェントを区別するには、データ エージェント ID を使用します（attributes 内のフィールドを参照）。
session_id STRING NULLABLE 会話全体ではなく、1 ターン。1 つの質問とその回答のすべてのイベントは、session_id を共有します。ターンを会話にグループ化するには、attributes の会話 ID を使用します。
invocation_id STRING NULLABLE 1 ターン内の 1 回の実行。
user_id STRING NULLABLE 質問をした発信者。ユーザー ID をご覧ください。
trace_id STRING NULLABLE OpenTelemetry トレース ID（32 桁の 16 進数）。
span_id STRING NULLABLE ターンの実行ツリーにおけるこのオペレーションの ID。
parent_span_id STRING NULLABLE 親オペレーションの ID。
content JSON NULLABLE イベント ペイロード。その形状は event_type によって異なります。
content_parts RECORD REPEATED マルチパート コンテンツ。パートごとに 1 つの要素（mime_type、uri、object_ref、text、part_index、part_attributes、storage_mode など）。
attributes JSON NULLABLE メタデータ: データ エージェント ID、会話 ID、内部ユーザーキー、モデル バージョン、詳細なトークン使用量。
latency_ms JSON NULLABLE レイテンシの測定（total_ms、time_to_first_token_ms など）。
status STRING NULLABLE OK または ERROR
error_message STRING NULLABLE エラーの詳細。モデルが通常の停止以外の理由で停止した場合（最大トークン上限に達した場合など）、OK LLM_RESPONSE 行に設定することもできます。
is_truncated BOOLEAN NULLABLE イベント内のテキスト値が 512,000 文字（500 * 1,024）を超えて切り捨てられた場合は true。カット値の末尾は ...[TRUNCATED] です。削除した部分は復元できません。

イベントタイプ

次の表に、event_type 列に表示される値と、各イベントのデータを格納する列または JSON フィールドを示します。

event_type 値 説明 入力された列と JSON フィールド
INVOCATION_STARTING ターンの開始。 なし
USER_MESSAGE_RECEIVED ユーザーの質問。 content.text_summary
AGENT_RESPONSE エージェントの回答（構造化オブジェクト）。 content.text_summary（書式なしテキスト）と content.response（AGENT_RESPONSE の構造を参照）
LLM_RESPONSE モデル呼び出しごとに 1 行。ツールをリクエストした呼び出しも含まれます（検証済みのクエリからターンに直接回答された場合は書き込まれません。attributes.fast_path は true です）。モデルの出力は保存されません。 トークン: content.usage.prompt、content.usage.completion、content.usage.total。モデル: attributes.model_version。終了理由: attributes.finish_reason。詳細な使用方法: attributes.usage_metadata（例: cached_content_token_count、thoughts_token_count）。
INVOCATION_COMPLETED ターンの終了。ターンごとのレイテンシ。content が空です。 latency_ms.total_ms
EMBEDDING_SUGGESTION エンベディングのメリットを享受できる列に関するエージェント オーナー向けの提案。一部のエージェントにのみ表示されます。 content.reason、 content.suggested_columns
INVOCATION_ERROR, AGENT_ERROR, LLM_ERROR 曲がり損ね。status は ERROR、content は NULL です。 error_message（SQL ステートメントとテーブル名が削除された 1 行の概要）

ユーザー ID

user_id 列には、呼び出し元のメールアドレス（ユーザーのメールアドレス、API 呼び出し元がサービス アカウントで認証する場合はサービス アカウントのメールアドレス、呼び出し元にメールアドレスがない場合は NULL（Workforce Identity フェデレーション ID など））が含まれます。内部ユーザーキーもすべての行の attributes.session_metadata.user_id に記録されるため、internal_user_key を使用して個別のユーザーをカウントできます（クロスエージェント イベント ビューを作成するをご覧ください）。

サービス アカウントを介して API を呼び出すときに、ターンを独自のエンドユーザーに帰属させるには、アプリケーションにユーザー マッピングを記録します。この API は、ロギング用のエンドユーザー識別子を受け入れません。

attributes 内のフィールド

次の表に、attributes JSON 列からメタデータ フィールドを抽出するために使用される GoogleSQL 式を示します。

必要なもの GoogleSQL 式
データ エージェント ID JSON_VALUE(attributes, '$.session_metadata.state."data-agent-id"')
データ エージェントの完全なリソース名 JSON_VALUE(attributes, '$.adk.app_name')
会話 ID JSON_VALUE(attributes, '$.session_metadata.state."conversation-id"')
内部ユーザーキー JSON_VALUE(attributes, '$.session_metadata.user_id')
モデル バージョン（LLM_RESPONSE 行） JSON_VALUE(attributes, '$.model_version')

AGENT_RESPONSE の構造

エージェントの回答を書式なしテキストとして読み取るには、JSON_VALUE(content, '$.text_summary') を使用します。回答の Markdown、前提、分析情報の部分、明確化のための質問を組み合わせます。AGENT_RESPONSE 行では、content.response は文字列ではなく JSON オブジェクトであるため、JSON_VALUE(content, '$.response') は NULL を返します。

次の表に、content.response のパスを示します。

content.response のパス 種類 目次
parts ARRAY<JSON> 回答（部分）。
parts[].markdown STRING 回答テキスト（マークダウン）。
parts[].insight STRING データから得られた分析情報。
parts[].assumption STRING エージェントが行った仮定。
parts[].data_result_artifact_name STRING データ結果の名前。
parts[].chart_artifact_name STRING グラフの名前。
followup_questions ARRAY<STRING> フォローアップの質問の候補。
clarifying_question STRING エージェントが回答する代わりに、ユーザーに確認の質問をした場合に設定します。
citation_sources JSON 回答で引用されているソース。

次のステップ