Membangun set konteks menggunakan agen rekayasa konteks

Dokumen ini menjelaskan cara membuat dan mengoptimalkan set konteks yang membantu mencapai akurasi kueri QueryData yang tinggi pada aplikasi agen data Anda. Agen context engineering membantu Anda membangun, mengevaluasi, dan meningkatkan set konteks dengan mengotomatiskan pembuatan dan pengoptimalannya.

Untuk mempelajari set konteks dan QueryData, lihat Ringkasan set konteks dan Ringkasan QueryData.

Untuk membangun aplikasi data tingkat perusahaan, akurasi model text-to-query biasanya perlu mencapai kualitas hampir 100%. SQL yang dibuat secara tidak benar akan memengaruhi keseluruhan kegunaan aplikasi dan pengalaman pengguna. Untuk mendapatkan jawaban yang dapat dijelaskan, relevan dengan bisnis, dan akurasi tinggi, diperlukan rekayasa konteks, yaitu proses pembuatan dan pengoptimalan konteks secara berulang untuk mencapai akurasi yang optimal.

Dengan memberikan QueryData dengan konteks yang ditargetkan ke aplikasi bisnis Anda, Anda memberikan aturan bisnis yang tepat yang diperlukan sistem untuk menyelesaikan niat pengguna yang bernuansa.

Agen rekayasa konteks

Agen rekayasa konteks mengotomatiskan alur kerja pengoptimalan ini. Anda dapat berinteraksi dengan agen untuk menangani tugas ad hoc guna mengoptimalkan konteks Anda. Daftar berikut memberikan contoh prompt bahasa alami yang dapat Anda gunakan untuk memberi petunjuk kepada agen, beserta deskripsi cara agen merespons. Gunakan contoh berikut untuk membantu membangun dan mengoptimalkan konteks Anda:

  • Contoh perintah untuk analisis kegagalan: "Perbarui konteks agar kita mengidentifikasi bandara dengan benar untuk kueri seperti 'penerbangan disney world'." Agen menganalisis kegagalan, alasan kesenjangan, dan merekomendasikan penambahan item konteks yang sesuai, seperti kueri penelusuran nilai.
  • Contoh perintah untuk saran konteks: "Baca kode aplikasi saya dan sarankan beberapa konteks untuk ditambahkan." Agen akan mengurai kode, mempertimbangkan domain aplikasi Anda, dan menyarankan item konteks yang relevan.
  • Contoh perintah untuk pemrosesan massal: "Berikut adalah 10 contoh pertanyaan dan kueri SQL. Ubah menjadi template." Agen akan memproses input Anda secara massal dan memperbarui set konteks Anda.

Pentingnya set data emas

Untuk mengoptimalkan konteks, pertama-tama Anda harus membuat set data yang sesuai dengan input bahasa alami aplikasi Anda. Agen dapat membantu Anda membuat set data emas ini, yang terdiri dari pertanyaan pengguna dan kueri database yang diharapkan. Set data emas memungkinkan Anda:

  • Tetapkan dasar pengukuran untuk performa kueri.
  • Memvalidasi update terhadap kueri database kebenaran nyata.
  • Mengukur peningkatan akurasi di seluruh iterasi.

Proses hill-climbing yang sistematis

Dalam pendakian bukit sistematis, agen secara berulang meningkatkan set konteks melalui evaluasi set data golden, analisis kesenjangan, dan pembaruan untuk mendorong akurasi mendekati 100%.

  • Membuat konteks dasar pengukuran secara otomatis: Buat kumpulan konteks awal yang berasal dari skema database dan artefak aplikasi Anda.
  • Alur kerja pengoptimalan pendakian bukit: Biarkan agen mengevaluasi akurasi QueryData Anda, melakukan analisis kesenjangan pada kegagalan, dan otomatis mengusulkan peningkatan untuk meningkatkan akurasi.

Diagram berikut menunjukkan alur kerja hill-climbing sistematis:

Alur kerja untuk membangun konteks secara iteratif.

Sebelum memulai

Selesaikan prasyarat berikut sebelum menggunakan agen rekayasa konteks.

Mengaktifkan layanan yang diperlukan

Aktifkan layanan berikut untuk project Anda:

Menyiapkan cluster, instance, dan database AlloyDB untuk PostgreSQL

Pastikan Anda memiliki akses ke cluster dan instance AlloyDB yang ada atau buat yang baru.
Tutorial ini mengharuskan Anda memiliki database di instance AlloyDB. Untuk mengetahui informasi selengkapnya, lihat Membuat database.

Peran dan izin yang diperlukan

  • Tambahkan akun pengguna atau layanan Identity and Access Management (IAM) ke cluster di tingkat database. Untuk mengetahui informasi selengkapnya, lihat Mengelola pengguna database.
  • Berikan peran alloydb.databaseUser, serviceusage.serviceUsageConsumer, dan geminidataanalytics.queryDataUser kepada pengguna IAM di level project. Untuk mengetahui informasi selengkapnya, lihat Menambahkan binding kebijakan IAM untuk project.
  • Untuk membuat, mengupload, dan mengelola set konteks, berikan peran Dataplex Catalog Editor (roles/dataplex.catalogEditor) atau Dataplex Catalog Admin (roles/dataplex.catalogAdmin) kepada pengguna IAM di level project. Untuk mengetahui informasi selengkapnya, lihat Context menetapkan izin.

Memberikan izin executesql ke instance AlloyDB untuk PostgreSQL

Untuk memberikan izin executesql ke instance AlloyDB untuk PostgreSQL dan menetapkan setelan instance data_api_access ke nilai ALLOW_DATA_API, gunakan perintah curl berikut: 
   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json" \
     https://alloydb.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID/instances/INSTANCE_ID?updateMask=dataApiAccess \
     -d '{
       "dataApiAccess": "ENABLED",
     }'
Ganti kode berikut:
  • PROJECT_ID: ID project Google Cloud Anda.
  • LOCATION: Region tempat cluster AlloyDB Anda berada.
  • CLUSTER_ID: ID cluster AlloyDB Anda.
  • INSTANCE_ID: ID instance AlloyDB Anda.
Untuk melakukan langkah-langkah dalam tutorial ini, login ke Google Cloud, lalu lakukan autentikasi ke database menggunakan autentikasi IAM.

Menyiapkan lingkungan Anda

Anda dapat membuat file set konteks dari lingkungan pengembangan lokal atau IDE apa pun. Untuk mempersiapkan lingkungan Anda, lakukan langkah-langkah berikut:

  • Menginstal agen rekayasa konteks
  • Menyiapkan koneksi database

Menginstal agen rekayasa konteks

Agen context engineering menjalankan server Model Context Protocol (MCP) yang memerlukan uv untuk mengelola paket Python yang mendasarinya.

  1. Instal uv dengan mengikuti petunjuk di Menginstal uv.

  2. Pastikan uv telah diinstal dan dapat diakses dari command line Anda:

    uv --version

Untuk menyiapkan lingkungan Anda, instal agen context engineering di harness agen yang Anda pilih, seperti Antigravity CLI, Claude Code, atau Gemini CLI.

Bergantung pada infrastruktur pengelola agen yang Anda pilih, ikuti langkah-langkah penginstalan yang sesuai:

Antigravity CLI

Untuk menginstal agen context engineering di Antigravity CLI, ikuti langkah-langkah berikut:

  1. Instal Antigravity CLI. Lihat Mulai Menggunakan Antigravity CLI.
  2. Instal plugin agen rekayasa konteks, yang mencakup alur kerja untuk pembuatan konteks. Ganti VERSION dengan versi rilis yang diperlukan: 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION
  3. Mulai Antigravity CLI: 
    agy

Untuk mengupdate plugin ke versi terbaru, jalankan perintah berikut. Ganti VERSION dengan versi rilis yang diperlukan:

agy plugin uninstall google-cloud-db-context-engineering
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION

Claude Code

Untuk menginstal agen context engineering di Claude Code, ikuti langkah-langkah berikut:

  1. Tambahkan marketplace plugin: 
    /plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git
  2. Instal plugin: 
    /plugin install db-context-engineering@db-context-enrichment-marketplace
  3. Muat ulang plugin untuk mengaktifkan perubahan: 
    /reload-plugins
  4. Update plugin: 
    /plugin update db-context-engineering@db-context-enrichment-marketplace

Gemini CLI (Tidak digunakan lagi)

Untuk menginstal agen rekayasa konteks di Gemini CLI, ikuti langkah-langkah berikut:

  1. Menginstal Gemini CLI. Lihat Mulai Menggunakan Gemini CLI.
  2. Instal ekstensi: 
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
  3. Update ekstensi: 
    gemini extensions update google-cloud-db-context-engineering

Menyiapkan koneksi database

Agen memerlukan koneksi database untuk mengambil skema dan kemampuan untuk memvalidasi sintaksis konteks SQL yang dihasilkan. Agar agen dapat berinteraksi dengan database Anda, konfigurasikan kredensial autentikasi dan tentukan konfigurasi koneksi database Anda.

Mengonfigurasi Kredensial Default Aplikasi

Konfigurasikan Kredensial Default Aplikasi (ADC) untuk memberikan kredensial pengguna guna mengakses resource Google Cloud dari agen rekayasa konteks:

  • Server MCP Toolbox: Menggunakan kredensial untuk terhubung ke database Anda, mengambil skema, dan menjalankan SQL untuk validasi.
  • Evalbench: Menggunakan kredensial untuk memanggil QueryData untuk evaluasi.

Jalankan perintah berikut di terminal Anda untuk melakukan autentikasi:

gcloud auth application-default login

Mengonfigurasi file koneksi database

Agen memerlukan koneksi database untuk pembuatan konteks, yang didukung dan ditentukan oleh MCP Toolbox dalam file konfigurasi.

File konfigurasi menentukan sumber database dan alat yang diperlukan untuk mengambil skema atau menjalankan SQL. Agen rekayasa konteks dilengkapi dengan Keterampilan Agen yang telah diinstal sebelumnya untuk membantu Anda membuat konfigurasi.

  1. Mulai lingkungan agen Anda.

  2. Minta agen untuk membantu menyiapkan koneksi database—misalnya, perintah "bantu saya menyiapkan koneksi database". Ikuti petunjuk agen untuk membuat file konfigurasi di direktori kerja Anda saat ini sebagai autoctx/tools.yaml.

  3. Untuk menerapkan konfigurasi tools.yaml baru, muat ulang koneksi Anda:

    • Di Antigravity CLI, jalankan /mcp dan pilih toolbox untuk memulai ulang.
    • Di Gemini CLI, jalankan /mcp reload.
    • Di Claude Code, jalankan /mcp, pilih toolbox, lalu pilih Reconnect.

Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi file konfigurasi database secara manual, lihat Konfigurasi MCP Toolbox.

Membuat dan mengoptimalkan konteks

Agen rekayasa konteks menyediakan serangkaian Keterampilan Agen dan alat MCP untuk meningkatkan kemampuan rekayasa konteks agen coding Anda. Anda dapat menggunakan alat ini bersama-sama untuk membuat dasar pengukuran, mengukur efektivitas, dan menerapkan peningkatan secara berulang. Namun, Anda dapat memulai di tahap alur kerja mana pun:

  • Jika sudah memiliki set konteks, Anda dapat langsung melanjutkan ke evaluasi.
  • Jika ada kueri gagal yang ingin diperbaiki, Anda dapat langsung melanjutkan ke analisis kesenjangan.

Setiap kemampuan menjelaskan tindakan, kasus penggunaan, dan perintah pemanggilan agen.

Contoh perintah menunjukkan cara membuat kueri agen dalam bahasa alami. Jika agen memerlukan detail tambahan untuk menyelesaikan permintaan, agen akan meminta klarifikasi kepada Anda.

Membangun dan memperluas set data evaluasi

Untuk meningkatkan performa, Anda harus mengukurnya terlebih dahulu. Rekayasa konteks tanpa set data emas, yang terdiri dari pertanyaan pengguna yang dipasangkan dengan SQL yang diharapkan, tidak memiliki verifikasi sistematis. Dengan set data emas, setiap perubahan adalah peningkatan terukur yang dapat Anda validasi terhadap kebenaran nyata.

Membuat set data golden yang representatif secara manual memerlukan waktu yang lama, dan set data kecil mungkin melewatkan variasi dalam frasa pengguna. Agen menyelesaikan masalah ini dengan:

  • Membuat kandidat pasangan pertanyaan-SQL berdasarkan skema database Anda.
  • Memperluas set data seed kecil menggunakan variasi filter, sinonim, dan pengungkapan ulang.

Secara opsional, Anda dapat mengizinkan agen menjalankan SQL yang dihasilkan terhadap database Anda. Verifikasi ini mengonfirmasi bahwa kueri berhasil dijalankan sebelum Anda menambahkannya ke set data.

Set data ini adalah file JSON yang berisi pasangan pertanyaan-SQL:

json [ { "id": "example_001", "nlq": "What is the total revenue for the top 5 products?", "golden_sql": "SELECT product_id, sum(net_revenue) FROM sales GROUP BY product_id ORDER BY sum(net_revenue) DESC LIMIT 5;" } ]

Pasangan yang disetujui akan mengisi file autoctx/golden.json di ruang kerja Anda, dan siap untuk dievaluasi. Anda dapat memberikan file yang ada atau menulis beberapa contoh evaluasi secara inline untuk diperluas oleh agen.

Anda dapat menggunakan contoh perintah berikut untuk menginstruksikan agen:

  • "Buat set data evaluasi dari skema saya."
  • "Berikut adalah pertanyaan awal dan SQL. Perluas menjadi set data yang lebih luas dan verifikasi kueri yang dijalankan."

Membuat set data konteks dasar pengukuran

Agar tidak perlu membuat konteks dari awal, Anda dapat mengizinkan agen memperoleh kumpulan konteks awal dari skema database dan artefak aplikasi, seperti aturan bisnis, contoh kueri, atau file README. Meskipun konteks dasar pengukuran ini belum final, konteks ini memberikan titik awal yang divalidasi dan didasarkan pada model database Anda.

Anda dapat menggunakan contoh perintah berikut untuk menginstruksikan agen:

  • "Buat set konteks dari skema saya."
  • "Buat konteks awal menggunakan skema ini dan aturan bisnis di requirements.md."

Agen akan meminta Anda memberi nama eksperimen, yang mengatur artefak yang dihasilkan, dan mungkin meminta Anda mempersempit cakupan jika skema database Anda besar. Untuk mengupload konteks menggunakan AlloyDB Studio, ikuti petunjuk setelah agen membuat file JSON.

Mengevaluasi efektivitas konteks

Setelah membuat set konteks dan set data golden, Anda dapat mengizinkan agen mengukur performa konteks dengan mengkueri QueryData API agen data Anda dengan setiap pertanyaan golden. Agen membandingkan SQL yang dihasilkan dan hasil eksekusinya dengan jawaban yang diharapkan menggunakan Evalbench untuk menangani perbandingan.

Menjalankan evaluasi akan memberikan hal berikut:

  • Metrik kuantitatif, seperti hasil lulus dan gagal serta skor gabungan, untuk melacak progres di seluruh iterasi konteks.
  • Ringkasan percakapan inline dan laporan CSV mendetail yang ditulis ke direktori eval_reports/ di folder eksperimen Anda.

Untuk memulai evaluasi, berikan jalur set data emas dan ID set konteks. Untuk mempelajari cara menemukan ID set konteks, lihat Menemukan ID konteks agen .

Anda dapat menggunakan contoh perintah berikut untuk menginstruksikan agen:

  • "Evaluasi konteks saya terhadap golden.json."
  • "Jalankan ulang evaluasi menggunakan konfigurasi dari eksperimen terakhir saya."

Untuk menjalankan ulang konfigurasi evaluasi yang dibuat sebelumnya tanpa menyiapkannya lagi, tanyakan kepada agen atau panggil CLI secara langsung:

uvx google-evalbench --experiment_config=autoctx/experiments/my-experiment/eval_configs/run_config.yaml

Untuk mengetahui detail tentang skema konfigurasi evaluasi dan cara menyesuaikan proses evaluasi, lihat Dokumentasi Evalbench.

Melakukan analisis kesenjangan dan mengusulkan peningkatan

Untuk mengatasi kegagalan kueri, Anda harus mengidentifikasi penyebab utamanya, seperti kolom yang salah, gabungan tabel yang tidak ada, atau istilah fuzzy yang tidak terselesaikan. Mengidentifikasi masalah ini secara manual memerlukan analisis ekstensif terhadap laporan evaluasi.

Agen mengotomatiskan loop analisis dan koreksi ini:

  • Analisis kesenjangan: Agen membaca hasil evaluasi dan set konteks Anda untuk mengelompokkan kegagalan serupa dan merekomendasikan penambahan konteks yang ditargetkan, seperti template, faset, atau penelusuran nilai.
  • Perbaikan yang diusulkan: Agen mengusulkan pengeditan konkret dan secara opsional menguji SQL terhadap database Anda untuk memverifikasi resolusi.
  • Pelestarian dasar pengukuran: Agen menulis peningkatan ke file JSON baru bersama dengan konteks dasar pengukuran Anda, sehingga file asli tetap dipertahankan.

Anda dapat menggunakan contoh perintah berikut untuk menginstruksikan agen:

  • "Jalankan analisis kesenjangan pada evaluasi terakhir saya dan usulkan perbaikan."
  • "Optimalkan set konteks ini terhadap golden.json."

Untuk mempersiapkan iterasi berikutnya, upload konteks yang ditingkatkan ke set konteks target menggunakan AlloyDB Studio, ikuti petunjuk.

Membuat item konteks tertentu sesuai permintaan

Jika Anda sudah mengetahui konteks yang diperlukan, seperti template untuk pertanyaan tertentu, faset untuk filter berulang, atau penelusuran nilai untuk kolom tertentu, menulis JSON konteks secara manual dapat menyebabkan error serialisasi dalam nama parameter, metadata jenis, atau sintaksis fragmen. Agen menangani pemformatan JSON agar Anda dapat berfokus pada maksud bisnis Anda.

Anda juga dapat menggunakan fitur ini untuk update ad hoc, seperti saat Anda perlu mendukung pola kueri baru atau mengatasi detail skema yang tidak ada. Untuk mendapatkan JSON, jelaskan konteks yang diperlukan kepada agen tanpa menjalankan evaluasi atau menyiapkan eksperimen.

Ini juga merupakan kemampuan yang tepat untuk digunakan saat Anda diberi tugas sekali saja: pemangku kepentingan memberi Anda pasangan pertanyaan-SQL baru yang ingin mereka dukung, atau Anda melihat faset yang hilang selama peninjauan kode. Anda tidak perlu menyiapkan eksperimen atau menjalankan evaluasi untuk memperbaikinya—deskripsikan apa yang Anda inginkan dan agen akan menghasilkan JSON.

Anda dapat menggunakan contoh perintah berikut untuk menginstruksikan agen:

  • "Buat template untuk: 'Bandara mana saja yang ada di California?' dengan SQL: SELECT name FROM airports WHERE country = 'United States' AND state = 'CA'."
  • "Buat faset untuk filter departure_time BETWEEN '00:00:00' AND '06:00:00' yang diberi label 'red eye'."
  • "Buat penelusuran nilai untuk airports.iata."

Menentukan pilihan jenis konteks

Memilih jenis konteks yang benar, baik penelusuran template, faset, maupun nilai, akan membantu mencegah pembengkakan konteks dan regresi kueri database. Misalnya, menggunakan template, bukan faset, dapat menyebabkan aturan duplikat, sedangkan penelusuran nilai yang diperkenalkan saat template sudah cukup dapat meningkatkan latensi kueri. Untuk menemukan format skema yang benar, minta agen untuk merekomendasikan jenis berdasarkan struktur kueri atau kolom database sebelum Anda membuat item konteks. Agen akan menjelaskan penalarannya untuk membantu Anda memahami opsi konteks.

Anda dapat menggunakan contoh perintah berikut untuk menginstruksikan agen:

  • "Saya terus menulis filter departure_time BETWEEN '00:00:00' AND '06:00:00' di banyak kueri. Bagaimana cara terbaik untuk menangkapnya?"
  • "Pengguna mendeskripsikan status penerbangan dalam teks bebas dan saya ingin mencocokkannya dengan flights.status. Jenis penelusuran nilai apa yang harus saya siapkan?"
  • "Apa perbedaan antara template dan faset, dan kapan saya harus menggunakan masing-masing?"

Menerapkan operasi massal di seluruh kumpulan konteks

Agen mendukung update massal untuk mengelola set konteks yang besar secara konsisten. Jika Anda perlu memperbarui beberapa item konteks secara bersamaan, seperti saat kolom database diganti namanya, nilai kode berubah format, atau template merujuk ke tabel yang tidak digunakan lagi, agen dapat menerapkan perubahan di setiap item yang terpengaruh tanpa mengubah entri yang tidak terkait.

Anda dapat menggunakan contoh perintah berikut untuk menginstruksikan agen:

  • "Baca golden.txt dan ubah semua pasangan menjadi template."
  • "Di context_set.json, ganti airline = 'UA' dengan airline = 'United Airlines' untuk item apa pun yang merujuk ke 'United'. Biarkan item yang tidak terkait."

Langkah berikutnya