Menggunakan BigQuery Agent Analytics

BigQuery Agent Analytics adalah solusi open source yang memungkinkan Anda menangkap, menganalisis, dan memvisualisasikan data interaksi agen multimodal dalam skala besar dengan melakukan streaming interaksi agen mentah—seperti permintaan, respons, panggilan alat, dan error—langsung ke BigQuery. Solusi ini memungkinkan Anda melakukan evaluasi yang didukung AI, mengoptimalkan perintah agen, dan mengekstrak memori jangka panjang untuk meningkatkan interaksi di masa mendatang. BigQuery Agent Analytics didukung di Agent Development Kit (ADK) dan LangGraph (Pratinjau).

Arsitektur

BigQuery Agent Analytics mengalirkan data aktivitas agen ke BigQuery menggunakan BigQuery Storage Write API (gRPC), yang menyediakan streaming log dengan throughput tinggi dan latensi rendah tanpa memblokir eksekusi agen.

Aliran data terdiri dari tahap-tahap berikut:

  1. Ambil. Gunakan plugin logging di ADK atau handler callback di LangGraph untuk menangkap dan merekam peristiwa interaksi agen.
  2. Streaming. Peristiwa interaksi dikirim ke BigQuery melalui Storage Write API (gRPC). Jika skema standar tidak ada, agen akan membuatnya secara otomatis.
  3. Konsumsi. Menganalisis dan mengevaluasi data agen yang dicatat dalam log. Anda dapat mengkueri data mentah dengan SQL, melacak metrik di dasbor kustom, atau menggunakan BigQuery Agent Analytics SDK untuk merekonstruksi dan mengevaluasi trace eksekusi agen multi-turn yang kompleks.

Diagram yang menunjukkan data aktivitas agen yang mengalir dari framework orkestrasi ke BigQuery untuk dianalisis.

Manfaat analisis agen

  • Aktifkan logging yang komprehensif dengan satu baris kode dan otomatiskan pengelolaan skema.
  • Mencatat dan menganalisis data multimodal, seperti teks, gambar, video, dan audio, menggunakan tabel objek.
  • Lacak metrik operasional, seperti konsumsi token dan latensi, dalam skema yang andal dan telah ditentukan sebelumnya.
  • Mengidentifikasi peluang pengoptimalan menggunakan fungsi AI generatif dan penelusuran vektor BigQuery.
  • Amankan log agen dengan kontrol akses terperinci, penyamaran data, dan enkripsi.

Memilih library untuk setiap tahap alur kerja

BigQuery Agent Analytics memiliki dua integrasi logging dan satu SDK analisis. Integrasi logging dan SDK analisis melayani berbagai tahapan alur kerja Anda:

  • Mencatat peristiwa agen ke dalam log: gunakan integrasi logging untuk framework agen Anda, baik plugin ADK maupun handler callback LangGraph dan LangChain. Anda hanya memerlukan satu integrasi logging, dan Anda tidak memerlukan SDK analisis untuk mencatat peristiwa ke dalam log. Untuk framework lain, atau untuk mengaktifkan logging percakapan bawaan bagi agen data analisis percakapan, lihat Cara mengambil data log agen.
  • Menganalisis peristiwa agen: gunakan BigQuery Agent Analytics SDK untuk membuat kueri, merekonstruksi, dan mengevaluasi peristiwa yang dicatat ke dalam log. Anda juga dapat menganalisis peristiwa dengan kueri SQL dan dasbor.

Diagram berikut menunjukkan library yang akan digunakan di setiap tahap alur kerja:

Plugin ADK atau handler callback LangGraph dan LangChain melakukan streaming peristiwa agen ke tabel peristiwa BigQuery yang Anda analisis dengan SDK analisis agen BigQuery, kueri SQL, atau dasbor.

Tabel berikut menjelaskan setiap integrasi logging dan Analytics SDK:

Tahap alur kerja Integrasi atau SDK Paket dan titik entri Kapan menggunakannya
Mencatat peristiwa agen ke dalam log Plugin analisis agen BigQuery ADK

Paket Python google-adk[bigquery-analytics]

Class BigQueryAgentAnalyticsPlugin

Untuk bahasa lain, seperti Java, lihat panduan plugin ADK.

 Gunakan di agen ADK untuk menstreaming permintaan LLM, panggilan alat, dan peristiwa alur kerja ke BigQuery.
Mencatat peristiwa agen ke dalam log Handler callback BigQuery LangGraph dan LangChain (Pratinjau)

Paket Python langchain-google-community[bigquery]

Class BigQueryCallbackHandler

 Gunakan dalam aplikasi LangGraph atau LangChain untuk melakukan streaming peristiwa eksekusi agen ke BigQuery.
Menganalisis peristiwa agen BigQuery Agent Analytics SDK

Paket Python bigquery-agent-analytics

Class Client dan GraderPipeline

 Gunakan dalam pipeline evaluasi, notebook, atau layanan audit untuk membaca tabel peristiwa yang ditulis oleh integrasi logging Anda, merekonstruksi sesi multi-turn, dan menjalankan evaluasi otomatis.

Cara mengambil data log agen

Untuk merekam telemetri interaksi agen Anda (permintaan, respons, panggilan alat, dan log error) secara native ke BigQuery, Anda dapat mencatat data peristiwa ke dalam log dengan beberapa cara:

  • Plugin framework orkestrasi: gunakan plugin logging standar yang disediakan oleh toolkit orkestrasi agen Anda. Misalnya, BigQueryAgentAnalyticsPlugin di ADK terhubung ke runner agen untuk otomatis menangkap, melakukan serialisasi, dan menstreaming peristiwa.
  • Handler callback framework: mengintegrasikan callback standar di lingkungan agen populer. Misalnya, Anda dapat menggunakan BigQueryCallbackHandler dari paket langchain-google-community di LangGraph dan LangChain untuk mencegat dan meneruskan trace ke BigQuery.
  • Penyerapan API langsung: untuk framework kustom atau eksklusif, gunakan library klienGoogle Cloud untuk mengalirkan peristiwa terstruktur langsung ke tabel peristiwa menggunakan Storage Write API (gRPC).
  • Agen data analisis percakapan: aktifkan logging percakapan bawaan saat Anda mengonfigurasi setelan untuk agen data BigQuery di BigQuery Studio atau melalui Conversational Analytics API untuk otomatis melakukan streaming peristiwa percakapan ke tabel BigQuery tujuan dan menganalisis log percakapan.

Terlepas dari metodenya, semua opsi logging menggunakan BigQuery Storage Write API (gRPC) dengan latensi rendah dan throughput tinggi. API ini menyediakan endpoint streaming yang andal, yang melakukan buffering dan serialisasi baris (menggunakan mesin PyArrow) secara asinkron dalam memori sebelum meng-commit-nya, sehingga memastikan tugas pipeline kemampuan observasi tidak memblokir giliran eksekusi agen yang ditampilkan kepada pengguna.

Cara menganalisis data log agen

Untuk memahami dan mengoptimalkan performa agen, analisis dan evaluasi log interaksi dengan cara berikut:

  • Kueri SQL langsung: jalankan kueri kustom di BigQuery untuk menghitung metrik seperti konsumsi token dan latensi eksekusi. Anda juga dapat menggunakan AI.GENERATE untuk analisis penyebab utama error secara otomatis, atau melakukan penggabungan dengan tabel bisnis untuk mengukur dampak bisnis.
  • Dasbor interaktif: hubungkan alat visualisasi seperti Data Studio ke tampilan BigQuery bawaan atau kustom untuk melacak kondisi agen, tingkat error, dan tren penggunaan dari waktu ke waktu. Pelanggan Looker juga dapat menggunakan template dasbor BigQuery Agent Analytics bawaan (Looker Block) dari Looker Marketplace.
  • Notebook Jupyter: menjelajahi dan bereksperimen dengan data log menggunakan library Python, pandas, atau BigFrames di lingkungan interaktif.
  • Python SDK: mengkueri, merekonstruksi, dan mengaudit trace eksekusi agen secara terprogram langsung dalam kode aplikasi atau pipeline evaluasi otomatis Anda.

Contoh penggunaan data log agen

Berikut adalah kasus penggunaan umum dan contoh penggunaan data log agen di BigQuery.

Metrik operasional dan kemampuan observasi

  • Buat kueri data untuk menguraikan biaya berdasarkan alur agen dan menentukan apakah agen tertentu, seperti agen penyempurnaan, menggunakan jumlah token yang tidak proporsional dibandingkan dengan kontribusinya terhadap respons akhir.
  • Gunakan agen analisis percakapan BigQuery untuk analisis akar masalah yang didukung AI dengan menjalankan kueri menggunakan fungsi AI.GENERATE. Misalnya, "Analisis log percakapan ini dan jelaskan akar penyebab kegagalan."

Evaluasi agen dan analisis kualitas

  • Beri peringkat percakapan dan ukur peringkat agen dari waktu ke waktu menggunakan fungsi AI.SCORE.
  • Identifikasi cluster percakapan tempat agen gagal membantu pengguna dengan menggunakan kueri SQL dengan Penelusuran Vektor, lalu bandingkan dengan niat asli pengguna. Hal ini membantu Anda mengidentifikasi kesenjangan dalam alat atau pusat informasi agen.

Insight bisnis dan kontekstualisasi

Untuk mengontekstualisasikan data agen, gabungkan tabel agent_events dengan tabel bisnis lainnya. Misalnya, tampilkan nilai pesanan rata-rata (AOV) untuk pelanggan yang berinteraksi dengan agen AI versus pelanggan yang menggunakan kotak penelusuran.

Untuk contoh lainnya, lihat resep kueri.

Menggunakan notebook Jupyter untuk menggunakan log agen

Gunakan contoh notebook Jupyter Colab ini untuk membuat kueri, memvisualisasikan, dan mengevaluasi log agen secara interaktif.

Menggunakan SDK BigQuery Agent Analytics

BigQuery Agent Analytics SDK adalah library Python open source yang menyediakan lapisan konsumsi dan evaluasi untuk observabilitas agen jangka panjang. Dasbor dan notebook sangat cocok untuk eksplorasi ad hoc, dan SDK menyediakan cara untuk menganalisis dan mengaudit perilaku agen secara sistematis dalam skala besar.

Yang dapat Anda lakukan dengan SDK

Anda dapat melakukan tugas berikut menggunakan SDK BigQuery Agent Analytics. Untuk contoh analisis log yang mendetail, lihat repositori GitHub untuk SDK.

  • Rekonstruksi rekaman aktivitas: merekonstruksi log peristiwa polimorfik menjadi rantai peristiwa kausal untuk men-debug sesi di beberapa giliran, termasuk panggilan alat dan LLM bertingkat.
  • Evaluasi deterministik dan semantik: menilai kualitas agen berdasarkan kriteria berbasis aturan, seperti latensi, jumlah giliran, dan tingkat error, serta kriteria semantik, seperti kebenaran, sentimen, dan halusinasi.
  • Pencocokan lintasan: bandingkan jalur eksekusi agen yang sebenarnya dengan lintasan emas yang diharapkan untuk memverifikasi efisiensi langkah dan apakah alat digunakan dalam urutan yang benar.
  • Pemantauan perilaku dan deteksi penyimpangan: melakukan analisis statistik pada output agen non-deterministik, memantau distribusi permintaan pengguna, dan mendeteksi regresi produksi atau penyimpangan semantik.
  • Memori agen jangka panjang: memberikan konteks lintas sesi, pengambilan semantik profil pengguna, dan memori episodik yang mempertimbangkan anggaran token yang disimpan secara native di BigQuery kepada agen.

Mencatat dan menganalisis aktivitas agen

SDK membaca dan mengevaluasi peristiwa yang ditulis oleh integrasi logging. Alur kerja standar melibatkan langkah-langkah berikut:

  1. Mencatat interaksi ke dalam log: dalam framework orkestrasi agen, lampirkan integrasi logging, seperti BigQueryAgentAnalyticsPlugin di ADK atau BigQueryCallbackHandler di LangGraph. Saat pengguna berinteraksi dengan agen Anda, integrasi akan mengalirkan peristiwa secara asinkron ke BigQuery menggunakan Storage Write API (gRPC) dengan throughput tinggi. Langkah ini tidak memerlukan SDK.

  2. Melakukan inisialisasi klien: hubungkan ke set data log Anda dari Python SDK:

    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",
)

    Cuplikan ini menggunakan komponen berikut:

    • client: instance Client induk yang secara terprogram merutekan kueri dan mengelola koneksi database aktif.
    • project_id: Google Cloud project ID yang menampung set data target.
    • dataset_id: nama set data BigQuery yang menyimpan log.
    • table_id: tabel yang menyimpan peristiwa yang dicatat ke dalam log (agent_events secara default). Nilai ini harus cocok dengan tabel yang ditulis oleh integrasi logging Anda. Misalnya, BigQueryCallbackHandler di langchain-google-community versi 4.0.0 dan yang lebih lama menulis ke agent_events_v2 secara default.

  3. Merekonstruksi rekaman aktivitas sesi: mengambil sesi percakapan tertentu untuk memvisualisasikan dan meninjau urutan peristiwa yang tepat:

    trace = client.get_session_trace(
    session_id="YOUR_SESSION_ID"
)
trace.render()

    Cuplikan ini menggunakan komponen berikut:

    • trace: objek Trace yang di-hydrate yang menampung hierarki span DAG hierarkis yang direkonstruksi secara kausal dari semua tindakan pengguna dan agen.
    • YOUR_SESSION_ID: ID unik sesi yang ingin Anda periksa.

  4. Menjalankan evaluasi otomatis: memberi skor pada trajektori sesi secara terprogram atau memeriksa regresi terhadap suite pengujian emas:

    from bigquery_agent_analytics import (
    LLMAsJudge,
    TraceFilter,
)

# Run semantic evaluations across target sessions
evaluator = LLMAsJudge.correctness()
filters = TraceFilter(session_ids=["session_1", "session_2"])

report = client.evaluate(evaluator, filters=filters)
print(f"Evaluation Pass Rate: {report.pass_rate:.2%}")

    Cuplikan ini menggunakan komponen berikut:

    • evaluator: evaluator semantik (LLMAsJudge) yang digunakan untuk menilai sesi (Anda juga dapat menjalankan pemeriksaan SystemEvaluator berbasis aturan atau menggabungkan evaluator ke dalam GraderPipeline berbobot).
    • filters: instance TraceFilter yang menentukan daftar session_ids (atau periode waktu dan filter agen) untuk menjalankan evaluasi batch di BigQuery.
    • report: objek EvaluationReport yang dihasilkan yang berisi nilai sesi mentah, ringkasan metrik, dan masukan penilai otomatis.

Mengintegrasikan BigQuery Agent Analytics ke dalam alur kerja Anda

Untuk mengintegrasikan BigQuery Agent Analytics ke dalam alur kerja Anda, lakukan hal berikut:

  1. Siapkan integrasi logging untuk framework agen Anda:

  2. Analisis peristiwa yang dicatat ke dalam log dengan BigQuery Agent Analytics SDK, contoh notebook Colab, atau resep kueri SQL.

Langkah berikutnya