Integrar o QueryData a um aplicativo

Neste tutorial, descrevemos como configurar e usar o QueryData no Cloud SQL para MySQL usando o Google Cloud console e como integrá-lo ao seu aplicativo. Saiba como criar o arquivo de conjunto de contexto, criar um conjunto de contexto que use o arquivo de conjunto 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 e preencher bancos de dados 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 Cloud SQL 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 Cloud SQL

Papéis e permissões necessárias

Conceder permissão executesql à instância do Cloud SQL

Para conceder a permissão executesql à instância do Cloud SQL e ativar a API Data do Cloud SQL, execute o seguinte comando: 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
Substitua o seguinte:
  • PROJECT_ID: ID do seu projeto do Google Cloud .
  • INSTANCE_ID: o ID da sua instância do Cloud SQL.
Para realizar as etapas deste tutorial, faça login no Google Cloud e autentique-se no banco de dados usando a autenticação do IAM.

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 do Google Cloud , acesse a página do Cloud SQL.

    Acessar o Cloud SQL

  2. Selecione uma instância na lista.

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

  4. Faça login no Studio usando a autenticação do Identity and Access Management.

  5. Clique em Autenticar. O painel "Explorer" mostra uma lista dos objetos no seu banco de dados.

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

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

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

  8. Crie a tabela e o 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)
);

Preencher 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;

Preparar o banco de dados para pesquisas de valor

Para usar pesquisas semânticas e de valor de trigrama, configure sua instância do Cloud SQL para MySQL para oferecer suporte a embeddings de vetor e indexação de n-gramas.

  1. Para permitir que a instância do Cloud SQL para MySQL realize pesquisas de valor semântico, ative as flags a seguir.

    1. Ative a flag cloudsql_vector.

      gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on

    2. Ative a flag enable-google-ml-integration para permitir que a instância do Cloud SQL para MySQL se integre à Vertex AI.

      gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration

    3. Criar uma coluna de vetor para armazenar embeddings de cidades

      ALTER TABLE `airports` 
ADD COLUMN `city_embedding` VECTOR(768);

    4. Gerar e armazenar embeddings de vetor para nomes de cidades

      UPDATE `airports` 
SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`) 
WHERE `city` IS NOT NULL;

  2. Para permitir que a instância do Cloud SQL para MySQL realize pesquisas de valor de trigrama, siga as etapas abaixo.

    1. Ative a flag ngram_token_size.

      gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3

    2. Criar um índice FULLTEXT para correspondência de trigrama no nome do aeroporto

      CREATE FULLTEXT INDEX `idx_ngram_airports_name` 
ON `airports`(`name`) 
WITH PARSER ngram;

Criar um conjunto de contexto no Cloud SQL 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 do Google Cloud , acesse a página do Cloud SQL.

    Acessar o Cloud SQL

  2. Selecione uma instância na lista.

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

  4. Faça login no Studio usando a autenticação do IAM.

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

  6. Clique em Criar conjunto de contexto.

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

  8. Clique em Criar.

Testar QueryData no Studio

Nesta seção, use o contexto flights-assistant definido 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 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 inequívoca.

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

    Find flights heading into Manhattan

    A lógica de contexto definido gera uma consulta para encontrar um aeroporto com "Manhattan" no nome. Como não há esse aeroporto ou cidade no banco de dados, a consulta não vai retornar nenhuma linha.

    SELECT
  `skybot`.`flights`.*
FROM
  `skybot`.`flights`
JOIN
  `skybot`.`airports`
ON
  `skybot`.`flights`.`arrival_airport` = `skybot`.`airports`.`iata`
WHERE
  `skybot`.`airports`.`city` = 'Manhattan';

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. Configure uma conexão de banco de dados para geração de contexto usando a 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 da 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 o contexto a definir frases de valor do mapa lógico para valores específicos armazenados nas colunas do banco de dados. Por exemplo, se um usuário pedir "voos para Manhattan", primeiro Manhattan será extraída como uma frase de valor, e a pesquisa de similaridade semântica associará Manhattan a "Nova York", que é armazenada na coluna airports.city.

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

  1. Insira o seguinte comando na estrutura de agentes:

  2. Digite mysql para selecionar o MySQL como o banco de dados.

  3. Insira a versão do MySQL que você quer usar. Selecione default para escolher o MySQL 8.0.

    Generate a trigram value search on table "airports" for column "name" with concept "airport name". Then generate a semantic value search on table "airports" for column "city" with concept "airport city" using embedding column "city_embedding".

  4. Revise a definição de pesquisa de valor gerada. É possível salvar a definição de pesquisa de valor como um novo arquivo de conjunto de contexto ou anexá-la a um arquivo de conjunto de contexto atual.

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

  6. Insira a instância do banco de dados e o nome do banco de dados para o qual 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 * FROM (  WITH TrigramMetrics AS (    SELECT T.`name` AS original_value,     MATCH(T.`name`) AGAINST($value IN NATURAL LANGUAGE MODE) AS raw_score     FROM `airports` AS T     WHERE MATCH(T.`name`) AGAINST($value IN NATURAL LANGUAGE MODE) > 0     ORDER BY raw_score DESC LIMIT 10  ),   NormalizationParams AS (    SELECT MAX(raw_score) AS max_score     FROM TrigramMetrics  )   SELECT original_value AS value, 'name' AS `columns`,   'airport city' AS concept_type,   (CASE WHEN n.max_score > 0 THEN (1 - (m.raw_score / n.max_score)) ELSE 0 END) AS distance,   JSON_OBJECT() AS context   FROM TrigramMetrics m, NormalizationParams n) AS wrapped_query ",
    "concept_type": "airport city",
    "description": null
  },
  {
    "query": "SELECT * FROM (  WITH search_embedding AS (    SELECT mysql.ml_embedding('text-embedding-005', $value) AS val  )   SELECT T.`city` AS value, 'city' AS `columns`,   'airport name' AS concept_type,   COSINE_DISTANCE(T.`city_embedding`, search_embedding.val) AS distance,   JSON_OBJECT() AS context   FROM `airports` AS T, search_embedding   WHERE T.`city_embedding` IS NOT NULL) AS wrapped_query ",
    "concept_type": "airport name",
    "description": null
  }
]
}

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 do Google Cloud , acesse a página do Cloud SQL.

    Acessar o Cloud SQL

  2. Selecione uma instância na lista.

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

  4. Faça login no Studio usando a autenticação do Identity and Access Management.

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

  6. Clique em Editar conjunto de contexto.

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

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

  8. Insira a pergunta a seguir para gerar uma consulta SQL e clique em Atualizar.

    Find flights heading into Manhattan

    A consulta SQL gerada é semelhante a esta:

    SELECT
  *
FROM `skybot`.`flights` AS t1
INNER JOIN `skybot`.`airports` AS t2
  ON t1.`arrival_airport` = t2.`iata`
WHERE t2.`city` = 'New York';

    Observe que o QueryData agora pode interpretar com precisão que "Manhattan" se relaciona a "Nova York" no banco de dados usando a correspondência semântica.

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 contextos 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 mais informações sobre 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 o 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:
    cloudSqlReference:
      databaseReference:
        engine: "MYSQL"
        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

    Substitua:

    • PROJECT_ID: o ID do projeto do Google Cloud .
    • REGION_ID: a região da instância do Cloud SQL (por exemplo, us-central1).
    • INSTANCE_ID: o ID da instância do Cloud SQL.
    • 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. Configure 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 IA do Google e insira sua chave de API Gemini. Para mais informações sobre como encontrar sua chave de API, consulte Como usar chaves da 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 seguinte exemplo de código do aplicativo Assistente de dados de voo.

      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.

    Find flights heading into Manhattan

    Com base no contexto de pesquisa de valor adicionado anteriormente, o agente entende que "Manhattan" se refere à cidade de "Nova York" e retorna os dados associados para o agente usar na construção da resposta.

    There are 6 flights heading into New York City, specifically arriving at JFK airport, which serves Manhattan.

Here are the details for these flights:

AA 24 from SFO, departing 2025-01-01 07:14:00 and arriving 2025-01-01 15:46:00.
UA 758 from SFO, departing 2025-01-02 07:07:00 and arriving 2025-01-02 15:53:00.
AA 24 from SFO, departing 2025-01-02 07:06:00 and arriving 2025-01-02 15:29:00.
DL 2040 from SFO, departing 2025-01-02 15:09:00 and arriving 2025-01-02 23:20:00.
DL 1370 from SFO, departing 2025-01-02 23:04:00 and arriving 2025-01-03 07:36:00.
CY 34 from SFO, departing 2025-01-02 23:15:00 and arriving 2025-01-03 07:54:00.

Iterar o desempenho do agente

Com a UI da Web do ADK, é possível inspecionar a solicitação e a resposta da ferramenta QueryData MCP 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, expanda o functionResponse para ver a seguinte resposta.

"{"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 contexto e faça upload do arquivo atualizado do conjunto de contexto para o agente de dados flights-assistant atual. Para mais informações, consulte Gerenciar conjuntos de contexto no Cloud SQL Studio. O console ingere imediatamente o novo contexto após o upload, permitindo que você melhore a precisão do agente sem qualquer inatividade do aplicativo.

Vários agentes

No seu ambiente de desenvolvimento, é possível realizar testes A/B em vários contextos de agente 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 do Google Cloud , acesse a página do Cloud SQL.

    Acessar o Cloud SQL

  2. Selecione uma instância na lista.

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

  4. Faça login no Studio usando a autenticação do Identity and Access Management.

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

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

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

    Acessar o Cloud SQL

  2. Selecione uma instância na lista.

  3. Clique em Excluir.

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

A seguir