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 Analisis Agen BigQuery Tersedia Umum (GA). Contoh dalam codelab ini menggunakan data sintetis.

Seiring dengan makin banyaknya tanggung jawab operasional yang diemban oleh agen AI otonom (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 tentang keputusan agen — sesuai jadwal, tanpa database grafik eksternal atau pipeline ETL.

Istilah utama

• Agent Decision Trace — bukti tingkat keputusan yang diambil dari proses eksekusi agen itu sendiri: opsi yang dipertimbangkan, data yang diakses, dan hasil yang dilakukan.
• Grafik Konteks Agen — grafik yang diketik dan dapat dikueri di BigQuery Graph yang digunakan untuk mewujudkan rekaman aktivitas 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); penentu "Agent" mencakupnya ke eksekusi agen Anda sendiri, bukan lapisan konteks di seluruh perusahaan.

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

Yang akan Anda build

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

Yang akan Anda pelajari

• Cara Plugin Analisis Agen BigQuery 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 Grafik BigQuery.
• Cara membuat kueri grafik menggunakan GQL.
• Kemampuan tingkat produksi yang didukung SDK untuk deployment perusahaan.

Yang Anda butuhkan

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

Codelab ini ditujukan bagi developer dari semua level, termasuk yang baru mengenal BigQuery Graph.

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

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

2. Sebelum memulai

Pilih 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 terwujud. Penggunaan satu set data membuat codelab tetap sederhana. Deployment produksi sering kali membagi peristiwa dan grafik menjadi 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 berhasil:

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

Jika set data sudah ada, perintah akan error tanpa menimbulkan masalah. 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, jadi 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 ini hanya memerlukan dua artefak siap pakai: DDL tabel (tabel grafik fisik) dan skema grafik properti (CREATE PROPERTY GRAPH). Anda tidak perlu membuatnya sendiri; codelab ini menggunakannya apa adanya, dan README di folder artefak menjelaskan cara menyesuaikannya untuk domain keputusan Anda sendiri.

Skema grafik properti adalah satu-satunya sumber kebenaran untuk apa yang ada dalam grafik. Anda menerapkannya ke BigQuery satu kali; sejak saat itu, grafik yang di-deploy itu sendiri adalah kontraknya. Saat Anda melakukan materialisasi, bqaa context-graph akan membaca kembali definisi grafik dari INFORMATION_SCHEMA.PROPERTY_GRAPHS BigQuery (bersama dengan skema tabel yang dirujuknya) untuk menentukan entitas dan hubungan mana yang akan diekstrak dan ke mana akan ditulis — sehingga tidak ada file SQL yang diteruskan ke materializer.

Codelab ini mandiri, jadi tidak ada yang perlu didownload. Perintah di bawah akan menulis DDL grafik konteks ke 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} 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 mereka deskripsikan memiliki tiga jenis node dan dua tepi heterogen:

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

5. Menerapkan skema grafik properti

bqaa context-graph menulis ke tabel BigQuery, jadi tabel tersebut harus ada sebelum dijalankan pertama kali. 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 saat 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 untuk 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, Plugin Analisis Agen BigQuery akan merekam peristiwa secara otomatis 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 baris dengan bentuk 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.

Lihat pratinjau korpus secara sekilas — jumlah sesi, jumlah peristiwa, dan rentang waktu yang dicakupnya — 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 5 sesi default yang dijalankan, laporan ini menampilkan 5 sesi dan 30 peristiwa yang berlangsung selama beberapa menit. (Buat skenario realistis di bawah dan kueri yang sama melaporkan sekitar 100 sesi selama sekitar tiga hari.)

Verifikasi bahwa peristiwa telah masuk:

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 bqaa context-graph untuk deteksi peristiwa terminal.

Opsional: data skala realistis

Korpus 5 sesi di atas sengaja dibuat kecil sehingga proses pertama berjalan cepat dan murah. Jika Anda menginginkan data berbentuk produksi — beberapa agen dan pengguna yang tersebar selama beberapa hari, dengan sesi yang gagal, tidak memiliki induk, dan terpotong — gunakan skenario decision-realistic. Secara default, nilai ini adalah 100 sesi selama periode 72 jam; jalur percobaan 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 yang realistis ini, panduan Conversational Analytics-first menunjukkan cara mengajukannya dalam bahasa Inggris sederhana ("which requests weighed a low-confidence option?") 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). Pass pertama mengklasifikasikan setiap sesi, lalu pass kedua menggabungkan 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 keberhasilan, 10 kegagalan, 10 tidak terkait, dan 10 terpotong (plus 5 sesi berhasil dari korpus run pertama jika Anda melakukan seeding sebelumnya dalam set data yang sama).

10 sesi tanpa induk tidak pernah memancarkan AGENT_COMPLETED, sehingga eksekusi bqaa context-graph default akan melewati sesi tersebut (hanya mematerialisasi sesi yang ditutup dengan peristiwa terminal). Untuk menampilkannya sebagai session_orphaned, bukan mencoba lagi secara diam-diam selamanya, tambahkan --max-session-age-hours saat Anda menjalankannya — lihat --max-session-age-hours di Bawa ke produksi.

Skenario ini sengaja menyebarkan sesi di jendela 72 jam. Penjelasan Mewujudkan grafik konteks di bawah menggunakan --lookback-hours 24 dan ditulis untuk korpus run pertama 5 sesi kecil, sehingga jumlah persisnya mengasumsikan Anda belum menjalankan langkah opsional ini. Jika Anda melakukannya, itulah pelajaran yang dimaksud: jendela perwujudan 24 jam hanya mengambil irisan 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 menentukan apa yang akan diekstrak langsung dari grafik yang di-deploy: membaca definisi CREATE PROPERTY GRAPH yang Anda terapkan di Terapkan skema grafik properti kembali dari INFORMATION_SCHEMA.PROPERTY_GRAPHS BigQuery, menggabungkannya dengan skema tabel yang direferensikannya, menentukan entitas, hubungan, dan jenis kolom, serta mengisi tabel grafik. Anda mengarahkannya ke grafik yang di-deploy menurut nama dengan --graph agent_decisions_graph — tidak ada file SQL yang perlu diteruskan.

Run

bqaa context-graph secara lokal:

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

Run pertama membaca setiap peristiwa dalam periode lihat kembali dan menulis tabel grafik, sehingga proses ini mungkin memerlukan waktu beberapa menit untuk diselesaikan.

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 bahwa bqaa context-graph menemukan lima sesi yang telah diselesaikan, 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, lalu 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.

Pastikan 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 kelima sesi tersebut, terdapat total 25 node grafik — 5 DecisionRequest, 15 DecisionOption, dan 5 DecisionOutcome — yang digabungkan oleh 15 tepi evaluatesOption dan 5 tepi resultedIn (satu web keputusan per sesi).

Dua cara untuk mengekstrak keputusan dari peristiwa

bqaa context-graph menawarkan dua jalur ekstraksi. Pilih salah satu yang sesuai dengan beban kerja Anda:

• Ekstraksi default. Jalur termudah. Menggunakan AI.GENERATE BigQuery untuk membaca konten peristiwa dan menyimpulkan entitas serta 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 sesuai untuk audit. Menggunakan pengekstraksi 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 opsi ini jika prediktabilitas biaya atau reproduksibilitas yang ketat penting.

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

8. Membuat kueri rekaman aktivitas keputusan

Setelah grafik terisi, Anda dapat menjawab pertanyaan audit secara langsung. Pilih salah satu yang konkret: "Untuk setiap permintaan, opsi apa yang dipertimbangkan agen, dan bagaimana cara menyelesaikannya?" Dalam GQL, hal ini merupakan satu-satunya penelusuran di seluruh permintaan, opsi, dan hasilnya.

Tulis kueri ke file (traversal.sql). Penanda ${DATASET} 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 menampilkan permintaan, opsi yang dipertimbangkan agen, skor keyakinannya, hasil akhir, dan alasan.

Untuk mendapatkan 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 diberikan.

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 meluaskan 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.

Ajukan pertanyaan yang sama dalam bahasa Inggris yang sederhana

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

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

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

Analisis Percakapan melakukan penalaran atas grafik, menulis SQL untuk Anda, dan membalas dalam bahasa Inggris biasa dengan tabel pendukung — di sini, setiap permintaan yang direkam mencapai hasil yang dijanjikan:

Balasan di atas mencerminkan korpus skala realistis dari langkah data skala realistis opsional (90 permintaan yang diwujudkan, semuanya dilakukan); angka pasti Anda bergantung pada korpus yang Anda gunakan, dan lima sesi default ditampilkan lima.

Lihat dokumentasi Conversational Analytics untuk penyiapan.

9. Menerapkannya ke produksi

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

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

Dari "jalankan sekali ini" hingga "jalankan setiap enam jam": SDK mengirimkan skrip deployment dan modul Terraform yang membungkus bqaa context-graph sebagai Tugas Cloud Run yang dipicu oleh Cloud Scheduler, dengan akun layanan hak istimewa terendah dan pemberian IAM yang diperlukan tugas. Ikuti buku pedoman menjalankan deployment terjadwal Agent Context Graph untuk membawa grafik yang di-deploy ini ke deployment terjadwal dengan alur --graph yang sama.

10. Pembersihan

Hapus apa 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 end-to-end, 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) dengan domain Anda, dan terapkan ke BigQuery — bqaa context-graph --graph membaca kembali grafik yang di-deploy dari INFORMATION_SCHEMA dan mendapatkan 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 rekaman jejak keputusan agen ke dalam Grafik Konteks Agen dari peristiwa tersebut, dengan membaca kembali definisi grafik dari INFORMATION_SCHEMA.
• Cara membuat kueri grafik yang dihasilkan dalam 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 Analisis Percakapan BigQuery (Pratinjau).