Membangun dan mengoptimalkan set konteks dengan agen rekayasa konteks

Untuk mencapai akurasi kueri QueryData yang tinggi dan latensi online yang rendah dalam aplikasi agen data, Anda dapat menggunakan agen rekayasa konteks untuk membangun, mengevaluasi, dan mengoptimalkan set konteks. Dengan mengotomatiskan pembuatan, upload, dan pengoptimalan konteks, agen ini membantu aplikasi Anda memberikan jawaban yang cepat, deterministik, dan dapat dijelaskan untuk pertanyaan dalam bahasa alami.

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

Dengan memberikan konteks yang disesuaikan dengan aplikasi bisnis Anda kepada QueryData, Anda memberikan aturan bisnis yang tepat yang diperlukan sistem untuk menyelesaikan niat pengguna yang bernuansa dan memberikan kualitas kueri hampir 100%. Saat Anda bekerja di CLI atau IDE, agen rekayasa konteks akan otomatis mengupload set konteks Anda ke Google Cloud sambil menyimpan file lokal di ruang kerja Anda untuk kontrol versi.

Agen rekayasa konteks

Agen context engineering bertindak sebagai asisten waktu desain Anda langsung di CLI atau IDE Anda. Pembuatan konteks manual memerlukan penulisan pola kueri mendetail secara manual, mengantisipasi setiap variasi frasa, dan mendiagnosis kegagalan kueri secara manual di seluruh iterasi. Agen rekayasa konteks menghilangkan overhead ini dengan melakukan bootstrap pada konteks dasar, mengumpulkan set data evaluasi kebenaran nyata, melakukan hill-climbing secara iteratif untuk memperbaiki kesenjangan akurasi, dan membuktikan bahwa konteks Anda digeneralisasi di seluruh pertanyaan baru.

Anda berkomunikasi dengan agen menggunakan bahasa alami untuk mendorong alur kerja pengoptimalan. Mulailah dengan perintah seperti "Optimalkan set konteks terhadap persyaratan aplikasi saya".

Sebelum memulai

Sebelum Anda menggunakan agen rekayasa konteks, selesaikan prasyarat di bagian berikut. Anda dapat membuat dan menyimpan set konteks di region us-central1, us-east1, europe-west4, dan asia-southeast1, meskipun instance database Anda berada di region yang berbeda.

Mengaktifkan layanan yang diperlukan

Aktifkan layanan berikut untuk project Anda:

Menyiapkan database Anda

Siapkan instance AlloyDB untuk PostgreSQL dan konfigurasikan akses untuk agen:

  • Buat cluster dan instance AlloyDB dan buat database, atau gunakan instance dan database yang ada.
  • Aktifkan akses Data API di instance AlloyDB Anda. Jika Anda menggunakan IP pribadi, tetapkan kolom akses Data API (dataApiAccess) ke ENABLED di instance utama agar agen dapat memeriksa skema dan memvalidasi kueri. Untuk instance yang dibuat tanpa mengaktifkan akses Data API, lihat Mengaktifkan akses Data API atau konfigurasikan di konsol Google Cloud .

Peran dan izin yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk menggunakan agen context engineering dan mengelola set konteks, konfigurasikan peran Identity and Access Management (IAM) dan hak istimewa database berikut:

  • Tambahkan akun pengguna atau layanan IAM ke cluster. Untuk mengetahui informasi selengkapnya, lihat Mengelola autentikasi IAM.
  • Berikan peran roles/alloydb.databaseUser, roles/serviceusage.serviceUsageConsumer, roles/geminidataanalytics.queryDataUser, dan roles/mcp.toolUser kepada pengguna IAM atau akun layanan 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 atau akun layanan di level project. Untuk mengetahui informasi selengkapnya, lihat Izin set konteks.
  • Jika Anda menggunakan penelusuran nilai semantik (google_ml.embedding), aktifkan Vertex AI API dan berikan peran roles/aiplatform.user ke akun layanan cluster AlloyDB.

  • Berikan 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 (untuk akun layanan, hapus akhiran .). Jika tabel Anda berada dalam skema kustom selain public, jalankan juga GRANT USAGE ON SCHEMA SCHEMA_NAME TO "USER_NAME"; dan GRANT SELECT ON ALL TABLES IN SCHEMA SCHEMA_NAME TO "USER_NAME";. Untuk mengetahui informasi selengkapnya, lihat Memberikan hak istimewa database kepada pengguna IAM.

Menyiapkan lingkungan Anda

Anda dapat membangun dan mengoptimalkan set konteks dari lingkungan pengembangan lokal atau IDE Anda.

Menginstal uv

Agen rekayasa konteks 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

Menginstal agen rekayasa konteks

Instal plugin agen rekayasa konteks di lingkungan pengembangan pilihan Anda:

Antigravity CLI

  1. Instal Antigravity CLI. Lihat Mulai menggunakan Antigravity CLI.
  2. Instal plugin agen rekayasa konteks: 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
  3. Mulai Antigravity CLI: 
    agy

Untuk mengupdate plugin nanti, jalankan agy plugin uninstall db-context-engineering diikuti dengan agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin.

Claude Code

  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

Untuk mengupdate plugin nanti, jalankan /plugin update db-context-engineering@db-context-enrichment-marketplace.

Gemini CLI (Tidak digunakan lagi)

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

Untuk mengupdate ekstensi nanti, jalankan gemini extensions update google-cloud-db-context-engineering.

Autentikasi dengan Google Cloud

  1. Konfigurasikan Kredensial Default Aplikasi (ADC) untuk mengautentikasi lingkungan pengembangan Anda:

    gcloud auth application-default login

  2. Tetapkan project kuota untuk kredensial Anda agar alat Model Context Protocol (MCP) dapat menggunakan project Google Cloud Anda:

    gcloud auth application-default set-quota-project PROJECT_ID

    Ganti PROJECT_ID dengan project ID Google Cloud Anda.

Menghubungkan ke database Anda

  1. Mulai lingkungan agen Anda dan minta agen untuk membuat koneksi database (misalnya, "Bantu saya menyiapkan koneksi database"). Agen ini akan memandu Anda membuat file konfigurasi .context-engineering/tools.yaml sehingga dapat membaca skema dan memvalidasi SQL. (Sebelum .context-engineering/tools.yaml dibuat, peringatan koneksi server MCP toolbox awal saat memulai adalah hal yang wajar.)

  2. Muat ulang koneksi server MCP untuk menerapkan konfigurasi .context-engineering/tools.yaml:

    • Antigravity CLI: Jalankan /mcp dan pilih toolbox (atau db-context-engineering_toolbox) untuk memulai ulang.
    • Claude Code: Jalankan /mcp, pilih toolbox, lalu pilih Reconnect.
    • Gemini CLI: Jalankan /mcp refresh (atau /mcp reload).

Membangun dan mengoptimalkan konteks

Agen rekayasa konteks memandu set konteks Anda melalui siklus proses end-to-end, mulai dari bootstrap awal hingga generalisasi yang terverifikasi.

Melakukan bootstrap pada set konteks dasar pengukuran

Untuk menghindari pembuatan konteks dari halaman kosong, agen akan memeriksa skema database Anda beserta artefak aplikasi yang tersedia, seperti persyaratan bisnis, dokumentasi, atau contoh kueri SQL. Agen memperoleh set konteks dasar pengukuran awal yang berisi template kueri dasar dan aspek kueri yang didasarkan pada model database Anda.

Setelah membuat dan memvalidasi konteks dasar pengukuran, agen akan menguploadnya langsung ke Google Cloud dan menampilkan nama resource set konteks.

Membuat set data evaluasi dan held-out dari artefak aplikasi

Untuk meningkatkan akurasi secara sistematis, Anda memerlukan pertanyaan kebenaran nyata yang dipasangkan dengan kueri SQL yang diverifikasi. Jika Anda belum memiliki tolok ukur evaluasi, agen dapat membuatnya dengan mengekstrak skenario bisnis dari kode aplikasi, kueri historis, dan skema database Anda.

Selama pembuatan set data, agen membuat dua set yang berbeda:

  • Tolok ukur pelatihan: Kumpulan pasangan pertanyaan-SQL representatif yang digunakan selama pengoptimalan iteratif.
  • Set data yang ditahan: Kumpulan pertanyaan terpisah yang mirip dalam domain dengan tolok ukur pelatihan Anda, yang disediakan untuk pengujian generalisasi.

Mengoptimalkan akurasi dengan hill-climbing

Dalam pengoptimalan hill-climbing, agen secara iteratif menyaring set konteks Anda untuk mendorong akurasi QueryData mendekati 100%:

  • Mengevaluasi: Agen menguji set konteks Anda saat ini terhadap tolok ukur pelatihan dengan menggunakan API QueryData dan menilai akurasi.
  • Mendiagnosis kesenjangan: Agen menganalisis kegagalan kueri, mengidentifikasi akar masalahnya (seperti gabungan tabel yang hilang, entity pribadi yang tidak ditautkan, atau kondisi filter yang kompleks), dan merumuskan perbaikan yang ditargetkan.
  • Perbaiki dan upload: Agen menambahkan atau meningkatkan kualitas template kueri, faset kueri, dan penelusuran nilai untuk mengatasi kesenjangan, dan otomatis mengupload set konteks yang diperbarui ke Google Cloud dari CLI Anda.
  • Iterasi: Agen mengulangi siklus ini di beberapa putaran hingga akurasi mencapai skor optimal.

Diagram berikut menunjukkan alur kerja hill-climbing sistematis:

Alur kerja untuk membangun konteks secara iteratif.

Membuktikan generalisasi dengan set data holdout

Mencapai akurasi tinggi pada tolok ukur pelatihan memang diperlukan, tetapi traffic produksi mencakup variasi frasa dan pertanyaan gabungan yang kompleks yang belum pernah terlihat selama pengembangan.

Setelah pengoptimalan hill-climbing konvergen, agen akan menguji set konteks yang dihasilkan terhadap set data yang ditahan. Langkah ini memverifikasi bahwa set konteks digeneralisasi dengan baik ke input pengguna baru tanpa overfitting ke tolok ukur awal. Agen akan menghasilkan laporan generalisasi yang menunjukkan akurasi di berbagai variasi pertanyaan yang belum pernah dilihat dan filter gabungan (seperti "Find me homes near good schools in Del Mar for a starter family with an ocean view").

Pembuatan dan penalaran on-demand

Selain menjalankan pengoptimalan penuh, Anda dapat berkomunikasi dengan agen untuk mendapatkan pembaruan yang ditargetkan seiring berkembangnya persyaratan bisnis:

  • Pembuatan yang ditargetkan: Deskripsikan persyaratan bisnis tertentu dalam bahasa alami, dan agen akan memformat item konteks dan menguploadnya langsung dari CLI Anda tanpa pengeditan manual:

    • "Create a template for: 'Find me homes near good schools in Del Mar' with SQL: SELECT p.property_id, p.address FROM properties AS p JOIN schools AS s ON p.school_id = s.school_id WHERE p.city = 'Del Mar' AND s.rating >= 7."
    • "Buat faset untuk filter properties.bedrooms BETWEEN 3 AND 4 AND properties.square_feet BETWEEN 1500 AND 2500 yang diberi label 'untuk keluarga pemula'."
    • "Buat penelusuran nilai untuk properties.city."

  • Update massal di seluruh set konteks: Jika kolom database diganti namanya atau struktur tabel berubah, agen dapat mengupdate semua item konteks yang terpengaruh secara bersamaan tanpa mengubah entri yang tidak terkait:

    • "Dalam set konteks saya, ganti properties.property_type = 'SFR' dengan properties.property_type = 'Single Family Residential' untuk item apa pun yang merujuk ke rumah satu keluarga. Biarkan item yang tidak terkait."

Langkah berikutnya