Integrar o QueryData a um aplicativo

Neste tutorial, descrevemos como configurar e usar o QueryData no Spanner com o console do Google Cloud e integrá-lo ao seu aplicativo. Saiba como criar o arquivo de conjuntos de contexto, criar um conjunto de contexto que use o arquivo de conjuntos de contexto, usar o MCP Toolbox para chamar o método QueryData na API Conversational Analytics para gerar consultas SQL para perguntas em linguagem natural e integrá-lo ao seu aplicativo.

Para mais informações, consulte Visão geral do QueryData.

Objetivos

  • Criar bancos de dados e preenchê-los com dados.
  • Crie um arquivo de conjunto de contextos com o agente de engenharia de contexto.
  • Crie um conjunto de contextos e faça upload de um arquivo dele.
  • Teste o QueryData e gere consultas SQL no Spanner Studio.
  • Integre o QueryData ao seu aplicativo usando a ferramenta QueryData do Gemini Data Analytics na MCP Toolbox.
  • Adicione embasamento às respostas do LLM usando consultas de pesquisa de valor.

Custos

Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste sem custo financeiro.

Para evitar o faturamento contínuo, exclua os recursos criados ao concluir as tarefas neste documento. Para mais informações, consulte Limpeza.

Antes de começar

Conclua os pré-requisitos a seguir antes de criar um conjunto de contexto.

Ativar serviços obrigatórios

Ative os seguintes serviços para seu projeto:

Preparar uma instância do Spanner


Este tutorial exige que você tenha um banco de dados na sua instância do Spanner. Para mais informações, consulte Criar um banco de dados.

Papéis e permissões necessárias

  • Adicione um usuário do IAM ou uma conta de serviço ao cluster. Para mais informações, consulte Aplicar papéis do IAM.
  • Conceda os papéis spanner.databaseReader e geminidataanalytics.queryDataUser ao usuário do IAM no nível do projeto. Para mais informações, consulte Adicionar uma vinculação de política do IAM a um projeto.
  • Para criar, fazer upload e gerenciar conjuntos de contexto, conceda o papel de Editor do Dataplex Catalog (roles/dataplex.catalogEditor) ou Administrador do Dataplex Catalog (roles/dataplex.catalogAdmin) ao usuário do IAM no nível do projeto. Para mais informações, consulte Permissões de conjuntos de contexto.
  • Conceda papéis e permissões ao usuário do IAM para envolvidos no projeto para os bancos de dados necessários.

Criar o esquema e as tabelas flights e airports

Nesta seção, você vai criar as tabelas de banco de dados flights e airports para este tutorial.

  1. No console Google Cloud , acesse a página do Spanner.

    Acessar o Spanner

  2. Selecione uma instância na lista e escolha um banco de dados.

  3. No menu de navegação, clique em Spanner Studio.

  4. Clique em Nova guia do editor de SQL ou Nova guia para abrir uma nova guia.

  5. Para criar a tabela e o esquema airports, execute a seguinte instrução SQL:

    CREATE TABLE IF NOT EXISTS airports (
  id INT64 PRIMARY KEY,
  iata STRING(MAX),
  name STRING(MAX),
  city STRING(MAX),
  country STRING(MAX)
);

  6. Crie a tabela e o esquema flights:

    CREATE TABLE flights (
  id INT64 NOT NULL,
  airline STRING(10),
  flight_number INT64,
  departure_airport STRING(5),
  arrival_airport STRING(5),
  departure_time TIMESTAMP,
  arrival_time TIMESTAMP,
  departure_gate STRING(10),
  arrival_gate STRING(10)
) PRIMARY KEY (id);

Preencha as tabelas flights e airports.

Nesta seção, você vai preencher as tabelas flights e airports usando os scripts SQL fornecidos.

  1. Preencha a tabela airports.

  2. Preencha a tabela flights.

  3. Execute a consulta a seguir para verificar se as tabelas estão preenchidas:

    SELECT * FROM flights LIMIT 10;
SELECT * FROM airports LIMIT 10;

Criar colunas tokenizadas e índices da Pesquisa

Use os recursos de Text Search integrados do Spanner para permitir que o QueryData mapeie com precisão frases de linguagem natural não estruturadas, como erros de digitação ou nomes parciais, para valores específicos no banco de dados. Isso requer a geração de uma coluna TOKENLIST oculta que divide as strings em n-grams e a criação de um índice da Pesquisa nessa coluna.

Para criar colunas tokenizadas e índices da Pesquisa, execute as seguintes instruções SQL:

  1. Crie a coluna de token e o índice para nomes de aeroportos:

    ALTER TABLE `airports` ADD COLUMN `name_tokens` TOKENLIST AS (TOKENIZE_SUBSTRING(`name`)) STORED HIDDEN;
CREATE SEARCH INDEX `airports_name_idx` ON `airports`(`name_tokens`);

  2. Crie a coluna de token e o índice para cidades com aeroportos:

    ALTER TABLE `airports` ADD COLUMN `city_tokens` TOKENLIST AS (TOKENIZE_SUBSTRING(`city`)) STORED HIDDEN;
CREATE SEARCH INDEX `airports_city_idx` ON `airports`(`city_tokens`);

Criar um conjunto de contextos no Spanner Studio

Nesta seção, crie um conjunto de contexto chamado flights-assistant. Este conjunto de contexto não inclui nenhum arquivo enviado a ele.

  1. No console Google Cloud , acesse a página do Spanner.

    Acessar o Spanner

  2. Selecione uma instância na lista e escolha um banco de dados.

  3. No menu de navegação, clique em Spanner Studio.

  4. No painel Explorador, ao lado de Conjuntos de contexto, clique em Mais ações ().

  5. Clique em Criar conjunto de contexto.

  6. Em Nome do conjunto de contexto, insira flights-assistant.

  7. Clique em Criar.

Testar QueryData no Studio

Nesta seção, use o conjunto de contexto flights-assistant fazendo perguntas em linguagem natural para gerar uma consulta SQL. Como o conjunto de contexto não tem nenhum arquivo enviado, mesmo depois de fazer uma pergunta com contexto, como nighttime traffic, o QueryData gera uma consulta abaixo do ideal.

  1. No painel Explorer, ao lado do conjunto de contexto, clique em Mais ações ().
  2. Clique em Contexto de teste definido.
  3. No editor de consultas, clique em Gerar SQL usando o QueryData com: flights-assistant.

  4. Insira a seguinte pergunta em linguagem natural para gerar uma consulta SQL e clique em Gerar.

    Find flights from SFO to JFK.

    Analise a consulta SQL. Observe que o QueryData gera o SQL correto para essa pergunta sem ambiguidade.

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

  5. Na janela Gerar SQL usando QueryData com: flights-assistant, clique em Editar.

  6. Insira a seguinte pergunta em linguagem natural para gerar uma consulta SQL e clique em Atualizar.

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

    O banco de dados não entende o termo tráfego de nighttime. Isso pode impedir que ele gere uma consulta SQL ou fazer com que ele gere uma consulta que ignore o termo, como mostra a consulta a seguir.

    -- 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. Na janela Gerar SQL usando QueryData com: flights-assistant, clique em Editar.

  8. Insira a seguinte pergunta em linguagem natural para gerar uma consulta SQL e clique em Atualizar.

    Show me the flight to Houston Intercontinental

    A lógica do conjunto de contexto gera uma consulta para encontrar um aeroporto com "Houston Intercontinental" no nome. Como não existe um aeroporto ou cidade assim no banco de dados, a consulta não vai retornar nenhuma linha.

    SELECT
  f.*
FROM
  `flights` AS f
JOIN
  `airports` AS a
ON
  f.arrival_airport = a.id
WHERE
  a.name LIKE '%Houston Intercontinental%';

Gerar contexto para o conjunto de contextos

Nesta seção, você vai preparar o ambiente e criar um arquivo de contexto que ajuda a melhorar os recursos de consulta do conjunto de contexto.

Configurar o ambiente

Antes de começar a gerar contexto, é preciso preparar o ambiente.

Para configurar o ambiente, siga estas etapas:

  1. Instale a CLI do Antigravity. Para mais informações, consulte Começar a usar a CLI do Antigravity.
  2. Instale a CLI do Google Cloud.

  3. Configure o Application Default Credentials (ADC). Execute os seguintes comandos no terminal para autenticar e selecionar seu projeto:

    gcloud auth application-default login

  4. Instale o uv, um gerenciador de projetos e pacotes Python que é um pré-requisito para o agente de engenharia de contexto. Se você ainda não tiver o Python no sistema, o uv poderá instalá-lo para você.

  5. Instale o agente de engenharia de contexto:

    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin

  6. No terminal, inicie a CLI do Antigravity.

    agy

  7. Configurar uma conexão de banco de dados para geração de contexto usando o MCP Toolbox. A conexão é definida no arquivo de configuração tools.yaml.

    Para criar o arquivo de configuração tools.yaml no diretório atual, insira um comando como: 

    Help me set up a database connection.

    Siga as instruções fornecidas pela skill. Para mais informações sobre o arquivo tools.yaml, consulte a documentação do MCP Toolbox.

  8. Para recarregar a configuração depois que o arquivo tools.yaml for criado, execute o seguinte comando na CLI do Antigravity e siga as instruções para recarregar o servidor MCP da caixa de ferramentas:

    /mcp

    1. Selecione db-context-engineering_toolbox.

    2. Selecione Restart.

  9. Verifique se a caixa de ferramentas do MCP e o plug-in do agente de engenharia de contexto estão conectados e prontos para uso.

    /mcp

Gerar contexto de modelo

Nesta seção, para resolver o problema da seção anterior em que o QueryData não reconheceu o termo nighttime traffic, defina o termo no arquivo de conjunto de contexto como tráfego que ocorre entre 5:00 PM e 7:00 PM.

Para gerar o contexto do modelo, siga estas etapas:

  1. Insira o seguinte comando na CLI do Antigravity:

    Generate a template for the question: "Tell me flights that can help me beat nighttime traffic if traveling from New York" with the following SQL query:

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;

  2. O agente converte sua entrada em um formato específico que refina o desempenho do conjunto de contexto em uma ampla variedade de consultas de usuários. Para mais informações, consulte Visão geral dos conjuntos de contexto.

  3. Revise o modelo de consulta gerado. Você pode salvar o modelo de consulta como um novo arquivo de contexto do agente ou anexá-lo a um arquivo de contexto do agente atual.

  4. Peça para o agente salvar o modelo:

    Save it to context_set.json.

    O agente cria o arquivo no mesmo diretório, com o seguinte conteúdo:

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

Gerar contexto de pesquisa de valor

Nesta seção, você vai gerar um contexto de pesquisa de valor para ajudar a lógica do conjunto de contexto a mapear frases de valor para valores específicos armazenados nas colunas do banco de dados usando similaridade de string (correspondência de trigrama). Por exemplo, se um usuário pedir voos para "Houston Intercontinental", a pesquisa de valor poderá mapear isso para o valor exato do banco de dados de "Aeroporto Intercontinental George Bush de Houston".

Para gerar um contexto de pesquisa de valor, siga estas etapas:

  1. Insira o seguinte comando na estrutura de agentes:

  2. Insira spanner para selecionar o Spanner como o banco de dados.

    Generate a value search on table "airports" for column "city" with concept "Airport City" using match function "TRIGRAM_STRING_MATCH".

  3. Revise a definição de pesquisa de valor gerada. Você pode salvar a definição de pesquisa de valor como um novo arquivo de conjunto de contexto ou anexá-la a um arquivo existente.

  4. Envie o comando Append the context to context_set.json para o agente. Isso adiciona a definição de pesquisa de valor ao arquivo de contexto criado na seção anterior.

  5. Insira a instância e o nome do banco de dados para os quais o arquivo de conjunto de contexto foi gerado.

    O arquivo de contexto atual é atualizado com a definição de pesquisa de valor, com o seguinte conteúdo:

      {
"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 ?"
    }
  }
],
"facets": [],
"value_searches": [
  {
    "query": "SELECT CAST(T.`name` AS STRING) AS value, 'name' AS `columns`, 'airport name' AS concept_type, 1 - SCORE_NGRAMS(T.`name_tokens`, CAST($value AS STRING)) AS distance, JSON '{}' AS context FROM `airports` AS T WHERE SEARCH_NGRAMS(T.`name_tokens`, CAST($value AS STRING)) ",
    "concept_type": "airport name",
    "description": "String similarity using Spanner Search Indexes."
  },
  {
    "query": "SELECT CAST(T.`city` AS STRING) AS value, 'city' AS `columns`, 'airport city' AS concept_type, 1 - SCORE_NGRAMS(T.`city_tokens`, CAST($value AS STRING)) AS distance, JSON '{}' AS context FROM `airports` AS T WHERE SEARCH_NGRAMS(T.`city_tokens`, CAST($value AS STRING)) ",
    "concept_type": "airport city",
    "description": "String similarity using Spanner Search Indexes."
  }
]
}

Fazer upload do arquivo de conjunto de contexto para o QueryData

Nesta seção, você vai fazer upload do arquivo de conjunto de contexto para o QueryData, para que ele melhore os recursos de geração de SQL do QueryData no seu banco de dados.

Para fazer upload do contexto, siga estas etapas:

  1. No console Google Cloud , acesse a página do Spanner.

    Acessar o Spanner

  2. Selecione uma instância na lista e, em seguida, um banco de dados.

  3. No menu de navegação, clique em Spanner Studio.

  4. No painel "Explorer", ao lado de Conjuntos de contexto, clique no ícone Ações ().

  5. Clique em Editar conjunto de contexto.

  6. Clique em Procurar na seção Fazer upload do arquivo de conjunto de contexto e selecione o arquivo de conjunto de contexto gerado anteriormente.

  7. Clique em Salvar.

Gerar consulta SQL usando o QueryData

Nesta seção, você vai usar o arquivo de conjunto de contexto que enviou para fazer perguntas em linguagem natural. Isso permite verificar se o QueryData entende e aplica corretamente as definições de termos como nighttime traffic e outras frases relacionadas.

Para gerar consultas SQL, siga estas etapas:

  1. No painel Explorer, ao lado do conjunto de contexto, clique em Mais ações ().
  2. Clique em Contexto de teste definido.
  3. No editor de consultas, clique em Gerar SQL usando o QueryData com: flights-assistant.

  4. Insira a seguinte pergunta em linguagem natural para gerar uma consulta SQL e clique em Gerar.

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

    A consulta SQL gerada é semelhante a esta:

    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;

    Essa é a mesma pergunta que você adicionou ao contexto de QueryData. Observe que o QueryData agora pode interpretar com precisão o termo nighttime traffic.

    Embora o contexto tenha origem em uma pergunta específica, o QueryData o usa para melhorar a geração de SQL para uma ampla variedade de perguntas semelhantes.

  5. Na janela Gerar SQL usando QueryData com: flights-assistant, clique em Editar.

  6. Insira a seguinte pergunta semelhante para gerar uma consulta SQL e clique em Atualizar.

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

    Como a pergunta substitui o termo nighttime traffic por um termo semelhante, evening traffic, o QueryData fornece uma resposta consistente a essa pergunta aplicando a mesma interpretação.

    A consulta SQL gerada é semelhante a esta:

    -- 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. Insira a pergunta a seguir para gerar uma consulta SQL e clique em Atualizar.

    Show me the flight to Houston Intercontinental

    A consulta SQL gerada é semelhante a esta:

    SELECT
  f.*
FROM
  flights AS f
INNER JOIN
  airports AS a
ON
  f.arrival_airport = a.iata
WHERE
  a.name = 'George Bush Intercontinental Houston Airport'

    Observe que o QueryData agora pode interpretar com precisão que "Houston Intercontinental" se relaciona ao "Aeroporto Intercontinental George Bush de Houston" no banco de dados.

Integrar o QueryData ao seu aplicativo

Nesta seção, você vai criar um agente de dados para um aplicativo de busca de voos. Esse agente de dados oferece uma interface de conversa para as tabelas flights e airports criadas anteriormente. Ele também explica como criar e integrar esse agente de dados ao seu aplicativo usando o Kit de Desenvolvimento de Agente (ADK), a ferramenta QueryData do MCP de análise de dados do Gemini e um conjunto de contexto para melhorar a qualidade das respostas.

  1. Baixe a versão 1.14.0 ou mais recente do MCP Toolbox. O MCP Toolbox expõe o agente de dados como uma ferramenta para os aplicativos se conectarem. O MCP Toolbox é diferente do agente de engenharia de contexto que você instalou anteriormente, que gera contexto.

  2. Configure o Application Default Credentials (ADC).

    gcloud auth application-default login

  3. Encontre o ID do conjunto de contexto que você criou anteriormente. Para saber como encontrar o ID do conjunto de contexto, consulte Encontrar o ID do conjunto de contexto.

  4. Adicione o seguinte à configuração tools.yaml para se conectar ao agente de dados usando a MCP Toolbox. Para mais informações, consulte Origem da análise de dados do Gemini e Ferramenta QueryData da análise de dados do Gemini.

    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:
    spannerReference:
      databaseReference:
        engine: "GOOGLE_SQL"
        projectId: "PROJECT_ID"
        instanceId: "INSTANCE_ID"
        databaseId: "DATABASE_ID"
      agentContextReference:
        contextSetId: "CONTEXT_SET_ID"
generationOptions:
  generateQueryResult: true
  generateNaturalLanguageAnswer: true
  generateExplanation: true
  generateDisambiguationQuestion: true

    Substitua:

    • PROJECT_ID: o ID do projeto do Google Cloud .
    • REGION_ID: a região da instância do Spanner (por exemplo, us-central1).
    • INSTANCE_ID: o ID da instância do Spanner.
    • DATABASE_ID: o nome do banco de dados a ser conectado.
    • CONTEXT_SET_ID: o ID do conjunto de contexto. Para saber como encontrar o ID do conjunto de contexto, consulte Encontrar o ID do conjunto de contexto.

  5. Execute o servidor da caixa de ferramentas do MCP com o arquivo tools.yaml.

    ./toolbox --config autoctx/tools.yaml

  6. Criar um aplicativo do ADK que invoque a ferramenta QueryData da análise de dados do Gemini usando o SDK do Python do MCP Toolbox. Para mais informações sobre como usar o SDK da MCP Toolbox para Python, consulte o guia de início rápido da Toolbox e, para o ADK do Python, consulte o guia de início rápido do ADK.

    1. Crie um diretório para armazenar o aplicativo, por exemplo, flight-assistant-app.

    2. Altere o diretório para flight-assistant-app.

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

    3. Execute os comandos a seguir no diretório flight-assistant-app para criar um ambiente virtual e instalar os componentes necessários.

      uv init
uv add google-adk toolbox-core google-genai

    4. Configurar um agente do ADK.

      1. Criar um agente do ADK.

        uv run adk create my_agent

      2. Selecione o modelo gemini-3.8-flash ou mais recente.

      3. Selecione Google AI e insira sua chave de API Gemini. Para mais informações sobre como encontrar sua chave de API, consulte Como usar chaves de API Gemini. Se você não precisar de um teste sem custo financeiro, selecione Vertex AI e especifique um projeto do Google Cloud com o faturamento ativado.

    5. Substitua o conteúdo do arquivo agent.py pelo código de exemplo do aplicativo Flight Data Assistant a seguir.

      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-3.8-flash",  # Or newer.
    name="root_agent",
    instruction=INSTRUCTION,
    tools=cast(list[ToolUnion], [mcp_tool]),
)

  7. Execute os comandos a seguir no diretório flight-assistant-app para iniciar o aplicativo e acessar o servidor da Web do ADK em http://127.0.0.1:8000.

    uv run adk web --port 8000

  8. Digite qualquer texto, como hello, para começar a interagir com o agente.

    O agente do ADK responde a perguntas gerais e chama as ferramentas do MCP necessárias.

  9. Digite a seguinte pergunta relacionada a voos.

    How many flights depart from the west side?

    A ferramenta do MCP é chamada para responder a essa pergunta. No entanto, como o termo the west é ambíguo e não especifica nenhum aeroporto, a ferramenta do MCP retorna uma pergunta de desambiguação que o agente usa para construir uma resposta.

    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. Insira uma pergunta semelhante à do modelo de consulta gerado para o agente.

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

    Com base no contexto QueryData adicionado anteriormente, a ferramenta MCP entende que evening traffic ocorre entre 17h e 19h. A ferramenta do MCP retorna os dados associados para o agente usar na criação da resposta.

    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. Insira uma pergunta com base no tipo de conceito que você adicionou no contexto do agente QueryData.

    Show me the flight to Houston Intercontinental

    Com base no contexto de pesquisa de valor adicionado anteriormente, o agente entende que "Houston Intercontinental" se refere ao "Aeroporto Intercontinental George Bush de Houston" (código do aeroporto IAH) e retorna os dados associados para que o agente os use na construção da resposta.

    Here are the flights heading to Houston Intercontinental (IAH):

* Flight UA 1285 departs from SFO and arrives at IAH on 2025-01-01 at 23:20:00Z.
* Flight F9 1056 departs from SFO and arrives at IAH on 2025-01-02 at 20:09:00Z.
* Flight UA 1722 departs from SFO and arrives at IAH on 2025-01-03 at 02:29:00Z.

Iterar o desempenho do agente

A UI da Web do ADK permite inspecionar a solicitação e a resposta da ferramenta MCP QueryData do Gemini Data Analytics. Use essa resposta para observar as respostas da ferramenta, como a consulta SQL gerada, o conjunto de resultados, a explicação da intenção, a pergunta de desambiguação e a resposta em linguagem natural, para ajudar a confirmar a precisão das respostas do agente.

Por exemplo, para o texto de entrada How many flights depart from the west side? que você inseriu anteriormente, clique no balão do agente. Na guia Evento no menu de navegação à esquerda, abra functionResponse para ver a resposta a seguir.

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

Refinar a precisão da resposta

Você pode refinar continuamente a precisão das respostas da ferramenta QueryData do Gemini Análise de dados adicionando mais contexto. Use o agente de engenharia de contexto para gerar o contexto e, em seguida, faça upload do arquivo de conjunto de contexto atualizado para o agente de dados flights-assistant atual. Para mais informações, consulte Gerenciar conjuntos de contexto no Spanner Studio. O console ingere imediatamente o novo contexto depois que você o envia, permitindo melhorar a precisão do agente sem tempo de inatividade do aplicativo.

Vários agentes

No seu ambiente de desenvolvimento, é possível realizar testes A/B em vários contextos de agentes de dados atribuindo nomes distintos às ferramentas no arquivo tools.yaml. Por exemplo, é possível criar configurações exclusivas de tools.yaml definindo duas ferramentas cloud-gemini-data-analytics-query com nomes diferentes, como cloud_gda_query_tool_v1 e cloud_gda_query_tool_v2. Essa configuração permite implementar uma lógica de aplicativo que seleciona programaticamente a versão de contexto necessária escolhendo o nome da ferramenta correspondente.

O exemplo tools.yaml a seguir mostra como configurar vários agentes de dados para uma origem de banco de dados:

kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: PROJECT_ID
---
kind: tool
name: cloud_gda_query_tool_v1
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    DB_SOURCE:
      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:
    DB_SOURCE:
      databaseReference: ...
      agentContextReference:
        contextSetId: "V2_YOUR_CONTEXT_SET_ID"
generationOptions: ...

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • V1_YOUR_CONTEXT_SET_ID: o ID do conjunto de contexto da versão 1.
  • V2_YOUR_CONTEXT_SET_ID: o ID do conjunto de contexto da versão 2.

Limpar

Depois de concluir este tutorial, exclua os recursos criados para evitar custos contínuos. Nas seções a seguir, você verá como excluir esses recursos.

Excluir o conjunto de contexto

Antes de excluir a instância, exclua o conjunto de contexto que você criou.

  1. No console Google Cloud , acesse a página do Spanner.

    Acessar o Spanner

  2. Selecione uma instância na lista e escolha um banco de dados.

  3. No menu de navegação, clique em Spanner Studio.

  4. No painel Explorer, ao lado do conjunto de contexto, clique em Mais ações ().

  5. Na janela Excluir conjunto de contexto, insira flight-assistant na caixa de confirmação.

  6. Clique em Confirmar.

Excluir a instância

Quando você exclui a instância criada na seção Antes de começar, todos os objetos criados também são excluídos.

  1. No console Google Cloud , acesse a página do Spanner.

    Acessar o Spanner

  2. Clique no nome da instância que você quer excluir, por exemplo, Instância de teste.

  3. Clique em Excluir instância.

  4. Confirme que você quer excluir a instância inserindo o nome dela e clicando em Excluir.

A seguir