Membangun konteks menggunakan Gemini CLI

Pratinjau — Data agents

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Spesifik per 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.

Untuk mengetahui informasi tentang akses ke rilis ini, lihat halaman permintaan akses.

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

Dokumen ini menjelaskan cara menggunakan Gemini CLI dan toolbox MCP untuk membuat file konteks agen. File ini berisi template dan aspek yang memberikan konteks untuk membuat kueri SQL dari bahasa alami. Anda juga akan menggunakan Server MCP Pengayaan Konteks DB.

Untuk mempelajari agen data, lihat Ringkasan agen data.

Untuk membangun konteks agen, lakukan langkah-langkah tingkat tinggi berikut:

• Menyiapkan lingkungan Anda
• Membuat template yang ditargetkan
• Membuat aspek yang ditargetkan
• Opsional. Membuat template massal

Sebelum memulai

Selesaikan prasyarat berikut sebelum membuat agen.

Siapkan instance Spanner

• Pastikan instance Spanner tersedia. Untuk mengetahui informasi selengkapnya, lihat Membuat instance.
• Isi database dengan data dan skema yang ingin diakses pengguna akhir.

Peran dan izin yang diperlukan

• Tambahkan akun pengguna atau layanan IAM ke cluster. Untuk mengetahui informasi selengkapnya, lihat Menerapkan peran IAM.
• Berikan peran spanner.databaseReader kepada pengguna IAM di tingkat project. Untuk mengetahui informasi selengkapnya, lihat Menambahkan binding kebijakan IAM untuk project.
• Berikan peran dan izin kepada pengguna IAM di tingkat project untuk database yang diperlukan.

Menyiapkan lingkungan Anda

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

• Menginstal Gemini CLI
• Menginstal dan menyiapkan MCP toolbox
• Menginstal dan menyiapkan Server MCP Pengayaan Konteks DB

Menginstal Gemini CLI

Untuk menginstal Gemini CLI, lihat Mulai Menggunakan Gemini CLI. Pastikan Anda menginstal Gemini CLI di direktori terpisah, yang juga digunakan untuk menginstal toolbox MCP dan Server MCP Pengayaan Konteks DB.

Menginstal dan menyiapkan MCP toolbox

1. Di direktori yang sama tempat Anda menginstal Gemini CLI, instal ekstensi Gemini CLI MCP Toolbox:

   gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

2. Buat file konfigurasi tools.yaml di direktori yang sama tempat Anda menginstal toolbox MCP untuk mengonfigurasi koneksi database:

     sources:
       my-spanner-source:
         kind: spanner
         project: PROJECT_ID
         instance: INSTANCE_ID
         database: DATABASE_ID
   

   Ganti kode berikut:

   • PROJECT_ID: Project ID Google Cloud Anda.
   • INSTANCE_ID: ID instance Spanner Anda.
   • DATABASE_ID: Nama database yang akan dihubungkan.

3. Pastikan file tools.yaml dikonfigurasi dengan benar:

   ./toolbox --tools-file "tools.yaml"

Menginstal Server MCP Pengayaan Konteks DB

Server MCP Pengayaan Konteks DB menyediakan alur kerja interaktif yang dipandu untuk membuat template NL2SQL terstruktur dari skema database Anda. Fitur ini mengandalkan ekstensi MCP Toolbox untuk konektivitas database. Untuk mengetahui informasi selengkapnya tentang cara menginstal Server MCP Pengayaan Konteks DB, lihat Server MCP Pengayaan Konteks DB.

Untuk menginstal Server MCP Pengayaan Konteks DB, lakukan hal berikut:

1. Di direktori yang sama tempat Anda menginstal Gemini CLI, instal penginstal paket Python uv.

     pip install --user pipx
     pipx ensurepath
     pipx install uv

2. Instal Server MCP Pengayaan Konteks DB.

   gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

Server menggunakan Gemini API untuk pembuatan. Pastikan Anda mengekspor kunci API sebagai variabel lingkungan. Untuk mengetahui informasi selengkapnya tentang cara menemukan kunci API Anda, lihat Menggunakan kunci API Gemini.

Untuk mengekspor kunci Gemini API, jalankan perintah berikut:

export GEMINI_API_KEY="YOUR_API_KEY"

Ganti YOUR_API_KEY dengan kunci Gemini API Anda.

Membuat template yang ditargetkan

Jika Anda ingin menambahkan pasangan kueri tertentu sebagai template kueri ke konteks agen, Anda dapat menggunakan perintah /generate_targeted_templates. Untuk mengetahui informasi selengkapnya tentang template, lihat Ringkasan agen data.

Untuk menambahkan template kueri ke konteks agen, lakukan langkah-langkah berikut:

1. Di direktori yang sama tempat Anda menginstal Gemini CLI, mulai Gemini:

   gemini

2. Selesaikan Penyiapan Autentikasi Gemini CLI.

3. Verifikasi bahwa toolbox MCP dan ekstensi pengayaan database siap digunakan:

   /mcp list

4. Jalankan perintah /generate_targeted_templates:

   /generate_targeted_templates

5. Masukkan kueri bahasa alami yang ingin Anda tambahkan ke template kueri.

6. Masukkan kueri SQL yang sesuai ke template kueri.

7. Tinjau template kueri yang dihasilkan. Anda dapat menyimpan template kueri sebagai file konteks agen atau menambahkannya ke file konteks yang ada.

File konteks agen yang mirip dengan my-cluster-psc-primary_postgres_templates_20251104111122.json disimpan di direktori tempat Anda menjalankan perintah.

Untuk mengetahui informasi selengkapnya tentang file konteks dan template kueri, lihat Konteks agen.

Membuat aspek yang ditargetkan

Jika ingin menambahkan pasangan kueri tertentu sebagai aspek ke file konteks agen, Anda dapat menggunakan perintah /generate_targeted_fragments. Untuk mengetahui informasi selengkapnya tentang aspek, lihat Ringkasan agen data.

Untuk menambahkan aspek ke konteks agen, lakukan langkah-langkah berikut:

1. Jalankan perintah /generate_targeted_fragments:

   /generate_targeted_fragments

2. Masukkan kueri bahasa alami yang ingin Anda tambahkan ke template kueri.

3. Masukkan kueri SQL yang sesuai ke template kueri.

4. Tinjau aspek yang dihasilkan. Anda dapat menyimpan aspek ke file konteks agen atau menambahkannya ke file konteks yang ada.

File konteks agen yang mirip dengan my-cluster-psc-primary_postgres_templates_20251104111122.json disimpan di direktori tempat Anda menjalankan perintah.

Untuk mengetahui informasi selengkapnya tentang file konteks dan aspek, lihat Konteks agen.

Opsional: Membuat template massal

Jika ingin membuat file konteks agen secara otomatis berdasarkan skema dan data database, Anda dapat menggunakan perintah /generate_bulk_templates.

Untuk membuat template massal secara otomatis, lakukan langkah-langkah berikut:

1. Jalankan perintah /generate_bulk_templates:

   /generate_bulk_templates

2. Berdasarkan skema database Anda, pembuatan SQL berbasis template akan memandu Anda melalui serangkaian pertanyaan terkait verifikasi informasi database dan pemberian izin untuk mengakses skema database.

3. Tinjau template kueri yang dihasilkan. Anda dapat menyetujui template atau memperbarui pasangan kueri yang ingin direvisi.

4. Masukkan kueri bahasa alami yang ingin Anda tambahkan ke template kueri.

5. Masukkan kueri SQL yang sesuai ke template kueri.

6. Tinjau template kueri yang dihasilkan. Anda dapat menyimpan template kueri sebagai file konteks agen atau menambahkannya ke file konteks yang ada.

7. Setelah menyetujui template kueri, Anda dapat membuat file template baru atau menambahkan pasangan kueri ke file template yang ada. Template kueri disimpan sebagai file JSON di direktori lokal Anda.

File konteks agen yang mirip dengan my-cluster-psc-primary_postgres_templates_20251104111122.json disimpan di direktori tempat Anda menjalankan perintah.

Untuk mengetahui informasi selengkapnya tentang file konteks agen, lihat Konteks agen.

Langkah berikutnya

• Pelajari agen data lebih lanjut.
• Pelajari cara membuat atau menghapus agen data di Spanner Studio.
• Pelajari cara memeriksa dan memanggil agen data.