Membangun dan mengoptimalkan set konteks dengan agen rekayasa konteks

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan, dan Persyaratan Tambahan untuk Produk Pratinjau AI Generatif. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Catatan antarmuka PostgreSQL: Contoh dalam topik ini ditujukan untuk database dialek GoogleSQL. Fitur ini tidak mendukung antarmuka PostgreSQL.

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 membantu aplikasi Anda memberikan jawaban yang cepat, deterministik, dan dapat dijelaskan untuk pertanyaan 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:

• Data Analytics API with Gemini
• Gemini for Google Cloud API
• Knowledge Catalog API

Menyiapkan database Anda

Siapkan instance dan database Spanner Anda:

• Buat instance Spanner atau gunakan instance yang ada.
• Buat database di instance Spanner atau gunakan database yang ada.

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:

• Berikan peran roles/spanner.databaseReader, roles/serviceusage.serviceUsageConsumer, roles/geminidataanalytics.queryDataUser, dan roles/mcp.toolUser kepada pengguna IAM atau akun layanan di level project (atau berikan roles/spanner.databaseReader di level database untuk database yang diperlukan). Untuk mengetahui informasi selengkapnya, lihat Menerapkan peran IAM dan 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 Izin set konteks.

Semua konteks agen yang terkait dengan database dapat dilihat oleh semua pengguna yang memiliki akses baca ke database tersebut. Jika pengguna memiliki akses yang lebih sempit ke database, seperti kontrol akses terperinci Spanner, pengguna berpotensi menemukan kolom dan tabel lain dari konteks agen.

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)

Catatan: Dukungan Gemini CLI tidak digunakan lagi. Jika Anda menggunakan Gemini CLI, lakukan migrasi ke Antigravity CLI. Untuk mengetahui informasi selengkapnya, lihat Bermigrasi dari Gemini CLI.

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:

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:

  • "In my context set, replace properties.property_type = 'SFR' with properties.property_type = 'Single Family Residential' for any item referencing single-family homes. Biarkan item yang tidak terkait."

Langkah berikutnya

• Pelajari lebih lanjut set konteks.
• Pelajari cara menguji QueryData di Spanner Studio.
• Pelajari cara mengintegrasikan QueryData dengan aplikasi.
• Pelajari cara membuat atau menghapus set konteks di Spanner Studio.