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 rekayasa konteks membantu Anda membuat, mengevaluasi, dan meningkatkan set konteks dengan mengotomatiskan pembuatan dan pengoptimalannya.

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

Untuk membuat aplikasi data tingkat perusahaan, akurasi model text-to-SQL biasanya harus mencapai kualitas mendekati 100%. Hasil kueri yang salah memengaruhi kegunaan aplikasi secara keseluruhan dan pengalaman pengguna. Mencapai jawaban yang dapat dijelaskan dan relevan dengan bisnis dengan akurasi tinggi memerlukan 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 menyediakan 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 berkomunikasi dengan agen untuk menangani tugas ad hoc guna mengoptimalkan konteks Anda. Daftar berikut memberikan contoh perintah bahasa alami yang dapat Anda gunakan untuk menginstruksikan agen, beserta deskripsi tentang cara agen merespons. Gunakan contoh ini untuk membantu membangun dan mengoptimalkan konteks Anda:

  • Contoh perintah untuk analisis kegagalan: "Update context so that we correctly identify the airport for queries like 'disney world flights'." Agen menganalisis kegagalan, alasan tentang kesenjangan, dan merekomendasikan penambahan item konteks yang sesuai, seperti kueri penelusuran nilai.
  • Contoh perintah untuk saran konteks: "Read my app code and suggest some context to add." Agen mengurai kode, alasan tentang domain aplikasi Anda, dan menyarankan item konteks yang relevan.
  • Contoh perintah untuk pemrosesan massal: "Here are 10 examples of questions and SQL queries. Turn them into templates." Agen memproses input Anda secara massal dan memperbarui set konteks Anda.

Pentingnya set data emas

Untuk mengoptimalkan konteks, Anda harus membuat set data yang cocok 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:

  • Menetapkan dasar pengukuran untuk performa kueri.
  • Memvalidasi pembaruan terhadap kueri database kebenaran dasar.
  • Mengukur peningkatan akurasi di seluruh iterasi.

Proses pendakian bukit sistematis

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

  • Membuat konteks dasar pengukuran secara otomatis: Buat set konteks awal yang berasal dari skema database dan artefak aplikasi Anda.
  • Alur kerja pengoptimalan pendakian bukit: Izinkan agen mengevaluasi akurasi QueryData Anda, melakukan analisis kesenjangan pada kegagalan, dan secara otomatis menyarankan peningkatan untuk mendorong akurasi yang lebih tinggi.

Diagram berikut menunjukkan alur kerja pendakian bukit 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 instance Cloud SQL

Pastikan Anda memiliki akses ke instance Cloud SQL yang ada atau buat instance baru. Untuk mengetahui informasi selengkapnya, lihat Membuat instance untuk Cloud SQL.

Tutorial ini mengharuskan Anda memiliki database di instance Cloud SQL. Untuk mengetahui informasi selengkapnya, lihat Membuat database di instance Cloud SQL

Peran dan izin yang diperlukan

  • Tambahkan akun pengguna atau layanan IAM ke instance. Untuk mengetahui informasi selengkapnya, lihat Mengelola pengguna dengan autentikasi database IAM untuk Cloud SQL.
  • Berikan peran cloudsql.studioUser, cloudsql.instanceUser, dan geminidataanalytics.queryDataUser kepada pengguna IAM di tingkat project. Untuk mengetahui informasi selengkapnya, lihat Menambahkan binding kebijakan IAM untuk project.
  • Anda juga harus memberikan hak istimewa database hanya baca kepada pengguna atau akun layanan IAM dengan login sebagai pengguna yang memiliki hak istimewa superuser, seperti pengguna postgres.

    GRANT SELECT ON ALL TABLES IN SCHEMA public TO USER_NAME;

    Ganti USER_NAME dengan alamat email untuk pengguna. Anda harus menggunakan tanda kutip di sekitar email karena berisi karakter khusus (@ dan .).

    Untuk mengetahui informasi selengkapnya, lihat Memberikan hak istimewa database kepada pengguna atau akun layanan IAM.

Memberikan izin executesql ke instance Cloud SQL

Untuk memberikan izin executesql ke instance Cloud SQL dan mengaktifkan Cloud SQL Data API, jalankan perintah berikut: 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
Ganti kode berikut:
  • PROJECT_ID: ID project Anda. Google Cloud
  • INSTANCE_ID: ID instance Cloud SQL 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. Untuk mempersiapkan lingkungan Anda, lakukan langkah-langkah berikut:

  • Menginstal agen rekayasa konteks
  • Menyiapkan koneksi database

Menginstal agen rekayasa konteks

Agen rekayasa konteks 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 diinstal dan dapat diakses dari command line Anda:

    uv --version

Untuk mempersiapkan lingkungan Anda, instal agen rekayasa konteks di harness agen yang Anda pilih, seperti Antigravity CLI, Claude Code, atau Gemini CLI.

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

Antigravity CLI

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

  1. Instal Antigravity CLI. Lihat Memulai 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
  4. Opsional. Perbarui plugin: 
    agy plugin uninstall google-cloud-db-context-engineering
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/NEW_VERSION

Claude Code

Untuk menginstal agen rekayasa konteks 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. Opsional. Perbarui 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. Instal Gemini CLI. Lihat Memulai Gemini CLI.
  2. Instal ekstensi: 
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
  3. Opsional. Perbarui ekstensi: 
    gemini extensions update mcp-db-context-enrichment

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 untuk mengakses Google Cloud resource 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 Agent Skills yang telah diinstal sebelumnya untuk membantu Anda membuat konfigurasi.

  1. Mulai lingkungan agen Anda.

  2. Minta agen untuk membantu menyiapkan koneksi database—misalnya, perintah "help me set up the database connection". 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 /reload-plugins.

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 Agent Skills 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 mana pun dalam alur kerja:

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

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

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

Membuat 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 dasar.

Membuat set data emas representatif secara manual memerlukan waktu yang lama, dan set data kecil mungkin tidak mencakup variasi dalam frasa pengguna. Agen mengatasi hal ini dengan:

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

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

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

[
  {
    "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 mengisi file autoctx/golden.json di ruang kerja Anda, tempat pasangan tersebut siap untuk dievaluasi. Anda dapat menyediakan file yang ada atau menulis beberapa contoh evaluasi secara inline agar agen dapat memperluasnya.

Anda dapat menggunakan contoh perintah berikut untuk menginstruksikan agen:

  • "Generate an evaluation dataset from my schema."
  • "Here's a seed question and SQL—expand it into a broader dataset and verify the queries run."

Membuat set konteks dasar pengukuran

Untuk menghindari pembuatan konteks dari awal, Anda dapat mengizinkan agen memperoleh set konteks awal dari skema database dan artefak aplikasi Anda, seperti aturan bisnis, contoh kueri, atau file README. Meskipun konteks dasar pengukuran ini belum final, konteks ini memberikan titik awal yang divalidasi berdasarkan model database Anda.

Anda dapat menggunakan contoh perintah berikut untuk menginstruksikan agen:

  • "Generate a context set from my schema."
  • "Generate initial context using these schemas and the business rules in requirements.md."

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

Mengevaluasi efektivitas konteks

Setelah membuat set konteks dan set data emas, Anda dapat mengizinkan agen mengukur performa konteks dengan meng-kueri QueryData API agen data Anda dengan setiap pertanyaan emas. 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:

  • "Evaluate my context against golden.json."
  • "Re-run the evaluation using the config from my last experiment."

Untuk menjalankan kembali konfigurasi evaluasi yang sebelumnya dibuat tanpa menyiapkan ulang, minta agen atau panggil CLI secara langsung:

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

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

Melakukan analisis kesenjangan dan menyarankan 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 laporan evaluasi yang ekstensif.

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, aspek, atau penelusuran nilai.
  • Perbaikan yang disarankan: Agen menyarankan pengeditan konkret dan secara opsional menguji SQL terhadap database Anda untuk memverifikasi resolusi.
  • Mempertahankan dasar pengukuran: Agen menulis peningkatan ke file JSON baru bersama dengan konteks dasar pengukuran Anda, sehingga mempertahankan file asli.

Anda dapat menggunakan contoh perintah berikut untuk menginstruksikan agen:

  • "Run gap analysis on my last evaluation and propose fixes."
  • "Optimize this context set against golden.json."

Untuk mempersiapkan iterasi berikutnya, upload konteks yang ditingkatkan ke set konteks target menggunakan Data Agents Studio, ikuti petunjuknya.

Membuat item konteks tertentu sesuai permintaan

Jika Anda sudah mengetahui konteks yang diperlukan, seperti template untuk pertanyaan tertentu, aspek 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 pembaruan 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 satu kali: pemangku kepentingan memberi Anda pasangan pertanyaan-SQL baru yang ingin mereka dukung, atau Anda melihat aspek yang tidak ada selama peninjauan kode. Anda tidak perlu menyiapkan eksperimen atau menjalankan evaluasi untuk memperbaikinya—jelaskan apa yang Anda inginkan dan agen akan menghasilkan JSON.

Anda dapat menggunakan contoh perintah berikut untuk menginstruksikan agen:

  • "Create a template for: 'Which airports are in California?' with SQL: SELECT name FROM airports WHERE country = 'United States' AND state = 'CA'."
  • "Create a facet for the filter departure_time BETWEEN '00:00:00' AND '06:00:00' labeled 'red eye'."
  • "Create a value search for airports.iata."

Alasan pemilihan jenis konteks

Memilih jenis konteks yang benar, terlepas dari apakah template, aspek, atau penelusuran nilai, membantu mencegah pembengkakan konteks dan regresi kueri database. Misalnya, menggunakan template, bukan aspek, dapat menyebabkan aturan duplikat, sedangkan penelusuran nilai yang diperkenalkan jika 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 menjelaskan alasannya untuk membantu Anda memahami opsi konteks.

Anda dapat menggunakan contoh perintah berikut untuk menginstruksikan agen:

  • "I keep writing the filter departure_time BETWEEN '00:00:00' AND '06:00:00' across many queries. What's the best way to capture this?"
  • "Users describe flight status in free text and I want to match them to flights.status. What kind of value search should I set up?"
  • "What's the difference between a template and a facet, and when should I use each?"

Menerapkan operasi massal di seluruh set konteks

Agen mendukung pembaruan massal untuk mengelola set konteks besar secara konsisten. Jika Anda perlu memperbarui beberapa item konteks secara bersamaan, seperti saat kolom database diganti namanya, nilai kode berubah format, atau template mereferensikan 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:

  • "Read golden.txt and turn all the pairs into templates."
  • "In context_set.json, replace airline = 'UA' with airline = 'United Airlines' for any item referencing 'United'. Leave unrelated items alone."

Langkah berikutnya