会話ログのスキーマ
このドキュメントでは、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 |
回答で引用されているソース。 |