Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Skema log percakapan

Dokumen ini menjelaskan tata letak tabel, kolom, jenis peristiwa, kolom identitas pengguna, dan struktur payload JSON untuk logging percakapan analisis percakapan di BigQuery. Untuk ringkasan tentang cara kerja logging percakapan, lihat Ringkasan logging percakapan.

Tata letak tabel dan pembuatan otomatis

Buat set data tujuan dalam project yang sama dengan agen data sebelum mengaktifkan logging; agen layanan Conversational Analytics API membuat tabel di lokasi set data pada giliran pertama yang dicatat ke dalam log (atau menambahkan kolom skema yang tidak ada ke tabel yang kompatibel yang sudah ada). Tabel yang dibuat otomatis dipartisi berdasarkan hari di timestamp (mewarisi masa berlaku partisi default pada set data) dan dikelompokkan di event_type, agent, dan user_id. Selalu filter di timestamp saat Anda membuat kueri tabel.

Kolom

Tabel berikut menjelaskan kolom dalam tabel tujuan logging percakapan.

Kolom	Jenis	Mode	Daftar Isi
`timestamp`	`TIMESTAMP`	`REQUIRED`	Waktu UTC peristiwa. Kolom partisi.
`event_id`	`STRING`	`NULLABLE`	ID unik untuk peristiwa. ID ini tetap sama jika penulisan dicoba lagi, sehingga Anda dapat menggunakannya untuk menghapus duplikat.
`event_type`	`STRING`	`NULLABLE`	Jenis acara. Lihat Jenis peristiwa.
`agent`	`STRING`	`NULLABLE`	Jenis agen, bukan nama atau ID agen Anda (misalnya, `ConversationalAnalyticsAgent`). Untuk membedakan agen, gunakan ID agen data (lihat Kolom di dalam `attributes`).
`session_id`	`STRING`	`NULLABLE`	Satu giliran, bukan seluruh percakapan. Semua peristiwa untuk satu pertanyaan dan jawabannya memiliki `session_id` yang sama. Untuk mengelompokkan giliran menjadi percakapan, gunakan ID percakapan di `attributes`.
`invocation_id`	`STRING`	`NULLABLE`	Satu eksekusi dalam satu giliran.
`user_id`	`STRING`	`NULLABLE`	Penelepon yang mengajukan pertanyaan. Lihat Identitas pengguna.
`trace_id`	`STRING`	`NULLABLE`	ID trace OpenTelemetry (32 karakter heksadesimal).
`span_id`	`STRING`	`NULLABLE`	ID operasi ini di hierarki eksekusi giliran.
`parent_span_id`	`STRING`	`NULLABLE`	ID operasi induk.
`content`	`JSON`	`NULLABLE`	Payload peristiwa. Bentuknya bergantung pada `event_type`.
`content_parts`	`RECORD`	`REPEATED`	Konten multi-bagian, dengan satu elemen per bagian (misalnya, `mime_type`, `uri`, `object_ref`, `text`, `part_index`, `part_attributes`, dan `storage_mode`).
`attributes`	`JSON`	`NULLABLE`	Metadata: ID agen data, ID percakapan, kunci pengguna internal, versi model, dan penggunaan token mendetail.
`latency_ms`	`JSON`	`NULLABLE`	Pengukuran latensi, seperti `total_ms` dan `time_to_first_token_ms`.
`status`	`STRING`	`NULLABLE`	`OK` atau `ERROR`.
`error_message`	`STRING`	`NULLABLE`	Detail error. Nilai ini juga dapat ditetapkan pada baris `OK` `LLM_RESPONSE` saat model berhenti karena alasan selain penghentian normal (misalnya, saat mencapai batas token maksimum).
`is_truncated`	`BOOLEAN`	`NULLABLE`	`true` jika ada nilai teks dalam peristiwa yang melebihi 512.000 karakter (`500 * 1,024`) dan dipotong. Nilai potongan diakhiri dengan `...[TRUNCATED]`. Bagian yang dihapus tidak dapat dipulihkan.

Jenis peristiwa

Tabel berikut menjelaskan nilai yang dapat muncul di kolom event_type dan kolom atau kolom JSON yang menyimpan data untuk setiap peristiwa.

Nilai `event_type`	Deskripsi	Kolom yang terisi dan kolom JSON
`INVOCATION_STARTING`	Awal giliran.	Tidak ada
`USER_MESSAGE_RECEIVED`	Pertanyaan pengguna.	`content.text_summary`
`AGENT_RESPONSE`	Jawaban agen, sebagai objek terstruktur.	`content.text_summary` (teks biasa) dan `content.response` (lihat Struktur `AGENT_RESPONSE`)
`LLM_RESPONSE`	Satu baris untuk setiap panggilan model, termasuk panggilan yang meminta alat (tidak ditulis saat giliran dijawab langsung dari kueri terverifikasi, dengan `attributes.fast_path` adalah `true`). Output model tidak disimpan.	Token: `content.usage.prompt`, `content.usage.completion`, `content.usage.total`. Model: `attributes.model_version`. Alasan penyelesaian: `attributes.finish_reason`. Penggunaan mendetail: `attributes.usage_metadata` (misalnya, `cached_content_token_count` dan `thoughts_token_count`).
`INVOCATION_COMPLETED`	Akhir giliran, dengan latensi per giliran. `content` kosong.	`latency_ms.total_ms`
`EMBEDDING_SUGGESTION`	Saran untuk pemilik agen tentang kolom yang dapat memperoleh manfaat dari embedding. Kolom ini hanya muncul untuk beberapa agen.	`content.reason`, `content.suggested_columns`
`INVOCATION_ERROR`, `AGENT_ERROR`, `LLM_ERROR`	Giliran gagal. `status` adalah `ERROR` dan `content` adalah `NULL`.	`error_message` (ringkasan satu baris dengan pernyataan SQL dan nama tabel yang disamarkan)

Identitas pengguna

Kolom user_id berisi alamat email pemanggil: alamat email pengguna, alamat email akun layanan saat pemanggil API melakukan autentikasi dengan akun layanan, atau NULL jika pemanggil tidak memiliki alamat email (seperti beberapa identitas gabungan Workforce Identity Federation). Kunci pengguna internal juga dicatat di attributes.session_metadata.user_id pada setiap baris, sehingga Anda dapat menghitung pengguna yang berbeda dengan internal_user_key (lihat Membuat tampilan peristiwa lintas agen).

Untuk mengatribusikan giliran ke pengguna akhir Anda sendiri saat Anda memanggil API melalui akun layanan, catat pemetaan pengguna di aplikasi Anda. API tidak menerima ID pengguna akhir untuk logging.

Kolom di dalam `attributes`

Tabel berikut menunjukkan ekspresi GoogleSQL yang digunakan untuk mengekstrak kolom metadata dari kolom JSON attributes.

Yang Anda perlukan	Ekspresi GoogleSQL
ID agen data	`JSON_VALUE(attributes, '$.session_metadata.state."data-agent-id"')`
Nama lengkap resource agen data	`JSON_VALUE(attributes, '$.adk.app_name')`
ID Percakapan	`JSON_VALUE(attributes, '$.session_metadata.state."conversation-id"')`
Kunci pengguna internal	`JSON_VALUE(attributes, '$.session_metadata.user_id')`
Versi model (pada `LLM_RESPONSE` baris)	`JSON_VALUE(attributes, '$.model_version')`

Struktur `AGENT_RESPONSE`

Untuk membaca jawaban agen sebagai teks biasa, gunakan JSON_VALUE(content, '$.text_summary'). Respons ini menggabungkan bagian Markdown, asumsi, dan insight jawaban, serta pertanyaan klarifikasi. Dalam baris AGENT_RESPONSE, content.response adalah objek JSON, bukan string, sehingga JSON_VALUE(content, '$.response') menampilkan NULL.

Tabel berikut menjelaskan jalur di bagian content.response.

Jalur di `content.response`	Jenis	Daftar Isi
`parts`	`ARRAY<JSON>`	Jawabannya, dalam beberapa bagian.
`parts[].markdown`	`STRING`	Teks jawaban (Markdown).
`parts[].insight`	`STRING`	Insight yang diambil dari data.
`parts[].assumption`	`STRING`	Asumsi yang dibuat agen.
`parts[].data_result_artifact_name`	`STRING`	Nama hasil data.
`parts[].chart_artifact_name`	`STRING`	Nama diagram.
`followup_questions`	`ARRAY<STRING>`	Pertanyaan lanjutan yang disarankan.
`clarifying_question`	`STRING`	Ditetapkan saat agen mengajukan pertanyaan klarifikasi kepada pengguna, bukan menjawab.
`citation_sources`	`JSON`	Sumber yang dikutip dalam jawaban.