Tutorial ini menjelaskan cara menyiapkan dan menggunakan QueryData di Spanner menggunakan konsol Google Cloud dan mengintegrasikannya dengan aplikasi Anda. Pelajari cara membangun file set konteks, membuat set konteks yang menggunakan file set konteks, menggunakan MCP Toolbox untuk memanggil metode QueryData di Conversational Analytics API guna membuat kueri SQL untuk pertanyaan bahasa alami, dan mengintegrasikannya dengan aplikasi Anda.
Untuk mengetahui informasi selengkapnya, lihat Ringkasan QueryData.
Tujuan
Tutorial ini membahas tujuan berikut:
- Membuat database dan mengisinya dengan data.
- Membuat file set konteks dengan agen rekayasa konteks.
- Buat set data konteks dan upload file set data konteks.
- Menguji QueryData dan membuat kueri SQL di Spanner Studio.
- Integrasikan QueryData dengan aplikasi Anda menggunakan alat Gemini Data Analytics QueryData di MCP Toolbox.
- Menambahkan grounding ke respons LLM menggunakan kueri penelusuran nilai.
Biaya
Dalam dokumen ini, Anda akan menggunakan komponen Google Cloudyang dapat ditagih berikut:
Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga.
Pengguna Google Cloud baru mungkin memenuhi syarat untuk mendapatkan uji coba gratis.
Untuk menghindari penagihan berkelanjutan, hapus resource yang Anda buat setelah menyelesaikan tugas dalam dokumen ini. Untuk informasi selengkapnya, lihat Pembersihan.
Sebelum memulai
Selesaikan prasyarat berikut sebelum membuat set konteks.
Mengaktifkan layanan yang diperlukan
Aktifkan layanan berikut untuk project Anda:Menyiapkan instance Spanner
- Pastikan instance Spanner tersedia. Untuk mengetahui informasi selengkapnya, lihat Membuat instance.
- Pastikan Anda membuat database di instance tempat Anda akan membuat tabel. Untuk informasi selengkapnya, lihat Membuat database pada instance Spanner.
Peran dan izin yang diperlukan
- Tambahkan akun pengguna atau layanan IAM ke instance. Untuk mengetahui informasi selengkapnya, lihat Menerapkan peran IAM.
- Berikan peran
roles/spanner.databaseReader,roles/serviceusage.serviceUsageConsumer, danroles/geminidataanalytics.queryDataUserkepada pengguna IAM 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 di level project. Untuk mengetahui informasi selengkapnya, lihat Izin set konteks. - Berikan peran dan izin kepada pengguna IAM di level project untuk database yang diperlukan.
Membuat skema dan tabel flights dan airports
Di bagian ini, Anda akan membuat tabel database flights dan airports untuk tutorial ini.
Di konsol Google Cloud , buka halaman Spanner.
Pilih instance dari daftar, lalu pilih database.
Di menu navigasi, klik Spanner Studio.
Klik New SQL editor tab atau New tab untuk membuka tab baru.
Untuk membuat tabel dan skema
airports, jalankan pernyataan SQL berikut:CREATE TABLE IF NOT EXISTS airports ( id INT64 PRIMARY KEY, iata STRING(MAX), name STRING(MAX), city STRING(MAX), country STRING(MAX) );Buat tabel dan skema
flights:CREATE TABLE flights ( id INT64 NOT NULL, airline STRING(10), flight_number INT64, departure_airport STRING(5), arrival_airport STRING(5), departure_time TIMESTAMP, arrival_time TIMESTAMP, departure_gate STRING(10), arrival_gate STRING(10) ) PRIMARY KEY (id);
Mengisi tabel flights dan airports
Di bagian ini, Anda akan mengisi tabel flights dan airports menggunakan skrip SQL yang disediakan.
Isi tabel
airports.Isi tabel
flights.Jalankan kueri berikut untuk memverifikasi bahwa tabel telah diisi:
SELECT * FROM flights LIMIT 10; SELECT * FROM airports LIMIT 10;
Membuat kolom yang ditokenisasi dan indeks penelusuran
Gunakan kemampuan penelusuran teks bawaan Spanner untuk memungkinkan QueryData memetakan frasa bahasa alami yang tidak terstruktur secara akurat, seperti salah ketik atau nama parsial, ke nilai tertentu dalam database Anda. Hal ini memerlukan pembuatan kolom TOKENLIST tersembunyi yang memecah string Anda menjadi n-grams, dan membuat indeks penelusuran di kolom tersebut.
Untuk membuat kolom yang ditokenisasi dan indeks penelusuran, jalankan pernyataan SQL berikut:
Buat kolom token dan indeks untuk nama bandara:
ALTER TABLE `airports` ADD COLUMN `name_tokens` TOKENLIST AS (TOKENIZE_SUBSTRING(`name`)) STORED HIDDEN; CREATE SEARCH INDEX `airports_name_idx` ON `airports`(`name_tokens`);Buat kolom token dan indeks untuk kota bandara:
ALTER TABLE `airports` ADD COLUMN `city_tokens` TOKENLIST AS (TOKENIZE_SUBSTRING(`city`)) STORED HIDDEN; CREATE SEARCH INDEX `airports_city_idx` ON `airports`(`city_tokens`);
Membuat set data konteks di Spanner Studio
Di bagian ini, buat set konteks bernama flights-assistant. Set konteks ini tidak menyertakan file set konteks yang diupload ke dalamnya.
Di konsol Google Cloud , buka halaman Spanner.
Pilih instance dari daftar, lalu pilih database.
Di menu navigasi, klik Spanner Studio.
Di panel Explorer, di samping Context sets, klik View actions ().
Klik Create context set.
Di Nama set konteks, masukkan
flights-assistant.Klik Create.
Menguji QueryData di Studio
Di bagian ini, gunakan set konteks flights-assistant dengan mengajukan pertanyaan dalam bahasa alami untuk membuat kueri SQL.
Karena set konteks tidak memiliki file set konteks yang diupload, bahkan setelah mengajukan pertanyaan dengan konteks seperti nighttime traffic, QueryData akan menghasilkan kueri yang kurang optimal.
- Di panel Explorer, di samping set konteks, klik View actions ().
- Klik Test context set.
- Di editor kueri, klik Generate SQL using QueryData with: flights-assistant.
Masukkan pertanyaan bahasa alami berikut untuk membuat kueri SQL, lalu klik Generate.
Find flights from SFO to JFK.Tinjau kueri SQL. Perhatikan bahwa QueryData menghasilkan SQL yang benar untuk pertanyaan yang tidak ambigu ini.
SELECT * FROM flights WHERE departure_airport = 'SFO' AND arrival_airport = 'JFK';Di jendela Generate SQL using QueryData with: flights-assistant, klik Edit.
Masukkan pertanyaan bahasa alami berikut untuk membuat kueri SQL, lalu klik Update.
Tell me flights that can help me beat nighttime traffic if traveling from New YorkDatabase gagal memahami istilah traffic
nighttime. Hal ini dapat mencegahnya membuat kueri SQL atau menyebabkannya membuat kueri yang mengabaikan istilah tersebut, seperti yang ditunjukkan kueri berikut.-- The database schema does not contain information about traffic. -- Returning all flights departing from New York airports. SELECT f.airline, f.flight_number, a.name AS departure_airport_name, f.departure_time, b.name AS arrival_airport_name, f.arrival_time FROM flights AS f JOIN airports AS a ON f.departure_airport = a.iata JOIN airports AS b ON f.arrival_airport = b.iata WHERE a.city = 'New York' ORDER BY f.departure_time;Di jendela Generate SQL using QueryData with: flights-assistant, klik Edit.
Masukkan pertanyaan bahasa alami berikut untuk membuat kueri SQL, lalu klik Update.
Show me the flight to Houston IntercontinentalLogika set konteks menghasilkan kueri untuk menemukan bandara dengan nama "Houston Intercontinental". Karena bandara atau kota tersebut tidak ada dalam database, kueri tidak akan menampilkan baris apa pun.
SELECT f.* FROM `flights` AS f JOIN `airports` AS a ON f.arrival_airport = a.id WHERE a.name LIKE '%Houston Intercontinental%';
Membuat konteks untuk set data konteks
Di bagian ini, Anda akan menyiapkan lingkungan dan membuat file konteks yang membantu meningkatkan kemampuan kueri set konteks.
Menyiapkan lingkungan Anda
Sebelum dapat mulai membuat konteks, Anda harus menyiapkan lingkungan Anda.
Untuk menyiapkan lingkungan Anda, lakukan langkah-langkah berikut:
- Instal Antigravity CLI. Untuk mengetahui informasi selengkapnya, lihat Memulai Antigravity CLI.
- Menginstal Google Cloud CLI.
Siapkan Kredensial Default Aplikasi (ADC). Jalankan perintah berikut di terminal Anda untuk mengautentikasi dan memilih project Anda:
gcloud auth application-default login gcloud auth application-default set-quota-project PROJECT_IDInstal
uv, paket Python dan pengelola project yang merupakan prasyarat untuk agen rekayasa konteks. Jika Anda belum memiliki Python di sistem,uvdapat menginstalnya untuk Anda.Menginstal agen rekayasa konteks:
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/pluginDi terminal Anda, mulai Antigravity CLI.
agySiapkan koneksi database untuk pembuatan konteks menggunakan MCP Toolbox. Koneksi ditentukan dalam file konfigurasi
.context-engineering/tools.yaml.Untuk membuat file konfigurasi
.context-engineering/tools.yaml, masukkan perintah seperti:Help me set up a database connection.Ikuti petunjuk yang diberikan oleh skill. Untuk mengetahui informasi selengkapnya tentang file
tools.yaml, lihat dokumentasi MCP Toolbox.Untuk memuat ulang konfigurasi setelah file
.context-engineering/tools.yamldibuat, jalankan perintah berikut di Antigravity CLI dan ikuti petunjuk untuk memuat ulang server MCP toolbox:/mcpPilih
db-context-engineering_toolbox.Pilih
Restart.
Pastikan toolbox MCP dan plugin agen rekayasa konteks terhubung dan siap digunakan.
/mcp
Membuat konteks template
Di bagian ini, untuk mengatasi masalah dari bagian sebelumnya, yaitu QueryData tidak mengenali istilah nighttime traffic, tentukan istilah tersebut dalam file set konteks sebagai traffic yang terjadi antara 5:00 PM dan 7:00 PM.
Untuk membuat konteks template, lakukan langkah-langkah berikut:
Masukkan perintah berikut ke Antigravity CLI:
Generate a template for the question: "Tell me flights that can help me beat nighttime traffic if traveling from New York" with the following SQL query: SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND ( EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19 ) ORDER BY f.departure_time;Agen mengonversi input Anda ke dalam format tertentu yang meningkatkan performa set konteks di berbagai kueri pengguna. Untuk mengetahui informasi selengkapnya, lihat Ringkasan set konteks.
Tinjau template kueri yang dihasilkan. Anda dapat menyimpan template kueri sebagai file konteks agen baru atau menambahkannya ke file konteks agen yang ada.
Minta agen untuk menyimpan template:
Save it to context_set.json.Agen akan membuat file di direktori yang sama, dengan konten berikut:
{ "templates": [ { "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York", "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19) ORDER BY f.departure_time;", "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York", "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city", "parameterized": { "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = ? AND (EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19) ORDER BY f.departure_time;", "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from ?" } } ] }
Membuat konteks penelusuran nilai
Di bagian ini, Anda akan membuat konteks penelusuran nilai untuk membantu logika set konteks memetakan frasa nilai ke nilai tertentu yang disimpan di kolom database menggunakan kesamaan string (pencocokan trigram). Misalnya, jika pengguna meminta penerbangan ke "Houston Intercontinental", penelusuran nilai dapat memetakan ini ke nilai database yang tepat, yaitu "George Bush Intercontinental Houston Airport".
Untuk membuat konteks penelusuran nilai, lakukan langkah-langkah berikut:
Masukkan perintah berikut ke dalam infrastruktur pengelola agen:
Generate a value search on table "airports" for column "city" with concept "Airport City" using match function "TRIGRAM_STRING_MATCH".Tinjau definisi penelusuran nilai yang dihasilkan. Anda dapat menyimpan definisi penelusuran nilai sebagai file set konteks baru atau menambahkannya ke file set konteks yang ada.
Berikan perintah kepada agen dengan
Append the context to context_set.json. Tindakan ini akan menambahkan definisi penelusuran nilai ke file konteks yang dibuat di bagian sebelumnya.Masukkan instance database dan nama database tempat file set konteks dibuat.
File konteks yang ada diperbarui dengan definisi penelusuran nilai, dengan konten berikut:
{ "templates": [ { "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York", "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19) ORDER BY f.departure_time;", "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York", "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city", "parameterized": { "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = ? AND (EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19) ORDER BY f.departure_time;", "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from ?" } } ], "facets": [], "value_searches": [ { "query": "SELECT CAST(T.`name` AS STRING) AS value, 'name' AS `columns`, 'airport name' AS concept_type, 1 - SCORE_NGRAMS(T.`name_tokens`, CAST($value AS STRING)) AS distance, JSON '{}' AS context FROM `airports` AS T WHERE SEARCH_NGRAMS(T.`name_tokens`, CAST($value AS STRING)) ", "concept_type": "airport name", "description": "String similarity using Spanner Search Indexes." }, { "query": "SELECT CAST(T.`city` AS STRING) AS value, 'city' AS `columns`, 'airport city' AS concept_type, 1 - SCORE_NGRAMS(T.`city_tokens`, CAST($value AS STRING)) AS distance, JSON '{}' AS context FROM `airports` AS T WHERE SEARCH_NGRAMS(T.`city_tokens`, CAST($value AS STRING)) ", "concept_type": "airport city", "description": "String similarity using Spanner Search Indexes." } ] }
Mengupload file set konteks ke QueryData
Di bagian ini, Anda akan mengupload file set konteks ke QueryData, sehingga meningkatkan kemampuan pembuatan SQL QueryData di database Anda.
Untuk mengupload konteks, lakukan langkah-langkah berikut:
Di konsol Google Cloud , buka halaman Spanner.
Pilih instance dari daftar, lalu pilih database.
Di menu navigasi, klik Spanner Studio.
Di panel Explorer, di bagian Context sets dan di samping set konteks
flights-assistant, klik ikon View actions ().Klik Edit context set.
Klik Browse di bagian Upload context file, lalu pilih file set konteks yang dibuat sebelumnya.
Klik Simpan.
Membuat kueri SQL menggunakan QueryData
Di bagian ini, Anda akan menggunakan file set konteks yang Anda upload untuk mengajukan pertanyaan dalam bahasa alami. Dengan demikian, Anda dapat memverifikasi bahwa QueryData memahami dan menerapkan definisi dengan benar untuk istilah seperti nighttime traffic dan frasa terkait lainnya.
Untuk membuat kueri SQL, lakukan langkah-langkah berikut:
- Di panel Explorer, di samping set konteks, klik View actions ().
- Klik Test context set.
- Di editor kueri, klik Generate SQL using QueryData with: flights-assistant.
Untuk membuat kueri SQL, masukkan pertanyaan bahasa alami berikut, lalu klik Generate.
Tell me flights that can help me beat nighttime traffic if traveling from New YorkKueri SQL yang dihasilkan akan terlihat mirip dengan berikut ini:
SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND ( EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19 ) ORDER BY f.departure_time;Ini adalah pertanyaan yang sama dengan yang Anda tambahkan ke konteks QueryData. Perhatikan bahwa QueryData kini dapat menafsirkan istilah
nighttime trafficsecara akurat.Meskipun konteksnya berasal dari satu pertanyaan tertentu, QueryData menggunakannya untuk meningkatkan pembuatan SQL untuk berbagai pertanyaan serupa.
Di jendela Generate SQL using QueryData with: flights-assistant, klik Edit.
Masukkan pertanyaan serupa berikut untuk membuat kueri SQL, lalu klik Update.
What are the flights that can help me avoid evening traffic if departing from BostonKarena pertanyaan mengganti istilah
nighttime trafficdengan istilah yang serupa,evening traffic, QueryData memberikan jawaban yang konsisten untuk pertanyaan ini dengan menerapkan interpretasi yang sama.Kueri SQL yang dihasilkan akan terlihat mirip dengan berikut ini:
-- What are the flights that can help me avoid evening traffic if departing from Boston SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'Boston' AND ( EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') < 17 OR EXTRACT(HOUR FROM f.departure_time AT TIME ZONE 'UTC') >= 19 ) ORDER BY f.departure_time;Masukkan pertanyaan berikut untuk membuat kueri SQL, lalu klik Update.
Show me the flight to Houston IntercontinentalKueri SQL yang dihasilkan akan terlihat mirip dengan berikut ini:
SELECT f.* FROM flights AS f INNER JOIN airports AS a ON f.arrival_airport = a.iata WHERE a.name = 'George Bush Intercontinental Houston Airport'Perhatikan bahwa QueryData kini dapat menafsirkan secara akurat bahwa "Houston Intercontinental" berkaitan dengan "George Bush Intercontinental Houston Airport" dalam database.
Mengintegrasikan QueryData dengan aplikasi Anda
Di bagian ini, Anda akan membuat agen data untuk aplikasi pencarian penerbangan. Agen data ini menyediakan antarmuka percakapan ke tabel flights dan airports yang Anda buat sebelumnya. Dokumen ini juga menjelaskan cara membuat dan mengintegrasikan agen data ini ke dalam aplikasi Anda menggunakan Agent Development Kit (ADK), alat MCP QueryData Gemini Data Analytics, dan set konteks untuk meningkatkan kualitas respons.
Download MCP Toolbox versi 1.14.0 atau yang lebih baru. MCP Toolbox mengekspos agen data sebagai alat yang dapat dihubungkan oleh aplikasi. MCP Toolbox berbeda dengan agen rekayasa konteks yang Anda instal sebelumnya, yang menghasilkan konteks.
Siapkan Kredensial Default Aplikasi (ADC).
gcloud auth application-default login gcloud auth application-default set-quota-project PROJECT_IDTemukan ID set konteks yang Anda buat sebelumnya. Untuk mengetahui informasi selengkapnya tentang cara menemukan ID set konteks, lihat Menemukan ID set konteks.
Tambahkan kode berikut ke konfigurasi
.context-engineering/tools.yaml(atautools.yamldi direktori kerja Anda) untuk terhubung ke agen data menggunakan MCP Toolbox. Untuk mengetahui informasi selengkapnya, lihat Sumber Analisis Data Gemini dan Alat QueryData Analisis Data Gemini.--- kind: source name: gda-api-source type: cloud-gemini-data-analytics projectId: "PROJECT_ID" --- kind: tool name: cloud_gda_query_tool type: cloud-gemini-data-analytics-query source: gda-api-source description: Use this tool to send natural language queries to the Gemini Data Analytics API and receive SQL, natural language answers, and explanations. location: "REGION_ID" context: datasourceReferences: spannerReference: databaseReference: engine: "GOOGLE_SQL" projectId: "PROJECT_ID" instanceId: "INSTANCE_ID" databaseId: "DATABASE_ID" agentContextReference: contextSetId: "CONTEXT_SET_ID" generationOptions: generateQueryResult: true generateNaturalLanguageAnswer: true generateExplanation: true generateDisambiguationQuestion: trueGanti kode berikut:
PROJECT_ID: Project ID Google Cloud Anda.REGION_ID: Region instance Spanner Anda (misalnyaus-central1).INSTANCE_ID: ID instance Spanner Anda.DATABASE_ID: Nama database yang akan dihubungkan.CONTEXT_SET_ID: ID set konteks. Untuk mengetahui informasi selengkapnya tentang cara menemukan ID set konteks, lihat Menemukan ID set konteks.
Jalankan server MCP Toolbox dengan file
tools.yaml../toolbox --config PATH_TO_TOOLS_YAMLGanti
PATH_TO_TOOLS_YAMLdengan jalur ke filetools.yamlyang Anda buat sebelumnya (misalnya,.context-engineering/tools.yamlatautools.yaml).Buat aplikasi ADK yang memanggil alat QueryData Analisis Data Gemini menggunakan Python SDK MCP Toolbox. Untuk mengetahui informasi selengkapnya tentang cara menggunakan SDK Python MCP Toolbox, lihat panduan memulai Toolbox dan untuk ADK Python, lihat panduan memulai ADK.
- Buat direktori untuk menyimpan aplikasi, misalnya
flight-assistant-app. Ubah direktori ke direktori
flight-assistant-app.mkdir flight-assistant-appcd flight-assistant-appJalankan perintah berikut di direktori
flight-assistant-appuntuk membuat lingkungan virtual dan menginstal komponen yang diperlukan.uv inituv add google-adk toolbox-core google-genaiMenyiapkan agen ADK.
Membuat agen ADK.
uv run adk create my_agentPilih model
gemini-2.5-flash, atau yang lebih baru.Pilih Google AI, lalu masukkan kunci Gemini API Anda. Untuk mengetahui informasi selengkapnya tentang cara menemukan kunci API Anda, lihat Menggunakan kunci Gemini API. (Atau, jika Anda tidak memerlukan uji coba gratis, Anda dapat memilih Vertex AI, menentukan project Google Cloud dengan penagihan yang diaktifkan, dan memasukkan
globalsaat diminta untuk region Google Cloud (Enter Google Cloud region) sehinggaGOOGLE_CLOUD_LOCATION=globalditetapkan dimy_agent/.env).
Ganti konten file
agent.pydengan kode aplikasi contoh Flight Data Assistant berikut.from typing import cast from google.adk.agents.llm_agent import Agent from google.adk.agents.llm_agent import ToolUnion from toolbox_core import ToolboxSyncClient TOOLBOX_URL = "http://127.0.0.1:5000" INSTRUCTION = """ # ROLE You are a friendly and factual flight data assistant. Your goal is to help users find the best flights for their needs by providing accurate information with a helpful, professional tone. - use the Query Data Tool to answer the user's question, if the tool fails to generate a valid query, ask the user to clarify their question. # OPERATIONAL CONSTRAINTS - TOOL LIMITATION: You only have access to the Query Data Tool. Do not claim to have capabilities beyond what this tool provides. - TRANSPARENCY POLICY: Maintain a seamless user experience. Never mention that you are using a tool, querying a database, or generating SQL. Frame all responses as your own direct assistance. - SCOPE MANAGEMENT: If a user asks for something beyond your capabilities, politely state that you cannot perform that specific task. Guide the user towards what you can help with. # COMMUNICATION STYLE - Be concise and scannable when listing answers. - Maintain a helpful, professional persona. ===== # QUERY DATA TOOL Inputs: 1. query: A natural language formulation of a database query. Outputs: (all optional) 1. disambiguation_question: Clarification questions or comments where the tool needs the users' input. 2. generated_query: The generated query for the user query. 3. intent_explanation: An explanation for why the tool produced `generated_query`. 4. query_result: The result of executing `generated_query`. 5. natural_language_answer: The natural language answer that summarizes the `query` and `query_result`. Usage guidance: 1. If `disambiguation_question` is produced, then solicit the needed inputs from the user and try the tool with a new `query` that has the needed clarification. 2. If `natural_language_answer` is produced, use `intent_explanation` and `generated_query` to see if you need to clarify any assumptions for the user. 3. If the tool output indicates failure or empty results, explain that clearly using the provided reasoning. """ client = ToolboxSyncClient(TOOLBOX_URL) mcp_tool = client.load_tool("cloud_gda_query_tool") root_agent = Agent( model="gemini-2.5-flash", # Or newer. name="root_agent", instruction=INSTRUCTION, tools=cast(list[ToolUnion], [mcp_tool]), )
- Buat direktori untuk menyimpan aplikasi, misalnya
Untuk memulai aplikasi, jalankan perintah berikut di direktori
flight-assistant-app. Akses server web ADK dihttp://127.0.0.1:8000.uv run adk web --port 8000Masukkan teks apa pun, seperti
hello, untuk mulai berinteraksi dengan agen.Agen ADK menjawab pertanyaan umum dan memanggil alat MCP yang diperlukan.
Masukkan pertanyaan terkait penerbangan berikut.
How many flights depart from the west side?Alat MCP dipanggil untuk menjawab pertanyaan ini. Namun, karena istilah
the westambigu dan tidak menentukan bandara mana pun, alat MCP menampilkan pertanyaan disambiguasi yang digunakan agen untuk membuat respons.I cannot determine how many flights depart from the 'west side' as the database does not contain information about which airports are considered to be on the 'west side'. However, I can help you with questions like: 1. How many flights depart from a specific airport? 2. What are the departure airports for all flights? 3. How many flights depart from each airport? Would you like to rephrase your question based on these options?Masukkan pertanyaan yang mirip dengan pertanyaan di template kueri yang dibuat untuk agen.
Help me find flights from San Francisco that avoid the evening rush hour.Berdasarkan konteks QueryData yang ditambahkan sebelumnya, alat MCP memahami bahwa
evening trafficterjadi antara pukul 17.00 dan 19.00. Alat MCP menampilkan data terkait untuk digunakan agen dalam menyusun responsnya.Here are the flights departing from San Francisco that avoid the evening rush hour (defined as 5 PM to 7 PM): * UA 1532 departing at 05:50:00 * UA 1158 departing at 05:57:00 * CY 922 departing at 06:38:00 * OO 5441 departing at 07:08:00 * UA 616 departing at 07:14:00 * AA 24 departing at 07:14:00 * B6 434 departing at 08:00:00 * AA 242 departing at 08:18:00 * UA 1739 departing at 08:22:00 * OO 6336 departing at 08:32:00 * US 1784 departing at 08:47:00 * DL 1631 departing at 09:00:00 * DL 1106 departing at 09:06:00 * OO 5427 departing at 09:06:00 * CY 352 departing at 09:25:00Masukkan pertanyaan berdasarkan jenis konsep yang Anda tambahkan dalam konteks agen QueryData.
Show me the flight to Houston IntercontinentalBerdasarkan konteks penelusuran nilai yang ditambahkan sebelumnya, agen memahami bahwa "Houston Intercontinental" berkaitan dengan "George Bush Intercontinental Houston Airport" (kode bandara IAH) dan menampilkan data terkait untuk digunakan agen dalam menyusun responsnya.
Here are the flights heading to Houston Intercontinental (IAH): * Flight UA 1285 departs from SFO and arrives at IAH on 2025-01-01 at 15:20:00Z. * Flight F9 1056 departs from SFO and arrives at IAH on 2025-01-02 at 12:09:00Z. * Flight UA 1722 departs from SFO and arrives at IAH on 2025-01-02 at 18:29:00Z. * Flight UA 1705 departs from SFO and arrives at IAH on 2025-01-02 at 18:50:00Z. * Flight UA 1762 departs from SFO and arrives at IAH on 2025-01-02 at 23:11:00Z.
Melakukan iterasi performa agen
UI web ADK memungkinkan Anda memeriksa permintaan dan respons dari alat MCP QueryData Analisis Data Gemini. Anda dapat menggunakan respons ini untuk mengamati respons alat seperti kueri SQL yang dihasilkan, set hasil, penjelasan intent, pertanyaan disambiguasi, dan jawaban bahasa alami, untuk membantu Anda mengonfirmasi kebenaran respons agen.
Misalnya, untuk teks input How many flights depart from the west side?
yang Anda masukkan sebelumnya, klik balon agen. Di tab Event di navigasi kiri, luaskan functionResponse untuk melihat respons berikut.
"{"disambiguationQuestion": ["[NOT_ENOUGH_INFO] The database schema does not
contain information about which airports are on the 'west side'. Therefore, I
cannot determine how many flights depart from the west side.Possible alternative
questions: 1. How many flights depart from a specific airport? 2. What are the
departure airports for all flights? 3. How many flights depart from each
airport?"]}"
Mempertajam akurasi respons
Anda dapat terus meningkatkan akurasi respons dari alat QueryData Gemini Data Analytics dengan menambahkan konteks tambahan. Gunakan agen rekayasa konteks untuk membuat konteks, lalu upload file set konteks yang diperbarui ke agen data flights-assistant yang ada. Untuk mengetahui informasi selengkapnya, lihat Mengelola set konteks di Spanner Studio. Konsol akan langsung menyerap konteks baru setelah Anda menguploadnya, sehingga Anda dapat meningkatkan akurasi agen tanpa waktu nonaktif aplikasi.
Beberapa agen
Di lingkungan pengembangan, Anda dapat melakukan pengujian A/B pada beberapa konteks agen data dengan menetapkan nama yang berbeda untuk alat dalam file tools.yaml. Misalnya, Anda dapat membuat konfigurasi tools.yaml yang unik dengan menentukan dua alat cloud-gemini-data-analytics-query dengan nama yang berbeda, seperti cloud_gda_query_tool_v1 dan cloud_gda_query_tool_v2. Penyiapan ini memungkinkan Anda menerapkan logika aplikasi yang secara terprogram memilih versi konteks yang diperlukan dengan memilih nama alat yang sesuai.
Contoh tools.yaml berikut menunjukkan cara menyiapkan beberapa agen data untuk sumber database:
kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: PROJECT_ID
---
kind: tool
name: cloud_gda_query_tool_v1
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
datasourceReferences:
DB_SOURCE:
databaseReference: ...
agentContextReference:
contextSetId: "V1_YOUR_CONTEXT_SET_ID"
generationOptions: ...
---
kind: tool
name: cloud_gda_query_tool_v2
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
datasourceReferences:
DB_SOURCE:
databaseReference: ...
agentContextReference:
contextSetId: "V2_YOUR_CONTEXT_SET_ID"
generationOptions: ...
Ganti kode berikut:
PROJECT_ID: Project ID Google Cloud Anda.V1_YOUR_CONTEXT_SET_ID: ID set konteks untuk versi 1.V2_YOUR_CONTEXT_SET_ID: ID set konteks untuk versi 2.DB_SOURCE: konfigurasi sumber database.
Pembersihan
Setelah Anda selesai mengikuti tutorial ini, hapus resource yang Anda buat untuk menghindari biaya berkelanjutan. Bagian berikut menjelaskan cara menghapus resource ini.
Menghapus set konteks
Sebelum menghapus instance, hapus set konteks yang Anda buat.
Di konsol Google Cloud , buka halaman Spanner.
Pilih instance dari daftar, lalu pilih database.
Di menu navigasi, klik Spanner Studio.
Di panel Explorer, di samping set konteks, klik View actions ().
Klik Hapus set konteks.
Di jendela Delete context set, masukkan
flights-assistant.Klik Konfirmasi.
Menghapus instance
Saat Anda menghapus instance yang Anda buat di bagian sebelum memulai, Anda juga menghapus semua objek yang Anda buat.
Di konsol Google Cloud , buka halaman Spanner.
Klik nama instance yang ingin Anda hapus, misalnya, Test Instance.
Klik Delete instance.
Konfirmasi bahwa Anda ingin menghapus instance dengan memasukkan nama instance dan mengklik Delete.
Langkah berikutnya
- Pelajari lebih lanjut set konteks.
- Pelajari cara menentukan konteks yang ditulis untuk sumber data database.