Melacak Keputusan Agen AI dengan BigQuery Graph

1. Pengantar

BigQuery Graph, BigQuery Conversational Analytics, dan BigQuery Agent Analytics SDK saat ini dalam Pratinjau di Google Cloud. Plugin BigQuery Agent Analytics Tersedia Secara Umum (GA). Contoh dalam codelab ini menggunakan data sintetis.

Saat agen AI otonom mengambil lebih banyak tanggung jawab operasional (mengevaluasi permohonan pinjaman, mengelola anggaran pemasaran, menyetujui permintaan akses), organisasi harus dapat mengaudit dan menjelaskan keputusannya. Merekonstruksi konteks yang tepat, alternatif yang dipertimbangkan, dan alasan akhir keputusan agen sangat penting untuk kepatuhan, pengelolaan risiko, dan kepercayaan operasional.

Codelab ini menggunakan BigQuery Agent Analytics SDK untuk mengubah log peristiwa agen mentah menjadi Grafik Konteks Agen — grafik yang dapat dikueri di BigQuery Graph keputusan agen — sesuai jadwal, tanpa database grafik eksternal atau pipeline ETL.

Istilah utama

• Jejak Keputusan Agen — bukti tingkat keputusan yang diambil dari operasi agen itu sendiri: opsi yang dipertimbangkan, data yang disentuh, dan hasil yang dilakukan.
• Grafik Konteks Agen — grafik yang diketik dan dapat dikueri di BigQuery Graph yang diwujudkan menjadi jejak tersebut. Ini adalah instance cakupan agen dari konsep grafik konteks industri (lapisan konteks keputusan yang tahan lama dan terkait waktu yang dihasilkan dan digunakan oleh agen); kualifikasi "Agen" mencakupnya ke operasi agen Anda sendiri, bukan lapisan konteks di seluruh perusahaan.

Dalam codelab ini, bqaa context-graph mengekstrak jejak keputusan agen dari agent_events Anda dan mewujudkannya menjadi Grafik Konteks Agen yang dapat Anda kueri dengan GQL — mengikuti pola industri tempat grafik konteks dibuat dari jejak keputusan.

Yang akan Anda buat

• Grafik Konteks Agen (dengan BigQuery Graph) yang memodelkan alur keputusan agen generik: permintaan masuk, agen mempertimbangkan opsi, hasil dilakukan.
• Tabel agent_events yang diisi dengan korpus peristiwa sintetis.
• Operasi bqaa context-graph yang berfungsi dan mengisi grafik dari peristiwa tersebut.
• Kueri GQL gaya audit yang melacak satu keputusan secara menyeluruh.

Yang akan Anda pelajari

• Cara BigQuery Agent Analytics Plugin menulis ke agent_events.
• Cara grafik konteks ditentukan hanya oleh dua artefak deklaratif — DDL tabel dan skema CREATE PROPERTY GRAPH.
• Cara menjalankan bqaa context-graph terhadap BigQuery Graph.
• Cara mengkueri grafik menggunakan GQL.
• Kemampuan tingkat produksi yang didukung SDK untuk deployment perusahaan.

Yang akan Anda butuhkan

• Project Google Cloud yang mengaktifkan penagihan.
• Peran Pemilik atau Editor di project tersebut. Anda akan membuat set data BigQuery dan memberikan IAM.
• gcloud CLI diinstal dan diautentikasi, atau akses ke Cloud Shell.
• Python 3.10 atau yang lebih baru.
• Pengetahuan tentang BigQuery SQL. Pengetahuan GQL tidak diperlukan.

Codelab ini ditujukan untuk developer dari semua level, termasuk yang baru menggunakan BigQuery Graph.

Resource yang dibuat dalam codelab ini memerlukan biaya yang sangat kecil, dan langkah terakhir akan menghapus semuanya sehingga Anda tidak ditagih untuk set data yang tidak aktif.

Perkiraan durasi: Codelab ini memerlukan waktu sekitar 35 menit untuk diselesaikan.

2. Sebelum memulai

Memilih project dan region

Buka Cloud Shell atau terminal lokal:

export PROJECT_ID="your-project-id"
export REGION="us-central1"
export DATASET="agent_analytics_demo"
gcloud config set project "$PROJECT_ID"

Variabel DATASET tunggal menyimpan tabel agent_events mentah dan tabel grafik yang diwujudkan. Menggunakan satu set data membuat codelab tetap sederhana. Deployment produksi sering kali membagi peristiwa dan grafik ke dalam set data terpisah sehingga IAM dapat diberikan secara sempit per set data.

Mengaktifkan API yang diperlukan

Jalankan perintah berikut untuk mengaktifkan API yang digunakan codelab ini:

gcloud services enable \
    bigquery.googleapis.com \
    aiplatform.googleapis.com \
    --project="$PROJECT_ID"

aiplatform.googleapis.com API diperlukan karena jalur ekstraksi default SDK memanggil fungsi AI.GENERATE BigQuery. Jika Anda kemudian beralih ke ekstraksi deterministik dengan --extraction-mode=compiled-only, API ini tidak lagi diperlukan.

Membuat set data BigQuery

Buat set data yang akan menyimpan tabel agent_events mentah dan tabel grafik yang diwujudkan:

bq --location=US mk --dataset "$PROJECT_ID:$DATASET"

Anda akan melihat pesan keberhasilan:

Dataset 'your-project-id:agent_analytics_demo' successfully created.

Jika set data sudah ada, perintah akan menampilkan error tanpa membahayakan. Biarkan di tempatnya.

3. Menginstal SDK

Siapkan lingkungan virtual Python dan instal SDK dari PyPI:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install bigquery-agent-analytics

Paket bigquery-agent-analytics menarik library klien BigQuery, sehingga ini adalah satu-satunya penginstalan yang Anda perlukan untuk seluruh codelab.

Verifikasi penginstalan:

bqaa context-graph --help | head -8

Anda akan melihat banner CLI.

Autentikasikan

Jika Anda menggunakan workstation:

gcloud auth login
gcloud auth application-default login

Pengguna Cloud Shell dapat melewati langkah ini; kredensial sudah dikonfigurasi.

4. Mendapatkan artefak codelab

Codelab hanya memerlukan dua artefak siap pakai: DDL tabel (tabel grafik fisik) dan skema grafik properti (CREATE PROPERTY GRAPH). Anda tidak membuat keduanya sendiri; codelab menggunakannya apa adanya, dan README di folder artefak menjelaskan cara mengadaptasinya untuk domain keputusan Anda sendiri.

Skema grafik properti adalah satu-satunya sumber kebenaran untuk apa yang ada dalam grafik. Anda menerapkannya ke BigQuery sekali; sejak saat itu grafik yang di-deploy itu sendiri adalah kontraknya. Saat Anda mewujudkan, bqaa context-graph membaca kembali definisi grafik dari INFORMATION_SCHEMA.PROPERTY_GRAPHS BigQuery (bersama dengan skema tabel yang direferensikannya) untuk mengetahui entity dan hubungan mana yang akan diekstrak dan tempat menuliskannya — sehingga tidak ada file SQL yang pernah diteruskan ke materializer.

Codelab ini mandiri, sehingga tidak ada yang perlu didownload. Perintah di bawah ini menulis DDL grafik konteks ke dalam direktori kerja. Isinya identik dengan artefak yang dikirimkan di examples/context_graph/codelab/.

Buat direktori kerja:

mkdir -p ~/context-graph-codelab
cd ~/context-graph-codelab

Tulis DDL grafik konteks (context_graph_ddl.sql). Penanda ${PROJECT_ID} / ${DATASET} akan diisi saat Anda menerapkan file pada langkah berikutnya.

cat > context_graph_ddl.sql <<'SQL'

-- Node and edge table DDL for the context-graph codelab.
--
-- `bqaa context-graph` writes into these tables on every run.
-- `session_id` and `extracted_at` are SDK metadata columns that
-- `bqaa context-graph` fills automatically; they are required on
-- every table behind the graph.
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.decision_request` (
  request_id STRING, request_text STRING, requested_at TIMESTAMP,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.decision_option` (
  option_id STRING, option_label STRING, confidence FLOAT64,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.decision_outcome` (
  outcome_id STRING, status STRING, rationale STRING, decided_at TIMESTAMP,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.evaluates_option` (
  request_id STRING, option_id STRING,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.resulted_in` (
  request_id STRING, outcome_id STRING,
  session_id STRING, extracted_at TIMESTAMP
);

-- Graph DDL for the context-graph codelab.
--
-- Models a generic agent decision flow:
--   DecisionRequest -> evaluatesOption -> DecisionOption
--   DecisionRequest -> resultedIn       -> DecisionOutcome
CREATE OR REPLACE PROPERTY GRAPH `${PROJECT_ID}.${DATASET}.agent_decisions_graph`
  NODE TABLES (
    `${PROJECT_ID}.${DATASET}.decision_request` AS decision_request
      KEY (request_id)
      LABEL DecisionRequest PROPERTIES (request_id, request_text, requested_at),
    `${PROJECT_ID}.${DATASET}.decision_option` AS decision_option
      KEY (option_id)
      LABEL DecisionOption PROPERTIES (option_id, option_label, confidence),
    `${PROJECT_ID}.${DATASET}.decision_outcome` AS decision_outcome
      KEY (outcome_id)
      LABEL DecisionOutcome PROPERTIES (outcome_id, status, rationale, decided_at)
  )
  EDGE TABLES (
    `${PROJECT_ID}.${DATASET}.evaluates_option` AS evaluates_option
      KEY (request_id, option_id)
      SOURCE KEY (request_id) REFERENCES decision_request (request_id)
      DESTINATION KEY (option_id) REFERENCES decision_option (option_id)
      LABEL evaluatesOption,
    `${PROJECT_ID}.${DATASET}.resulted_in` AS resulted_in
      KEY (request_id, outcome_id)
      SOURCE KEY (request_id) REFERENCES decision_request (request_id)
      DESTINATION KEY (outcome_id) REFERENCES decision_outcome (outcome_id)
      LABEL resultedIn
  );
SQL

Pastikan file sudah ada:

ls

Anda akan melihat satu file:

context_graph_ddl.sql

Alur keputusan yang dijelaskan memiliki tiga jenis node dan dua edge heterogen:

DecisionRequest adalah pertanyaan yang diterima agen. DecisionOption adalah salah satu alternatif yang dipertimbangkan agen. DecisionOutcome mencatat pilihan yang dilakukan dan alasannya.

5. Menerapkan skema grafik properti

bqaa context-graph menulis ke dalam tabel BigQuery, sehingga tabel tersebut harus ada sebelum operasi pertama. context_graph_ddl.sql membuat lima tabel terlebih dahulu, lalu grafik properti yang mereferensikannya (BigQuery menolak CREATE PROPERTY GRAPH yang mengarah ke tabel yang belum ada), sehingga satu penerapan akan menyiapkan semuanya:

envsubst < context_graph_ddl.sql | bq query --use_legacy_sql=false

Anda akan melihat lima hasil CREATE TABLE dan satu hasil CREATE PROPERTY GRAPH. DDL bersifat idempoten; Anda dapat menjalankannya kembali dengan aman.

Itulah satu-satunya pekerjaan skema yang Anda lakukan — dan satu-satunya waktu file SQL ini digunakan. BigQuery kini mencatat definisi grafik Anda, dan bqaa context-graph membacanya kembali dari INFORMATION_SCHEMA.PROPERTY_GRAPHS berdasarkan nama. Tidak ada file terpisah yang akan diteruskan ke materializer, dan apa yang Anda kueri dengan GQL dan apa yang diwujudkan tidak akan pernah berbeda: keduanya adalah grafik yang sama yang di-deploy.

6. Membuat peristiwa agen contoh

Dalam produksi, BigQuery Agent Analytics Plugin otomatis menangkap peristiwa saat agen ADK Anda berjalan. Cuplikan ini hanya untuk referensi — Anda tidak menjalankannya dalam codelab ini:

from google.adk.plugins import BigQueryAgentAnalyticsPlugin

plugin = BigQueryAgentAnalyticsPlugin(
    project_id="your-project-id",
    dataset_id="agent_analytics_demo",
)
runner = Runner(agent=root_agent, plugins=[plugin])

Untuk codelab ini, Anda menggunakan generator peristiwa sintetis kecil yang menulis bentuk baris yang sama langsung ke agent_events. Jalankan:

bqaa seed-events \
    --project-id "$PROJECT_ID" \
    --dataset-id "$DATASET" \
    --sessions 5

Perintah ini mencetak laporan JSON. Untuk 5 sesi, Anda akan melihat "events_generated": 30, "events_inserted": 30, dan "ok": true.

Pratinjau korpus secara sekilas — jumlah sesi, jumlah peristiwa, dan rentang waktu yang dicakup — dalam satu baris:

bq query --use_legacy_sql=false \
    "SELECT COUNT(DISTINCT session_id) AS sessions, COUNT(*) AS events, MIN(timestamp) AS earliest_event, MAX(timestamp) AS latest_event FROM \`$PROJECT_ID.$DATASET.agent_events\`"

Untuk operasi 5 sesi default, ini menunjukkan 5 sesi dan 30 peristiwa yang berlangsung selama beberapa menit. (Isi skenario realistis di bawah dan kueri yang sama melaporkan ~100 sesi selama sekitar tiga hari.)

Verifikasi peristiwa yang terjadi:

bq query --use_legacy_sql=false \
    "SELECT event_type, COUNT(*) AS n FROM \`$PROJECT_ID.$DATASET.agent_events\` GROUP BY event_type ORDER BY n DESC"

Anda akan melihat 25 baris TOOL_COMPLETED dan 5 baris AGENT_COMPLETED (setiap sesi memancarkan satu submit_request, tiga evaluate_option, satu commit_outcome, dan satu AGENT_COMPLETED penutup — lima peristiwa alat ditambah satu penghentian agen per sesi). Baris AGENT_COMPLETED adalah penghentian sesi yang dikunci oleh bqaa context-graph untuk deteksi peristiwa terminal.

Opsional: data skala realistis

Korpus 5 sesi di atas sengaja dibuat kecil sehingga operasi pertama cepat dan murah. Jika Anda menginginkan data berbentuk produksi — beberapa agen dan pengguna tersebar selama beberapa hari, dengan sesi yang gagal, tidak terkait, dan terpotong — gunakan skenario decision-realistic. Skenario ini ditetapkan secara default ke 100 sesi selama periode 72 jam; jalur operasi pertama di atas tidak berubah.

bqaa seed-events \
    --project-id "$PROJECT_ID" \
    --dataset-id "$DATASET" \
    --scenario decision-realistic \
    --sessions 100 \
    --seed 42

session_outcome_counts laporan JSON menunjukkan campuran — kira-kira {"success": 70, "failed": 10, "orphaned": 10, "truncated": 10}.

Setelah Anda memiliki korpus realistis ini, panduan Conversational Analytics-first menunjukkan cara mengajukan pertanyaan dalam bahasa Inggris biasa ("permintaan mana yang mempertimbangkan opsi keyakinan rendah?") sebelum beralih ke GQL.

Konfirmasi distribusi hasil dengan mengklasifikasikan setiap sesi dari barisnya (tidak terkait = tidak ada AGENT_COMPLETED; gagal = AGENT_COMPLETED dengan status = 'error'; terpotong = baris apa pun dengan is_truncated = true; jika tidak, berhasil). Operasi pertama mengklasifikasikan setiap sesi, lalu operasi kedua mengagregasi per hasil:

bq query --use_legacy_sql=false \
    "WITH per_session AS (SELECT session_id, CASE WHEN COUNTIF(event_type = 'AGENT_COMPLETED') = 0 THEN 'orphaned' WHEN COUNTIF(event_type = 'AGENT_COMPLETED' AND status = 'error') > 0 THEN 'failed' WHEN COUNTIF(is_truncated) > 0 THEN 'truncated' ELSE 'success' END AS outcome FROM \`$PROJECT_ID.$DATASET.agent_events\` GROUP BY session_id) SELECT outcome, COUNT(*) AS sessions FROM per_session GROUP BY outcome ORDER BY outcome"

Anda akan melihat sekitar 70 berhasil, 10 gagal, 10 tidak terkait, dan 10 terpotong (ditambah 5 sesi yang berhasil dari korpus operasi pertama jika Anda mengisinya sebelumnya dalam set data yang sama).

10 sesi yang tidak terkait tidak pernah memancarkan AGENT_COMPLETED, sehingga operasi bqaa context-graph default akan melewatinya (hanya mewujudkan sesi yang ditutup peristiwa terminal). Untuk menampilkannya sebagai session_orphaned, bukan mencoba ulang secara diam-diam selamanya, tambahkan --max-session-age-hours saat Anda menjalankannya — lihat --max-session-age-hours di Menerapkannya ke produksi.

Skenario ini menyebarkan sesinya selama periode 72 jam dengan sengaja. Panduan Mewujudkan grafik konteks di bawah menggunakan --lookback-hours 24 dan ditulis untuk korpus operasi pertama 5 sesi kecil, sehingga jumlah pastinya mengasumsikan Anda tidak menjalankan langkah opsional ini. Jika Anda melakukannya, itulah pelajaran yang dimaksud: periode pewujudan 24 jam hanya mengambil bagian terbaru dari backlog multi-hari — perluas --lookback-hours untuk mengambil sesi yang lebih lama.

7. Mewujudkan grafik konteks

bqaa context-graph membaca agent_events mentah, lalu menurunkan apa yang akan diekstrak langsung dari grafik yang di-deploy: membaca definisi CREATE PROPERTY GRAPH yang Anda terapkan di Menerapkan skema grafik properti kembali dari INFORMATION_SCHEMA.PROPERTY_GRAPHS BigQuery, menggabungkannya dengan skema tabel yang direferensikannya, menentukan entity, hubungan, dan jenis kolom, serta mengisi tabel grafik. Anda mengarahkannya ke grafik yang di-deploy berdasarkan nama dengan --graph agent_decisions_graph — tidak ada file SQL yang akan diteruskan.

Jalankan

bqaa context-graph secara lokal:

bqaa context-graph \
    --project-id "$PROJECT_ID" \
    --dataset-id "$DATASET" \
    --graph agent_decisions_graph \
    --lookback-hours 24 \
    --format json

Operasi pertama membaca setiap peristiwa di periode lihat balik dan menulis tabel grafik, sehingga proses ini mungkin memerlukan waktu beberapa menit untuk selesai.

Anda akan melihat laporan JSON terstruktur:

{
  "run_id": "...",
  "sessions_discovered": 5,
  "sessions_materialized": 5,
  "sessions_failed": 0,
  "rows_materialized": {
    "DecisionRequest": 5,
    "DecisionOption": 15,
    "DecisionOutcome": 5
  },
  "ok": true
}

ok: true menunjukkan bqaa context-graph menemukan lima sesi yang selesai, mengekstrak alur keputusan dari setiap sesi melalui AI.GENERATE, dan menulis baris yang sesuai ke dalam tabel grafik. Ekstraksi deterministik (--extraction-mode=compiled-only, dibahas di bawah) menampilkan bentuk laporan yang sama — kolom yang sama, ok: true yang sama — hanya melewati panggilan AI.GENERATE.

Pemecahan masalah: ekstraksi kosong

Jika Anda melihat ok: false dengan error_code = "empty_extraction", penyebab paling umum adalah aiplatform.googleapis.com API belum disebarkan, atau akun Anda tidak memiliki roles/aiplatform.user. Tunggu sebentar dan coba lagi, atau berikan peran:

USER_EMAIL=$(gcloud auth list --filter=status:ACTIVE --format="value(account)")
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
    --member="user:$USER_EMAIL" --role="roles/aiplatform.user"

Kemudian, jalankan kembali perintah bqaa context-graph di atas.

Verifikasi bahwa grafik memiliki baris:

bq query --use_legacy_sql=false \
    "SELECT COUNT(*) AS n FROM \`$PROJECT_ID.$DATASET.decision_request\`"

Anda akan melihat lima baris. Di lima sesi, ada 25 node grafik secara keseluruhan — 5 DecisionRequest, 15 DecisionOption, dan 5 DecisionOutcome — yang digabungkan oleh 15 edge evaluatesOption dan 5 edge resultedIn (satu web keputusan per sesi).

Dua cara untuk mengekstrak keputusan dari peristiwa

bqaa context-graph menawarkan dua jalur ekstraksi. Pilih yang sesuai dengan workload Anda:

• Ekstraksi default. Jalur termudah. Menggunakan AI.GENERATE BigQuery untuk membaca konten peristiwa dan menyimpulkan entity dan hubungan. Berfungsi untuk bentuk peristiwa apa pun tanpa kode tambahan. Inilah yang digunakan codelab.
• Ekstraksi deterministik (--extraction-mode=compiled-only). Jalur yang lebih murah dan ramah audit. Menggunakan ekstraktor referensi Python kecil yang Anda tulis sekali untuk domain Anda. Tidak ada panggilan Vertex AI, tidak ada biaya per token, output yang sepenuhnya dapat direproduksi. Deployment produksi memilih ini jika prediktabilitas biaya atau kemampuan reproduksi yang ketat penting.

Panduan deployment grafik konteks adalah referensi untuk kedua jalur, termasuk detail IAM dan cara membuat ekstraktor referensi.

8. Mengkueri jejak keputusan

Dengan grafik yang diisi, Anda dapat menjawab pertanyaan audit secara langsung. Ambil contoh konkret: "Untuk setiap permintaan, opsi apa yang dipertimbangkan agen, dan bagaimana penyelesaiannya?" Dalam GQL, itu adalah satu traversal di seluruh permintaan, opsinya, dan hasilnya.

Tulis kueri ke file (traversal.sql). Penanda ${DATASET} akan diisi saat Anda menjalankannya pada langkah berikutnya:

cat > traversal.sql <<'SQL'
SELECT *
FROM GRAPH_TABLE (
  ${DATASET}.agent_decisions_graph
  MATCH
    (req:DecisionRequest) -[eo:evaluatesOption]-> (opt:DecisionOption),
    (req)                 -[ri:resultedIn]->      (out:DecisionOutcome)
  COLUMNS (
    req.request_id   AS request,
    req.request_text AS question,
    opt.option_label AS considered,
    opt.confidence   AS score,
    out.status       AS outcome,
    out.rationale    AS rationale
  )
);
SQL

Eksekusi:

envsubst < traversal.sql | bq query --use_legacy_sql=false --max_rows=20

Anda akan melihat lima belas baris: tiga opsi per permintaan, lima permintaan. Setiap baris menunjukkan permintaan, opsi yang dipertimbangkan agen, skor keyakinannya, hasil akhir, dan alasannya.

Untuk gambaran lengkap satu keputusan, filter menurut request_id untuk mendapatkan kumpulan baris yang dibutuhkan tim audit: pertanyaan yang masuk, opsi yang dipertimbangkan (dengan skor), dan alasan yang dilakukan.

Memvisualisasikan grafik di BigQuery Studio

BigQuery Studio juga dapat merender grafik secara visual. Buka BigQuery Studio di konsol BigQuery, jalankan kueri jalur di bawah, lalu alihkan panel hasil ke tab Grafik untuk melihat web keputusan. Dengan korpus skala realistis, Anda akan mendapatkan peta visual permintaan, opsi, dan hasil:

GRAPH agent_analytics_demo.agent_decisions_graph
MATCH p = (a)-[e]->(b)
RETURN TO_JSON(p) AS path_json

Konsol BigQuery tidak memperluas variabel shell, jadi tempelkan nama set data literal. Kueri ini menggunakan agent_analytics_demo (nilai DATASET dari Sebelum memulai); ubah jika Anda menggunakan set data yang berbeda.

Mengajukan pertanyaan yang sama dalam bahasa Inggris biasa

Tidak semua pembaca audit menulis GQL. Dengan BigQuery Conversational Analytics (Pratinjau), tim kepatuhan Anda dapat mengajukan jenis pertanyaan yang sama dalam bahasa alami dan mendapatkan kartu jawaban terstruktur — tanpa sintaksis kueri, tanpa gabungan untuk dipelajari.

Daftarkan agent_decisions_graph (bersama dengan agent_events dan tabel keputusan) sebagai sumber data Conversational Analytics, lalu ajukan pertanyaan audit secara langsung:

Pertanyaan audit (bahasa Inggris biasa): "Permintaan mana yang tidak pernah mencapai hasil yang dilakukan?"

Conversational Analytics memberikan alasan atas grafik, menulis SQL untuk Anda, dan membalas dalam bahasa Inggris biasa dengan tabel pendukung — di sini, setiap permintaan yang dicatat mencapai hasil yang dilakukan:

Balasan di atas mencerminkan korpus skala realistis dari langkah opsional data skala realistis (90 permintaan yang diwujudkan, semuanya dilakukan); jumlah pasti Anda bergantung pada korpus yang Anda isi, dan operasi 5 sesi default menampilkan lima.

Lihat dokumentasi Conversational Analytics untuk penyiapan.

9. Menerapkannya ke produksi

Operasi lokal di atas menggunakan perilaku default, yang sudah mencakup dasar-dasar untuk deployment sebenarnya: setiap operasi meninggalkan jejak audit (Cloud Logging terstruktur ditambah baris per operasi dalam tabel status di set data Anda), kegagalan sementara akan otomatis dicoba ulang, dan progres hanya akan maju pada sesi yang sepenuhnya berhasil, sehingga tidak ada penghitungan ganda.

Kontrol produksi — ekstraksi deterministik (--extraction-mode=compiled-only), deteksi sesi yang macet (--max-session-age-hours), pemutaran ulang satu kali dari periode sebelumnya (--backfill --from / --to, dilacak secara terpisah dari pemuatan ulang reguler sehingga tidak dapat mengganggu jadwal aktif), dan pembatasan batch per operasi (--max-sessions) — adalah flag keikutsertaan yang Anda gunakan saat memerlukannya. Panduan deployment grafik konteks mendokumentasikan setiap panduan dengan matriks IAM lengkap dan jadwal yang direkomendasikan.

Dari "jalankan sekali" hingga "jalankan setiap enam jam": SDK mengirimkan skrip deployment dan modul Terraform yang menggabungkan bqaa context-graph sebagai Cloud Run Job yang dipicu oleh Cloud Scheduler, dengan akun layanan hak istimewa terendah dan pemberian IAM yang diperlukan tugas. Ikuti runbook deployment Grafik Konteks Agen terjadwal untuk menerapkan grafik yang di-deploy ini ke deployment terjadwal dengan alur --graph yang sama.

10. Pembersihan

Hapus semua yang Anda buat agar Anda tidak ditagih untuk set data yang tidak aktif:

bq rm -r -f --dataset "$PROJECT_ID:$DATASET"

Satu perintah tersebut akan menghapus set data, peristiwa agen, tabel grafik, dan tabel status secara bersamaan.

11. Selamat

Selamat! Anda telah mengubah log peristiwa agen mentah menjadi Grafik Konteks Agen yang dapat dikueri dan melacak satu keputusan secara menyeluruh, tanpa database grafik eksternal atau pipeline ETL.

Pola yang sama berlaku di mana pun agen membuat keputusan penting: penjaminan kredit, otorisasi sebelumnya, pergerakan anggaran pemasaran, pengadaan, layanan pelanggan, dan IT internal. Untuk membuat Grafik Konteks Agen Anda sendiri, salin artefak codelab sebagai titik awal, sesuaikan dua file deklaratif (DDL tabel + skema CREATE PROPERTY GRAPH) ke domain Anda, dan terapkan ke BigQuery — bqaa context-graph --graph membaca kembali grafik yang di-deploy dari INFORMATION_SCHEMA dan menurunkan sisanya.

Yang telah Anda pelajari

• Cara membuat set data BigQuery dan menerapkan skema grafik properti yang menjelaskan domain keputusan agen.
• Cara mengisi agent_events dengan korpus peristiwa sintetis.
• Cara menjalankan bqaa context-graph untuk mengekstrak jejak keputusan agen ke dalam Grafik Konteks Agen dari peristiwa tersebut, membaca kembali definisi grafik dari INFORMATION_SCHEMA.
• Cara mengkueri grafik yang dihasilkan di GQL dan membaca jawaban gaya audit.

Dokumen referensi

• Repositori BigQuery Agent Analytics SDK
• Artefak codelab dan panduan adaptasi
• Panduan deployment grafik konteks: API yang diperlukan, matriks IAM, jadwal yang direkomendasikan, kueri pemberitahuan Cloud Monitoring, dan modul Terraform.
• Dokumentasi BigQuery Graph (Pratinjau).
• Dokumentasi BigQuery Conversational Analytics (Pratinjau).