Integrar o QueryData a um aplicativo

Neste tutorial, descrevemos como configurar e usar QueryData no Cloud SQL para PostgreSQL usando o console Google Cloud e integrá-lo ao seu aplicativo. Aprenda a criar o arquivo de conjunto de contexto, criar um conjunto de contexto que usa o arquivo de conjunto de contexto, usar a Caixa de ferramentas do MCP para chamar a API QueryData e gerar consultas SQL para perguntas em linguagem natural, além de integrar tudo isso ao seu aplicativo.

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

Objetivos

  • Criar tabelas de banco de dados e preenchê-las com dados.
  • Crie um arquivo de conjunto de contexto com a CLI do Gemini e a caixa de ferramentas do MCP.
  • Crie um conjunto de contexto e faça upload do arquivo dele.
  • Teste o QueryData e gere consultas SQL no Studio.
  • Integre o QueryData ao seu aplicativo usando a ferramenta QueryData do Gemini Data Analytics na MCP Toolbox.
  • Adicionar 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

Verifique se você tem acesso a uma instância do Cloud SQL ou crie uma nova. Para mais informações, consulte Criar instâncias para o Cloud SQL.

Este tutorial exige que você tenha um banco de dados na sua instância do Cloud SQL. Para mais informações, consulte Criar um banco de dados na 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: o 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 em Google Cloud e autentique o 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 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 e o esquema airports, 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)
);

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 "public"."flights" LIMIT 10;
SELECT * FROM "public"."airports" LIMIT 10;

Criar um conjunto de contexto no Studio

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

  1. No console 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 Ver ações.

  6. Clique em Criar conjunto de contexto.

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

  8. Clique em Criar.

Testar QueryData no Studio

Nesta seção, use o contexto flights-assistant definido ao fazer perguntas em linguagem natural para gerar uma consulta SQL. Como o conjunto de contexto não tem um arquivo de conjunto de contexto 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 Ver ações.
  2. Clique em Testar conjunto de contexto.
  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 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 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.

    flight to disney world

    A lógica de definição de contexto gera uma consulta para encontrar um aeroporto com "disney world" no nome. Como não há aeroporto ou cidade desse tipo no banco de dados, a consulta não retorna nenhuma linha.

    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%';

Gerar contexto para o conjunto de contexto

Nesta seção, você vai 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, você precisa preparar seu ambiente.

Para configurar o ambiente, siga estas etapas:

  1. Instale a CLI do Gemini. Para mais informações, consulte o Guia de início rápido da CLI do Gemini.
  2. Instale a CLI gcloud.

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

    gcloud auth application-default login

  4. Instale a extensão de enriquecimento de contexto do banco de dados, que inclui fluxos de trabalho para geração de contexto.

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

    Verifique se a versão é 0.4.2 ou mais recente. Para atualizar a extensão de enriquecimento de contexto do banco de dados, execute o seguinte comando:

    gemini extensions update mcp-db-context-enrichment

  5. Para atualizar a extensão de enriquecimento de contexto do banco de dados ou substituir o GEMINI_API_KEY, execute o seguinte comando:

    gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

    Substitua GEMINI_API_KEY pela sua chave de API Gemini.

  6. No terminal, inicie a CLI do Gemini.

    gemini

  7. Conclua a configuração de autenticação da CLI do Gemini.

  8. Configure a conexão de banco de dados. A extensão exige uma conexão de banco de dados para a geração de contexto, que é compatível com a MCP Toolbox e 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 the database connection e siga as instruções fornecidas pela skill. Para mais informações sobre o arquivo tools.yaml, consulte a documentação da MCP Toolbox.

  9. Para recarregar a configuração depois de criar o arquivo tools.yaml, execute o seguinte comando na CLI do Gemini:

    /mcp reload

  10. Verifique se a caixa de ferramentas do MCP e a extensão de enriquecimento do banco de dados estão conectadas e prontas para uso.

    /mcp list

Gerar contexto de modelo

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

Para gerar o contexto do modelo, siga estas etapas:

  1. Execute o comando /generate_targeted_templates e siga o fluxo de trabalho:

    /generate_targeted_templates

  2. Forneça a consulta em linguagem natural que você quer adicionar ao modelo no terminal.

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

  3. Forneça uma consulta SQL correspondente que você quer adicionar ao modelo. Esse modelo de consulta define o termo nighttime como ocorrendo entre 5:00 PM e 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. Pressione Enter. O Gemini converte sua entrada em um formato específico que refina a performance do conjunto de contextos em uma ampla variedade de consultas do usuário. Para mais informações, consulte Visão geral dos conjuntos de contexto.

    Se quiser, execute o fluxo de trabalho /generate_bulk_templates para que a CLI do Gemini gere mais contexto ao analisar o esquema do banco de dados e sugerir contexto relacionado.

  5. Revise o modelo de consulta gerado. É possível salvar o modelo de consulta como um novo arquivo de contexto do agente ou anexá-lo a um arquivo existente.

  6. Selecione a opção para criar um novo arquivo de contexto do agente. O Gemini cria um nome de arquivo INSTANCE_ID_DATABASE_ID_context_set_TIMESTAMP.json 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 de conjunto de contexto a mapear frases de valor para valores específicos armazenados nas colunas do banco de dados. Por exemplo, se um usuário perguntar "Voos para a Disney World", a pesquisa de valor poderá mapear isso para a Disney World na cidade de "Orlando" com base no tipo de conceito que se correlaciona à coluna airports.city no seu banco de dados.

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

  1. Execute o comando /generate_targeted_value_searches:

    /generate_targeted_value_searches

  2. Insira postgresql para selecionar o Cloud SQL como mecanismo de banco de dados.

  3. Insira a configuração de pesquisa de valor da seguinte forma:

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

  4. Confirme se você quer gerar a definição de pesquisa de valor.

  5. 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 de conjunto de contexto existente.

  6. Selecione a opção para adicionar ao final a um arquivo de conjunto de contexto existente. Isso adiciona a definição de pesquisa de valor ao arquivo de contexto criado na seção anterior.

  7. 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. O Gemini cria um nome de arquivo INSTANCE_ID_DATABASE_ID_context_set_TIMESTAMP.json 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 = $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"
      }
  ]
  }

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, melhorando 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 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. Opcional: edite a Descrição do conjunto de contexto.

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

  9. Clique em Salvar.

Gerar consulta SQL usando 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 definições para termos como nighttime traffic e outras frases relacionadas, e se a pesquisa de valores mapeia frases de valor para valores específicos armazenados nas colunas do banco de dados (por exemplo, mapeando "Disney World" para "Orlando").

Para gerar consultas SQL, siga estas etapas:

  1. No painel Explorer, ao lado do conjunto de contexto, clique em Ver ações.
  2. Clique em Testar conjunto de contexto.
  3. No editor de consultas, clique em Gerar SQL usando QueryData com: assistente de voos.

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

    flights to disney world

    A consulta SQL gerada é semelhante a esta:

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

    Observe que o QueryData agora pode interpretar com precisão que "disney world" se refere à cidade de "Orlando".

Integrar o QueryData ao seu aplicativo

Nesta seção, você vai criar um agente QueryData para um aplicativo de pesquisa de voos. Esse agente QueryData fornece uma interface de conversa para as tabelas flights e airports que você criou anteriormente. Ele também explica como criar e integrar esse agente QueryData ao seu aplicativo usando o Kit de Desenvolvimento de Agente (ADK), a ferramenta QueryData MCP do Gemini Data Analytics e o contexto definido para melhorar a qualidade das respostas.

  1. Baixe a versão 0.31.0 ou mais recente da MCP Toolbox. A MCP Toolbox expõe o agente QueryData como uma ferramenta para os aplicativos se conectarem. A caixa de ferramentas do MCP é diferente da extensão da CLI do Gemini para a caixa de ferramentas do MCP que você instalou antes, que gera contexto.

  2. Configure as Application Default Credentials (ADC).

    gcloud auth application-default login

  3. Encontre o ID do conjunto de contexto. Para mais informações sobre como encontrar o ID do conjunto de contexto, consulte Encontrar o ID do conjunto de contexto.

  4. Crie a configuração tools.yaml para se conectar ao agente QueryData usando a caixa de ferramentas do MCP. Para mais informações, consulte Origem da análise de dados do Gemini e a 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: "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

    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 sua 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 mais informações sobre como encontrar o ID do conjunto de contexto, consulte Encontrar o ID do conjunto de contexto.

  5. Execute o servidor da MCP Toolbox com o arquivo tools.yaml.

    ./toolbox --config "tools.yaml"

  6. Crie um aplicativo ADK que invoque a ferramenta QueryData do Gemini Data Analytics usando o SDK do Python da MCP Toolbox. Para mais informações sobre como usar o SDK da caixa de ferramentas do MCP para Python, consulte o guia de início rápido da caixa de ferramentas 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. Mude 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.

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

    4. Configure um agente do ADK.

      1. Crie um agente do ADK.

        adk create my_agent

      2. Selecione o modelo gemini-2.5-flash.

      3. Selecione Google AI e insira sua chave da API Gemini. Para saber como encontrar sua chave de API, consulte Como usar chaves de API do Gemini.

    5. Substitua o conteúdo do arquivo agent.py pelo seguinte exemplo de código do aplicativo do 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-2.5-flash",
    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.

    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 necessárias do MCP.

  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 MCP retorna os dados associados para o agente usar na construçã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.

    Get me flights to disney world

    Com base no contexto de pesquisa de valor adicionado anteriormente, o agente QueryData entende que disney world se relaciona à cidade Orlando e retorna os dados associados para que o agente QueryData use na construção da resposta.

    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.

Iterar a performance do agente

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

Por exemplo, para o texto de entrada How many flights depart from the west side? que você inseriu antes, clique na bolha 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?"]}"

Melhorar a precisão da resposta

Você pode refinar continuamente a precisão das respostas da ferramenta QueryData do Gemini Data Analytics adicionando mais contexto. Use a CLI do Gemini para gerar contexto e faça upload do arquivo de conjunto de contexto atualizado para o agente flights-assistant QueryData atual. Para mais informações, consulte Criar contextos usando a CLI do Gemini. O console ingere imediatamente o novo contexto depois que você faz upload dele, permitindo melhorar a precisão do agente sem tempo de inatividade do aplicativo.

Vários agentes

No ambiente de desenvolvimento, é possível realizar testes A/B em vários contextos de agente QueryData 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 QueryData para uma fonte de banco de dados:

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

Substitua:

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

Limpar

As seções a seguir descrevem como excluir esses recursos e objetos.

Excluir o conjunto de contextos

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

  1. No console 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 Ver 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 digitando o nome dela e clicando em Excluir.

A seguir