Integra QueryData en una aplicación

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 FinGraph y propagarlo con datos de grafo de muestra
  • Crea un archivo de conjunto de contexto para FinGraph con 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 QueryData con graph_ids especificado en spanner_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

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.serviceUsageConsumer y roles/geminidataanalytics.queryDataUser al 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:

  1. Sigue las instrucciones de Crea una base de datos de grafos con un esquema para crear las tablas Person, Account, PersonOwnAccount y AccountTransferAccount, y la definición del grafo de propiedades FinGraph.
  2. Sigue las instrucciones de Inserta datos de grafos para insertar las personas de muestra (Alex, Dana y Lee), las cuentas (7, 16 y 20), los bordes de propietario de la cuenta y los bordes de transferencia de dinero en FinGraph.

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.

  1. En la consola de Google Cloud , ve a la página de Spanner.

    Ir a Spanner

  2. Selecciona tu instancia de la lista y, luego, la base de datos que contiene FinGraph.

  3. En el menú de navegación, haz clic en Spanner Studio.

  4. En el panel Explorador, junto a Conjuntos de contexto, haz clic en Ver acciones.

  5. Haz clic en Crear conjunto de contextos.

  6. En el campo Nombre del conjunto de contexto, ingresa fingraph-assistant.

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

  1. 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 contiene FinGraph.
  2. Crea una secuencia de comandos auxiliar llamada query_data.sh que envíe una pregunta a la API de REST de QueryData con graph_ids establecido en FinGraph. Si se configura la variable de entorno CONTEXT_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.sh
    

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

  3. 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 generatedQuery y queryResult. 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             |
    +----------------+----------------------+-----------------+
    
  4. 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 FinGraph no define lo que constituye un high-risk transfer (que, en tu lógica empresarial, significa una transferencia de 200 o más a una cuenta bloqueada en la que is_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 100 que no cumple con el umbral:

    +-------------------+------------------------+-----------------+-----------------+
    | source_account_id | destination_account_id | transfer_amount | order_number    |
    +-------------------+------------------------+-----------------+-----------------+
    | 7                 | 16                     | 300             | 304330008004315 |
    | 7                 | 16                     | 100             | 304120005529714 |
    +-------------------+------------------------+-----------------+-----------------+
    
  5. 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 propiedad Person.country en FinGraph almacena 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:

  1. Instala la CLI de Antigravity. Para obtener más información, consulta Comienza a usar la CLI de Antigravity.
  2. Instala Google Cloud CLI.
  3. Configura las credenciales predeterminadas de la aplicación (ADC). Ejecuta el siguiente comando en la terminal para autenticarte:

    gcloud auth application-default login
  4. Instala el agente de ingeniería de contexto.

  5. En la terminal, inicia la CLI de Antigravity:

    agy
  6. Configura 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 FinGraph para 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.yaml y autoctx/state.md. Luego, abre autoctx/state.md y verifica que la sección ## Active Database contenga 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 sobre tools.yaml, consulta la documentación de MCP Toolbox.

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

    /mcp
  8. Selecciona toolbox y, luego, Restart.

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

  1. Ingresa la siguiente instrucción en el arnés del agente y especifica que FinGraph es 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;
  2. 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.

  3. Revisa la plantilla de consulta de GQL generada y, luego, envíale la instrucción Save it to context_set.json al agente. El agente crea context_set.json en 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.

  1. Ingresa la siguiente instrucción en el arnés del agente y especifica que FinGraph es 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.
    
  2. Revisa el archivo context_set.json actualizado, 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_TABLE para que coincida con una etiqueta de nodo en FinGraph y devuelve el valor de la propiedad almacenada, la ubicación de la propiedad (FinGraph.Person.country), el tipo de concepto, una distancia de 0 para 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.

  1. En la consola de Google Cloud , ve a la página de Spanner.

    Ir a Spanner

  2. Selecciona tu instancia de la lista y, luego, tu base de datos de Spanner.

  3. En el menú de navegación, haz clic en Spanner Studio.

  4. En el panel Explorador, junto al conjunto de contexto fingraph-assistant, haz clic en Ver acciones.

  5. Haz clic en Editar conjunto de contextos.

  6. Opcional: Edita la descripción del conjunto de contexto.

  7. Haz clic en Explorar en la sección Subir archivo de conjunto de contexto y selecciona el archivo context_set.json que generaste.

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

  1. 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.
  2. Configura la variable de entorno CONTEXT_SET_ID para que query_data.sh envíe tu conjunto de contexto:

    export CONTEXT_SET_ID="CONTEXT_SET_ID"
    

    Reemplaza CONTEXT_SET_ID por el ID completo del conjunto de contexto, como projects/my-project/locations/us-central1/contextSets/fingraph-assistant.

  3. 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 100 de Alex a la cuenta bloqueada 16 y devuelve resultados similares a los siguientes:

    +------------------------+-----------------+
    | destination_account_id | transfer_amount |
    +------------------------+-----------------+
    | 16                     | 300             |
    +------------------------+-----------------+
    
  4. 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.json está parametrizada ({name: ?}), QueryData aplica la misma definición de high-risk transfers a Dana:

    GRAPH FinGraph
    MATCH
      (p:Person {name: 'Dana'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true})
    WHERE
      t.amount >= 200
    RETURN
      dst.id AS destination_account_id,
      t.amount AS transfer_amount
    ORDER BY
      t.amount DESC;
    

    Esto excluye la transferencia de Dana de 500 a la cuenta desbloqueada 7 y devuelve resultados similares a los siguientes:

    +------------------------+-----------------+
    | destination_account_id | transfer_amount |
    +------------------------+-----------------+
    | 16                     | 200             |
    +------------------------+-----------------+
    
  5. 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, vincula Czech Republic con el valor almacenado Czech_Republic y 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 |
    +------------+------------+----------------+
    
  6. 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 16 y 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.

  1. Descarga la versión 1.4.0 o posterior de MCP Toolbox. MCP Toolbox expone la API de REST de QueryData como una herramienta de MCP para que las aplicaciones se conecten.
  2. Configura las credenciales predeterminadas de la aplicación (ADC):

    gcloud auth application-default login
  3. Crea un archivo de configuración tools.yaml que defina una fuente HTTP para la API de Conversational Analytics y una herramienta HTTP que llame al método QueryData. Asegúrate de especificar graph_ids (establecido en ["FinGraph"]) en spanner_reference.database_reference en 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 carga tools.yaml y reemplaza {{json .query}} por la pregunta que el agente envía a la herramienta, codificada como una cadena JSON.

  4. 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 contiene FinGraph.
    • CONTEXT_SET_ID: el ID del conjunto de contexto completo de fingraph-assistant.
  5. Ejecuta el servidor de MCP Toolbox con el archivo tools.yaml:

    ./toolbox --config "tools.yaml"
  6. Crea una aplicación del ADK que invoque la herramienta fingraph_query_data_tool con el SDK de Python de MCP Toolbox:

    1. Crea un directorio para la aplicación y cámbiate a él, como fingraph-assistant-app:

      mkdir fingraph-assistant-app
      cd fingraph-assistant-app
    2. Crea un entorno virtual y, luego, instala los paquetes necesarios:

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

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

    5. Reemplaza el contenido de my_agent/agent.py por 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]),
      )
      
  7. Inicia el servidor web del ADK en http://127.0.0.1:8000:

    adk web --port 8000
  8. Ingresa 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 de QueryData con graph_ids establecido en FinGraph. 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): 200
    
  9. Ingresa una pregunta que use la plantilla de GQL high-risk transfers que 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 menos 200 a 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:

  1. En la consola de Google Cloud , ve a la página de Spanner.

    Ir a Spanner

  2. Selecciona tu instancia de la lista y, luego, tu base de datos de Spanner.

  3. En el menú de navegación, haz clic en Spanner Studio.

  4. En el panel Explorador, junto a fingraph-assistant, haz clic en Ver acciones.

  5. Haz clic en Borrar conjunto de contexto, ingresa fingraph-assistant en 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?