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
FinGraphet 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
QueryDataavecgraph_idsspécifié dansspanner_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
- Assurez-vous qu'une instance Spanner est disponible. Pour en savoir plus, consultez la page Créer une instance.
- Assurez-vous de créer une base de données dans votre instance où vous créerez les tables. Pour en savoir plus, consultez Créer une base de données sur l'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.serviceUsageConsumeretroles/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 :
- 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,PersonOwnAccountetAccountTransferAccount, ainsi que la définition du graphe de propriétésFinGraph. - Suivez les instructions de la section Insérer des données de graphe pour insérer les exemples de personnes (
Alex,DanaetLee), de comptes (7,16et20), d'arêtes de propriété de compte et d'arêtes de transfert d'argent dansFinGraph.
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.
Dans la console Google Cloud , accédez à la page "Spanner".
Sélectionnez votre instance dans la liste, puis sélectionnez la base de données contenant
FinGraph.Dans le menu de navigation, cliquez sur Spanner Studio.
Dans le volet Explorateur, à côté de Ensembles de contexte, cliquez sur Afficher les actions.
Cliquez sur Créer un ensemble de contextes.
Dans le champ Nom de l'ensemble de contextes, saisissez
fingraph-assistant.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.
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 contenantFinGraph.
Créez un script d'assistance nommé
query_data.shqui envoie une question à l'API RESTQueryDataavecgraph_idsdéfini surFinGraph. Si la variable d'environnementCONTEXT_SET_IDest 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.shLe script insère votre question telle quelle dans le corps de la requête. N'utilisez donc pas de guillemets doubles (
") dans la question.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
generatedQueryetqueryResult. 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 | +----------------+----------------------+-----------------+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
FinGraphne définit pas ce qui constitue unhigh-risk transfer(qui, dans votre logique métier, signifie un transfert de200ou 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
100qui n'atteint pas le seuil :+-------------------+------------------------+-----------------+-----------------+ | source_account_id | destination_account_id | transfer_amount | order_number | +-------------------+------------------------+-----------------+-----------------+ | 7 | 16 | 300 | 304330008004315 | | 7 | 16 | 100 | 304120005529714 | +-------------------+------------------------+-----------------+-----------------+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.countrydeFinGraphstocke 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 :
- Installez la CLI Antigravity. Pour en savoir plus, consultez Premiers pas avec la CLI Antigravity.
- Installez la Google Cloud CLI.
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 loginDans votre terminal, démarrez la CLI Antigravity :
agyConfigurez 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
FinGraphafin 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.yamletautoctx/state.md. Ouvrez ensuiteautoctx/state.mdet vérifiez que la section## Active Databasecontient 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 surtools.yaml, consultez la documentation de MCP Toolbox.Pour actualiser la configuration après la création de
autoctx/tools.yaml, exécutez la commande suivante dans la CLI Antigravity :/mcpSélectionnez
toolbox, puisRestart.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 :
Saisissez le prompt suivant dans le harnais d'agent, en spécifiant que
FinGraphest 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;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.
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éecontext_set.jsondans 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.
Saisissez le prompt suivant dans le harnais d'agent, en spécifiant que
FinGraphest 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.Examinez le fichier
context_set.jsonmis à 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_TABLEpour faire correspondre une étiquette de nœud dansFinGraphet renvoie la valeur de la propriété stockée, l'emplacement de la propriété (FinGraph.Person.country), le type de concept, une distance de0pour 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.
Dans la console Google Cloud , accédez à la page "Spanner".
Sélectionnez votre instance dans la liste, puis sélectionnez votre base de données Spanner.
Dans le menu de navigation, cliquez sur Spanner Studio.
Dans le volet Explorateur, à côté de votre ensemble de contexte
fingraph-assistant, cliquez sur Afficher les actions.Cliquez sur Modifier l'ensemble de contextes.
Facultatif : modifiez la description de l'ensemble de contextes.
Cliquez sur Parcourir dans la section Importer un fichier d'ensemble de contexte, puis sélectionnez le fichier
context_set.jsonque vous avez généré.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.
- 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. Définissez la variable d'environnement
CONTEXT_SET_IDpour quequery_data.shenvoie votre ensemble de contexte :export CONTEXT_SET_ID="CONTEXT_SET_ID"
Remplacez
CONTEXT_SET_IDpar l'ID complet de l'ensemble de contextes, par exempleprojects/my-project/locations/us-central1/contextSets/fingraph-assistant.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
100par Alex vers le compte bloqué16et renvoie des résultats semblables à ceux-ci :+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 300 | +------------------------+-----------------+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.jsonest paramétré ({name: ?}), QueryData applique la même définitionhigh-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
500par Dana vers le compte débloqué7et renvoie des résultats semblables à ceux-ci :+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 200 | +------------------------+-----------------+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, associeCzech Republicà la valeur stockéeCzech_Republicet 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 | +------------+------------+----------------+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é
16et 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.
- Téléchargez MCP Toolbox version 1.4.0 ou ultérieure. MCP Toolbox expose l'API REST
QueryDataen tant qu'outil MCP auquel les applications peuvent se connecter. Configurez les identifiants par défaut de l'application :
gcloud auth application-default loginCréez un fichier de configuration
tools.yamlqui définit une source HTTP pour l'API Conversational Analytics et un outil HTTP qui appelle la méthodeQueryData. Veillez à spécifiergraph_ids(défini sur["FinGraph"]) sousspanner_reference.database_referencedans 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 chargetools.yaml, et remplace{{json .query}}par la question que l'agent envoie à l'outil, encodée sous forme de chaîne JSON.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 contenantFinGraph.CONTEXT_SET_ID: ID de l'ensemble de contextes complet defingraph-assistant.
Exécutez le serveur MCP Toolbox avec le fichier
tools.yaml:./toolbox --config "tools.yaml"Créez une application ADK qui appelle l'outil
fingraph_query_data_toolà l'aide du SDK Python MCP Toolbox :Créez un répertoire pour l'application, par exemple
fingraph-assistant-app, et accédez-y :mkdir fingraph-assistant-appcd fingraph-assistant-appCréez un environnement virtuel et installez les packages requis :
python3 -m venv .venvsource .venv/bin/activatepip install toolbox-corepip install google-genaipip install google-adkCréez un agent ADK :
adk create my_agentSé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.Remplacez le contenu de
my_agent/agent.pypar 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]), )
Démarrez le serveur Web ADK sur
http://127.0.0.1:8000:adk web --port 8000Saisissez 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 RESTQueryDataavecgraph_idsdéfini surFinGraph. 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): 200Saisissez une question qui utilise le modèle GQL
high-risk transfersque 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 moins200vers 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 :
Dans la console Google Cloud , accédez à la page "Spanner".
Sélectionnez votre instance dans la liste, puis sélectionnez votre base de données Spanner.
Dans le menu de navigation, cliquez sur Spanner Studio.
Dans le volet Explorateur, à côté de
fingraph-assistant, cliquez sur Afficher les actions.Cliquez sur Supprimer l'ensemble de contextes, saisissez
fingraph-assistantdans 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
- En savoir plus sur les ensembles de contexte pour Spanner Graph
- Découvrez comment créer des ensembles de contextes à l'aide de l'agent d'ingénierie contextuelle.
- Découvrez comment définir un contexte créé pour les sources de données de base de données.