Membangun set konteks untuk Firestore dengan kompatibilitas MongoDB 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 harus mencapai kualitas mendekati 100%. MongoDB-compatible Query Language (MQL) yang dibuat secara tidak benar akan memengaruhi keseluruhan kegunaan aplikasi dan pengalaman pengguna. Untuk mendapatkan jawaban yang dapat dijelaskan dan relevan dengan bisnis dengan 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 menyediakan aturan bisnis yang tepat yang diperlukan sistem untuk menyelesaikan maksud pengguna yang rumit.

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 perintah bahasa alami yang dapat Anda gunakan untuk memberi tahu agen, beserta deskripsi tentang cara agen merespons. Gunakan contoh ini untuk membantu membangun dan mengoptimalkan konteks Anda:

  • Contoh perintah untuk analisis kegagalan: "Perbarui konteks agar kita dapat mengidentifikasi bandara dengan benar untuk kueri seperti 'penerbangan disney world'." Agen menganalisis kegagalan, mempertimbangkan 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 MQL. Ubah menjadi template." Agen 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.
  • Validasi update terhadap kueri database kebenaran nyata.
  • Mengukur peningkatan akurasi di seluruh iterasi.

Proses hill-climbing yang sistematis

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

  • Buat konteks dasar yang dibuat otomatis: Buat set 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 secara otomatis menyarankan 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 database Firestore

Pastikan Anda memiliki database Firestore Edisi Enterprise dengan kompatibilitas MongoDB.

Jika Anda mencoba contoh di halaman ini, sebaiknya buat database baru untuk tujuan ini. Untuk mengetahui informasi selengkapnya, lihat Membuat dan mengelola database.

Peran dan izin yang diperlukan

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

    uv --version

Untuk menyiapkan lingkungan Anda, instal agen rekayasa konteks di infrastruktur pengelola 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 rekayasa konteks 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: 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
  3. Mulai Antigravity CLI: 
    agy

Untuk mengupdate plugin ke versi terbaru:

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

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. 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 mcp-db-context-enrichment

Menyiapkan koneksi database

Agen memerlukan koneksi database untuk mengambil skema dan kemampuan untuk memvalidasi sintaksis konteks MQL 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 MQL 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-alat ini bersama-sama untuk membuat tolok ukur, mengukur efektivitas, dan menerapkan peningkatan secara berulang. Namun, Anda dapat memulai di tahap alur kerja mana pun:

  • Jika sudah menetapkan konteks, Anda dapat langsung melanjutkan ke evaluasi.
  • Jika ada kueri yang gagal dan ingin Anda perbaiki, Anda dapat langsung melanjutkan ke analisis kesenjangan.

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

Contoh perintah menunjukkan cara Anda dapat mengajukan kueri ke 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 MQL 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 emas yang representatif secara manual memerlukan waktu yang lama, dan set data kecil mungkin melewatkan variasi dalam frasa pengguna. Agen menyelesaikan masalah ini dengan:

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

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

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

[
  {
    "id": "example_001",
    "nlq": "What is the total revenue for each of the top 5 products?",
    "golden_sql": "db.sales.aggregate([ { $group: { _id: '$product_id', total_net_revenue: { $sum: '$net_revenue' } } }, { $sort: { total_net_revenue: -1 } }, { $limit: 5 } ]);"
  }
]

Pasangan yang disetujui akan mengisi file autoctx/golden.json di ruang kerja Anda, tempat pasangan tersebut siap dievaluasi. Anda dapat memberikan file yang ada atau menulis beberapa contoh evaluasi 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 MQL. Perluas menjadi set data yang lebih luas dan verifikasi kueri yang dijalankan."

Membuat set data konteks dasar pengukuran

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

Anda dapat menggunakan contoh perintah berikut untuk memberikan petunjuk kepada 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 Firestore Studio, ikuti petunjuk setelah agen membuat file JSON.

Mengevaluasi efektivitas konteks

Setelah membuat set konteks dan set data standar, Anda dapat membiarkan agen mengukur performa konteks dengan membuat kueri QueryData API agen data Anda dengan setiap pertanyaan standar. 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 memberikan petunjuk kepada 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 --run_config=autoctx/experiments/my-experiment/eval_configs/run_config.json

Untuk mengetahui detail tentang skema konfigurasi evaluasi dan cara menyesuaikan operasi 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 belum 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, aspek, 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:

  • "Run gap analysis on my last evaluation and propose fixes." (Lakukan analisis kesenjangan pada evaluasi terakhir saya dan sarankan perbaikan.)
  • "Optimalkan set konteks ini terhadap golden.json."

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

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 menimbulkan error serialisasi dalam nama parameter, metadata jenis, atau sintaksis fragmen. Agen menangani pemformatan JSON sehingga 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 satu kali: pemangku kepentingan memberi Anda pasangan SQL-pertanyaan baru yang ingin mereka dukung, atau Anda melihat aspek 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 kueri: db.airports.find({ country: "United States", state: "CA" }, { name: 1, _id: 0 })."
  • "Buat aspek untuk filter { departure_time: { $gte: "00:00:00", $lte: "06:00:00" } } berlabel 'mata merah'."
  • "Buat penelusuran nilai untuk airports.iata."

Alasan pemilihan 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 alih-alih aspek dapat menyebabkan aturan duplikat, sementara penelusuran nilai yang diperkenalkan saat template sudah cukup dapat meningkatkan latensi kueri. Untuk menemukan format skema yang benar, minta agen merekomendasikan jenis berdasarkan struktur kueri atau kolom database sebelum Anda membuat item konteks. Agen menjelaskan penalarannya untuk membantu Anda memahami opsi konteks.

Anda dapat menggunakan contoh perintah berikut untuk memberikan petunjuk kepada agen:

  • "Saya terus menulis filter { departure_time: { $gte: "00:00:00", $lte: "06:00:00" } }' di banyak kueri. Bagaimana cara terbaik untuk merekamnya?"
  • "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 aspek, dan kapan saya harus menggunakan masing-masing?"

Menerapkan operasi massal di seluruh set konteks

Agen mendukung update 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 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 memberikan petunjuk kepada 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