Questo tutorial descrive come configurare e utilizzare QueryData in Spanner utilizzando la console Google Cloud e integrarlo con la tua applicazione. Scopri come creare il file dei set di contesti, creare un set di contesti che utilizza il file dei set di contesti, utilizzare MCP Toolbox per chiamare il metodo QueryData nell'API Analisi conversazionale per generare query SQL per domande in linguaggio naturale e integrarlo con la tua applicazione.
Per saperne di più, consulta la panoramica di QueryData.
Obiettivi
Questo tutorial illustra come raggiungere i seguenti obiettivi:
- Creare database e compilarli con i dati.
- Crea un file di set di contesti con l'agente di progettazione del contesto.
- Crea un set di contesti e carica un file del set di contesti.
- Testa QueryData e genera query SQL in Spanner Studio.
- Integra QueryData con la tua applicazione utilizzando lo strumento QueryData di Gemini Data Analytics in MCP Toolbox.
- Aggiungi il grounding alle risposte dell'LLM utilizzando query di ricerca di valore.
Costi
In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:
Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi.
I nuovi utenti di Google Cloud potrebbero avere diritto a una prova senza costi.
Per evitare l'addebito di ulteriori costi, elimina le risorse che hai creato al termine delle attività descritte in questo documento. Per ulteriori informazioni, consulta Esegui la pulizia.
Prima di iniziare
Completa i seguenti prerequisiti prima di creare un set di contesti.
Abilita i servizi richiesti
Abilita i seguenti servizi per il tuo progetto:Prepara un'istanza Spanner
- Assicurati che sia disponibile un'istanza Spanner. Per saperne di più, consulta Crea un'istanza.
- Assicurati di creare un database nell'istanza in cui creerai le tabelle. Per saperne di più, consulta Crea un database nell'istanza Spanner.
Ruoli e autorizzazioni richiesti
- Aggiungi un utente o un account di servizio IAM all'istanza. Per saperne di più, consulta Applica i ruoli IAM.
- Concedi i ruoli
roles/spanner.databaseReader,roles/serviceusage.serviceUsageConsumereroles/geminidataanalytics.queryDataUserall'utente IAM a livello di progetto. Per saperne di più, consulta Aggiungi l'associazione delle policy IAM per un progetto. - Per creare, caricare e gestire i set di contesto, concedi il ruolo Dataplex Catalog Editor (
roles/dataplex.catalogEditor) o Dataplex Catalog Admin (roles/dataplex.catalogAdmin) all'utente IAM a livello di progetto. Per saperne di più, consulta Autorizzazioni per i set di contesti. - Concedi ruoli e autorizzazioni all'utente IAM a livello di progetto per i database richiesti.
Crea lo schema e le tabelle flights e airports
In questa sezione creerai le tabelle di database flights e airports per questo tutorial.
Nella console Google Cloud , vai alla pagina Spanner.
Seleziona un'istanza dall'elenco, quindi seleziona un database.
Nel menu di navigazione, fai clic su Spanner Studio.
Fai clic su Nuova scheda dell'editor SQL o su Nuova scheda per aprire una nuova scheda.
Per creare la tabella e lo schema
airports, esegui la seguente istruzione SQL:CREATE TABLE IF NOT EXISTS airports ( id INT64 PRIMARY KEY, iata STRING(MAX), name STRING(MAX), city STRING(MAX), country STRING(MAX) );Crea la tabella e lo schema
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);
Compila le tabelle flights e airports
In questa sezione, compili le tabelle flights e airports utilizzando gli script SQL forniti.
Compila la tabella
airports.Compila la tabella
flights.Esegui questa query per verificare che le tabelle siano compilate:
SELECT * FROM flights LIMIT 10; SELECT * FROM airports LIMIT 10;
Crea colonne tokenizzate e indici della Ricerca
Utilizza le funzionalità di ricerca testuale integrate di Spanner per consentire a QueryData di mappare con precisione frasi in linguaggio naturale non strutturate, come errori di battitura o nomi parziali, a valori specifici nel tuo database. Per farlo, devi generare una colonna TOKENLIST nascosta che suddivide le stringhe in n-grams e creare un indice della Ricerca su quella colonna.
Per creare colonne tokenizzate e indici della Ricerca, esegui le seguenti istruzioni SQL:
Crea la colonna e l'indice dei token per i nomi degli aeroporti:
ALTER TABLE `airports` ADD COLUMN `name_tokens` TOKENLIST AS (TOKENIZE_SUBSTRING(`name`)) STORED HIDDEN; CREATE SEARCH INDEX `airports_name_idx` ON `airports`(`name_tokens`);Crea la colonna e l'indice dei token per le città degli aeroporti:
ALTER TABLE `airports` ADD COLUMN `city_tokens` TOKENLIST AS (TOKENIZE_SUBSTRING(`city`)) STORED HIDDEN; CREATE SEARCH INDEX `airports_city_idx` ON `airports`(`city_tokens`);
Crea un set di contesti in Spanner Studio
In questa sezione, crea un set di contesti denominato flights-assistant. Questo set di contesto non include alcun file di set di contesto caricato.
Nella console Google Cloud , vai alla pagina Spanner.
Seleziona un'istanza dall'elenco, quindi seleziona un database.
Nel menu di navigazione, fai clic su Spanner Studio.
Nel riquadro Explorer, accanto a Set di contesto, fai clic su Visualizza azioni ().
Fai clic su Crea set di contesti.
In Nome set di contesti, inserisci
flights-assistant.Fai clic su Crea.
Testa QueryData in Studio
In questa sezione, utilizza il contesto flights-assistant impostato ponendo domande in linguaggio naturale per generare una query SQL.
Poiché nel set di contesti non è stato caricato alcun file di set di contesti, anche dopo aver posto una domanda con un contesto come nighttime traffic, QueryData genera una query non ottimale.
- Nel riquadro Explorer, accanto al set di contesto, fai clic su Visualizza azioni ().
- Fai clic su Set di contesti di test.
- Nell'editor di query, fai clic su Genera SQL utilizzando QueryData con: flights-assistant.
Inserisci la seguente domanda in linguaggio naturale per generare una query SQL e fai clic su Genera.
Find flights from SFO to JFK.Esamina la query SQL. Nota che QueryData genera l'SQL corretto per questa domanda non ambigua.
SELECT * FROM flights WHERE departure_airport = 'SFO' AND arrival_airport = 'JFK';Nella finestra Genera SQL utilizzando QueryData con: flights-assistant, fai clic su Modifica.
Inserisci la seguente domanda in linguaggio naturale per generare una query SQL e fai clic su Aggiorna.
Tell me flights that can help me beat nighttime traffic if traveling from New YorkIl database non riesce a comprendere il termine traffico
nighttime. Ciò potrebbe impedire la generazione di una query SQL o causare la generazione di una query che ignora il termine, come mostrato nella query seguente.-- 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;Nella finestra Genera SQL utilizzando QueryData con: flights-assistant, fai clic su Modifica.
Inserisci la seguente domanda in linguaggio naturale per generare una query SQL e fai clic su Aggiorna.
Show me the flight to Houston IntercontinentalLa logica del set di contesti genera una query per trovare un aeroporto con "Houston Intercontinental" nel nome. Poiché nel database non esiste un aeroporto o una città con questo nome, la query non restituirà alcuna riga.
SELECT f.* FROM `flights` AS f JOIN `airports` AS a ON f.arrival_airport = a.id WHERE a.name LIKE '%Houston Intercontinental%';
Genera il contesto per il set di contesti
In questa sezione, prepari l'ambiente e crei un file di contesto che aiuta a migliorare le funzionalità di query del set di contesti.
Configura l'ambiente
Prima di poter iniziare a generare il contesto, devi preparare l'ambiente.
Per configurare l'ambiente, segui questi passaggi:
- Installa Antigravity CLI. Per saperne di più, consulta Inizia a utilizzare Antigravity CLI.
- Installa Google Cloud CLI.
Configura le Credenziali predefinite dell'applicazione (ADC). Esegui questi comandi nel terminale per autenticarti e selezionare il tuo progetto:
gcloud auth application-default login gcloud auth application-default set-quota-project PROJECT_IDInstalla
uv, un pacchetto Python e un project manager che è un prerequisito per l'agente di context engineering. Se non hai già Python sul tuo sistema,uvpuò installarlo per te.Installa l'agente di context engineering:
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/pluginNel terminale, avvia l'interfaccia a riga di comando di Antigravity.
agyConfigura una connessione al database per la generazione del contesto utilizzando MCP Toolbox. La connessione è definita nel file di configurazione
.context-engineering/tools.yaml.Per creare il file di configurazione
.context-engineering/tools.yaml, inserisci un prompt come:Help me set up a database connection.Segui le istruzioni fornite dalla skill. Per saperne di più sul file
tools.yaml, consulta la documentazione di MCP Toolbox.Per ricaricare la configurazione dopo aver creato il file
.context-engineering/tools.yaml, esegui il comando seguente nell'interfaccia a riga di comando di Antigravity e segui le istruzioni per ricaricare il server MCP della toolbox:/mcpSeleziona
db-context-engineering_toolbox.Seleziona
Restart.
Verifica che il toolbox MCP e il plugin agenti di context engineering siano connessi e pronti per l'uso.
/mcp
Genera il contesto del template
In questa sezione, per risolvere il problema della sezione precedente in cui QueryData non riconosceva il termine nighttime traffic, definisci il termine nel file del set di contesto come traffico che si verifica tra 5:00 PM e 7:00 PM.
Per generare il contesto del template, segui questi passaggi:
Inserisci il seguente prompt nell'interfaccia a riga di comando di Antigravity:
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;L'agente converte l'input in un formato specifico che perfeziona le prestazioni del set di contesto in un'ampia gamma di query degli utenti. Per saperne di più, consulta la panoramica dei set di contesti.
Esamina il template di query generato. Puoi salvare il modello di query come nuovo file di contesto dell'agente o aggiungerlo a un file di contesto dell'agente esistente.
Chiedi all'agente di salvare il template:
Save it to context_set.json.L'agente crea il file nella stessa directory, con i seguenti contenuti:
{ "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 ?" } } ] }
Genera il contesto di ricerca del valore
In questa sezione, generi il contesto di ricerca dei valori per aiutare la logica del set di contesto a mappare le frasi dei valori a valori specifici archiviati nelle colonne del database utilizzando la somiglianza delle stringhe (corrispondenza dei trigrammi). Ad esempio, se un utente chiede informazioni sui voli per "Houston Intercontinental", la ricerca di valori può mappare questa richiesta al valore esatto del database "George Bush Intercontinental Houston Airport".
Per generare il contesto di ricerca del valore, segui questi passaggi:
Inserisci il seguente prompt nell'infrastruttura agentica:
Generate a value search on table "airports" for column "city" with concept "Airport City" using match function "TRIGRAM_STRING_MATCH".Rivedi la definizione di ricerca del valore generata. Puoi salvare la definizione della ricerca di valori come nuovo file del set di contesti o aggiungerla a un file del set di contesti esistente.
Invia un prompt all'agente con
Append the context to context_set.json. In questo modo, la definizione della ricerca dei valori viene aggiunta al file di contesto creato nella sezione precedente.Inserisci l'istanza del database e il nome del database per cui è stato generato il file del set di contesto.
Il file di contesto esistente viene aggiornato con la definizione di ricerca del valore, con i seguenti contenuti:
{ "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." } ] }
Carica il file del set di contesti in QueryData
In questa sezione caricherai il file del set di contesti in QueryData, in modo da migliorare le funzionalità di generazione SQL di QueryData nel tuo database.
Per caricare il contesto, segui questi passaggi:
Nella console Google Cloud , vai alla pagina Spanner.
Seleziona un'istanza dall'elenco, quindi seleziona un database.
Nel menu di navigazione, fai clic su Spanner Studio.
Nel riquadro Explorer, in Set di contesto e accanto al set di contesto
flights-assistant, fai clic sull'icona Visualizza azioni ().Fai clic su Modifica set di contesti.
Fai clic su Sfoglia nella sezione Carica file di contesto, quindi seleziona il file del set di contesto generato in precedenza.
Fai clic su Salva.
Genera una query SQL utilizzando QueryData
In questa sezione utilizzerai il file del set di contesto che hai caricato per porre domande in linguaggio naturale. In questo modo puoi verificare che QueryData comprenda e applichi correttamente le definizioni di termini come nighttime traffic e altre frasi correlate.
Per generare query SQL, segui questi passaggi:
- Nel riquadro Explorer, accanto al set di contesto, fai clic su Visualizza azioni ().
- Fai clic su Set di contesti di test.
- Nell'editor di query, fai clic su Genera SQL utilizzando QueryData con: flights-assistant.
Per generare una query SQL, inserisci la seguente domanda in linguaggio naturale, quindi fai clic su Genera.
Tell me flights that can help me beat nighttime traffic if traveling from New YorkLa query SQL generata è simile alla seguente:
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;Questa è la stessa domanda che hai aggiunto al contesto di QueryData. Osserva che QueryData ora può interpretare con precisione il termine
nighttime traffic.Sebbene il contesto provenga da una domanda specifica, QueryData lo utilizza per migliorare la generazione di SQL per un'ampia gamma di domande simili.
Nella finestra Genera SQL utilizzando QueryData con: flights-assistant, fai clic su Modifica.
Inserisci la seguente domanda simile per generare una query SQL e fai clic su Aggiorna.
What are the flights that can help me avoid evening traffic if departing from BostonPoiché la domanda sostituisce il termine
nighttime trafficcon un termine simile,evening traffic, QueryData fornisce una risposta coerente a questa domanda applicando la stessa interpretazione.La query SQL generata è simile alla seguente:
-- 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;Inserisci la seguente domanda per generare una query SQL e fai clic su Aggiorna.
Show me the flight to Houston IntercontinentalLa query SQL generata è simile alla seguente:
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'Osserva che QueryData ora può interpretare con precisione che "Houston Intercontinental" si riferisce a "George Bush Intercontinental Houston Airport" nel database.
Integra QueryData con la tua applicazione
In questa sezione creerai un agente per i dati per un'applicazione di ricerca di voli. Questo agente per i dati fornisce un'interfaccia di conversazione per le tabelle flights e airports che hai creato in precedenza. Spiega inoltre come creare e integrare questo agente per i dati nella tua applicazione utilizzando l'Agent Development Kit (ADK), lo strumento MCP QueryData di Gemini Data Analytics e un set di contesti per migliorare la qualità delle risposte.
Scarica MCP Toolbox versione 1.14.0 o successive. MCP Toolbox espone l'agente per i dati come strumento per la connessione delle applicazioni. MCP Toolbox è diverso dall'agente di context engineering installato in precedenza, che genera il contesto.
Configura le Credenziali predefinite dell'applicazione (ADC).
gcloud auth application-default login gcloud auth application-default set-quota-project PROJECT_IDTrova l'ID del set di contesti che hai creato in precedenza. Per saperne di più su come trovare l'ID del set di contesti, consulta Trova l'ID del set di contesti.
Aggiungi quanto segue alla configurazione
.context-engineering/tools.yaml(otools.yamlnella directory di lavoro) per connetterti all'agente per i dati utilizzando MCP Toolbox. Per saperne di più, consulta Origine Gemini Data Analytics e Strumento QueryData di Gemini Data Analytics.--- 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: trueSostituisci quanto segue:
PROJECT_ID: l'ID progetto Google Cloud .REGION_ID: la regione dell'istanza Spanner (ad esempious-central1).INSTANCE_ID: l'ID dell'istanza Spanner.DATABASE_ID: il nome del database a cui connettersi.CONTEXT_SET_ID: l'ID del set di contesti. Per saperne di più su come trovare l'ID del set di contesti, consulta Trova l'ID del set di contesti.
Esegui il server MCP Toolbox con il file
tools.yaml../toolbox --config PATH_TO_TOOLS_YAMLSostituisci
PATH_TO_TOOLS_YAMLcon il percorso del filetools.yamlcreato in precedenza (ad esempio,.context-engineering/tools.yamlotools.yaml).Crea un'applicazione ADK che richiama lo strumento QueryData di Gemini Data Analytics utilizzando l'SDK Python di MCP Toolbox. Per saperne di più su come utilizzare l'SDK Python di MCP Toolbox, consulta la guida rapida per Toolbox e per Python ADK, consulta la guida rapida per ADK.
- Crea una directory in cui archiviare l'applicazione, ad esempio
flight-assistant-app. Cambia la directory impostandola su
flight-assistant-app.mkdir flight-assistant-appcd flight-assistant-appEsegui questi comandi nella directory
flight-assistant-appper creare un ambiente virtuale e installare i componenti richiesti.uv inituv add google-adk toolbox-core google-genaiConfigura un agente ADK.
Crea un agente ADK.
uv run adk create my_agentSeleziona il modello
gemini-2.5-flasho uno più recente.Seleziona Google AI e inserisci la tua chiave API Gemini. Per saperne di più su come trovare la tua chiave API, consulta Utilizza le chiavi API Gemini. (In alternativa, se non hai bisogno di una prova senza costi, puoi selezionare Vertex AI, specificare un progetto Google Cloud con fatturazione abilitata e inserire
globalquando ti viene richiesta la regione Google Cloud (Enter Google Cloud region) in modo cheGOOGLE_CLOUD_LOCATION=globalsia impostato inmy_agent/.env).
Sostituisci i contenuti del file
agent.pycon il seguente codice dell'applicazione di esempio Flight Data Assistant.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]), )
- Crea una directory in cui archiviare l'applicazione, ad esempio
Per avviare l'applicazione, esegui i seguenti comandi nella directory
flight-assistant-app. Accedi al server web ADK all'indirizzohttp://127.0.0.1:8000.uv run adk web --port 8000Inserisci un testo qualsiasi, ad esempio
hello, per iniziare a interagire con l'agente.L'agente ADK risponde alle domande generali e chiama gli strumenti MCP richiesti.
Inserisci la seguente domanda relativa ai voli.
How many flights depart from the west side?Lo strumento MCP viene chiamato per rispondere a questa domanda. Tuttavia, poiché il termine
the westè ambiguo e non specifica alcun aeroporto, lo strumento MCP restituisce una domanda di disambiguazione che l'agente utilizza per creare una risposta.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?Inserisci una domanda simile a quella nel template di query generato per l'agente.
Help me find flights from San Francisco that avoid the evening rush hour.In base al contesto QueryData aggiunto in precedenza, lo strumento MCP comprende che
evening trafficsi verifica tra le 17:00 e le 19:00. Lo strumento MCP restituisce i dati associati che l'agente può utilizzare per creare la sua risposta.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:00Inserisci una domanda basata sul tipo di concetto che hai aggiunto nel contesto dell'agente QueryData.
Show me the flight to Houston IntercontinentalIn base al contesto di ricerca dei valori aggiunto in precedenza, l'agente comprende che "Houston Intercontinental" si riferisce a "George Bush Intercontinental Houston Airport" (codice aeroporto IAH) e restituisce i dati associati che l'agente utilizzerà per creare la risposta.
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.
Itera le prestazioni dell'agente
La UI web dell'ADK ti consente di esaminare la richiesta e la risposta dello strumento MCP QueryData di Gemini Data Analytics. Puoi utilizzare questa risposta per osservare le risposte dello strumento, come la query SQL generata, il set di risultati, la spiegazione dell'intent, la domanda di disambiguazione e la risposta in linguaggio naturale, per verificare la correttezza delle risposte dell'agente.
Ad esempio, per il testo di input How many flights depart from the west side? che hai inserito in precedenza, fai clic sul fumetto dell'agente. Nella scheda Evento nel
riquadro di navigazione a sinistra, espandi functionResponse per visualizzare la seguente risposta.
"{"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?"]}"
Perfeziona l'accuratezza della risposta
Puoi perfezionare continuamente l'accuratezza delle risposte dello strumento QueryData di Gemini Data Analytics aggiungendo ulteriore contesto. Utilizza l'agente di progettazione del contesto per generare il contesto, quindi carica il file del set di contesti aggiornato nell'agente per i dati flights-assistant esistente. Per saperne di più, consulta Gestisci i set di contesto in Spanner Studio. La console acquisisce immediatamente il nuovo contesto dopo il caricamento, consentendoti di migliorare l'accuratezza dell'agente senza tempi di inattività dell'applicazione.
Più agenti
Nel tuo ambiente di sviluppo, puoi eseguire test A/B su più contesti di agenti per i dati assegnando nomi distinti agli strumenti nel file tools.yaml. Ad esempio, puoi creare configurazioni tools.yaml univoche definendo due strumenti cloud-gemini-data-analytics-query con nomi diversi, ad esempio cloud_gda_query_tool_v1 e cloud_gda_query_tool_v2. Questa configurazione ti consente di implementare la logica dell'applicazione che seleziona in modo programmatico la versione del contesto richiesta scegliendo il nome dello strumento corrispondente.
L'esempio tools.yaml seguente mostra come configurare più agenti per i dati per un'origine 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: ...
Sostituisci quanto segue:
PROJECT_ID: il tuo ID progetto Google Cloud .V1_YOUR_CONTEXT_SET_ID: l'ID del set di contesto per la versione 1.V2_YOUR_CONTEXT_SET_ID: l'ID del set di contesto per la versione 2.DB_SOURCE: le configurazioni dell'origine del database.
Esegui la pulizia
Al termine di questo tutorial, elimina le risorse che hai creato per evitare l'addebito di costi ricorrenti. Le seguenti sezioni descrivono come eliminare queste risorse.
Elimina il set di contesti
Prima di eliminare l'istanza, elimina il set di contesti che hai creato.
Nella console Google Cloud , vai alla pagina Spanner.
Seleziona un'istanza dall'elenco, quindi seleziona un database.
Nel menu di navigazione, fai clic su Spanner Studio.
Nel riquadro Explorer, accanto al set di contesto, fai clic su Visualizza azioni ().
Fai clic su Elimina set di contesti.
Nella finestra Elimina set di contesti, inserisci
flights-assistant.Fai clic su Conferma.
Elimina l'istanza
Quando elimini l'istanza che hai creato nella sezione Prima di iniziare, elimini anche tutti gli oggetti che hai creato.
Nella console Google Cloud , vai alla pagina Spanner.
Fai clic sul nome dell'istanza che vuoi eliminare, ad esempio Test Instance.
Fai clic su Elimina istanza.
Conferma di voler eliminare l'istanza inserendo il nome dell'istanza e facendo clic su Elimina.
Passaggi successivi
- Scopri di più sui set di contesti.
- Scopri come definire il contesto creato per le origini dati del database.