Integra QueryData en una aplicación

En este instructivo, se describe cómo configurar y usar QueryData en Cloud SQL para PostgreSQL con la consola de Google Cloud y cómo integrarlo en tu aplicación. Aprende a compilar el archivo de conjunto de contexto, crear un conjunto de contexto que use el archivo de conjunto de contexto, usar MCP Toolbox para llamar a la API de QueryData y generar consultas en SQL para preguntas en lenguaje natural, y, luego, integrar todo esto en tu aplicación.

Para obtener más información, consulta la descripción general de QueryData.

Objetivos

  • Crear tablas de bases de datos y propagarlas con datos
  • Crea un archivo de conjunto de contexto con Gemini CLI y MCP Toolbox.
  • Crea un conjunto de contextos y sube el archivo correspondiente.
  • Probar QueryData y generar consultas en SQL en Studio
  • Integra QueryData en tu aplicación con la herramienta Gemini Data Analytics QueryData en MCP Toolbox.
  • Agregar fundamentación a las respuestas del LLM con búsquedas de valores

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 la facturación continua, 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 Cloud SQL

Asegúrate de tener acceso a una instancia de Cloud SQL existente o crea una nueva. Para obtener más información, consulta Crea instancias para Cloud SQL.

En este instructivo, se requiere que tengas una base de datos en tu instancia de Cloud SQL. Para obtener más información, consulta Crea una base de datos en la instancia de Cloud SQL.

Roles y permisos requeridos

Otorga permiso executesql a la instancia de Cloud SQL

Para otorgar el permiso executesql a la instancia de Cloud SQL y habilitar la API de Cloud SQL Data, ejecuta el siguiente comando: 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
Reemplaza lo siguiente:
  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
  • INSTANCE_ID: Es el ID de tu instancia de Cloud SQL.
Para seguir los pasos de este instructivo, accede a Google Cloud y, luego, autentícate en la base de datos con la autenticación de IAM.

Crea el esquema y las tablas flights y airports

En esta sección, crearás las tablas de la base de datos flights y airports para este instructivo.

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

    Ir a Cloud SQL

  2. Elige una instancia de la lista.

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

  4. Accede a Studio con la autenticación de Identity and Access Management.

  5. Haz clic en Autenticar. En el panel Explorador, se muestra una lista de los objetos de tu base de datos.

  6. Haz clic en Nueva pestaña del editor de SQL o Nueva pestaña para abrir una pestaña nueva.

  7. Para crear la tabla y el esquema airports, ejecuta la siguiente instrucción de SQL:

    CREATE TABLE IF NOT EXISTS airports (
  id INT PRIMARY KEY,
  iata TEXT,
  name TEXT,
  city TEXT,
  country TEXT
  );

  8. Crea la tabla y el esquema flights:

    CREATE TABLE IF NOT EXISTS flights (
  id INT PRIMARY KEY,
  airline VARCHAR(10),
  flight_number INT,
  departure_airport VARCHAR(5),
  arrival_airport VARCHAR(5),
  departure_time TIMESTAMP,
  arrival_time TIMESTAMP,
  departure_gate VARCHAR(10),
  arrival_gate VARCHAR(10)
);

Completa las tablas flights y airports

En esta sección, completarás las tablas flights y airports con las secuencias de comandos de SQL proporcionadas.

  1. Propaga la tabla airports.

  2. Propaga la tabla flights.

  3. Ejecuta la siguiente consulta para verificar que las tablas se hayan completado:

    SELECT * FROM "public"."flights" LIMIT 10;
SELECT * FROM "public"."airports" LIMIT 10;

Crea un conjunto de información contextual en Studio

En esta sección, crea un conjunto de contextos llamado flights-assistant. Este conjunto de contexto no incluye ningún archivo de conjunto de contexto subido a él.

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

    Ir a Cloud SQL

  2. Elige una instancia de la lista.

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

  4. Accede a Studio con la autenticación de IAM.

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

  6. Haz clic en Crear conjunto de contexto.

  7. En Nombre del conjunto de contextos, ingresa flights-assistant.

  8. Haz clic en Crear.

Cómo probar QueryData en Studio

En esta sección, usarás el contexto flights-assistant establecido haciendo preguntas en lenguaje natural para generar una consulta en SQL. Dado que el conjunto de contexto no tiene ningún archivo de conjunto de contexto subido, incluso después de hacer una pregunta con contexto, como nighttime traffic, QueryData genera una consulta subóptima.

  1. En el panel Explorador, junto a tu conjunto de contexto, haz clic en Ver acciones.
  2. Haz clic en Probar conjunto de contextos.
  3. En el editor de consultas, haz clic en Generar SQL con QueryData con: flights-assistant.

  4. Ingresa la siguiente pregunta en lenguaje natural para generar una consulta en SQL y haz clic en Generar.

    Find flights from SFO to JFK.

    Revisa la consulta en SQL. Observa que QueryData genera el código SQL correcto para esta pregunta inequívoca.

      SELECT
    *
  FROM
    "flights"
  WHERE
    "departure_airport" = 'SFO' AND "arrival_airport" = 'JFK';

  5. En la ventana Generar SQL con QueryData con: flights-assistant, haz clic en Editar.

  6. Ingresa la siguiente pregunta en lenguaje natural para generar una consulta en SQL y haz clic en Actualizar.

    Tell me flights that can help me beat nighttime traffic if traveling from New York

    La base de datos no comprende el término tráfico de nighttime. Esto podría impedir que genere una consulta en SQL o hacer que genere una consulta que ignore el término, como se muestra en la siguiente consulta.

    -- The database schema does not contain information about traffic.
-- Returning all flights departing from New York airports.
SELECT
  f.airline,
  f.flight_number,
  a.name AS departure_airport_name,
  f.departure_time,
  b.name AS arrival_airport_name,
  f.arrival_time
FROM
  flights AS f
JOIN
  airports AS a
  ON f.departure_airport = a.iata
JOIN
  airports AS b
  ON f.arrival_airport = b.iata
WHERE
  a.city = 'New York'
ORDER BY
  f.departure_time;

  7. En la ventana Generar SQL con QueryData con: flights-assistant, haz clic en Editar.

  8. Ingresa la siguiente pregunta en lenguaje natural para generar una consulta en SQL y haz clic en Actualizar.

    flight to disney world

    La lógica del conjunto de contexto genera una búsqueda para encontrar un aeropuerto con "disney world" en su nombre. Como no existe tal aeropuerto o ciudad en la base de datos, la consulta no devolverá ninguna fila.

    SELECT
  "flights"."id",
  "flights"."airline",
  "flights"."flight_number",
  "flights"."departure_airport",
  "flights"."arrival_airport",
  "flights"."departure_time",
  "flights"."arrival_time",
  "flights"."departure_gate",
  "flights"."arrival_gate"
FROM
  "flights"
INNER JOIN
  "airports" ON "flights"."arrival_airport" = "airports"."iata"
WHERE
  "airports"."name" ILIKE '%Disney World%';

Genera contexto para el conjunto de contextos

En esta sección, crearás un archivo de contexto que ayudará a mejorar las capacidades de consulta del conjunto de contexto.

Configura tu entorno

Antes de comenzar a generar contexto, debes preparar tu entorno.

Para configurar tu entorno, sigue estos pasos:

  1. Instala Gemini CLI. Para obtener más información, consulta la guía de inicio rápido de Gemini CLI.
  2. Instala la CLI de gcloud.

  3. Configura las credenciales predeterminadas de la aplicación (ADC). Ejecuta los siguientes comandos en tu terminal para autenticar y seleccionar tu proyecto:

    gcloud auth application-default login

  4. Instala la extensión DB Context Enrichment, que incluye flujos de trabajo para la generación de contexto.

    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

    Asegúrate de que la versión sea 0.4.2 o superior. Para actualizar la extensión DB Context Enrichment, ejecuta el siguiente comando:

    gemini extensions update mcp-db-context-enrichment

  5. Para actualizar la extensión DB Context Enrichment o reemplazar el GEMINI_API_KEY, ejecuta el siguiente comando:

    gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

    Reemplaza GEMINI_API_KEY por tu clave de la API de Gemini.

  6. En la terminal, inicia Gemini CLI.

    gemini

  7. Completa la Configuración de autenticación de Gemini CLI.

  8. Configura la conexión de la base de datos. La extensión requiere una conexión a la base de datos para la generación de contexto, que es compatible con MCP Toolbox y se define en el archivo de configuración tools.yaml.

    Para crear el archivo de configuración tools.yaml en tu directorio actual, ingresa una instrucción como Help me set up the database connection y sigue las instrucciones que proporciona la habilidad. Para obtener más información sobre el archivo tools.yaml, consulta la documentación de MCP Toolbox.

  9. Para volver a cargar la configuración después de crear el archivo tools.yaml, ejecuta el siguiente comando en Gemini CLI:

    /mcp reload

  10. Verifica que la caja de herramientas de MCP y la extensión de enriquecimiento de la base de datos estén conectadas y listas para usarse.

    /mcp list

Genera el contexto de la plantilla

En esta sección, para abordar el problema de la sección anterior en la que QueryData no reconoció el término nighttime traffic, define el término en el archivo de conjunto de contexto como tráfico que ocurre entre 5:00 PM y 7:00 PM.

Para generar el contexto de la plantilla, sigue estos pasos:

  1. Ejecuta el comando /generate_targeted_templates y sigue el flujo de trabajo:

    /generate_targeted_templates

  2. En la terminal, proporciona la consulta en lenguaje natural que deseas agregar a la plantilla de consulta.

    Tell me flights that can help me beat nighttime traffic if traveling from New York

  3. Proporciona una consulta en SQL correspondiente que quieras agregar a la plantilla de consulta. Esta plantilla de consulta define el término nighttime como un término que ocurre entre 5:00 PM y 7:00 PM.

    SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a
  ON f.departure_airport = a.iata
WHERE
  a.city = 'New York'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

  4. Presiona Intro. Gemini convierte tu entrada en un formato específico que mejora el rendimiento del conjunto de contexto en una amplia variedad de consultas de los usuarios. Para obtener más información, consulta la Descripción general de los conjuntos de contexto.

  5. Revisa la plantilla de búsqueda generada. Puedes guardar la plantilla de consulta como un nuevo archivo de contexto del agente o agregarla a un archivo de contexto del agente existente.

  6. Selecciona la opción para crear un archivo de contexto del agente nuevo. Gemini crea un nombre de archivo INSTANCE_ID_DATABASE_ID_context_set_TIMESTAMP.json en el mismo directorio, con el siguiente contenido:

    {
  "templates": [
    {
      "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
      "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
      "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
      "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city",
      "parameterized": {
        "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = ? AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
        "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from ?"
      }
    }
  ]
}

Genera el contexto de búsqueda de valores

En esta sección, generarás un contexto de búsqueda de valores para ayudar a la lógica del conjunto de contexto a asignar frases de valor a valores específicos almacenados en las columnas de tu base de datos. Por ejemplo, si un usuario busca "Vuelos a Disney World", la búsqueda por valor puede asignar esto a Disney World en la ciudad de "Orlando" según el tipo de concepto que se correlaciona con la columna airports.city de tu base de datos.

Para generar el contexto de búsqueda de valores, sigue estos pasos:

  1. Ejecuta el comando /generate_targeted_value_searches:

    /generate_targeted_value_searches

  2. Ingresa postgresql para seleccionar Cloud SQL como el motor de base de datos.

  3. Ingresa la configuración de búsqueda de valores de la siguiente manera:

    Table: airports
Column: city
Concept: Airport City
Match Function: SEMANTIC_SIMILARITY_MATCH

  4. Confirma si deseas generar la definición de búsqueda de valores.

  5. Revisa la definición de búsqueda de valores generada. Puedes guardar la definición de búsqueda de valores como un nuevo archivo de conjunto de contexto o agregarla a un archivo de conjunto de contexto existente.

  6. Selecciona la opción para agregar a un archivo de conjunto de información contextual existente. Esto agrega la definición de búsqueda de valores al archivo de contexto creado en la sección anterior.

  7. Ingresa la instancia de base de datos y el nombre de la base de datos para los que se generó el archivo de conjunto de contexto.

    El archivo de contexto existente se actualiza con la definición de búsqueda de valores. Gemini crea un nombre de archivo INSTANCE_ID_DATABASE_ID_context_set_TIMESTAMP.json en el mismo directorio, con el siguiente contenido:

      {
    "templates": [
      {
        "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
        "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
        "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
        "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city",
        "parameterized": {
          "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = $1 AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
          "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from $1"
        }
      }
    ],
    "value_searches": [
      {
          "query": "/* Requires extensions: vector, google_ml_integration */ WITH SemanticMetrics AS (    SELECT T.city AS original_value, (        (google_ml.embedding('gemini-embedding-001', $value)::vector <=>          google_ml.embedding('gemini-embedding-001', T.city)::vector) / 2.0    ) AS normalized_dist     FROM airports T     WHERE T.city IS NOT NULL) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, ''::text AS context FROM SemanticMetrics",
          "concept_type": "Airport City",
          "description": "Semantic search for airport city name"
      }
  ]
  }

Sube el archivo de conjunto de contexto a QueryData

En esta sección, subirás el archivo de conjunto de contexto a QueryData para que mejore las capacidades de generación de SQL de QueryData en tu base de datos.

Para subir el contexto, sigue estos pasos:

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

    Ir a Cloud SQL

  2. Elige una instancia de la lista.

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

  4. Accede a Studio con la autenticación de Identity and Access Management.

  5. En el panel Explorador, junto a Conjuntos de contexto, haz clic en el ícono de Acciones ().

  6. Haz clic en Editar conjunto de contexto.

  7. Opcional: Edita la Descripción del conjunto de contexto.

  8. Haz clic en Explorar en la sección Subir archivo de conjunto de contexto y selecciona el archivo de conjunto de contexto que se generó anteriormente.

  9. Haz clic en Guardar.

Genera una consulta en SQL con QueryData

En esta sección, usarás el archivo de conjunto de contexto que subiste para hacer preguntas en lenguaje natural. Esto te permite verificar que QueryData comprenda y aplique correctamente las definiciones de términos como nighttime traffic y otras frases relacionadas, y que la búsqueda de valores asigne frases de valor a valores específicos almacenados en las columnas de tu base de datos (por ejemplo, asignar "Disney World" a "Orlando").

Para generar consultas en SQL, sigue estos pasos:

  1. En el panel Explorador, junto a tu conjunto de contexto, haz clic en Ver acciones.
  2. Haz clic en Probar conjunto de contextos.
  3. En el editor de consultas, haz clic en Generar SQL con QueryData con: asistente de vuelos.

  4. Ingresa la siguiente pregunta en lenguaje natural para generar una consulta en SQL y haz clic en Generar.

    Tell me flights that can help me beat nighttime traffic if traveling from New York

    La consulta en SQL generada es similar a la siguiente:

    SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a ON f.departure_airport = a.iata
WHERE
  a.city = 'New York'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

    Esta es la misma pregunta que agregaste al contexto de QueryData. Observa que QueryData ahora puede interpretar con precisión el término nighttime traffic.

    Si bien el contexto se origina en una pregunta en particular, QueryData lo usa para mejorar la generación de SQL para una amplia variedad de preguntas similares.

  5. En la ventana Generar SQL con QueryData con: flights-assistant, haz clic en Editar.

  6. Ingresa la siguiente pregunta similar para generar una consulta en SQL y haz clic en Actualizar.

    What are the flights that can help me avoid evening traffic if departing from Boston

    Dado que la pregunta reemplaza el término nighttime traffic por un término similar, evening traffic, QueryData proporciona una respuesta coherente a esta pregunta aplicando la misma interpretación.

    La consulta en SQL generada es similar a la siguiente:

    -- What are the flights that can help me avoid evening traffic if departing from Boston
SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a
ON
  f.departure_airport = a.iata
WHERE
  a.city = 'Boston'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

  7. En la ventana Generar SQL con QueryData con: flights-assistant, haz clic en Editar.

  8. Ingresa la siguiente pregunta para generar una consulta en SQL y haz clic en Actualizar.

    flights to disney world

    La consulta en SQL generada es similar a la siguiente:

    SELECT
  "flights"."id",
  "flights"."airline",
  "flights"."flight_number",
  "flights"."departure_airport",
  "flights"."arrival_airport",
  "flights"."departure_time",
  "flights"."arrival_time",
  "flights"."departure_gate",
  "flights"."arrival_gate"
FROM
  "flights"
JOIN
  "airports" ON "flights"."arrival_airport" = "airports"."iata"
WHERE
  "airports"."city" = 'Orlando';

    Observa que QueryData ahora puede interpretar con precisión que "Disney World" se relaciona con la ciudad de "Orlando".

Integra QueryData en tu aplicación

En esta sección, crearás un agente de QueryData para una aplicación de búsqueda de vuelos. Este agente de QueryData proporciona una interfaz conversacional a la tabla flights y airports que creaste anteriormente. También se explica cómo crear e integrar este agente de QueryData en tu aplicación con el Kit de desarrollo de agentes (ADK), la herramienta de MCP de QueryData de Gemini Data Analytics y el conjunto de información contextual para mejorar la calidad de las respuestas.

  1. Descarga la versión 0.31.0 o posterior de MCP Toolbox. La caja de herramientas de MCP expone el agente QueryData como una herramienta con la que las aplicaciones pueden conectarse. La caja de herramientas de MCP difiere de la extensión de Gemini CLI de la caja de herramientas de MCP que instalaste anteriormente, que genera contexto.

  2. Configura las credenciales predeterminadas de la aplicación (ADC).

    gcloud auth application-default login

  3. Busca el ID del conjunto de contexto. Para obtener más información sobre cómo encontrar el ID del conjunto de contexto, consulta Cómo encontrar el ID del conjunto de contexto.

  4. Crea la configuración de tools.yaml para conectarte al agente de QueryData con el kit de herramientas de MCP. Para obtener más información, consulta Gemini Data Analytics Source y Gemini Data Analytics QueryData Tool.

    kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: "PROJECT_ID"
---
kind: tool
name: cloud_gda_query_tool
type: cloud-gemini-data-analytics-query
source: gda-api-source
description: Use this tool to send natural language queries to the Gemini Data Analytics API and receive SQL, natural language answers, and explanations.
location: "REGION_ID"
context:
  datasourceReferences:
    cloudSqlReference:
      databaseReference:
        engine: "POSTGRESQL"
        projectId: "PROJECT_ID"
        region: "REGION_ID"
        instanceId: "INSTANCE_ID"
        databaseId: "DATABASE_ID"
      agentContextReference:
        contextSetId: "CONTEXT_SET_ID"
generationOptions:
  generateQueryResult: true
  generateNaturalLanguageAnswer: true
  generateExplanation: true
  generateDisambiguationQuestion: true

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • REGION_ID: Es la región de tu instancia de Cloud SQL (p.ej., us-central1).
    • INSTANCE_ID: Es el ID de tu instancia de Cloud SQL.
    • DATABASE_ID: El nombre de la base de datos a la que te conectarás.
    • CONTEXT_SET_ID: Es el ID del conjunto de contexto. Para obtener más información sobre cómo encontrar el ID del conjunto de contexto, consulta Cómo encontrar el ID del conjunto de contexto.

  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 Gemini Data Analytics QueryData con el SDK de Python del kit de herramientas de MCP. Para obtener más información sobre cómo usar el SDK de Python de MCP Toolbox, consulta la guía de inicio rápido de Toolbox y, para el ADK de Python, consulta la guía de inicio rápido del ADK.

    1. Crea un directorio para almacenar la aplicación, por ejemplo, flight-assistant-app.

    2. Cambia el directorio al directorio flight-assistant-app.

      mkdir flight-assistant-app
cd flight-assistant-app

    3. Ejecuta los siguientes comandos en el directorio flight-assistant-app para crear un entorno virtual y, luego, instalar los componentes necesarios.

      python3 -m venv .venv
source .venv/bin/activate
pip install toolbox-core
pip install google-genai
pip install google-adk

    4. Configura un agente del ADK.

      1. Crea un agente del ADK.

        adk create my_agent

      2. Selecciona el modelo gemini-2.5-flash.

      3. Selecciona Google AI y, luego, ingresa tu clave de API de Gemini. Para obtener más información sobre cómo encontrar tu clave de API, consulta Usa claves de la API de Gemini.

    5. Reemplaza el contenido del archivo agent.py por el siguiente código de la aplicación de ejemplo del Asistente de datos de vuelo.

      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 friendly and factual flight data assistant. Your goal is to help users find the best flights for their needs by providing accurate information with a helpful, professional tone.
- use the Query Data Tool to answer the user's question, if the tool fails to generate a valid query, ask the user to clarify their question.

# 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 SQL. 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. Guide the user towards 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 database query.

Outputs: (all optional)
1. disambiguation_question: Clarification questions or comments where the tool needs the users' input.
2. generated_query: The generated query for the user query.
3. intent_explanation: An explanation for why the tool produced `generated_query`.
4. query_result: The result of executing `generated_query`.
5. natural_language_answer: The natural language answer that summarizes the `query` and `query_result`.

Usage guidance:
1. If `disambiguation_question` is produced, then solicit the needed inputs from the user and try the tool with a new `query` that has the needed clarification.
2. If `natural_language_answer` is produced, use `intent_explanation` and `generated_query` 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("cloud_gda_query_tool")

root_agent = Agent(
    model="gemini-2.5-flash",
    name="root_agent",
    instruction=INSTRUCTION,
    tools=cast(list[ToolUnion], [mcp_tool]),
)

  7. Ejecuta los siguientes comandos en el directorio flight-assistant-app para iniciar la aplicación y acceder al servidor web del ADK en http://127.0.0.1:8000.

    adk web --port 8000

  8. Ingresa cualquier texto, como hello, para comenzar a interactuar con el agente.

    El agente de ADK responde preguntas generales y llama a las herramientas de MCP requeridas.

  9. Ingresa la siguiente pregunta relacionada con vuelos.

    How many flights depart from the west side?

    Se llama a la herramienta de MCP para responder esta pregunta. Sin embargo, dado que el término the west es ambiguo y no especifica ningún aeropuerto, la herramienta de MCP devuelve una pregunta de desambiguación que el agente usa para construir una respuesta.

    I cannot determine how many flights depart from the 'west side' as the database does not contain information about which airports are considered to be on the 'west side'. However, I can help you with questions like:

1. How many flights depart from a specific airport?

2. What are the departure airports for all flights?

3. How many flights depart from each airport? Would you like to rephrase your question based on these options?

  10. Ingresa una pregunta similar a la de la plantilla de consulta generada para el agente.

    Help me find flights from San Francisco that avoid the evening rush hour.

    Según el contexto de QueryData que se agregó anteriormente, la herramienta de MCP comprende que evening traffic ocurre entre las 5 p.m. y las 7 p.m. La herramienta de MCP devuelve los datos asociados para que el agente los use en la construcción de su respuesta.

    Here are the flights departing from San Francisco that avoid the evening rush hour (defined as 5 PM to 7 PM):

* UA 1532 departing at 05:50:00
* UA 1158 departing at 05:57:00
* CY 922 departing at 06:38:00
* OO 5441 departing at 07:08:00
* UA 616 departing at 07:14:00
* AA 24 departing at 07:14:00
* B6 434 departing at 08:00:00
* AA 242 departing at 08:18:00
* UA 1739 departing at 08:22:00
* OO 6336 departing at 08:32:00
* US 1784 departing at 08:47:00
* DL 1631 departing at 09:00:00
* DL 1106 departing at 09:06:00
* OO 5427 departing at 09:06:00
* CY 352 departing at 09:25:00

  11. Ingresa una pregunta basada en el tipo de concepto que agregaste en el contexto del agente QueryData.

    Get me flights to disney world

    Según el contexto de búsqueda de valores que se agregó anteriormente, el agente de QueryData comprende que disney world se relaciona con la ciudad Orlando y devuelve los datos asociados para que el agente de QueryData los use en la construcción de su respuesta.

    Here are the flights heading to Orlando, which is the location of Disney World:

* Flight UA 1249 departs from SFO and arrives at MCO on 2025-01-02 at 18:15:00Z.
* Flight UA 698 departs from SFO and arrives at MCO on 2025-01-02 at 22:33:00Z.
* Flight UA 292 departs from SFO and arrives at MCO on 2025-01-03 at 06:37:00Z.

Itera el rendimiento del agente

La IU web del ADK te permite inspeccionar la solicitud y la respuesta de la herramienta QueryData del MCP de Gemini Data Analytics. Puedes usar esta respuesta para observar las respuestas de la herramienta, como la consulta en SQL generada, el conjunto de resultados, la explicación de la intención, la pregunta de desambiguación y la respuesta en lenguaje natural, para confirmar la exactitud de las respuestas del agente.

Por ejemplo, para el texto de entrada How many flights depart from the west side? que ingresaste antes, haz clic en la burbuja del agente. En la pestaña Evento del panel de navegación izquierdo, expande functionResponse para ver la siguiente respuesta.

"{"disambiguationQuestion": ["[NOT_ENOUGH_INFO] The database schema does not
contain information about which airports are on the 'west side'. Therefore, I
cannot determine how many flights depart from the west side.Possible alternative
questions: 1. How many flights depart from a specific airport? 2. What are the
departure airports for all flights? 3. How many flights depart from each
airport?"]}"

Mejora la precisión de la respuesta

Puedes mejorar continuamente la precisión de las respuestas de la herramienta Gemini Data Analytics QueryData agregando contexto adicional. Usa Gemini CLI para generar contexto y, luego, sube el archivo del conjunto de contexto actualizado al agente de flights-assistant QueryData existente. Para obtener más información, consulta Cómo crear contextos de compilación con Gemini CLI. La consola ingiere de inmediato el contexto nuevo después de que lo subes, lo que te permite mejorar la precisión del agente sin tiempo de inactividad de la aplicación.

Varios agentes

En tu entorno de desarrollo, puedes realizar pruebas A/B en varios contextos del agente QueryData asignando nombres distintos a las herramientas en tu archivo tools.yaml. Por ejemplo, puedes crear configuraciones de tools.yaml únicas definiendo dos herramientas de cloud-gemini-data-analytics-query con nombres diferentes, como cloud_gda_query_tool_v1 y cloud_gda_query_tool_v2. Esta configuración te permite implementar una lógica de aplicación que selecciona de forma programática la versión de contexto requerida eligiendo el nombre de la herramienta correspondiente.

En el siguiente ejemplo tools.yaml, se muestra cómo configurar varios agentes de QueryData para una fuente de base de datos:

kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: <var>PROJECT_ID</var>
---
kind: tool
name: cloud_gda_query_tool_v1
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    <var>DB_SOURCE</var>:
      databaseReference: ...
      agentContextReference:
        contextSetId: "V1_YOUR_CONTEXT_SET_ID"
generationOptions: ...
---
kind: tool
name: cloud_gda_query_tool_v2
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    <var>DB_SOURCE</var>:
      databaseReference: ...
      agentContextReference:
        contextSetId: "V2_YOUR_CONTEXT_SET_ID"
generationOptions: ...

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • V1_YOUR_CONTEXT_SET_ID: Es el ID del conjunto de contexto para la versión 1.
  • V2_YOUR_CONTEXT_SET_ID: Es el ID del conjunto de contexto para la versión 2.

Realiza una limpieza

En las siguientes secciones, se describe cómo borrar estos recursos y objetos.

Borra el conjunto de contextos

Antes de borrar la instancia, borra el conjunto de contexto que creaste.

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

    Ir a Cloud SQL

  2. Elige una instancia de la lista.

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

  4. Accede a Studio con la autenticación de Identity and Access Management.

  5. En el panel Explorador, junto a tu conjunto de contexto, haz clic en Ver acciones.

  6. En la ventana Borrar conjunto de contexto, ingresa flight-assistant en el cuadro de confirmación.

  7. Haz clic en Confirmar.

Borra la instancia

Cuando borras la instancia que creaste en la sección Antes de comenzar, también borras todos los objetos que creaste.

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

    Ir a Cloud SQL

  2. Elige una instancia de la lista.

  3. Haz clic en Borrar.

  4. Ingresa el nombre de la instancia y haz clic en Borrar para confirmar que deseas borrarla.

¿Qué sigue?