Intégrer QueryData à une application

Ce tutoriel explique comment configurer et utiliser QueryData dans Spanner Graph à l'aide de la console Google Cloud et l'intégrer à votre application. Vous allez apprendre à configurer le graphe de propriétés FinGraph, à créer un fichier d'ensemble de contextes GQL (Graph Query Language) à l'aide de l'agent d'ingénierie contextuelle, à créer un ensemble de contextes dans Spanner Studio, à tester QueryData en appelant la méthode QueryData dans l'API Conversational Analytics avec graph_ids configuré, et à utiliser un outil HTTP personnalisé dans MCP Toolbox pour connecter une application d'agent à QueryData.

Pour en savoir plus, consultez Présentation de QueryData.

Objectifs

  • Créez le schéma de graphique de propriétés FinGraph et remplissez-le avec des exemples de données de graphique.
  • Créez un fichier d'ensemble de contextes pour FinGraph à l'aide de l'agent d'ingénierie contextuelle.
  • Créez un ensemble de contextes et importez le fichier de l'ensemble de contextes dans Spanner Studio.
  • Testez QueryData et générez des requêtes GQL en appelant l'API REST QueryData avec graph_ids spécifié dans spanner_reference.
  • Intégrez QueryData à votre application à l'aide d'un outil HTTP personnalisé dans MCP Toolbox qui appelle l'API REST QueryData.
  • Ancrez les réponses du LLM dans les données de votre graphique à l'aide de modèles de requête, de facettes de requête et de requêtes de recherche de valeurs GRAPH_TABLE.

Coûts

Dans ce document, vous utilisez les composants facturables de Google Cloudsuivants :

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût.

Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai sans frais.

Pour éviter de continuer à payer des frais, supprimez les ressources que vous avez créées lorsque vous avez terminé les tâches décrites dans ce document. Pour en savoir plus, consultez la section Effectuer un nettoyage.

Avant de commencer

Avant de créer un ensemble de contextes, assurez-vous de remplir les conditions préalables suivantes :

Activer les services requis

Activez les services suivants pour votre projet :

Préparer une instance Spanner

Rôles et autorisations nécessaires

  • Ajoutez un compte d'utilisateur ou de service IAM à l'instance. Pour en savoir plus, consultez Appliquer des rôles IAM.
  • Attribuez les rôles roles/spanner.databaseReader, roles/serviceusage.serviceUsageConsumer et roles/geminidataanalytics.queryDataUser à l'utilisateur IAM au niveau du projet. Pour en savoir plus, consultez Ajouter une liaison de stratégie IAM pour un projet.
  • Pour créer, importer et gérer des ensembles de contextes, attribuez le rôle Éditeur de catalogue Dataplex (roles/dataplex.catalogEditor) ou Administrateur de catalogue Dataplex (roles/dataplex.catalogAdmin) à l'utilisateur IAM au niveau du projet. Pour en savoir plus, consultez Autorisations des ensembles de contextes.
  • Attribuez des rôles et des autorisations à l'utilisateur IAM au niveau du projet pour les bases de données requises.

Créer le schéma FinGraph et insérer des données de graphe

Ce tutoriel utilise l'ensemble de données de graphe de propriétés financières FinGraph, qui modélise les nœuds Person et Account connectés par les arêtes Owns (PersonOwnAccount) et Transfers (AccountTransferAccount).

Pour créer le schéma FinGraph et insérer les données du graphe dans votre base de données Spanner, suivez les étapes du guide de configuration de Spanner Graph :

  1. Suivez la procédure Créer une base de données de graphes à l'aide d'un schéma pour créer les tables Person, Account, PersonOwnAccount et AccountTransferAccount, ainsi que la définition du graphe de propriétés FinGraph.
  2. Suivez les instructions de la section Insérer des données de graphe pour insérer les exemples de personnes (Alex, Dana et Lee), de comptes (7, 16 et 20), d'arêtes de propriété de compte et d'arêtes de transfert d'argent dans FinGraph.

Créer un ensemble de contextes

Créez un ensemble de contextes vide nommé fingraph-assistant. Plus loin dans ce tutoriel, vous y importerez un fichier d'ensemble de contexte.

  1. Dans la console Google Cloud , accédez à la page "Spanner".

    Accéder à Spanner

  2. Sélectionnez votre instance dans la liste, puis sélectionnez la base de données contenant FinGraph.

  3. Dans le menu de navigation, cliquez sur Spanner Studio.

  4. Dans le volet Explorateur, à côté de Ensembles de contexte, cliquez sur Afficher les actions.

  5. Cliquez sur Créer un ensemble de contextes.

  6. Dans le champ Nom de l'ensemble de contextes, saisissez fingraph-assistant.

  7. Cliquez sur Créer.

Tester QueryData sans contexte

Dans cette section, vous allez appeler l'API REST QueryData pour générer des requêtes GQL pour des questions en langage naturel sans ensemble de contexte. Sans contexte, QueryData peut répondre aux questions qui correspondent directement au schéma FinGraph, mais il ne peut pas interpréter la terminologie métier personnalisée telle que high-risk transfers ni résoudre les différences de mise en forme des valeurs telles que Czech Republic par rapport à Czech_Republic.

  1. Dans votre terminal, définissez les variables d'environnement suivantes :

    export PROJECT_ID="PROJECT_ID"
    export INSTANCE_ID="INSTANCE_ID"
    export DATABASE_ID="DATABASE_ID"
    

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • INSTANCE_ID : ID de votre instance Spanner.
    • DATABASE_ID : ID de la base de données contenant FinGraph.
  2. Créez un script d'assistance nommé query_data.sh qui envoie une question à l'API REST QueryData avec graph_ids défini sur FinGraph. Si la variable d'environnement CONTEXT_SET_ID est définie, le script envoie également l'ID de votre ensemble de contexte :

    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
    

    Le script insère votre question telle quelle dans le corps de la requête. N'utilisez donc pas de guillemets doubles (") dans la question.

  3. Posez une question qui correspond directement au schéma FinGraph :

    ./query_data.sh "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts."
    

    Dans la réponse, examinez les champs generatedQuery et queryResult. Pour cette question sans ambiguïté, QueryData génère une requête GQL semblable à celle-ci :

    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;
    

    Elle renvoie des résultats semblables aux suivants :

    +----------------+----------------------+-----------------+
    | recipient_name | recipient_account_id | transfer_amount |
    +----------------+----------------------+-----------------+
    | Alex           | 7                    | 500             |
    | Lee            | 16                   | 200             |
    +----------------+----------------------+-----------------+
    
  4. Posez une question incluant le terme métier high-risk transfers :

    ./query_data.sh "Find all high-risk transfers initiated by Alex"
    

    Étant donné que le schéma FinGraph ne définit pas ce qui constitue un high-risk transfer (qui, dans votre logique métier, signifie un transfert de 200 ou plus vers un compte bloqué où is_blocked = true), QueryData n'applique pas les filtres de compte bloqué et de seuil de montant, ou applique sa propre interprétation du terme. Par exemple, QueryData peut inventer un seuil de montant qui ne renvoie aucune ligne, ou ignorer le terme et générer une requête semblable à la suivante :

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

    Cette requête renvoie les deux transferts d'Alex, y compris le transfert de 100 qui n'atteint pas le seuil :

    +-------------------+------------------------+-----------------+-----------------+
    | source_account_id | destination_account_id | transfer_amount | order_number    |
    +-------------------+------------------------+-----------------+-----------------+
    | 7                 | 16                     | 300             | 304330008004315 |
    | 7                 | 16                     | 100             | 304120005529714 |
    +-------------------+------------------------+-----------------+-----------------+
    
  5. Posez une question qui fait référence à un pays :

    ./query_data.sh "Find accounts owned by people from Czech Republic"
    

    Sans association de contexte ou de valeur, QueryData génère une requête GQL qui filtre 'Czech Republic' avec un espace. Étant donné que la propriété Person.country de FinGraph stocke la valeur sous la forme 'Czech_Republic' avec un trait de soulignement, la requête ne renvoie aucune ligne :

    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;
    

Générer un contexte pour l'ensemble de contextes

Dans cette section, vous allez préparer votre environnement local et utiliser l'agent d'ingénierie contextuelle pour créer un fichier d'ensemble de contexte (context_set.json) pour le graphe de propriétés FinGraph dans votre base de données Spanner.

Configurer votre environnement

Pour configurer votre environnement pour l'agent d'ingénierie de contexte, procédez comme suit :

  1. Installez la CLI Antigravity. Pour en savoir plus, consultez Premiers pas avec la CLI Antigravity.
  2. Installez la Google Cloud CLI.
  3. Configurez les Identifiants par défaut de l'application (ADC). Exécutez la commande suivante dans votre terminal pour vous authentifier :

    gcloud auth application-default login
  4. Installez l'agent d'ingénierie de contexte.

  5. Dans votre terminal, démarrez la CLI Antigravity :

    agy
  6. Configurez la connexion à votre base de données Spanner. Saisissez une requête qui spécifie explicitement que vous générez du contexte pour les graphiques de propriétés de votre base de données Spanner, et inclut le nom du graphique de propriétés FinGraph afin que l'agent déclenche le workflow d'ingénierie de contexte spécifique à GQL :

    Help me set up the database connection for the FinGraph property graph in my Spanner database.
    

    Suivez les instructions fournies par l'agent pour créer autoctx/tools.yaml et autoctx/state.md. Ouvrez ensuite autoctx/state.md et vérifiez que la section ## Active Database contient la ligne - **Graph Ids**: ["FinGraph"]. L'agent d'ingénierie de contexte lit les noms des graphiques de propriétés à partir de cette ligne lorsqu'il génère des configurations d'évaluation. Pour en savoir plus sur tools.yaml, consultez la documentation de MCP Toolbox.

  7. Pour actualiser la configuration après la création de autoctx/tools.yaml, exécutez la commande suivante dans la CLI Antigravity :

    /mcp
  8. Sélectionnez toolbox, puis Restart.

  9. Vérifiez que MCP Toolbox et le plug-in de l'agent d'ingénierie de contexte sont connectés et prêts à l'emploi :

    /mcp

Générer le contexte du modèle GQL

Pour résoudre le problème où QueryData n'a pas reconnu le terme métier high-risk transfers, définissez high-risk transfers dans le fichier d'ensemble de contexte comme des transferts de 200 ou plus envoyés à un compte bloqué (dst.is_blocked = true).

Pour générer le contexte du modèle GQL, procédez comme suit :

  1. Saisissez le prompt suivant dans le harnais d'agent, en spécifiant que FinGraph est un graphe de propriétés dans votre base de données 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'agent convertit votre entrée en un modèle GQL paramétré qui généralise les noms de personnes. Pour en savoir plus, consultez Présentation des ensembles de contextes.

  3. Examinez le modèle de requête GQL généré, puis envoyez le prompt Save it to context_set.json à l'agent. L'agent crée context_set.json dans votre répertoire avec le contenu suivant :

    {
      "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 ?"
          }
        }
      ]
    }
    

Générer un contexte de recherche d'attributs et de valeurs

Dans cette section, vous allez ajouter un attribut GQL et deux requêtes de recherche de valeur GRAPH_TABLE à context_set.json. Le modèle que vous avez ajouté dans la section précédente répond aux questions qui ont la même structure que "Trouver tous les transferts à haut risque initiés par Alex". L'attribut capture le modèle de compte bloqué afin que QueryData puisse également l'appliquer aux questions qui ne correspondent pas au modèle, telles que "Rechercher tous les transferts d'argent impliquant un compte bloqué". Les recherches de valeurs permettent à QueryData de mapper des expressions de valeur telles que Czech Republic à la valeur stockée Czech_Republic sur Person.country, et de faire correspondre les pseudos de compte sur Account.nick_name, quelle que soit la casse.

  1. Saisissez le prompt suivant dans le harnais d'agent, en spécifiant que FinGraph est un graphe de propriétés dans votre base de données 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. Examinez le fichier context_set.json mis à jour, qui contient désormais le modèle GQL, l'attribut GQL et les définitions de recherche de valeurs :

    {
      "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"
        }
      ]
    }
    

    Chaque recherche de valeur utilise l'opérateur GRAPH_TABLE pour faire correspondre une étiquette de nœud dans FinGraph et renvoie la valeur de la propriété stockée, l'emplacement de la propriété (FinGraph.Person.country), le type de concept, une distance de 0 pour une correspondance et un contexte JSON vide. Pour en savoir plus, consultez Requêtes de recherche de valeurs.

Importer le fichier de l'ensemble de contexte dans QueryData

Dans cette section, vous allez importer le fichier context_set.json dans votre ensemble de contexte fingraph-assistant dans Spanner Studio.

  1. Dans la console Google Cloud , accédez à la page "Spanner".

    Accéder à Spanner

  2. Sélectionnez votre instance dans la liste, puis sélectionnez votre base de données Spanner.

  3. Dans le menu de navigation, cliquez sur Spanner Studio.

  4. Dans le volet Explorateur, à côté de votre ensemble de contexte fingraph-assistant, cliquez sur Afficher les actions.

  5. Cliquez sur Modifier l'ensemble de contextes.

  6. Facultatif : modifiez la description de l'ensemble de contextes.

  7. Cliquez sur Parcourir dans la section Importer un fichier d'ensemble de contexte, puis sélectionnez le fichier context_set.json que vous avez généré.

  8. Cliquez sur Enregistrer.

Générer des requêtes GQL à l'aide de QueryData

Dans cette section, vous allez appeler l'API REST QueryData avec votre contexte fingraph-assistant défini pour vérifier que QueryData traduit correctement les termes métier tels que high-risk transfers et résout Czech Republic en Czech_Republic dans les requêtes GQL.

  1. Recherchez l'ID de l'ensemble de contextes pour fingraph-assistant. Pour savoir comment procéder, consultez Trouver l'ID de l'ensemble de contextes.
  2. Définissez la variable d'environnement CONTEXT_SET_ID pour que query_data.sh envoie votre ensemble de contexte :

    export CONTEXT_SET_ID="CONTEXT_SET_ID"
    

    Remplacez CONTEXT_SET_ID par l'ID complet de l'ensemble de contextes, par exemple projects/my-project/locations/us-central1/contextSets/fingraph-assistant.

  3. Posez à nouveau la question sur les transferts à haut risque :

    ./query_data.sh "Find all high-risk transfers initiated by Alex"
    

    La requête GQL générée applique désormais le filtre de compte de destination bloqué (is_blocked: true) et le seuil de montant (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;
    

    Cela exclut le transfert de 100 par Alex vers le compte bloqué 16 et renvoie des résultats semblables à ceux-ci :

    +------------------------+-----------------+
    | destination_account_id | transfer_amount |
    +------------------------+-----------------+
    | 16                     | 300             |
    +------------------------+-----------------+
    
  4. Posez une question similaire pour Dana :

    ./query_data.sh "What are the high-risk transfers initiated by Dana?"
    

    Étant donné que le modèle GQL dans context_set.json est paramétré ({name: ?}), QueryData applique la même définition high-risk transfers à 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;
    

    Cela exclut le transfert de 500 par Dana vers le compte débloqué 7 et renvoie des résultats semblables à ceux-ci :

    +------------------------+-----------------+
    | destination_account_id | transfer_amount |
    +------------------------+-----------------+
    | 16                     | 200             |
    +------------------------+-----------------+
    
  5. Posez à nouveau la question sur le pays :

    ./query_data.sh "Find accounts owned by people from Czech Republic"
    

    QueryData exécute la recherche de la valeur Person country, associe Czech Republic à la valeur stockée Czech_Republic et génère une requête semblable à la suivante :

    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;
    

    Elle renvoie des résultats semblables aux suivants :

    +------------+------------+----------------+
    | owner_name | account_id | nick_name      |
    +------------+------------+----------------+
    | Dana       | 20         | Rainy Day Fund |
    +------------+------------+----------------+
    
  6. Posez une question qui utilise l'attribut "blocked-account" :

    ./query_data.sh "Find all money transfers involving a blocked account."
    

    QueryData utilise l'attribut pour faire correspondre les transferts dans les deux sens impliquant le compte bloqué 16 et renvoie quatre transferts.

Intégrer QueryData à votre application

Dans cette section, vous allez créer une application d'agent de données conversationnel pour FinGraph à l'aide d'Agent Development Kit (ADK), de MCP Toolbox et de votre ensemble de contexte fingraph-assistant. Pour activer la génération de requêtes GQL pour Spanner Graph, vous devez définir un outil HTTP personnalisé dans votre fichier tools.yaml qui appelle l'API REST QueryData avec graph_ids défini dans spanner_reference.database_reference.

  1. Téléchargez MCP Toolbox version 1.4.0 ou ultérieure. MCP Toolbox expose l'API REST QueryData en tant qu'outil MCP auquel les applications peuvent se connecter.
  2. Configurez les identifiants par défaut de l'application :

    gcloud auth application-default login
  3. Créez un fichier de configuration tools.yaml qui définit une source HTTP pour l'API Conversational Analytics et un outil HTTP qui appelle la méthode QueryData. Veillez à spécifier graph_ids (défini sur ["FinGraph"]) sous spanner_reference.database_reference dans le corps de la requête :

    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 remplace les références ${...} par les valeurs des variables d'environnement correspondantes lorsqu'il charge tools.yaml, et remplace {{json .query}} par la question que l'agent envoie à l'outil, encodée sous forme de chaîne JSON.

  4. Dans le terminal où vous exécutez MCP Toolbox, définissez les variables d'environnement référencées par 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)"
    

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • INSTANCE_ID : ID de votre instance Spanner.
    • DATABASE_ID : ID de la base de données Spanner contenant FinGraph.
    • CONTEXT_SET_ID : ID de l'ensemble de contextes complet de fingraph-assistant.
  5. Exécutez le serveur MCP Toolbox avec le fichier tools.yaml :

    ./toolbox --config "tools.yaml"
  6. Créez une application ADK qui appelle l'outil fingraph_query_data_tool à l'aide du SDK Python MCP Toolbox :

    1. Créez un répertoire pour l'application, par exemple fingraph-assistant-app, et accédez-y :

      mkdir fingraph-assistant-app
      cd fingraph-assistant-app
    2. Créez un environnement virtuel et installez les packages requis :

      python3 -m venv .venv
      source .venv/bin/activate
      pip install toolbox-core
      pip install google-genai
      pip install google-adk
    3. Créez un agent ADK :

      adk create my_agent
    4. Sélectionnez le modèle gemini-2.5-flash, sélectionnez Google AI, puis saisissez votre clé API Gemini. Pour en savoir plus, consultez Utiliser des clés API Gemini.

    5. Remplacez le contenu de my_agent/agent.py par l'exemple de code d'application Financial Graph Assistant suivant :

      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. Démarrez le serveur Web ADK sur http://127.0.0.1:8000 :

    adk web --port 8000
  8. Saisissez une question sur un graphique à plusieurs sauts dans l'UI Web ADK :

    Who did Dana transfer money to, and what were the amounts?
    

    L'agent appelle l'outil fingraph_query_data_tool, qui envoie la question à l'API REST QueryData avec graph_ids défini sur FinGraph. QueryData exécute la requête GQL générée, et l'agent renvoie une réponse semblable à celle-ci :

    Dana transferred money from account 20 to the following recipients:
    
    * Alex (account 7): 500
    * Lee (account 16): 200
    
  9. Saisissez une question qui utilise le modèle GQL high-risk transfers que vous avez ajouté à l'ensemble de contexte :

    What are the high-risk transfers initiated by Alex?
    

    En fonction du modèle GQL dans fingraph-assistant, QueryData identifie les transferts d'au moins 200 vers un compte bloqué, et l'agent renvoie une réponse semblable à celle-ci :

    Here is the high-risk transfer initiated by Alex (transfers of 200 or more to a blocked account):
    
    * Blocked destination account 16: amount 300
    

Améliorer les performances de l'agent de manière itérative

L'interface utilisateur Web d'ADK vous permet d'inspecter les charges utiles de requête et de réponse de l'outil fingraph_query_data_tool. Dans l'onglet Événement du volet de navigation, développez functionResponse pour inspecter la requête GQL FinGraph générée (generatedQuery), queryResult, intentExplanation, disambiguationQuestion et naturalLanguageAnswer. L'API REST QueryData renvoie ces noms de champs en camelCase.

Améliorer la précision des réponses

Vous pouvez affiner en continu la précision des réponses de QueryData en ajoutant des modèles GQL, des attributs et des recherches de valeurs. Utilisez l'agent d'ingénierie contextuelle pour générer et évaluer le contexte mis à jour pour le graphe de propriétés FinGraph dans votre base de données Spanner, puis importez le fichier d'ensemble de contexte mis à jour dans Spanner Studio. Pour en savoir plus, consultez Gérer les ensembles de contexte dans Spanner Studio.

Plusieurs agents

Dans votre environnement de développement, vous pouvez effectuer des tests A/B sur plusieurs ensembles de contexte Spanner Graph en définissant plusieurs outils HTTP dans votre fichier tools.yaml (par exemple, fingraph_query_data_tool_v1 et fingraph_query_data_tool_v2). Le corps de la requête de chaque outil définit graph_ids sur ["FinGraph"] et un context_set_id différent.

Effectuer un nettoyage

Pour éviter de continuer à payer des frais, supprimez les ressources que vous avez créées lorsque vous aurez terminé ce tutoriel.

Supprimer l'ensemble de contextes

Avant de supprimer la base de données ou l'instance Spanner, supprimez l'ensemble de contexte fingraph-assistant :

  1. Dans la console Google Cloud , accédez à la page "Spanner".

    Accéder à Spanner

  2. Sélectionnez votre instance dans la liste, puis sélectionnez votre base de données Spanner.

  3. Dans le menu de navigation, cliquez sur Spanner Studio.

  4. Dans le volet Explorateur, à côté de fingraph-assistant, cliquez sur Afficher les actions.

  5. Cliquez sur Supprimer l'ensemble de contextes, saisissez fingraph-assistant dans le champ de confirmation, puis cliquez sur Confirmer.

Supprimer la base de données et l'instance

Pour supprimer le graphe de propriétés FinGraph, la base de données Spanner et l'instance Spanner, suivez les étapes décrites dans Configurer et interroger Spanner Graph : Nettoyer.

Étapes suivantes