Questo tutorial descrive come configurare e utilizzare QueryData in Spanner Graph utilizzando la console Google Cloud e integrarlo con la tua applicazione. Scoprirai come configurare il grafo delle proprietà FinGraph, creare un file del set di contesti Graph Query Language (GQL) utilizzando l'agente di progettazione del contesto, creare un set di contesti in Spanner Studio, testare QueryData chiamando il metodo QueryData nell'API Conversational Analytics con graph_ids configurato e utilizzare uno strumento HTTP personalizzato in MCP Toolbox per connettere un'applicazione agente a QueryData.
Per saperne di più, consulta la panoramica di QueryData.
Obiettivi
- Crea lo schema del grafo delle proprietà
FinGraphe compila i dati del grafo di esempio. - Crea un file del set di contesti per
FinGraphutilizzando l'agente di progettazione del contesto. - Crea un set di contesti e carica il file del set di contesti in Spanner Studio.
- Testa QueryData e genera query GQL chiamando l'API REST
QueryDatacongraph_idsspecificato inspanner_reference. - Integra QueryData con la tua applicazione utilizzando uno strumento HTTP personalizzato in MCP Toolbox che chiama l'API REST
QueryData. - Basare le risposte dell'LLM sui dati del grafico utilizzando modelli di query, facet di query e query di ricerca di valori
GRAPH_TABLE.
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
Prima di creare un set di contesto, completa i seguenti prerequisiti:
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 FinGraph e inserisci i dati del grafo
Questo tutorial utilizza il set di dati del grafo delle proprietà finanziarie FinGraph, che modella i nodi Person e Account collegati dagli archi Owns (PersonOwnAccount) e Transfers (AccountTransferAccount).
Per creare lo schema FinGraph e compilare i dati del grafico nel database Spanner, completa i seguenti passaggi della guida alla configurazione di Spanner Graph:
- Segui la procedura per creare un database a grafo utilizzando uno schema per creare le tabelle
Person,Account,PersonOwnAccounteAccountTransferAccounte la definizione del grafo delle proprietàFinGraph. - Segui Inserisci i dati del grafo per inserire in
FinGraphle persone (Alex,DanaeLee), gli account (7,16e20), gli archi di proprietà degli account e gli archi di trasferimento di denaro di esempio.
Crea un set di contesto
Crea un set di contesti vuoto denominato fingraph-assistant. Più avanti in questo tutorial, caricherai un file del set di contesto.
Nella console Google Cloud , vai alla pagina Spanner.
Seleziona l'istanza dall'elenco, quindi seleziona il database contenente
FinGraph.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.
Nel campo Nome set di contesti, inserisci
fingraph-assistant.Fai clic su Crea.
Testa QueryData senza contesto
In questa sezione, chiami l'API REST QueryData per generare query GQL per domande in linguaggio naturale senza un set di contesto. Senza contesto, QueryData può rispondere a domande che si mappano direttamente allo schema FinGraph, ma non può interpretare la terminologia aziendale personalizzata come high-risk transfers o risolvere le differenze di formattazione dei valori come Czech Republic rispetto a Czech_Republic.
Nel terminale, imposta le seguenti variabili di ambiente:
export PROJECT_ID="PROJECT_ID" export INSTANCE_ID="INSTANCE_ID" export DATABASE_ID="DATABASE_ID"
Sostituisci quanto segue:
PROJECT_ID: il tuo ID progetto Google Cloud .INSTANCE_ID: l'ID istanza Spanner.DATABASE_ID: l'ID del database che contieneFinGraph.
Crea uno script helper denominato
query_data.shche invia una domanda all'API RESTQueryDatacongraph_idsimpostato suFinGraph. Se la variabile di ambienteCONTEXT_SET_IDè impostata, lo script invia anche l'ID del set di contesto:cat > query_data.sh <<'EOF' #!/bin/bash # Usage: ./query_data.sh "NATURAL_LANGUAGE_QUESTION" if [[ -n "${CONTEXT_SET_ID}" ]]; then AGENT_CONTEXT=", \"agent_context_reference\": {\"context_set_id\": \"${CONTEXT_SET_ID}\"}" fi curl -sS -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: ${PROJECT_ID}" \ "https://geminidataanalytics.googleapis.com/v1beta/projects/${PROJECT_ID}/locations/global:queryData" \ -d @- <<JSON { "prompt": "$1", "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "${PROJECT_ID}", "instance_id": "${INSTANCE_ID}", "database_id": "${DATABASE_ID}", "graph_ids": ["FinGraph"] }${AGENT_CONTEXT} } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_explanation": true } } JSON EOF chmod +x query_data.shLo script inserisce la domanda nel corpo della richiesta così com'è, quindi non utilizzare virgolette doppie (
") nella domanda.Fai una domanda che corrisponda direttamente allo schema
FinGraph:./query_data.sh "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts."
Nella risposta, esamina i campi
generatedQueryequeryResult. Per questa domanda non ambigua, QueryData genera una query GQL simile alla seguente:GRAPH FinGraph MATCH (p:Person {name: 'Dana'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account), (recipient:Person)-[:Owns]->(dst) RETURN recipient.name AS recipient_name, dst.id AS recipient_account_id, t.amount AS transfer_amount;Vengono restituiti risultati simili ai seguenti:
+----------------+----------------------+-----------------+ | recipient_name | recipient_account_id | transfer_amount | +----------------+----------------------+-----------------+ | Alex | 7 | 500 | | Lee | 16 | 200 | +----------------+----------------------+-----------------+Fai una domanda che includa il termine aziendale
high-risk transfers:./query_data.sh "Find all high-risk transfers initiated by Alex"
Poiché lo schema
FinGraphnon definisce cosa costituisce unhigh-risk transfer(che nella tua logica di business significa un trasferimento di200o più a un account bloccato doveis_blocked = true), QueryData non applica i filtri per l'account bloccato e la soglia dell'importo o applica la propria interpretazione del termine. Ad esempio, QueryData potrebbe inventare una soglia di importo che non restituisce righe oppure potrebbe ignorare il termine e generare una query simile alla seguente:-- Returning transfers initiated by Alex because 'high-risk' is not defined in the schema. GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account) RETURN src.id AS source_account_id, dst.id AS destination_account_id, t.amount AS transfer_amount, t.order_number;Vengono restituiti entrambi i trasferimenti di Alex, incluso il trasferimento di
100che non soddisfa la soglia:+-------------------+------------------------+-----------------+-----------------+ | source_account_id | destination_account_id | transfer_amount | order_number | +-------------------+------------------------+-----------------+-----------------+ | 7 | 16 | 300 | 304330008004315 | | 7 | 16 | 100 | 304120005529714 | +-------------------+------------------------+-----------------+-----------------+Fai una domanda che si riferisce a un paese:
./query_data.sh "Find accounts owned by people from Czech Republic"
Senza contesto o collegamento di valori, QueryData genera una query GQL che filtra per
'Czech Republic'con uno spazio. Poiché la proprietàPerson.countryinFinGraphmemorizza il valore come'Czech_Republic'con un trattino basso, la query non restituisce righe:GRAPH FinGraph MATCH (p:Person {country: 'Czech Republic'})-[:Owns]->(a:Account) RETURN p.name AS owner_name, a.id AS account_id, a.nick_name;
Genera il contesto per il set di contesti
In questa sezione preparerai l'ambiente locale e utilizzerai l'agente di progettazione del contesto per creare un file di set di contesto (context_set.json) per il grafo delle proprietà FinGraph nel tuo database Spanner.
Configura l'ambiente
Per configurare l'ambiente per l'agente di context engineering, 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 questo comando nel terminale per eseguire l'autenticazione:
gcloud auth application-default loginNel terminale, avvia l'interfaccia a riga di comando Antigravity:
agyConfigura la connessione al database Spanner. Inserisci un prompt che specifichi esplicitamente che stai generando il contesto per i grafi delle proprietà nel tuo database Spanner e includi il nome del grafo delle proprietà
FinGraphin modo che l'agente attivi il workflow di context engineering specifico per GQL:Help me set up the database connection for the FinGraph property graph in my Spanner database.Segui le istruzioni fornite dall'agente per creare
autoctx/tools.yamleautoctx/state.md. Quindi apriautoctx/state.mde verifica che la sezione## Active Databasecontenga la riga- **Graph Ids**: ["FinGraph"]. L'agente di context engineering legge i nomi dei grafi delle proprietà da questa riga quando genera le configurazioni di valutazione. Per ulteriori informazioni sutools.yaml, consulta la documentazione di MCP Toolbox.Per ricaricare la configurazione dopo la creazione di
autoctx/tools.yaml, esegui questo comando nell'interfaccia a riga di comando di Antigravity:/mcpSeleziona
toolbox, quindiRestart.Verifica che MCP Toolbox e il plugin agenti di context engineering siano connessi e pronti per l'uso:
/mcp
Genera il contesto del template GQL
Per risolvere il problema per cui QueryData non ha riconosciuto il termine commerciale high-risk transfers, definisci high-risk transfers nel file del set di contesto come trasferimenti di 200 o più inviati a un account bloccato (dst.is_blocked = true).
Per generare il contesto del template GQL, segui questi passaggi:
Inserisci il seguente prompt nell'infrastruttura agentica, specificando che
FinGraphè un grafo di proprietà nel tuo database Spanner:For the FinGraph property graph in my Spanner database, generate a GQL template for the question: "Find all high-risk transfers initiated by Alex" with the following GQL query: GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;L'agente converte l'input in un template GQL parametrizzato che generalizza i nomi delle persone. Per saperne di più, consulta la panoramica dei set di contesti.
Esamina il modello di query GQL generato, quindi chiedi all'agente
Save it to context_set.json. L'agente creacontext_set.jsonnella tua directory con i seguenti contenuti:{ "templates": [ { "nl_query": "Find all high-risk transfers initiated by Alex", "sql": "GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "intent": "Find all high-risk transfers initiated by Alex", "manifest": "Find all high-risk transfers initiated by a given person", "parameterized": { "parameterized_sql": "GRAPH FinGraph MATCH (p:Person {name: ?})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "parameterized_intent": "Find all high-risk transfers initiated by ?" } } ] }
Genera il contesto di ricerca di facet e valori
In questa sezione, aggiungerai un facet GQL e due query di ricerca del valore GRAPH_TABLE a context_set.json. Il template aggiunto nella sezione precedente risponde a domande con la stessa struttura di "Trova tutti i trasferimenti ad alto rischio avviati da Alex". La facet acquisisce il pattern dell'account bloccato in modo che QueryData possa applicarlo anche alle domande che non corrispondono al template, ad esempio "Trova tutti i trasferimenti di denaro che coinvolgono un account bloccato". Le ricerche dei valori consentono a QueryData di mappare frasi di valore come Czech Republic al valore memorizzato Czech_Republic su Person.country e di trovare i nickname degli account su Account.nick_name indipendentemente dalle maiuscole/minuscole.
Inserisci il seguente prompt nell'infrastruttura agentica, specificando che
FinGraphè un grafo di proprietà nel tuo database Spanner:For the FinGraph property graph in my Spanner database, generate a GQL facet with the GQL clause "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})" for intent "transfers involving a blocked account". Then generate two GRAPH_TABLE value searches on FinGraph: one on Person.country that ignores case and treats underscores as spaces, with concept type "Person country", and one on Account.nick_name that ignores case, with concept type "Account nickname". Validate the value search queries against the database, and then append the facet and value searches to context_set.json.Esamina il file
context_set.jsonaggiornato, che ora contiene il modello GQL, il facet GQL e le definizioni di ricerca dei valori:{ "templates": [ { "nl_query": "Find all high-risk transfers initiated by Alex", "sql": "GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "intent": "Find all high-risk transfers initiated by Alex", "manifest": "Find all high-risk transfers initiated by a given person", "parameterized": { "parameterized_sql": "GRAPH FinGraph MATCH (p:Person {name: ?})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;", "parameterized_intent": "Find all high-risk transfers initiated by ?" } } ], "facets": [ { "sql_snippet": "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})", "intent": "transfers involving a blocked account", "manifest": "transfers involving a blocked account", "parameterized": { "parameterized_sql_snippet": "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})", "parameterized_intent": "transfers involving a blocked account" } } ], "value_searches": [ { "query": "SELECT value, columns, concept_type, distance, context FROM GRAPH_TABLE(FinGraph MATCH (p:Person) WHERE LOWER(REPLACE(p.country, '_', ' ')) = LOWER(REPLACE($value, '_', ' ')) RETURN DISTINCT p.country AS value, 'FinGraph.Person.country' AS columns, 'Person country' AS concept_type, 0 AS distance, JSON '{}' AS context)", "concept_type": "Person country", "description": "Match for country names on Person nodes in FinGraph that ignores case and treats underscores as spaces" }, { "query": "SELECT value, columns, concept_type, distance, context FROM GRAPH_TABLE(FinGraph MATCH (a:Account) WHERE LOWER(a.nick_name) = LOWER($value) RETURN DISTINCT a.nick_name AS value, 'FinGraph.Account.nick_name' AS columns, 'Account nickname' AS concept_type, 0 AS distance, JSON '{}' AS context)", "concept_type": "Account nickname", "description": "Case-insensitive match for account nicknames on Account nodes in FinGraph" } ] }Ogni ricerca di valori utilizza l'operatore
GRAPH_TABLEper trovare un'etichetta di nodo corrispondente inFinGraphe restituisce il valore della proprietà archiviata, la posizione della proprietà (FinGraph.Person.country), il tipo di concetto, una distanza di0per una corrispondenza e un contesto JSON vuoto. Per saperne di più, consulta Query di ricerca di Vault.
Carica il file del set di contesti in QueryData
In questa sezione caricherai il file context_set.json nel set di contesto fingraph-assistant in Spanner Studio.
Nella console Google Cloud , vai alla pagina Spanner.
Seleziona l'istanza dall'elenco, quindi seleziona il database Spanner.
Nel menu di navigazione, fai clic su Spanner Studio.
Nel riquadro Explorer, accanto al set di contesto
fingraph-assistant, fai clic su Visualizza azioni.Fai clic su Modifica set di contesti.
(Facoltativo) Modifica la descrizione del set di contesti.
Fai clic su Sfoglia nella sezione Carica file del set di contesto e seleziona il file
context_set.jsonche hai generato.Fai clic su Salva.
Genera query GQL utilizzando QueryData
In questa sezione, chiami l'API REST QueryData con il contesto fingraph-assistant impostato per verificare che QueryData traduca accuratamente i termini aziendali come high-risk transfers e risolva Czech Republic in Czech_Republic nelle query GQL.
- Trova l'ID del set di contesti per
fingraph-assistant. Per istruzioni, consulta Trova l'ID del set di contesti. Imposta la variabile di ambiente
CONTEXT_SET_IDin modo chequery_data.shinvii il tuo set di contesto:export CONTEXT_SET_ID="CONTEXT_SET_ID"
Sostituisci
CONTEXT_SET_IDcon l'ID del set di contesti completo, ad esempioprojects/my-project/locations/us-central1/contextSets/fingraph-assistant.Poni di nuovo la domanda sui trasferimenti ad alto rischio:
./query_data.sh "Find all high-risk transfers initiated by Alex"
La query GQL generata ora applica il filtro dell'account di destinazione bloccato (
is_blocked: true) e la soglia dell'importo (t.amount >= 200):GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;In questo modo, viene escluso il trasferimento di
100da parte di Alex all'account bloccato16e vengono restituiti risultati simili ai seguenti:+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 300 | +------------------------+-----------------+Fai una domanda simile per
Dana:./query_data.sh "What are the high-risk transfers initiated by Dana?"
Poiché il template GQL in
context_set.jsonè parametrizzato ({name: ?}), QueryData applica la stessa definizionehigh-risk transfersaDana:GRAPH FinGraph MATCH (p:Person {name: 'Dana'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;In questo modo, viene escluso il trasferimento di
500da parte di Dana all'account non bloccato7e vengono restituiti risultati simili ai seguenti:+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 200 | +------------------------+-----------------+Fai di nuovo la domanda sul paese:
./query_data.sh "Find accounts owned by people from Czech Republic"
QueryData esegue la ricerca del valore
Person country, collegaCzech Republical valore archiviatoCzech_Republice genera una query simile alla seguente:GRAPH FinGraph MATCH (p:Person {country: 'Czech_Republic'})-[:Owns]->(a:Account) RETURN p.name AS owner_name, a.id AS account_id, a.nick_name;Vengono restituiti risultati simili ai seguenti:
+------------+------------+----------------+ | owner_name | account_id | nick_name | +------------+------------+----------------+ | Dana | 20 | Rainy Day Fund | +------------+------------+----------------+Fai una domanda che utilizza l'aspetto dell'account bloccato:
./query_data.sh "Find all money transfers involving a blocked account."
QueryData utilizza l'aspetto per trovare i trasferimenti in entrambe le direzioni che coinvolgono l'account bloccato
16e restituisce quattro trasferimenti.
Integra QueryData con la tua applicazione
In questa sezione, creerai un'applicazione di agente per i dati conversazionale per FinGraph utilizzando l'Agent Development Kit (ADK), MCP Toolbox e il set di contesto fingraph-assistant. Per abilitare la generazione di query GQL per Spanner Graph, definisci uno strumento HTTP personalizzato nel file tools.yaml che chiama l'API REST QueryData con graph_ids impostato in spanner_reference.database_reference.
- Scarica MCP Toolbox versione 1.4.0 o successive. MCP Toolbox espone l'API REST
QueryDatacome strumento MCP per la connessione delle applicazioni. Configura le Credenziali predefinite dell'applicazione (ADC):
gcloud auth application-default loginCrea un file di configurazione
tools.yamlche definisca un'origine HTTP per l'API Analisi conversazionale e uno strumento HTTP che chiami il metodoQueryData. Assicurati di specificaregraph_ids(impostato su["FinGraph"]) inspanner_reference.database_referencenel corpo della richiesta:kind: source name: gda-rest-source type: http baseUrl: https://geminidataanalytics.googleapis.com timeout: 120s headers: Authorization: Bearer ${GDA_ACCESS_TOKEN} Content-Type: application/json x-goog-user-project: ${PROJECT_ID} --- kind: tool name: fingraph_query_data_tool type: http source: gda-rest-source method: POST path: /v1beta/projects/${PROJECT_ID}/locations/global:queryData description: Use this tool to send natural language questions about the FinGraph property graph to the QueryData API and receive GQL queries, query results, natural language answers, and explanations. requestBody: | { "parent": "projects/${PROJECT_ID}/locations/global", "prompt": {{json .query}}, "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "${PROJECT_ID}", "instance_id": "${INSTANCE_ID}", "database_id": "${DATABASE_ID}", "graph_ids": ["FinGraph"] }, "agent_context_reference": { "context_set_id": "${CONTEXT_SET_ID}" } } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_explanation": true, "generate_disambiguation_question": true } } bodyParams: - name: query type: string description: A natural language question about the FinGraph property graph.MCP Toolbox sostituisce i riferimenti
${...}con i valori delle variabili di ambiente corrispondenti quando caricatools.yamle sostituisce{{json .query}}con la domanda che l'agente invia allo strumento, codificata come stringa JSON.Nel terminale in cui esegui MCP Toolbox, imposta le variabili di ambiente a cui fa riferimento
tools.yaml:export PROJECT_ID="PROJECT_ID" export INSTANCE_ID="INSTANCE_ID" export DATABASE_ID="DATABASE_ID" export CONTEXT_SET_ID="CONTEXT_SET_ID" export GDA_ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
Sostituisci quanto segue:
PROJECT_ID: il tuo ID progetto Google Cloud .INSTANCE_ID: l'ID dell'istanza Spanner.DATABASE_ID: l'ID del database Spanner che contieneFinGraph.CONTEXT_SET_ID: l'ID del set di contesto completo difingraph-assistant.
Esegui il server MCP Toolbox con il file
tools.yaml:./toolbox --config "tools.yaml"Crea un'applicazione ADK che richiama lo strumento
fingraph_query_data_toolutilizzando l'SDK Python di MCP Toolbox:Crea una directory per l'applicazione, ad esempio
fingraph-assistant-app, e passa a questa directory:mkdir fingraph-assistant-appcd fingraph-assistant-appCrea un ambiente virtuale e installa i pacchetti richiesti:
python3 -m venv .venvsource .venv/bin/activatepip install toolbox-corepip install google-genaipip install google-adkCrea un agente ADK:
adk create my_agentSeleziona il modello
gemini-2.5-flash, seleziona Google AI e inserisci la tua chiave API Gemini. Per saperne di più, consulta Utilizza le chiavi API Gemini.Sostituisci i contenuti di
my_agent/agent.pycon il seguente codice dell'applicazione di esempio Financial Graph 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 factual financial graph data assistant for FinGraph. Your goal is to help users analyze account ownership, money transfers, and risk patterns by providing accurate information with a helpful, professional tone. - Always call the Query Data Tool first to answer questions about the graph data, including questions with domain-specific terms (such as "high-risk"), because the tool resolves domain definitions against the database context. Ask the user to clarify only if the tool returns a disambiguation question or fails to generate a valid query. # 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 GQL. 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 and guide the user toward 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 graph database query. Outputs: (all optional) 1. disambiguationQuestion: Clarification questions or comments where the tool needs the user's input. 2. generatedQuery: The generated GQL query for the user query. 3. intentExplanation: An explanation for why the tool produced `generatedQuery`. 4. queryResult: The result of executing `generatedQuery`. 5. naturalLanguageAnswer: The natural language answer that summarizes the `query` and `queryResult`. Usage guidance: 1. If `disambiguationQuestion` is produced, solicit the needed inputs from the user and try the tool with a new `query` that includes the clarification. 2. If `naturalLanguageAnswer` is produced, use `intentExplanation` and `generatedQuery` 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("fingraph_query_data_tool") root_agent = Agent( model="gemini-2.5-flash", name="root_agent", instruction=INSTRUCTION, tools=cast(list[ToolUnion], [mcp_tool]), )
Avvia il server web ADK all'indirizzo
http://127.0.0.1:8000:adk web --port 8000Inserisci una domanda sul grafo multi-hop nell'UI web di ADK:
Who did Dana transfer money to, and what were the amounts?L'agente chiama lo strumento
fingraph_query_data_tool, che invia la domanda all'API RESTQueryDatacongraph_idsimpostato suFinGraph. QueryData esegue la query GQL generata e l'agente restituisce una risposta simile alla seguente:Dana transferred money from account 20 to the following recipients: * Alex (account 7): 500 * Lee (account 16): 200Inserisci una domanda che utilizza il template GQL
high-risk transfersche hai aggiunto al set di contesto:What are the high-risk transfers initiated by Alex?In base al template GQL in
fingraph-assistant, QueryData identifica i trasferimenti di almeno200a un account bloccato e l'agente restituisce una risposta simile alla seguente:Here is the high-risk transfer initiated by Alex (transfers of 200 or more to a blocked account): * Blocked destination account 16: amount 300
Itera le prestazioni dell'agente
La UI web dell'ADK ti consente di ispezionare i payload di richiesta e risposta dello strumento fingraph_query_data_tool. Nella scheda Evento del riquadro di navigazione, espandi functionResponse per esaminare la query GQL FinGraph generata (generatedQuery), queryResult, intentExplanation, disambiguationQuestion e naturalLanguageAnswer. L'API REST QueryData restituisce questi nomi di campo in camelCase.
Perfeziona l'accuratezza della risposta
Puoi perfezionare continuamente l'accuratezza delle risposte di QueryData aggiungendo modelli GQL, facet e ricerche di valori. Utilizza l'agente di progettazione del contesto per generare e valutare il contesto aggiornato per il grafo delle proprietà FinGraph nel tuo database Spanner, quindi carica il file del set di contesto aggiornato in Spanner Studio. Per saperne di più, consulta Gestisci i set di contesto in Spanner Studio.
Più agenti
Nel tuo ambiente di sviluppo, puoi eseguire test A/B su più set di contesto di Spanner Graph definendo più strumenti HTTP nel file tools.yaml (ad esempio fingraph_query_data_tool_v1 e fingraph_query_data_tool_v2). Il corpo della richiesta di ogni strumento imposta graph_ids su ["FinGraph"] e un context_set_id diverso.
Esegui la pulizia
Per evitare l'addebito di ulteriori costi, elimina le risorse create al termine di questo tutorial.
Elimina il set di contesti
Prima di eliminare il database o l'istanza Spanner, elimina il set di contesti fingraph-assistant:
Nella console Google Cloud , vai alla pagina Spanner.
Seleziona l'istanza dall'elenco, quindi seleziona il database Spanner.
Nel menu di navigazione, fai clic su Spanner Studio.
Nel riquadro Explorer, accanto a
fingraph-assistant, fai clic su Visualizza azioni.Fai clic su Elimina set di contesto, inserisci
fingraph-assistantnel campo di conferma e fai clic su Conferma.
Elimina il database e l'istanza
Per eliminare il property graph FinGraph, il database Spanner e l'istanza Spanner, segui i passaggi descritti in Configura ed esegui query su Spanner Graph: esegui la pulizia.
Passaggi successivi
- Scopri di più sui set di contesto per Spanner Graph.
- Scopri come creare set di contesti utilizzando l'agente di progettazione del contesto.
- Scopri come definire il contesto creato per le origini dati del database.