En este instructivo, se describe cómo configurar y usar QueryData en Spanner Graph con la consola de Google Cloud y cómo integrarlo en tu aplicación. Aprenderás a configurar el grafo de propiedades de FinGraph, compilar un archivo de conjunto de información contextual de Graph Query Language (GQL) con el agente de ingeniería de contexto, crear un conjunto de información contextual en Spanner Studio, probar QueryData llamando al método QueryData en la API de Conversational Analytics con graph_ids configurado y usar una herramienta HTTP personalizada en MCP Toolbox para conectar una aplicación de agente a QueryData.
Para obtener más información, consulta la descripción general de QueryData.
Objetivos
- Crear el esquema del grafo de propiedades
FinGraphy propagarlo con datos de grafo de muestra - Crea un archivo de conjunto de contexto para
FinGraphcon el agente de ingeniería de contexto. - Crear un conjunto de contextos y subir el archivo del conjunto de contextos en Spanner Studio
- Prueba QueryData y genera consultas en GQL llamando a la API de REST de
QueryDatacongraph_idsespecificado enspanner_reference. - Integra QueryData en tu aplicación con una herramienta HTTP personalizada en MCP Toolbox que llame a la API de REST de
QueryData. - Fundamenta las respuestas del LLM en tus datos de grafos con plantillas de consultas, facetas de consultas y consultas de búsqueda de valores de
GRAPH_TABLE.
Costos
En este documento, usarás los siguientes componentes facturables de Google Cloud:
Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.
Es posible que los usuarios nuevos de Google Cloud cumplan con los requisitos para acceder a una prueba gratuita.
Para evitar que se te siga facturando, borra los recursos que creaste cuando termines las tareas de este documento. Para obtener más información, consulta Cómo realizar una limpieza.
Antes de comenzar
Completa los siguientes requisitos previos antes de crear un conjunto de contexto:
Habilita los servicios obligatorios
Habilita los siguientes servicios para tu proyecto:Prepara una instancia de Spanner
- Asegúrate de que haya una instancia de Spanner disponible. Para obtener más información, consulta Crea una instancia.
- Asegúrate de crear una base de datos en tu instancia en la que crearás las tablas. Para obtener más información, consulta Crea una base de datos en la instancia de Spanner.
Roles y permisos requeridos
- Agrega un usuario o una cuenta de servicio de IAM a la instancia. Para obtener más información, consulta Aplica roles de IAM.
- Otorga los roles
roles/spanner.databaseReader,roles/serviceusage.serviceUsageConsumeryroles/geminidataanalytics.queryDataUseral usuario de IAM a nivel del proyecto. Para obtener más información, consulta Agrega una vinculación de política de IAM para un proyecto. - Para crear, subir y administrar conjuntos de contexto, otorga el rol de editor de Dataplex Catalog (
roles/dataplex.catalogEditor) o de administrador de Dataplex Catalog (roles/dataplex.catalogAdmin) al usuario de IAM a nivel del proyecto. Para obtener más información, consulta El contexto establece permisos. - Otorga roles y permisos al usuario de IAM a nivel de proyecto para las bases de datos requeridas.
Crea el esquema de FinGraph y, luego, inserta datos de grafo
En este instructivo, se usa el conjunto de datos de grafos de propiedades financieras FinGraph, que modela los nodos Person y Account conectados por las aristas Owns (PersonOwnAccount) y Transfers (AccountTransferAccount).
Para crear el esquema FinGraph y propagar los datos del grafo en tu base de datos de Spanner, completa los siguientes pasos de la guía de configuración de Spanner Graph:
- Sigue las instrucciones de Crea una base de datos de grafos con un esquema para crear las tablas
Person,Account,PersonOwnAccountyAccountTransferAccount, y la definición del grafo de propiedadesFinGraph. - Sigue las instrucciones de Inserta datos de grafos para insertar las personas de muestra (
Alex,DanayLee), las cuentas (7,16y20), los bordes de propietario de la cuenta y los bordes de transferencia de dinero enFinGraph.
Crear un conjunto de contextos
Crea un conjunto de contextos vacío llamado fingraph-assistant. Más adelante en este instructivo, subirás un archivo de conjunto de contexto a él.
En la consola de Google Cloud , ve a la página de Spanner.
Selecciona tu instancia de la lista y, luego, la base de datos que contiene
FinGraph.En el menú de navegación, haz clic en Spanner Studio.
En el panel Explorador, junto a Conjuntos de contexto, haz clic en Ver acciones.
Haz clic en Crear conjunto de contextos.
En el campo Nombre del conjunto de contexto, ingresa
fingraph-assistant.Haz clic en Crear.
Prueba QueryData sin contexto
En esta sección, llamarás a la API de REST de QueryData para generar consultas de GQL para preguntas en lenguaje natural sin un conjunto de contexto. Sin contexto, QueryData puede responder preguntas que se asignan directamente al esquema FinGraph, pero no puede interpretar la terminología empresarial personalizada, como high-risk transfers, ni resolver las diferencias de formato de los valores, como Czech Republic en comparación con Czech_Republic.
En la terminal, configura las siguientes variables de entorno:
export PROJECT_ID="PROJECT_ID" export INSTANCE_ID="INSTANCE_ID" export DATABASE_ID="DATABASE_ID"
Reemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto de Google Cloud .INSTANCE_ID: Es el ID de tu instancia de Spanner.DATABASE_ID: Es el ID de la base de datos que contieneFinGraph.
Crea una secuencia de comandos auxiliar llamada
query_data.shque envíe una pregunta a la API de REST deQueryDatacongraph_idsestablecido enFinGraph. Si se configura la variable de entornoCONTEXT_SET_ID, la secuencia de comandos también envía el ID del conjunto de contexto: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.shLa secuencia de comandos inserta tu pregunta en el cuerpo de la solicitud tal como está, por lo que no debes usar comillas dobles (
") en la pregunta.Haz una pregunta que se asigne directamente al esquema
FinGraph:./query_data.sh "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts."
En la respuesta, revisa los campos
generatedQueryyqueryResult. Para esta pregunta inequívoca, QueryData genera una consulta de GQL similar a la siguiente: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;Esto devuelve resultados similares a los siguientes:
+----------------+----------------------+-----------------+ | recipient_name | recipient_account_id | transfer_amount | +----------------+----------------------+-----------------+ | Alex | 7 | 500 | | Lee | 16 | 200 | +----------------+----------------------+-----------------+Haz una pregunta que incluya el término empresarial
high-risk transfers:./query_data.sh "Find all high-risk transfers initiated by Alex"
Debido a que el esquema
FinGraphno define lo que constituye unhigh-risk transfer(que, en tu lógica empresarial, significa una transferencia de200o más a una cuenta bloqueada en la queis_blocked = true), QueryData no aplica los filtros de umbral de importe y cuenta bloqueada, o bien aplica su propia interpretación del término. Por ejemplo, QueryData podría inventar un umbral de importe que no devuelva filas o podría ignorar el término y generar una consulta similar a la siguiente:-- 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;Esto devuelve las dos transferencias de Alex, incluida la transferencia de
100que no cumple con el umbral:+-------------------+------------------------+-----------------+-----------------+ | source_account_id | destination_account_id | transfer_amount | order_number | +-------------------+------------------------+-----------------+-----------------+ | 7 | 16 | 300 | 304330008004315 | | 7 | 16 | 100 | 304120005529714 | +-------------------+------------------------+-----------------+-----------------+Haz una pregunta que haga referencia a un país:
./query_data.sh "Find accounts owned by people from Czech Republic"
Sin contexto ni vinculación de valores, QueryData genera una consulta de GQL que filtra por
'Czech Republic'con un espacio. Debido a que la propiedadPerson.countryenFinGraphalmacena el valor como'Czech_Republic'con un guion bajo, la consulta no devuelve filas: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 contexto para el conjunto de contextos
En esta sección, prepararás tu entorno local y usarás el agente de ingeniería de contexto para crear un archivo de conjunto de contexto (context_set.json) para el grafo de propiedades FinGraph en tu base de datos de Spanner.
Configura tu entorno
Para configurar tu entorno para el agente de ingeniería de contexto, sigue estos pasos:
- Instala la CLI de Antigravity. Para obtener más información, consulta Comienza a usar la CLI de Antigravity.
- Instala Google Cloud CLI.
Configura las credenciales predeterminadas de la aplicación (ADC). Ejecuta el siguiente comando en la terminal para autenticarte:
gcloud auth application-default loginEn la terminal, inicia la CLI de Antigravity:
agyConfigura la conexión de base de datos para tu base de datos de Spanner. Ingresa una instrucción que especifique de forma explícita que estás generando contexto para los grafos de propiedades en tu base de datos de Spanner y que incluya el nombre del grafo de propiedades
FinGraphpara que el agente active el flujo de trabajo de ingeniería de contexto específico de GQL:Help me set up the database connection for the FinGraph property graph in my Spanner database.Sigue las instrucciones que proporciona el agente para crear
autoctx/tools.yamlyautoctx/state.md. Luego, abreautoctx/state.mdy verifica que la sección## Active Databasecontenga la línea- **Graph Ids**: ["FinGraph"]. El agente de ingeniería de contexto lee los nombres de los grafos de propiedades de esta línea cuando genera parámetros de configuración de evaluación. Para obtener más información sobretools.yaml, consulta la documentación de MCP Toolbox.Para volver a cargar la configuración después de que se cree
autoctx/tools.yaml, ejecuta el siguiente comando en la CLI de Antigravity:/mcpSelecciona
toolboxy, luego,Restart.Verifica que MCP Toolbox y el complemento del agente de ingeniería de contexto estén conectados y listos para usarse:
/mcp
Genera el contexto de la plantilla de GQL
Para solucionar el problema en el que QueryData no reconoció el término empresarial high-risk transfers, define high-risk transfers en el archivo de conjunto de contexto como transferencias de 200 o más enviadas a una cuenta bloqueada (dst.is_blocked = true).
Para generar el contexto de la plantilla de GQL, sigue estos pasos:
Ingresa la siguiente instrucción en el arnés del agente y especifica que
FinGraphes un grafo de propiedades en tu base de datos de 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;El agente convierte tu entrada en una plantilla de GQL parametrizada que generaliza los nombres de las personas. Para obtener más información, consulta Descripción general de los conjuntos de contexto.
Revisa la plantilla de consulta de GQL generada y, luego, envíale la instrucción
Save it to context_set.jsonal agente. El agente creacontext_set.jsonen tu directorio con el siguiente contenido:{ "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 el contexto de búsqueda de facetas y valores
En esta sección, agregarás una faceta de GQL y dos consultas de búsqueda de valores de GRAPH_TABLE a context_set.json. La plantilla que agregaste en la sección anterior responde preguntas que tienen la misma estructura que "Encuentra todas las transferencias de alto riesgo iniciadas por Alex". La faceta captura el patrón de cuenta bloqueada para que QueryData también pueda aplicarlo a las preguntas que no coinciden con la plantilla, como "Encuentra todas las transferencias de dinero que involucren una cuenta bloqueada". Las búsquedas de valores permiten que QueryData asigne frases de valor, como Czech Republic, al valor almacenado Czech_Republic en Person.country y que coincida con los sobrenombres de las cuentas en Account.nick_name, independientemente de si se usan mayúsculas o minúsculas.
Ingresa la siguiente instrucción en el arnés del agente y especifica que
FinGraphes un grafo de propiedades en tu base de datos de 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.Revisa el archivo
context_set.jsonactualizado, que ahora contiene la plantilla de GQL, la faceta de GQL y las definiciones de búsqueda de valores:{ "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" } ] }Cada búsqueda de valor usa el operador
GRAPH_TABLEpara que coincida con una etiqueta de nodo enFinGraphy devuelve el valor de la propiedad almacenada, la ubicación de la propiedad (FinGraph.Person.country), el tipo de concepto, una distancia de0para una coincidencia y un contexto JSON vacío. Para obtener más información, consulta Cómo valorar las búsquedas de los usuarios.
Sube el archivo de conjunto de contexto a QueryData
En esta sección, subirás el archivo context_set.json a tu conjunto de contexto fingraph-assistant en Spanner Studio.
En la consola de Google Cloud , ve a la página de Spanner.
Selecciona tu instancia de la lista y, luego, tu base de datos de Spanner.
En el menú de navegación, haz clic en Spanner Studio.
En el panel Explorador, junto al conjunto de contexto
fingraph-assistant, haz clic en Ver acciones.Haz clic en Editar conjunto de contextos.
Opcional: Edita la descripción del conjunto de contexto.
Haz clic en Explorar en la sección Subir archivo de conjunto de contexto y selecciona el archivo
context_set.jsonque generaste.Haz clic en Guardar.
Genera consultas de GQL con QueryData
En esta sección, llamarás a la API de REST de QueryData con tu contexto de fingraph-assistant establecido para verificar que QueryData traduzca con precisión términos empresariales como high-risk transfers y resuelva Czech Republic como Czech_Republic en las consultas de GQL.
- Busca el ID del conjunto de información contextual de
fingraph-assistant. Para obtener instrucciones, consulta Cómo encontrar el ID del conjunto de contexto. Configura la variable de entorno
CONTEXT_SET_IDpara quequery_data.shenvíe tu conjunto de contexto:export CONTEXT_SET_ID="CONTEXT_SET_ID"
Reemplaza
CONTEXT_SET_IDpor el ID completo del conjunto de contexto, comoprojects/my-project/locations/us-central1/contextSets/fingraph-assistant.Vuelve a hacer la pregunta sobre las transferencias de alto riesgo:
./query_data.sh "Find all high-risk transfers initiated by Alex"
La consulta de GQL generada ahora aplica el filtro de cuenta de destino bloqueada (
is_blocked: true) y el umbral de importe (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;Esto excluye la transferencia de
100de Alex a la cuenta bloqueada16y devuelve resultados similares a los siguientes:+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 300 | +------------------------+-----------------+Haz una pregunta similar para
Dana:./query_data.sh "What are the high-risk transfers initiated by Dana?"
Debido a que la plantilla de GQL en
context_set.jsonestá parametrizada ({name: ?}), QueryData aplica la misma definición dehigh-risk transfersaDana:GRAPH FinGraph MATCH (p:Person {name: 'Dana'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;Esto excluye la transferencia de Dana de
500a la cuenta desbloqueada7y devuelve resultados similares a los siguientes:+------------------------+-----------------+ | destination_account_id | transfer_amount | +------------------------+-----------------+ | 16 | 200 | +------------------------+-----------------+Vuelve a hacer la pregunta sobre el país:
./query_data.sh "Find accounts owned by people from Czech Republic"
QueryData ejecuta la búsqueda del valor
Person country, vinculaCzech Republiccon el valor almacenadoCzech_Republicy genera una consulta similar a la siguiente: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;Esto devuelve resultados similares a los siguientes:
+------------+------------+----------------+ | owner_name | account_id | nick_name | +------------+------------+----------------+ | Dana | 20 | Rainy Day Fund | +------------+------------+----------------+Haz una pregunta que use la faceta de cuenta bloqueada:
./query_data.sh "Find all money transfers involving a blocked account."
QueryData usa la faceta para hacer coincidir las transferencias en cualquier dirección que involucren a la cuenta bloqueada
16y devuelve cuatro transferencias.
Integra QueryData en tu aplicación
En esta sección, crearás una aplicación de agente de datos conversacional para FinGraph con el Kit de desarrollo de agentes (ADK), MCP Toolbox y tu conjunto de contexto de fingraph-assistant. Para habilitar la generación de consultas de GQL para Spanner Graph, define una herramienta HTTP personalizada en tu archivo tools.yaml que llame a la API de REST de QueryData con graph_ids establecido en spanner_reference.database_reference.
- Descarga la versión 1.4.0 o posterior de MCP Toolbox. MCP Toolbox expone la API de REST de
QueryDatacomo una herramienta de MCP para que las aplicaciones se conecten. Configura las credenciales predeterminadas de la aplicación (ADC):
gcloud auth application-default loginCrea un archivo de configuración
tools.yamlque defina una fuente HTTP para la API de Conversational Analytics y una herramienta HTTP que llame al métodoQueryData. Asegúrate de especificargraph_ids(establecido en["FinGraph"]) enspanner_reference.database_referenceen el cuerpo de la solicitud: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 reemplaza las referencias
${...}por los valores de las variables de entorno correspondientes cuando cargatools.yamly reemplaza{{json .query}}por la pregunta que el agente envía a la herramienta, codificada como una cadena JSON.En la terminal en la que ejecutas MCP Toolbox, establece las variables de entorno a las que hace referencia
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)"
Reemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto de Google Cloud .INSTANCE_ID: Es el ID de tu instancia de Spanner.DATABASE_ID: Es el ID de la base de datos de Spanner que contieneFinGraph.CONTEXT_SET_ID: el ID del conjunto de contexto completo defingraph-assistant.
Ejecuta el servidor de MCP Toolbox con el archivo
tools.yaml:./toolbox --config "tools.yaml"Crea una aplicación del ADK que invoque la herramienta
fingraph_query_data_toolcon el SDK de Python de MCP Toolbox:Crea un directorio para la aplicación y cámbiate a él, como
fingraph-assistant-app:mkdir fingraph-assistant-appcd fingraph-assistant-appCrea un entorno virtual y, luego, instala los paquetes necesarios:
python3 -m venv .venvsource .venv/bin/activatepip install toolbox-corepip install google-genaipip install google-adkCrea un agente del ADK:
adk create my_agentSelecciona el modelo
gemini-2.5-flash, elige Google AI y, luego, ingresa tu clave de API de Gemini. Para obtener más información, consulta Usa claves de API de Gemini.Reemplaza el contenido de
my_agent/agent.pypor el siguiente código de la aplicación de ejemplo de 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]), )
Inicia el servidor web del ADK en
http://127.0.0.1:8000:adk web --port 8000Ingresa una pregunta de grafo de varios saltos en la IU web del ADK:
Who did Dana transfer money to, and what were the amounts?El agente llama a la herramienta
fingraph_query_data_tool, que envía la pregunta a la API de REST deQueryDatacongraph_idsestablecido enFinGraph. QueryData ejecuta la consulta de GQL generada y el agente devuelve una respuesta similar a la siguiente:Dana transferred money from account 20 to the following recipients: * Alex (account 7): 500 * Lee (account 16): 200Ingresa una pregunta que use la plantilla de GQL
high-risk transfersque agregaste al conjunto de contexto:What are the high-risk transfers initiated by Alex?Según la plantilla de GQL en
fingraph-assistant, QueryData identifica las transferencias de al menos200a una cuenta bloqueada, y el agente devuelve una respuesta similar a la siguiente: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 el rendimiento del agente
La IU web del ADK te permite inspeccionar las cargas útiles de solicitud y respuesta de la herramienta fingraph_query_data_tool. En la pestaña Evento del panel de navegación, expande functionResponse para inspeccionar la consulta de GQL FinGraph generada (generatedQuery), queryResult, intentExplanation, disambiguationQuestion y naturalLanguageAnswer. La API de REST de QueryData devuelve estos nombres de campo en formato de mayúsculas mediales.
Define mejor la precisión de las respuestas
Puedes definir mejor de forma continua la exactitud de las respuestas de QueryData agregando plantillas de GQL, facetas y búsquedas de valores. Usa el agente de ingeniería de contexto para generar y evaluar el contexto actualizado del grafo de propiedades FinGraph en tu base de datos de Spanner y, luego, sube el archivo de conjunto de contexto actualizado en Spanner Studio. Para obtener más información, consulta Administra conjuntos de contexto en Spanner Studio.
Varios agentes
En tu entorno de desarrollo, puedes realizar pruebas A/B en varios conjuntos de contexto de Spanner Graph definiendo varias herramientas HTTP en tu archivo tools.yaml (como fingraph_query_data_tool_v1 y fingraph_query_data_tool_v2). El cuerpo de la solicitud de cada herramienta establece graph_ids en ["FinGraph"] y un context_set_id diferente.
Realiza una limpieza
Para evitar que se te siga facturando, borra los recursos que creaste cuando termines este instructivo.
Borra el conjunto de contextos
Antes de borrar la base de datos o la instancia de Spanner, borra el conjunto de contextos fingraph-assistant:
En la consola de Google Cloud , ve a la página de Spanner.
Selecciona tu instancia de la lista y, luego, tu base de datos de Spanner.
En el menú de navegación, haz clic en Spanner Studio.
En el panel Explorador, junto a
fingraph-assistant, haz clic en Ver acciones.Haz clic en Borrar conjunto de contexto, ingresa
fingraph-assistanten el campo de confirmación y haz clic en Confirmar.
Borra la base de datos y la instancia
Para borrar el grafo de propiedades FinGraph, la base de datos de Spanner y la instancia de Spanner, sigue los pasos que se indican en Configura y consulta Spanner Graph: Limpieza.
¿Qué sigue?
- Obtén más información sobre los conjuntos de contexto para Spanner Graph.
- Obtén más información para crear conjuntos de información contextual con el agente de ingeniería de contexto.
- Obtén más información para definir el contexto creado para las fuentes de datos de la base de datos.