Integrar o QueryData a um aplicativo

Neste tutorial, descrevemos como configurar e usar o QueryData no Cloud SQL para MySQL usando o console Cloud de Confiance e integrar 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 Cloud de Confiance by S3NS:

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

Novos usuários do Cloud de Confiance by S3NS 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: o ID do seu projeto do Cloud de Confiance by S3NS .
  • INSTANCE_ID: o ID da sua instância do Cloud SQL.
Para realizar as etapas deste tutorial, faça login em Cloud de Confiance by S3NS 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 Cloud de Confiance , 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 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 faça pesquisas de valor semântico, ative as seguintes flags.

    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 faça pesquisas de valores de trigramas, siga estas etapas.

    1. Ative a flag ngram_token_size.

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

    2. Crie um índice FULLTEXT para correspondência de trigramas no nome do aeroporto

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

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 Cloud de Confiance by S3NS , 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.

    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á aeroporto ou cidade desse tipo no banco de dados, a consulta não retorna 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 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 pedir "voos para Manhattan", primeiro Manhattan será extraído como uma frase de valor, e a pesquisa de similaridade semântica vai associar Manhattan a "Nova York", que é armazenado na coluna airports.city.

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

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

    Table: airports
Column: name
Concept: airport name
Match Function: TRIGRAM_STRING_MATCH

  5. Repita o processo para a correspondência semântica.

    Table: airports
Column: city
Concept: airport city
Match Function: SEMANTIC_STRING_MATCH
Column Embedding: city_embedding

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

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

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

  9. 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 = ? 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, 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 Cloud de Confiance , 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 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 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. Na janela Gerar SQL usando QueryData com: flights-assistant, clique em Editar.

  9. Insira a seguinte pergunta 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 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: "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 Cloud de Confiance .
    • 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. Faça uma pergunta com base no tipo de conceito que você adicionou ao contexto do agente.

    Find flights heading into Manhattan

    Com base no contexto de pesquisa de valor adicionado anteriormente, o agente entende que Manhattan se relaciona à cidade New 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 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 Cloud de Confiance by S3NS .
  • 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 Cloud de Confiance , 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 Cloud de Confiance , 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