Integra QueryData con un'applicazione

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à FinGraph e compila i dati del grafo di esempio.
  • Crea un file del set di contesti per FinGraph utilizzando 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 QueryData con graph_ids specificato in spanner_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

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.serviceUsageConsumer e roles/geminidataanalytics.queryDataUser all'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:

  1. Segui la procedura per creare un database a grafo utilizzando uno schema per creare le tabelle Person, Account, PersonOwnAccount e AccountTransferAccount e la definizione del grafo delle proprietà FinGraph.
  2. Segui Inserisci i dati del grafo per inserire in FinGraph le persone (Alex, Dana e Lee), gli account (7, 16 e 20), 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.

  1. Nella console Google Cloud , vai alla pagina Spanner.

    Vai a Spanner

  2. Seleziona l'istanza dall'elenco, quindi seleziona il database contenente FinGraph.

  3. Nel menu di navigazione, fai clic su Spanner Studio.

  4. Nel riquadro Explorer, accanto a Set di contesto, fai clic su Visualizza azioni.

  5. Fai clic su Crea set di contesti.

  6. Nel campo Nome set di contesti, inserisci fingraph-assistant.

  7. 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.

  1. 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 contiene FinGraph.
  2. Crea uno script helper denominato query_data.sh che invia una domanda all'API REST QueryData con graph_ids impostato su FinGraph. Se la variabile di ambiente CONTEXT_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.sh
    

    Lo script inserisce la domanda nel corpo della richiesta così com'è, quindi non utilizzare virgolette doppie (") nella domanda.

  3. 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 generatedQuery e queryResult. 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             |
    +----------------+----------------------+-----------------+
    
  4. 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 FinGraph non definisce cosa costituisce un high-risk transfer (che nella tua logica di business significa un trasferimento di 200 o più a un account bloccato dove is_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 100 che non soddisfa la soglia:

    +-------------------+------------------------+-----------------+-----------------+
    | source_account_id | destination_account_id | transfer_amount | order_number    |
    +-------------------+------------------------+-----------------+-----------------+
    | 7                 | 16                     | 300             | 304330008004315 |
    | 7                 | 16                     | 100             | 304120005529714 |
    +-------------------+------------------------+-----------------+-----------------+
    
  5. 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.country in FinGraph memorizza 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:

  1. Installa Antigravity CLI. Per saperne di più, consulta Inizia a utilizzare Antigravity CLI.
  2. Installa Google Cloud CLI.
  3. Configura le Credenziali predefinite dell'applicazione (ADC). Esegui questo comando nel terminale per eseguire l'autenticazione:

    gcloud auth application-default login
  4. Installa l'agente di progettazione del contesto.

  5. Nel terminale, avvia l'interfaccia a riga di comando Antigravity:

    agy
  6. Configura 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à FinGraph in 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.yaml e autoctx/state.md. Quindi apri autoctx/state.md e verifica che la sezione ## Active Database contenga 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 su tools.yaml, consulta la documentazione di MCP Toolbox.

  7. Per ricaricare la configurazione dopo la creazione di autoctx/tools.yaml, esegui questo comando nell'interfaccia a riga di comando di Antigravity:

    /mcp
  8. Seleziona toolbox, quindi Restart.

  9. 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:

  1. 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;
  2. 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.

  3. Esamina il modello di query GQL generato, quindi chiedi all'agente Save it to context_set.json. L'agente crea context_set.json nella 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.

  1. 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.
    
  2. Esamina il file context_set.json aggiornato, 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_TABLE per trovare un'etichetta di nodo corrispondente in FinGraph e restituisce il valore della proprietà archiviata, la posizione della proprietà (FinGraph.Person.country), il tipo di concetto, una distanza di 0 per 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.

  1. Nella console Google Cloud , vai alla pagina Spanner.

    Vai a Spanner

  2. Seleziona l'istanza dall'elenco, quindi seleziona il database Spanner.

  3. Nel menu di navigazione, fai clic su Spanner Studio.

  4. Nel riquadro Explorer, accanto al set di contesto fingraph-assistant, fai clic su Visualizza azioni.

  5. Fai clic su Modifica set di contesti.

  6. (Facoltativo) Modifica la descrizione del set di contesti.

  7. Fai clic su Sfoglia nella sezione Carica file del set di contesto e seleziona il file context_set.json che hai generato.

  8. 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.

  1. Trova l'ID del set di contesti per fingraph-assistant. Per istruzioni, consulta Trova l'ID del set di contesti.
  2. Imposta la variabile di ambiente CONTEXT_SET_ID in modo che query_data.sh invii il tuo set di contesto:

    export CONTEXT_SET_ID="CONTEXT_SET_ID"
    

    Sostituisci CONTEXT_SET_ID con l'ID del set di contesti completo, ad esempio projects/my-project/locations/us-central1/contextSets/fingraph-assistant.

  3. 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 100 da parte di Alex all'account bloccato 16 e vengono restituiti risultati simili ai seguenti:

    +------------------------+-----------------+
    | destination_account_id | transfer_amount |
    +------------------------+-----------------+
    | 16                     | 300             |
    +------------------------+-----------------+
    
  4. 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 definizione high-risk transfers a Dana:

    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 500 da parte di Dana all'account non bloccato 7 e vengono restituiti risultati simili ai seguenti:

    +------------------------+-----------------+
    | destination_account_id | transfer_amount |
    +------------------------+-----------------+
    | 16                     | 200             |
    +------------------------+-----------------+
    
  5. 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, collega Czech Republic al valore archiviato Czech_Republic e 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 |
    +------------+------------+----------------+
    
  6. 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 16 e 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.

  1. Scarica MCP Toolbox versione 1.4.0 o successive. MCP Toolbox espone l'API REST QueryData come strumento MCP per la connessione delle applicazioni.
  2. Configura le Credenziali predefinite dell'applicazione (ADC):

    gcloud auth application-default login
  3. Crea un file di configurazione tools.yaml che definisca un'origine HTTP per l'API Analisi conversazionale e uno strumento HTTP che chiami il metodo QueryData. Assicurati di specificare graph_ids (impostato su ["FinGraph"]) in spanner_reference.database_reference nel 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 carica tools.yaml e sostituisce {{json .query}} con la domanda che l'agente invia allo strumento, codificata come stringa JSON.

  4. 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 contiene FinGraph.
    • CONTEXT_SET_ID: l'ID del set di contesto completo di fingraph-assistant.
  5. Esegui il server MCP Toolbox con il file tools.yaml:

    ./toolbox --config "tools.yaml"
  6. Crea un'applicazione ADK che richiama lo strumento fingraph_query_data_tool utilizzando l'SDK Python di MCP Toolbox:

    1. Crea una directory per l'applicazione, ad esempio fingraph-assistant-app, e passa a questa directory:

      mkdir fingraph-assistant-app
      cd fingraph-assistant-app
    2. Crea un ambiente virtuale e installa i pacchetti richiesti:

      python3 -m venv .venv
      source .venv/bin/activate
      pip install toolbox-core
      pip install google-genai
      pip install google-adk
    3. Crea un agente ADK:

      adk create my_agent
    4. Seleziona 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.

    5. Sostituisci i contenuti di my_agent/agent.py con 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]),
      )
      
  7. Avvia il server web ADK all'indirizzo http://127.0.0.1:8000:

    adk web --port 8000
  8. Inserisci 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 REST QueryData con graph_ids impostato su FinGraph. 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): 200
    
  9. Inserisci una domanda che utilizza il template GQL high-risk transfers che 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 almeno 200 a 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:

  1. Nella console Google Cloud , vai alla pagina Spanner.

    Vai a Spanner

  2. Seleziona l'istanza dall'elenco, quindi seleziona il database Spanner.

  3. Nel menu di navigazione, fai clic su Spanner Studio.

  4. Nel riquadro Explorer, accanto a fingraph-assistant, fai clic su Visualizza azioni.

  5. Fai clic su Elimina set di contesto, inserisci fingraph-assistant nel 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