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

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 interaksi di masa mendatang. Analisis agen BigQuery didukung di Agent Development Kit (ADK) dan LangGraph (Pratinjau).

Arsitektur

Analisis agen BigQuery melakukan streaming 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 tahapan berikut:

Ambil. Gunakan plugin di Agent Development Kit (ADK) atau callback di LangGraph untuk mencegat peristiwa interaksi guna mengambil peristiwa agen.
Streaming. Peristiwa interaksi dikirim ke BigQuery melalui Storage Write API (gRPC). Jika tidak ada skema standar, agen akan membuatnya secara otomatis.
Konsumsi. Analisis dan evaluasi data agen yang dicatat dalam log. Anda dapat membuat kueri data mentah dengan SQL, melacak metrik di dasbor kustom, atau menggunakan BigQuery agent analytics SDK untuk merekonstruksi dan mengevaluasi jejak 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.
Catat dan analisis data multimodal, seperti teks, gambar, video, dan audio, menggunakan tabel objek.
Lacak metrik operasional, seperti penggunaan token dan latensi, dalam skema yang kuat dan telah ditentukan sebelumnya.
Identifikasi peluang pengoptimalan menggunakan fungsi AI generatif dan penelusuran vektor BigQuery.
Amankan log agen dengan kontrol akses terperinci, penyamaran data, dan enkripsi.

Cara mengambil data log agen

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

Plugin framework orkestrasi: gunakan plugin logging standar yang disediakan oleh toolkit orkestrasi agen Anda. Misalnya, BigQueryAgentAnalyticsPlugin di Agent Development Kit (ADK) terhubung ke runner agen untuk otomatis mencegat, melakukan serialisasi, dan melakukan streaming peristiwa.
Handler callback framework: integrasikan callback standar di lingkungan agen populer. Misalnya, Anda dapat menggunakan handler BigQuery bawaan di LangGraph dan LangChain untuk mencegat dan meneruskan jejak.
Penyerapan API langsung: untuk framework kustom atau eksklusif, gunakan Google Cloud library klien untuk melakukan streaming peristiwa terstruktur langsung ke tabel peristiwa menggunakan Storage Write API (gRPC).

Terlepas dari metodenya, semua opsi logging menggunakan BigQuery Storage Write API (gRPC) dengan latensi rendah dan throughput tinggi. API ini menyediakan endpoint streaming yang kuat yang melakukan buffering dan serialisasi baris (menggunakan mesin PyArrow) secara asinkron dalam memori sebelum melakukan commit, sehingga memastikan bahwa tugas pipeline kemampuan observasi tidak memblokir giliran eksekusi agen yang dihadapi 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 penggunaan token dan latensi eksekusi. Anda juga dapat menggunakan AI.GENERATE untuk analisis penyebab utama error otomatis, atau melakukan gabungan dengan tabel bisnis untuk mengukur dampak bisnis.
Dasbor interaktif: hubungkan alat visualisasi seperti Data Studio ke tampilan BigQuery bawaan atau kustom untuk melacak kesehatan agen, rasio error, dan tren penggunaan dari waktu ke waktu. Pelanggan Looker juga dapat menggunakan template dasbor Analisis Agen BigQuery bawaan (Blok Looker) dari Looker Marketplace.
Notebook Jupyter: jelajahi dan bereksperimen dengan data log menggunakan library Python, pandas, atau BigFrames di lingkungan interaktif.
Python SDK: secara terprogram kueri, rekonstruksi, dan audit jejak eksekusi agen langsung dalam kode aplikasi atau pipeline evaluasi otomatis.

Contoh penggunaan data log agen

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

Metrik kemampuan observasi dan operasional

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

Evaluasi agen dan analisis kualitas

Beri peringkat percakapan dan ukur peringkat agen dari waktu ke waktu menggunakan AI.SCORE fungsi.
Identifikasi cluster percakapan tempat agen gagal membantu pengguna dengan menggunakan kueri SQL dengan Penelusuran Vektor, lalu bandingkan dengan maksud awal pengguna. Hal ini membantu Anda mengidentifikasi celah dalam alat atau basis pengetahuan 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 dibandingkan dengan pelanggan yang menggunakan kotak penelusuran.

Untuk contoh lainnya, lihat Kueri analisis lanjutan.

Menggunakan notebook Jupyter untuk menggunakan log agen

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

Menggunakan BigQuery agent analytics SDK

BigQuery agent analytics SDK adalah library Python open source yang menyediakan lapisan konsumsi dan evaluasi untuk observabilitas agen jangka panjang. Dasbor dan notebook sangat baik 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 BigQuery agent analytics SDK. Untuk contoh analisis log yang mendetail, lihat repositori GitHub untuk SDK.

Rekonstruksi jejak: rekonstruksi 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 terhadap kriteria berbasis aturan, seperti latensi, jumlah giliran, dan rasio error, serta kriteria semantik, seperti kebenaran, sentimen, dan halusinasi.
Pencocokan lintasan: membandingkan jalur eksekusi agen aktual 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 atas output agen non-deterministik, memantau distribusi permintaan pengguna, dan mendeteksi regresi produksi atau penyimpangan semantik.
Memori agen jangka panjang: menyediakan konteks lintas sesi, 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:

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 (gRPC) dengan throughput tinggi.
Menginisialisasi klien: Hubungkan ke set data log 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 berisi set data target.
- dataset_id: nama set data BigQuery yang menyimpan log.
- table_id: tabel tertentu yang menyimpan peristiwa telemetri (agent_events secara default).
Merekonstruksi jejak 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 ini menggunakan komponen berikut:
- trace: objek Trace yang di-hydrate yang berisi pohon rentang DAG hierarkis yang direkonstruksi dan terhubung secara kausal dari semua tindakan pengguna dan agen.
- YOUR_SESSION_ID: ID unik sesi yang ingin Anda periksa.

Menjalankan evaluasi otomatis: Beri skor lintasan sesi secara terprogram atau periksa regresi terhadap suite pengujian emas:

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 ini menggunakan komponen berikut:

evaluator: logika terstruktur GraderPipeline yang dikompilasi yang 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 auto-rater.

Mengintegrasikan analisis agen BigQuery ke dalam alur kerja Anda

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

Panduan plugin Analisis BigQuery ADK
Integrasi handler callback BigQuery (LangChain dan LangGraph)

Langkah berikutnya

Pelajari codelab.