Menggunakan analisis agen BigQuery

Analisis agen BigQuery adalah solusi open source yang memungkinkan Anda mengambil, 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 kualitas interaksi di masa mendatang. Analisis agen BigQuery didukung di Agent Development Kit (ADK) dan LangGraph (Pratinjau).

Arsitektur

Analisis agen BigQuery mengalirkan data aktivitas agen ke BigQuery menggunakan BigQuery Storage Write API, yang menyediakan streaming log berlatensi rendah dan throughput tinggi tanpa memblokir eksekusi agen.

Aliran data terdiri dari tahap-tahap berikut:

  1. Ambil. Gunakan plugin di Agent Development Kit (ADK) atau callback di LangGraph untuk mencegat peristiwa interaksi guna merekam peristiwa agen.
  2. Streaming. Peristiwa interaksi dikirim ke BigQuery melalui Storage Write API. Jika skema standar tidak ada, agen akan membuatnya secara otomatis.
  3. Konsumsi. Menganalisis dan mengevaluasi data agen yang dicatat. Anda dapat membuat kueri data mentah dengan SQL, melacak metrik di dasbor kustom, atau menggunakan SDK analisis agen BigQuery untuk merekonstruksi dan mengevaluasi rekaman aktivitas 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 komprehensif dengan satu baris kode dan otomatiskan pengelolaan skema.
  • Mencatat dan menganalisis data multimodal, seperti teks, gambar, video, dan audio, dengan menggunakan tabel objek.
  • Pantau metrik operasional, seperti penggunaan token dan latensi, dalam skema yang telah ditentukan dan kuat.
  • Identifikasi peluang pengoptimalan menggunakan fungsi AI generatif dan penelusuran vektor BigQuery.
  • Amankan log agen dengan kontrol akses terperinci, penyamaran data, dan enkripsi.

Cara merekam 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 dengan beberapa cara:

  • Plugin framework orkestrasi: menggunakan plugin logging standar yang disediakan oleh toolkit orkestrasi agen Anda. Misalnya, BigQueryAgentAnalyticsPlugin di Agent Development Kit (ADK) terhubung ke pelaksana agen untuk otomatis mencegat, membuat serial, dan melakukan streaming peristiwa.
  • Handler callback framework: mengintegrasikan callback standar di lingkungan agen yang populer. Misalnya, Anda dapat menggunakan handler BigQuery bawaan di LangGraph dan LangChain untuk mencegat dan meneruskan rekaman aktivitas.
  • Penyerapan API langsung: untuk framework kustom atau eksklusif, gunakan library klienGoogle Cloud untuk melakukan streaming peristiwa terstruktur langsung ke tabel peristiwa menggunakan Storage Write API.

Terlepas dari metode yang digunakan, semua opsi logging menggunakan BigQuery Storage Write API dengan latensi rendah dan throughput tinggi. API ini menyediakan endpoint streaming yang kuat yang melakukan buffering dan menyerialkan baris (menggunakan mesin PyArrow) secara asinkron dalam memori sebelum melakukan commit, sehingga memastikan tugas pipeline observabilitas tidak memblokir giliran eksekusi agen yang terlihat oleh 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 masalah otomatis pada error, 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, rasio error, dan tren penggunaan dari waktu ke waktu.
  • Notebook Jupyter: jelajahi dan bereksperimen dengan data log menggunakan library Python, pandas, atau BigFrames di lingkungan interaktif.
  • Python SDK: mengkueri, merekonstruksi, dan mengaudit jejak eksekusi agen secara terprogram langsung dalam kode aplikasi atau pipeline evaluasi otomatis.

Contoh cara menggunakan data log agen

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

Metrik operasional dan kemampuan observasi

  • Kueri data untuk mengelompokkan biaya menurut 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 penyebab 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

  • Peringkat percakapan dan ukur peringkat agen dari waktu ke waktu menggunakan fungsi AI.SCORE.
  • Identifikasi kelompok percakapan saat agen gagal membantu pengguna dengan menggunakan kueri SQL dengan Penelusuran Vektor, lalu bandingkan dengan maksud awal pengguna. Hal ini membantu Anda mengidentifikasi kekurangan dalam alat atau basis pengetahuan agen.

Insight dan kontekstualisasi bisnis

Untuk memberikan konteks pada data agen, gabungkan tabel agent_events dengan tabel bisnis lainnya . Misalnya, tunjukkan nilai pesanan rata-rata (AOV) untuk pelanggan yang berinteraksi dengan agen AI dibandingkan dengan pelanggan yang menggunakan kotak penelusuran.

Untuk contoh lainnya, lihat Kueri analisis lanjutan.

Menggunakan notebook Jupyter untuk menangani log agen

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

Menggunakan SDK analisis agen BigQuery

SDK analisis agen BigQuery adalah library Python open source yang menyediakan lapisan konsumsi dan evaluasi untuk kemampuan observasi 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 analisis agen BigQuery. Untuk contoh analisis log yang mendetail, lihat repositori GitHub untuk SDK.

  • Rekonstruksi jejak: merekonstruksi log peristiwa polimorfik menjadi rantai peristiwa kausal untuk men-debug sesi di beberapa giliran, termasuk panggilan alat dan LLM bertingkat.
  • Evaluasi semantik dan deterministik: 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 sebenarnya dengan lintasan ideal yang diharapkan untuk memverifikasi efisiensi langkah dan apakah alat digunakan dalam urutan yang benar.
  • Pemantauan perilaku dan deteksi penyimpangan: melakukan analisis statistik terhadap output agen non-deterministik, memantau distribusi permintaan pengguna, dan mendeteksi regresi produksi atau penyimpangan semantik.
  • Memori agen dengan cakrawala panjang: memberikan konteks lintas sesi kepada agen, pengambilan semantik profil pengguna, dan memori episodik yang memperhatikan anggaran token yang disimpan secara native di BigQuery.

Mencatat dan menganalisis aktivitas agen

Mengintegrasikan SDK ke dalam alur kerja agen biasanya melibatkan langkah-langkah berikut:

  1. Mencatat interaksi: Lampirkan plugin logger (seperti BigQueryAgentAnalyticsPlugin di ADK) atau handler callback di framework orkestrasi agen Anda. Saat pengguna berinteraksi dengan agen Anda, log akan di-streaming secara asinkron ke BigQuery menggunakan Storage Write API dengan throughput tinggi.

  2. Menginisialisasi 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 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 tertentu yang menyimpan peristiwa telemetri (agent_events secara default).

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

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

    Cuplikan menggunakan komponen berikut:

    • trace: objek Trace yang di-hydrasi yang menyimpan pohon rentang DAG hierarkis yang direkonstruksi dan terkait secara kausal dari semua tindakan pengguna dan agen.
    • YOUR_SESSION_ID: ID unik sesi yang ingin Anda periksa.

  4. Menjalankan evaluasi otomatis: Memberi skor secara terprogram pada alur sesi atau memeriksa regresi terhadap suite pengujian golden:

    from bigquery_agent_analytics.evaluators import CodeEvaluator, LLMAsJudge
from bigquery_agent_analytics.grader_pipeline import GraderPipeline

# Create a grader pipeline with deterministic and semantic metrics
evaluator = GraderPipeline(
    graders=[
        CodeEvaluator.latency(threshold_ms=5000),
        LLMAsJudge.correctness(),
    ]
)
report = client.evaluate(evaluator, session_ids=["session_1", "session_2"])
print(f"Evaluation Pass Rate: {report.pass_rate:.2%}")

    Cuplikan menggunakan komponen berikut:

    • evaluator: logika terstruktur GraderPipeline yang dikompilasi dan terdiri dari metrik evaluasi semantik dan berbasis aturan heterogen.
    • session_ids: daftar string ID sesi untuk menjalankan evaluasi batch di BigQuery.
    • report: objek EvaluationReport yang dihasilkan berisi nilai sesi mentah, ringkasan metrik, statistik uji coba, dan masukan pemberi nilai otomatis.

Mengintegrasikan analisis agen BigQuery ke dalam alur kerja Anda

Untuk mengintegrasikan analisis agen BigQuery ke dalam alur kerja Anda, lihat dokumentasi untuk framework Anda:

Langkah berikutnya