Neste tutorial, descrevemos como configurar e usar o QueryData no AlloyDB para PostgreSQL usando o console do Google Cloud e 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 Análise conversacional 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
Este tutorial aborda os seguintes objetivos:
- Criar bancos de dados e preenchê-los com dados.
- Crie um arquivo de conjunto de contexto com o agente de engenharia de contexto.
- Crie um conjunto de contextos e faça upload de um arquivo de conjunto de contextos.
- Teste o QueryData e gere consultas SQL no AlloyDB 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 deste documento. Para mais informações, consulte Limpeza.
Antes de começar
Conclua os seguintes pré-requisitos antes de criar um conjunto de contexto.
Ativar serviços obrigatórios
Ative os seguintes serviços para seu projeto:Preparar um cluster, uma instância e um banco de dados do AlloyDB para PostgreSQL
Verifique se você tem acesso a um cluster e uma instância do AlloyDB ou crie um novo.Para este tutorial, é necessário ter um banco de dados na instância do AlloyDB. Para mais informações, consulte Criar um banco de dados.
Papéis e permissões necessárias
- Ative a autenticação de banco de dados do Identity and Access Management (IAM) na instância definindo a flag de banco de dados
alloydb.iam_authenticationcomoon(alloydb.iam_authentication=on). Para mais informações, consulte Ativar e desativar a autenticação do IAM. - Adicione um usuário do IAM ou uma conta de serviço ao cluster no nível do banco de dados. Para mais informações, consulte Gerenciar a autenticação do IAM.
- Conceda os papéis
roles/alloydb.databaseUser,roles/serviceusage.serviceUsageConsumereroles/geminidataanalytics.queryDataUserao usuário do IAM no nível do projeto. Para mais informações, consulte Adicionar vinculação de política do IAM para um projeto. - Para criar, fazer upload e gerenciar conjuntos de contexto, conceda o papel de Editor do Dataplex Catalog
(
roles/dataplex.catalogEditor) ou Administrador do Dataplex Catalog (roles/dataplex.catalogAdmin) ao usuário do IAM no nível do projeto. Para mais informações, consulte Permissões de conjuntos de contexto. - Também é necessário conceder privilégios de banco de dados somente leitura ao usuário do IAM ou
à conta de serviço.
GRANT SELECT ON ALL TABLES IN SCHEMA public TO "USER_NAME";
Substitua USER_NAME pelo endereço de e-mail de um usuário ou pelo endereço da conta de serviço sem o sufixo.(por exemplo,my-sa@my-project.iam). Use aspas ao redor do identificador porque ele contém caracteres especiais (@ e .).
Para mais informações, consulte Conceder as permissões de banco de dados adequadas aos usuários do IAM.
Conceder permissão executesql à instância do AlloyDB para PostgreSQL
Para conceder a permissão executesql à instância do AlloyDB para PostgreSQL e definir
o campo de instância dataApiAccess como ENABLED (necessário para QueryData, mesmo que
o padrão permita alguns serviços internos do Google Cloud , como o AlloyDB Studio),
use o seguinte comando curl:
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID/instances/INSTANCE_ID?updateMask=dataApiAccess \
-d '{
"dataApiAccess": "ENABLED"
}'
PROJECT_ID: ID do seu projeto do Google Cloud .LOCATION: a região em que o cluster do AlloyDB está localizado.CLUSTER_ID: o ID do cluster do AlloyDB.INSTANCE_ID: o ID da instância do AlloyDB.
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.
No console do Google Cloud , acesse a página do AlloyDB.
Selecione um cluster na lista.
No menu de navegação, clique em AlloyDB Studio.
Faça login no Studio usando a autenticação do Identity and Access Management.
Clique em Autenticar. O painel Explorer mostra uma lista dos objetos no seu banco de dados.
Clique em Nova guia do editor de SQL ou Nova guia para abrir uma nova guia.
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 );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.
Preencha a tabela
airports.Preencha a tabela
flights.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;
Preparar o banco de dados para pesquisas de valor
Para usar pesquisas de valor semântico, configure o banco de dados do AlloyDB para oferecer suporte a embeddings de vetor e à integração com a Vertex AI, além de pré-computar embeddings para a coluna airports.city:
- Ative a API Vertex AI (
aiplatform.googleapis.com) no seu projeto.
Conceda ao agente de serviço do AlloyDB (
service-PROJECT_NUMBER@gcp-sa-alloydb.) o papel de Usuário da Vertex AI (roles/aiplatform.user). Para mais informações, consulte Integração com a Vertex AI.Conecte-se ao banco de dados como o usuário
postgres(ou um usuário com privilégios de extensão,ALTER TABLEeUPDATE) e ative as extensõesvectoregoogle_ml_integration:CREATE EXTENSION IF NOT EXISTS vector; CREATE EXTENSION IF NOT EXISTS google_ml_integration;Crie uma coluna de vetor para armazenar embeddings de cidades:
ALTER TABLE airports ADD COLUMN IF NOT EXISTS city_embedding vector(3072);Gere e armazene embeddings de vetor para nomes de cidades:
UPDATE airports SET city_embedding = google_ml.embedding('gemini-embedding-001', city)::vector WHERE city IS NOT NULL;
Criar um conjunto de contextos no AlloyDB Studio
Nesta seção, crie um conjunto de contexto chamado flights-assistant. Este conjunto de contexto não inclui nenhum arquivo de conjunto de contexto enviado por upload.
No console do Google Cloud , acesse a página do AlloyDB.
Selecione um cluster na lista.
No menu de navegação, clique em AlloyDB Studio.
Faça login no Studio usando a autenticação do IAM.
No painel Explorer, ao lado de Conjuntos de contexto, clique em Ver ações ().
Clique em Criar conjunto de contexto.
Em Nome do conjunto de contexto, insira
flights-assistant.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 de conjunto de contexto enviado, mesmo depois de fazer uma pergunta com contexto, como nighttime traffic, o QueryData gera uma consulta abaixo do ideal.
Você também faz uma pergunta ao conjunto de contexto flights-assistant, como "Quais voos partem de Raleigh?", para testar se ele consegue associar o nome da cidade ao valor armazenado no banco de dados (Raleigh-durham).
- No painel Explorer, ao lado do conjunto de contexto, clique em Ver ações ().
- Clique em Contexto de teste definido.
- No editor de consultas, clique em Gerar SQL usando o QueryData com: flights-assistant.
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';Na janela Gerar SQL usando QueryData com: flights-assistant, clique em Editar.
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 YorkO banco de dados não entende o termo tráfego de
nighttime. Isso pode impedir que ele gere uma consulta SQL ou fazer com que ele gere uma consulta que ignore o termo, como mostra a consulta a seguir.-- The database schema does not contain information about traffic. -- Returning all flights departing from New York airports. SELECT f.airline, f.flight_number, a.name AS departure_airport_name, f.departure_time, b.name AS arrival_airport_name, f.arrival_time FROM flights AS f JOIN airports AS a ON f.departure_airport = a.iata JOIN airports AS b ON f.arrival_airport = b.iata WHERE a.city = 'New York' ORDER BY f.departure_time;Na janela Gerar SQL usando QueryData com: flights-assistant, clique em Editar.
Insira a seguinte pergunta em linguagem natural para gerar uma consulta SQL e clique em Atualizar.
Which flights depart from Raleigh?A lógica do conjunto de contexto gera uma consulta que filtra por
"airports"."city" = 'Raleigh'. Como a colunaairports.cityarmazena'Raleigh-durham'em vez de'Raleigh', 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"."departure_airport" = "airports"."iata" WHERE "airports"."city" = 'Raleigh';
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:
- Instale a CLI do Antigravity. Para mais informações, consulte Primeiros passos com a CLI do Antigravity.
- Instale a CLI do Google Cloud.
Configure o Application Default Credentials (ADC). Execute os seguintes comandos no terminal para autenticar e selecionar seu projeto:
gcloud auth application-default login gcloud auth application-default set-quota-project PROJECT_IDInstale o
uv, um pacote Python e gerenciador de projetos que é um pré-requisito para o agente de engenharia de contexto. Se você ainda não tiver o Python no sistema, ouvpoderá instalá-lo para você.Instale o agente de engenharia de contexto:
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/pluginNo terminal, inicie a CLI do Antigravity.
agyConfigurar uma conexão de banco de dados para geração de contexto usando o MCP Toolbox. A conexão é definida no arquivo de configuração
.context-engineering/tools.yaml.Para criar o arquivo de configuração
.context-engineering/tools.yaml, insira um comando como:Help me set up a database connection.Siga as instruções fornecidas pela habilidade. Para mais informações sobre o arquivo
tools.yaml, consulte a documentação do MCP Toolbox.Para recarregar a configuração depois que o arquivo
.context-engineering/tools.yamlfor criado, execute o seguinte comando na CLI do Antigravity e siga as instruções para recarregar o servidor MCP da caixa de ferramentas:/mcpSelecione
db-context-engineering_toolbox.Selecione
Restart.
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 o tráfego que ocorre entre 5:00 PM e 7:00 PM.
Para gerar o contexto do modelo, siga estas etapas:
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;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.
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.
Peça ao agente para 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 a lógica de mapeamento de frases de valor para valores específicos armazenados nas colunas do banco de dados. Por exemplo, se um usuário perguntar "Quais voos partem de Raleigh?", a pesquisa de valor poderá mapear "Raleigh" para o valor de cidade armazenado "Raleigh-durham" na coluna airports.city do seu banco de dados.
Para gerar o contexto de pesquisa de valor, siga estas etapas:
Insira o seguinte comando na estrutura do agente:
Generate a value search on table "airports" for column "city" with concept "Airport City" using match function "SEMANTIC_SIMILARITY_MATCH" and embedding column "city_embedding".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 atual.
Envie o comando
Append the context to context_set.jsonpara o agente. Isso adiciona a definição de pesquisa de valor ao arquivo de contexto criado na seção anterior.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 = $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 search_embedding AS ( SELECT google_ml.embedding('gemini-embedding-001', $value)::vector AS val), SemanticMetrics AS ( SELECT T.city AS original_value, GREATEST(0.0, LEAST(1.0, (T.city_embedding <=> search_embedding.val) / 2.0)) AS normalized_dist FROM airports T, search_embedding WHERE T.city_embedding IS NOT NULL ORDER BY normalized_dist ASC LIMIT 10) 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" } ] }
Faça 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:
No console do Google Cloud , acesse a página do AlloyDB.
Selecione um cluster na lista.
No menu de navegação, clique em AlloyDB Studio.
Faça login no Studio usando a autenticação do Identity and Access Management.
No painel Explorer, em Conjuntos de contexto e ao lado do conjunto de contexto
flights-assistant, clique no ícone Ver ações ().Clique em Editar conjunto de contexto.
Clique em Procurar na seção Fazer upload do arquivo de contexto e selecione o arquivo de conjunto de contexto gerado anteriormente.
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, e se a pesquisa de valor mapeia frases de valor para valores específicos armazenados nas colunas do banco de dados (por exemplo, mapeando "Raleigh" para "Raleigh-durham").
Para gerar consultas SQL, siga estas etapas:
- No painel Explorer, ao lado do conjunto de contexto, clique em Ver ações ().
- Clique em Contexto de teste definido.
- No editor de consultas, clique em Gerar SQL usando o QueryData com: flights-assistant.
Para gerar uma consulta SQL, insira a seguinte pergunta em linguagem natural e clique em Gerar.
Tell me flights that can help me beat nighttime traffic if traveling from New YorkA consulta SQL gerada é semelhante a esta:
SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND ( EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19 ) ORDER BY f.departure_time;Essa é a mesma pergunta que você adicionou ao contexto de QueryData. Observe que o QueryData agora pode interpretar com precisão o termo
nighttime traffic.Embora o contexto tenha origem em uma pergunta específica, o QueryData o usa para melhorar a geração de SQL para uma ampla variedade de perguntas semelhantes.
Na janela Gerar SQL usando QueryData com: flights-assistant, clique em Editar.
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 BostonComo a pergunta substitui o termo
nighttime trafficpor 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;Na janela Gerar SQL usando QueryData com: flights-assistant, clique em Editar.
Insira a pergunta a seguir para gerar uma consulta SQL e clique em Atualizar.
Which flights depart from Raleigh?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"."departure_airport" = "airports"."iata" WHERE "airports"."city" = 'Raleigh-durham';Agora, o QueryData pode mapear "Raleigh" com precisão para o valor
"Raleigh-durham"armazenado na colunaairports.city.
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ção para as tabelas flights e airports que você criou anteriormente. Ele também explica como criar e integrar esse agente de dados ao seu aplicativo usando o Kit de Desenvolvimento de Agente (ADK), a ferramenta QueryData do MCP de análise de dados do Gemini e um conjunto de contexto para melhorar a qualidade das respostas.
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.
Configure o Application Default Credentials (ADC).
gcloud auth application-default login gcloud auth application-default set-quota-project PROJECT_IDEncontre 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.
Adicione o seguinte à configuração
.context-engineering/tools.yaml(outools.yamlno diretório de trabalho) para se conectar ao agente de dados usando a MCP Toolbox. Para mais informações, consulte Origem da análise de dados do Gemini e Ferramenta QueryData da análise de dados do Gemini.--- kind: source name: gda-api-source type: cloud-gemini-data-analytics projectId: "PROJECT_ID" --- kind: tool name: cloud_gda_query_tool type: cloud-gemini-data-analytics-query source: gda-api-source description: Use this tool to send natural language queries to the Gemini Data Analytics API and receive SQL, natural language answers, and explanations. location: "REGION_ID" context: datasourceReferences: alloydb: databaseReference: projectId: "PROJECT_ID" region: "REGION_ID" clusterId: "CLUSTER_ID" instanceId: "INSTANCE_ID" databaseId: "DATABASE_ID" agentContextReference: contextSetId: "CONTEXT_SET_ID" generationOptions: generateQueryResult: true generateNaturalLanguageAnswer: true generateExplanation: true generateDisambiguationQuestion: trueSubstitua:
PROJECT_ID: o ID do projeto do Google Cloud .REGION_ID: a região do cluster do AlloyDB (por exemplo,us-central1).CLUSTER_ID: o ID do cluster do AlloyDB.INSTANCE_ID: o ID da instância principal do AlloyDB.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.
Execute o servidor do MCP Toolbox com o arquivo
tools.yaml../toolbox --config PATH_TO_TOOLS_YAMLSubstitua
PATH_TO_TOOLS_YAMLpelo caminho para o arquivotools.yamlque você criou anteriormente (por exemplo,.context-engineering/tools.yamloutools.yaml).Crie 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 para Python da Toolbox do MCP, consulte o guia de início rápido da Toolbox. Para o ADK para Python, consulte o guia de início rápido do ADK.
- Crie um diretório para armazenar o aplicativo, por exemplo,
flight-assistant-app. Altere o diretório para
flight-assistant-app.mkdir flight-assistant-appcd flight-assistant-appExecute os comandos a seguir no diretório
flight-assistant-apppara criar um ambiente virtual e instalar os componentes necessários.uv inituv add google-adk toolbox-core google-genaiConfigurar um agente do ADK.
Criar um agente do ADK.
uv run adk create my_agentSelecione o modelo
gemini-2.5-flashou mais recente.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 de API Gemini. Como alternativa, se você não precisar de um teste sem custo financeiro, selecione Vertex AI, especifique um projeto do Google Cloud com o faturamento ativado e insira
globalquando for solicitada a região do Google Cloud (Enter Google Cloud region) para queGOOGLE_CLOUD_LOCATION=globalseja definido emmy_agent/.env.
Substitua o conteúdo do arquivo
agent.pypelo código do aplicativo de exemplo do Assistente de Dados de Voos abaixo.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", # Or newer. name="root_agent", instruction=INSTRUCTION, tools=cast(list[ToolUnion], [mcp_tool]), )
- Crie um diretório para armazenar o aplicativo, por exemplo,
Para iniciar o aplicativo, execute os seguintes comandos no diretório
flight-assistant-app. Acesse o servidor da Web do ADK emhttp://127.0.0.1:8000.uv run adk web --port 8000Insira 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.
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?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 trafficocorre 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:00Insira uma pergunta com base no tipo de conceito que você adicionou no contexto do agente QueryData.
Which flights depart from Raleigh?Com base no contexto de pesquisa de valor adicionado anteriormente, o agente QueryData mapeia "Raleigh" para a cidade
"Raleigh-durham"(código do aeroporto RDU) e retorna os dados associados para que o agente QueryData os use na construção da resposta.Here are the flights departing from Raleigh-Durham (RDU): * Flight UA 1552 departs from RDU on 2025-01-02 at 18:08:00 and arrives at SFO on 2025-01-02 at 20:51:00 (Departure Gate: B15, Arrival Gate: D48).
Iterar o desempenho do agente
A UI da Web do ADK permite inspecionar a solicitação e a resposta da ferramenta MCP QueryData do Gemini Data Analytics. Use essa resposta para observar as respostas da ferramenta, como consulta SQL gerada, conjunto de resultados, explicação da intenção, pergunta de desambiguação e 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 na
navegação à esquerda, expanda functionResponse para ver a resposta a seguir.
"{"disambiguationQuestion": ["[NOT_ENOUGH_INFO] The database schema does not
contain information about which airports are on the 'west side'. Therefore, I
cannot determine how many flights depart from the west side.Possible alternative
questions: 1. How many flights depart from a specific airport? 2. What are the
departure airports for all flights? 3. How many flights depart from each
airport?"]}"
Refinar a precisão da resposta
Você pode refinar continuamente a precisão das respostas da ferramenta QueryData da Análise de Dados do Gemini adicionando mais contexto. Use o agente de engenharia de contexto para gerar contexto e, em seguida, faça upload do arquivo de conjunto de contexto atualizado para o agente de dados flights-assistant atual. Para mais informações, consulte Gerenciar conjuntos de contexto no AlloyDB 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 ambiente de desenvolvimento, é possível realizar testes A/B em vários contextos de agentes de dados atribuindo nomes distintos às ferramentas no arquivo tools.yaml. Por exemplo, é possível criar configurações exclusivas de tools.yaml definindo duas ferramentas cloud-gemini-data-analytics-query com nomes diferentes, como cloud_gda_query_tool_v1 e cloud_gda_query_tool_v2. Essa configuração permite implementar uma lógica de aplicativo que seleciona de forma programática a versão de contexto necessária, escolhendo o nome da ferramenta correspondente.
O exemplo de tools.yaml a seguir mostra como configurar vários agentes de dados para uma fonte 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 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.DB_SOURCE: as configurações de origem do banco de dados.
Adicionar uma camada de acesso seguro usando visualizações SQL
Ao integrar o QueryData ao seu aplicativo, ele gera consultas SQL com base em entradas de linguagem natural. Para evitar que essas consultas geradas acessem dados fora do escopo de um usuário específico, implemente visualizações seguras parametrizadas (PSVs, na sigla em inglês). Para mais informações sobre PSVs, consulte Visão geral das visualizações seguras parametrizadas.
As PSVs fornecem uma camada de segurança que garante que o agente do QueryData só possa consultar linhas que o usuário atual do aplicativo tem autorização para acessar.
Essa camada de segurança envolve o seguinte:
- Como criar uma visualização segura parametrizada. Isso restringe o acesso no nível da linha com base em identidades fornecidas pelo aplicativo.
- Como configurar a segurança do aplicativo. Isso concede permissões
SELECTna visualização eUSAGEno esquema subjacente aos usuários autorizados do banco de dados. - Como consultar uma visualização segura parametrizada. Isso executa consultas na visualização transmitindo parâmetros de visualização aplicados pelo aplicativo em SQL ou no campo
parameterized_secure_view_parametersde uma solicitação QueryData.
Para um exemplo completo de como usar PSVs com conjuntos de contexto, consulte Proteger agentes de dados com visualizações seguras parametrizadas.
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 o cluster, exclua o conjunto de contexto que você criou.
No console do Google Cloud , acesse a página do AlloyDB.
Selecione um cluster na lista.
No menu de navegação, clique em AlloyDB Studio.
Faça login no Studio usando a autenticação do Identity and Access Management.
No painel Explorer, ao lado do conjunto de contexto, clique em Ver ações ().
Clique em Excluir conjunto de contexto.
Na janela Excluir conjunto de contexto, digite
flights-assistant.Clique em Confirmar.
excluir o cluster
Quando você exclui o cluster criado na seção Antes de começar, todos os objetos criados também são excluídos.
No console do Google Cloud , acesse a página do AlloyDB.
Selecione um cluster na lista.
Clique em Excluir cluster.
Em Excluir cluster, insira o nome do cluster para confirmar que você quer excluí-lo.
A seguir
- Saiba mais sobre os conjuntos de contexto.
- Saiba como definir o contexto criado para fontes de dados de banco de dados.