1. Introdução
Neste codelab, você vai criar um agente usando o Kit de Desenvolvimento de Agentes (ADK), que utiliza a MCP Toolbox for Databases.
Durante o codelab, você vai usar uma abordagem gradual da seguinte forma:
- Provisione um banco de dados do Cloud SQL para PostgreSQL que tenha o banco de dados de hotéis e dados de amostra.
- Configure o MCP Toolbox for Databases, que fornece acesso aos dados.
- Projete e desenvolva um agente usando o Kit de Desenvolvimento de Agentes (ADK) que vai usar a caixa de ferramentas do MCP para responder às consultas do usuário.
- Confira as opções para testar o agente e a caixa de ferramentas do MCP para bancos de dados localmente e no Google Cloud usando o serviço do Cloud Run.
O que você aprenderá
- Projete, crie e implante um agente que responda às consultas dos usuários sobre hotéis em um local ou pesquise hotéis por nome.
O que você vai aprender
- Provisionamento e preenchimento de um banco de dados do Cloud SQL para PostgreSQL com dados de amostra.
- Configure a caixa de ferramentas do MCP para bancos de dados na instância do banco de dados do Cloud SQL para PostgreSQL.
- Projete e desenvolva um agente usando o Kit de Desenvolvimento de Agentes (ADK) para responder às consultas do usuário.
- Teste o agente e a MCP Toolbox for Databases no ambiente local.
- (Opcional) Implante o agente e a MCP Toolbox for Databases no Google Cloud.
O que é necessário
- Navegador da Web Google Chrome
- Uma conta do Gmail
- Um projeto do Cloud com faturamento ativado
Este codelab, criado para desenvolvedores de todos os níveis (incluindo iniciantes), usa Python no aplicativo de exemplo. No entanto, não é necessário ter conhecimento de Python, e a capacidade básica de leitura de código é suficiente para entender os conceitos apresentados.
2. Antes de começar
Criar um projeto
- No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
- Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto .
- Você vai usar o Cloud Shell, um ambiente de linha de comando executado no Google Cloud que vem pré-carregado com bq. Clique em "Ativar o Cloud Shell" na parte de cima do console do Google Cloud.
- Depois de se conectar ao Cloud Shell, verifique se sua conta já está autenticada e se o projeto está configurado com seu ID do projeto usando o seguinte comando:
gcloud auth list
- Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto.
gcloud config list project
- Se o projeto não estiver definido, use este comando:
gcloud config set project <YOUR_PROJECT_ID>
- Ative as APIs necessárias com o comando mostrado abaixo. Isso pode levar alguns minutos.
gcloud services enable cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudfunctions.googleapis.com \
aiplatform.googleapis.com \
sqladmin.googleapis.com \
compute.googleapis.com
Após a execução do comando, você vai ver uma mensagem semelhante a esta:
Operation "operations/..." finished successfully.
A alternativa ao comando gcloud é pesquisar cada produto no console ou usar este link.
Se alguma API for esquecida, você sempre poderá ativá-la durante a implementação.
Consulte a documentação para ver o uso e os comandos gcloud.
3. crie uma instância do Cloud SQL
Vamos usar uma instância do Google Cloud SQL para PostgreSQL para armazenar os dados dos hotéis. O Cloud SQL para PostgreSQL é um serviço de banco de dados totalmente gerenciado que ajuda a configurar, manter, gerenciar e administrar seus bancos de dados relacionais PostgreSQL no Google Cloud Platform.
Execute o seguinte comando no Cloud Shell para criar a instância:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--tier db-g1-small \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
Esse comando leva de 3 a 5 minutos para ser executado. Depois que o comando for executado, você vai ver uma saída indicando que ele foi concluído, além das informações da instância do Cloud SQL, como NAME, DATABASE_VERSION, LOCATION etc.
4. Preparar o banco de dados de hotéis
Nossa tarefa agora é criar alguns dados de amostra para o agente de hotel.
Acesse a página do Cloud SQL no console do Google Cloud.O hoteldb-instance vai estar pronto e criado. Clique no nome da instância (hoteldb-instance), conforme mostrado abaixo:
No menu à esquerda do Cloud SQL, acesse a opção Cloud SQL Studio, conforme mostrado abaixo:
Isso vai pedir que você faça login no Cloud SQL Studio, em que vamos dar alguns comandos SQL. Selecione postgres para a opção "Banco de dados" e, para "Usuário" e "Senha", o valor a ser usado é postgres. Clique em AUTHENTICATE.
Primeiro, vamos criar a tabela de hotéis de acordo com o esquema abaixo. Em um dos painéis do editor no Cloud SQL Studio, execute o seguinte SQL:
CREATE TABLE hotels(
id INTEGER NOT NULL PRIMARY KEY,
name VARCHAR NOT NULL,
location VARCHAR NOT NULL,
price_tier VARCHAR NOT NULL,
checkin_date DATE NOT NULL,
checkout_date DATE NOT NULL,
booked BIT NOT NULL
);
Agora, vamos preencher a tabela "hotels" com dados de amostra. Execute o seguinte SQL:
INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked)
VALUES
(1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-20', '2024-04-22', B'0'),
(2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'),
(3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'),
(4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-05', '2024-04-24', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-01', '2024-04-23', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-02', '2024-04-27', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-09', '2024-04-24', B'0'),
(9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'),
(10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0');
Vamos validar os dados executando um SQL SELECT, conforme mostrado abaixo:
SELECT * FROM hotels;
Você vai encontrar vários registros na tabela "hotels", como mostrado abaixo:
Concluímos o processo de configuração de uma instância do Cloud SQL e criamos nossos dados de exemplo. Na próxima seção, vamos configurar a MCP Toolbox for Databases.
5. Configurar a MCP Toolbox for Databases
A MCP Toolbox for Databases é um servidor MCP de código aberto para bancos de dados. Ela foi projetada com qualidade de produção e nível empresarial em mente. Ele permite desenvolver ferramentas com mais facilidade, rapidez e segurança, lidando com complexidades como pool de conexões, autenticação e muito mais.
A caixa de ferramentas ajuda você a criar ferramentas de IA generativa que permitem que seus agentes acessem dados no seu banco de dados. A caixa de ferramentas oferece:
- Desenvolvimento simplificado: integre ferramentas ao seu agente em menos de 10 linhas de código, reutilize ferramentas entre vários agentes ou frameworks e implante novas versões de ferramentas com mais facilidade.
- Melhor desempenho: práticas recomendadas, como pooling de conexões, autenticação e muito mais.
- Segurança reforçada: autenticação integrada para acesso mais seguro aos seus dados
- Observabilidade de ponta a ponta: métricas e rastreamento prontos para uso com suporte integrado ao OpenTelemetry.
A caixa de ferramentas fica entre o framework de orquestração do aplicativo e o banco de dados, fornecendo um plano de controle usado para modificar, distribuir ou invocar ferramentas. Ele simplifica o gerenciamento das suas ferramentas ao fornecer um local centralizado para armazenar e atualizar ferramentas, permitindo que você compartilhe ferramentas entre agentes e aplicativos e atualize essas ferramentas sem precisar reimplantar o aplicativo.
Um dos bancos de dados compatíveis com a caixa de ferramentas do MCP para bancos de dados é o Cloud SQL, que provisionamos na seção anterior.
Instalar a caixa de ferramentas
Abra o terminal do Cloud Shell e crie uma pasta chamada mcp-toolbox.
mkdir mcp-toolbox
Acesse a pasta mcp-toolbox com o comando abaixo:
cd mcp-toolbox
Instale a versão binária da MCP Toolbox for Databases usando o script abaixo. O comando abaixo é para Linux, mas, se você estiver usando Mac ou Windows, baixe o binário correto. Confira a página de versões do seu sistema operacional e arquitetura e faça o download do binário correto.
export VERSION=0.13.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Agora temos a versão binária da caixa de ferramentas pronta para uso. A próxima etapa é configurar a caixa de ferramentas com nossas fontes de dados e outras configurações.
Como configurar o tools.yaml
A principal maneira de configurar a caixa de ferramentas é pelo arquivo tools.yaml. Crie um arquivo chamado tools.yaml na mesma pasta, ou seja, mcp-toolbox. O conteúdo dele é mostrado abaixo.
Você pode usar o editor nano disponível no Cloud Shell. O comando nano é o seguinte: "nano tools.yaml".
Substitua o valor YOUR_PROJECT_ID pelo ID do seu projeto do Google Cloud.
sources:
my-cloud-sql-source:
kind: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: "postgres"
tools:
search-hotels-by-name:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on name.
parameters:
- name: name
type: string
description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
search-hotels-by-location:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on location. Result is sorted by price from least to most expensive.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: |
SELECT *
FROM hotels
WHERE location ILIKE '%' || $1 || '%'
ORDER BY
CASE price_tier
WHEN 'Midscale' THEN 1
WHEN 'Upper Midscale' THEN 2
WHEN 'Upscale' THEN 3
WHEN 'Upper Upscale' THEN 4
WHEN 'Luxury' THEN 5
ELSE 99 -- Handle any unexpected values, place them at the end
END;
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
Vamos entender o arquivo brevemente:
Sourcesrepresentam as diferentes fontes de dados com que uma ferramenta pode interagir. Uma origem representa uma fonte de dados com que uma ferramenta pode interagir. É possível definirSourcescomo um mapa na seção "sources" do arquivo tools.yaml. Normalmente, uma configuração de origem contém todas as informações necessárias para se conectar e interagir com o banco de dados. No nosso caso, configuramos uma única origem que aponta para nossa instância do Cloud SQL para PostgreSQL com as credenciais. Para mais informações, consulte a referência Fontes.- Os
Toolsdefinem as ações que um agente pode realizar, como ler e gravar em uma fonte. Uma ferramenta representa uma ação que o agente pode realizar, como executar uma instrução SQL. É possível definirToolscomo um mapa na seção "tools" do arquivo tools.yaml. Normalmente, uma ferramenta precisa de uma fonte para agir. No nosso caso, estamos definindo duas ferramentas:search-hotels-by-nameesearch-hotels-by-location, e especificando a origem em que ela está atuando, junto com o SQL e os parâmetros. Para mais informações, consulte a referência de Ferramentas. - Por fim, temos o
Toolset, que permite definir grupos de ferramentas que você quer carregar juntas. Isso pode ser útil para definir diferentes grupos com base no agente ou no aplicativo. No nosso caso, temos um único conjunto de ferramentas chamadomy_first_toolset, que contém as duas ferramentas definidas.
Executar o servidor da caixa de ferramentas do MCP para bancos de dados
Execute o seguinte comando (na pasta mcp-toolbox) para iniciar o servidor:
./toolbox --tools-file "tools.yaml"
O ideal é que você veja uma saída informando que o servidor conseguiu se conectar às nossas fontes de dados e carregou o conjunto de ferramentas e as ferramentas. Confira um exemplo de saída abaixo:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!"
Por padrão, o servidor da caixa de ferramentas do MCP é executado na porta 5000. Se você descobrir que a porta 5000 já está em uso, use outra porta (por exemplo, 7000), conforme o comando mostrado abaixo. Use 7000 em vez da porta 5000 nos comandos subsequentes.
./toolbox --tools-file "tools.yaml" --port 7000
Vamos usar o Cloud Shell para testar isso.
Clique em "Visualização da Web" no Cloud Shell, conforme mostrado abaixo:
Clique em Alterar porta, defina a porta como 5000, conforme mostrado abaixo, e clique em "Alterar e visualizar".
Isso vai gerar a seguinte saída:
No URL do navegador, adicione o seguinte ao final:
/api/toolset
Isso vai abrir as ferramentas configuradas no momento. Confira um exemplo de saída abaixo:
{
"serverVersion": "0.13.0+binary.linux.amd64.1a6dfe8d37d0f42fb3fd3f75c50988534dbc1b85",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location. Result is sorted by price from least to most expensive.",
"parameters": [
{
"name": "location",
"type": "string",
"required": true,
"description": "The location of the hotel.",
"authSources": []
}
],
"authRequired": []
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"required": true,
"description": "The name of the hotel.",
"authSources": []
}
],
"authRequired": []
}
}
}
Testar as ferramentas na interface do MCP Toolbox for Databases
A caixa de ferramentas oferece uma interface visual (IU da caixa de ferramentas) para interagir diretamente com as ferramentas modificando parâmetros, gerenciando cabeçalhos e executando chamadas, tudo em uma interface da Web simples.
Para testar isso, execute o comando anterior que usamos para iniciar o servidor da caixa de ferramentas com uma opção --ui.
Para fazer isso, encerre a instância anterior do servidor da caixa de ferramentas MCP para bancos de dados que você pode estar executando e execute o seguinte comando:
./toolbox --tools-file "tools.yaml" --ui
O ideal é que você veja uma saída informando que o servidor conseguiu se conectar às nossas fontes de dados e carregou o conjunto de ferramentas e as ferramentas. Confira abaixo um exemplo de saída. Você vai notar que ela menciona que a interface da caixa de ferramentas está funcionando.
2025-09-08T02:44:11.561572538Z INFO "Initialized 1 sources."
2025-09-08T02:44:11.561966395Z INFO "Initialized 0 authServices."
2025-09-08T02:44:11.562060934Z INFO "Initialized 2 tools."
2025-09-08T02:44:11.562105678Z INFO "Initialized 2 toolsets."
2025-09-08T02:44:11.568209923Z INFO "Server ready to serve!"
2025-09-08T02:44:11.568259411Z INFO "Toolbox UI is up and running at: http://localhost:5000/ui"
Clique no URL da interface e verifique se você tem /ui no final do URL. Isso vai mostrar uma interface como esta:
Clique na opção "Ferramentas" à esquerda para ver as ferramentas configuradas. No nosso caso, devem ser duas: search-hotels-by-name e search-hotels-by-location, conforme mostrado abaixo:
Basta clicar em uma das ferramentas (search-hotels-by-location) para abrir uma página em que você pode testar a ferramenta. Para isso, forneça os valores de parâmetro necessários e clique em Executar ferramenta para ver o resultado. Confira um exemplo de execução abaixo:
O MCP Toolkit for Databases também descreve uma maneira Pythonic de validar e testar as ferramentas, que está documentada aqui. Vamos pular essa parte e passar direto para o Kit de desenvolvimento de agentes (ADK) na próxima seção, que vai usar essas ferramentas.
6. Como escrever nosso agente com o Kit de Desenvolvimento de Agente (ADK)
Instalar o Kit de Desenvolvimento de Agente (ADK)
Abra uma nova guia do terminal no Cloud Shell e crie uma pasta chamada my-agents da seguinte maneira. Navegue até a pasta my-agents também.
mkdir my-agents
cd my-agents
Agora, vamos criar um ambiente Python virtual usando venv da seguinte maneira:
python -m venv .venv
Ative o ambiente virtual da seguinte maneira:
source .venv/bin/activate
Instale o ADK e os pacotes do MCP Toolbox for Databases com a dependência do langchain da seguinte maneira:
pip install google-adk toolbox-core
Agora você pode invocar o utilitário adk da seguinte maneira.
adk
Uma lista de comandos vai aparecer.
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
create Creates a new app in the current folder with prepopulated agent template.
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
Como criar nosso primeiro aplicativo de agente
Agora vamos usar adk para criar uma estrutura para nosso aplicativo de agente de hotel usando o comando adk create com o nome do app **(hotel-agent-app)**, conforme mostrado abaixo.
adk create hotel-agent-app
Siga as etapas e selecione o seguinte:
- Modelo do Gemini para escolher um modelo para o agente raiz.
- Escolha a Vertex AI para o back-end.
- O ID e a região padrão do projeto do Google vão aparecer. Selecione o padrão.
Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [YOUR_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in <YOUR_HOME_FOLDER>/my-agents/hotel-agent-app:
- .env
- __init__.py
- agent.py
Observe a pasta em que um modelo padrão e os arquivos necessários para o agente foram criados.
Primeiro, o arquivo .env. O conteúdo dele é mostrado abaixo:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
Os valores indicam que vamos usar o Gemini pela Vertex AI com os respectivos valores do ID e local do projeto do Google Cloud.
Em seguida, temos o arquivo __init__.py, que marca a pasta como um módulo e tem uma única instrução que importa o agente do arquivo agent.py.
from . import agent
Por fim, vamos conferir o arquivo agent.py. O conteúdo é mostrado abaixo:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
Esse é o agente mais simples que você pode escrever com o ADK. Na página da documentação do ADK, um agente é uma unidade de execução independente projetada para agir de forma autônoma e alcançar metas específicas. Os agentes podem realizar tarefas, interagir com usuários, usar ferramentas externas e se coordenar com outros agentes.
Especificamente, um LLMAgent, geralmente conhecido como Agent, usa modelos de linguagem grandes (LLMs) como mecanismo principal para entender a linguagem natural, raciocinar, planejar, gerar respostas e decidir dinamicamente como proceder ou quais ferramentas usar, o que os torna ideais para tarefas flexíveis e centradas na linguagem. Saiba mais sobre os agentes de LLM neste link.
Vamos modificar o código do agent.py da seguinte maneira:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='hotel_agent',
description='A helpful assistant that answers questions about a specific city.',
instruction='Answer user questions about a specific city to the best of your knowledge. Do not answer questions outside of this.',
)
Testar o app do agente localmente
Na janela de terminal aberta, execute o seguinte comando. Confirme se você está na pasta mãe (my-agents) que contém a pasta hotel-agent-app.
adk web
Confira um exemplo de execução abaixo:
INFO: Started server process [1478]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Clique no último link para abrir um console da Web e testar o agente. Você vai ver o seguinte no navegador, conforme mostrado abaixo:
No canto superior esquerdo, o hotel-agent-app foi identificado. Agora você pode começar a conversar com o agente. Forneça alguns comandos perguntando sobre cidades. Confira um exemplo de conversa abaixo:
Você pode encerrar o processo em execução no terminal do Cloud Shell (Ctrl-C).
Uma maneira alternativa de testar o agente é usando o comando adk run, conforme mostrado abaixo, na pasta my-agents.
adk run hotel-agent-app
Teste o comando e converse com o agente pela linha de comando (terminal). Digite exit para fechar a conversa.
7. Conectar nosso agente a ferramentas
Agora que sabemos como escrever um agente e testá-lo localmente. Vamos conectar esse agente às ferramentas. No contexto do ADK, uma ferramenta representa uma capacidade específica fornecida a um agente de IA, permitindo que ele execute ações e interaja com o mundo além das habilidades básicas de geração de texto e raciocínio.
No nosso caso, vamos equipar nosso agente com as ferramentas que configuramos na MCP Toolbox for Databases.
Modifique o arquivo agent.py com o seguinte código. Observe que estamos usando a porta padrão 5000 no código, mas se você estiver usando um número de porta alternativo, use esse número.
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load single tool
# tools = toolbox.load_tool('search-hotels-by-location')
# Load all the tools
tools = toolbox.load_toolset('my_first_toolset')
root_agent = Agent(
name="hotel_agent",
model="gemini-2.5-flash",
description=(
"Agent to answer questions about hotels in a city or hotels by name."
),
instruction=(
"You are a helpful agent who can answer user questions about the hotels in a specific city or hotels by name. Use the tools to answer the question"
),
tools=tools,
)
Agora podemos testar o agente que vai buscar dados reais do nosso banco de dados PostgreSQL, que foi configurado com a caixa de ferramentas do MCP para bancos de dados.
Para fazer isso, siga esta sequência:
Em um terminal do Cloud Shell, inicie a MCP Toolbox for Databases. Talvez ele já esteja sendo executado localmente na porta 5000, como testamos antes. Se não estiver, execute o seguinte comando (na pasta mcp-toolbox) para iniciar o servidor:
./toolbox --tools_file "tools.yaml"
O ideal é que você veja uma saída informando que o servidor conseguiu se conectar às nossas fontes de dados e carregou o conjunto de ferramentas e as ferramentas. Confira um exemplo de saída abaixo:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!"
Depois que o servidor MCP for iniciado, em outro terminal, inicie o agente como fizemos antes usando o comando adk run (da pasta my-agents) mostrado abaixo. Se preferir, use o comando adk web.
$ adk run hotel-agent-app/
Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent hotel_agent, type exit to exit.
user: what can you do for me?
[hotel_agent]: I can help you find hotels in a specific city or search for hotels by name.
user: I would like to search for hotels
[hotel_agent]: Great, do you have a specific city or hotel name in mind?
user: Yes a specific city
[hotel_agent]: Great, which city are you interested in?
user: Basel
[hotel_agent]: OK. I found three hotels in Basel: Hilton Basel, Hyatt Regency Basel, and Holiday Inn Basel.
O agente agora está usando as duas ferramentas que configuramos no MCP Toolbox for Databases (search-hotels-by-name e search-hotels-by-location) e fornecendo as opções corretas. Em seguida, ele pode recuperar os dados do banco de dados da instância do PostgreSQL e formatar a resposta de acordo.
Isso conclui o desenvolvimento e o teste locais do nosso agente de hotel, que criamos usando o Kit de Desenvolvimento de Agentes (ADK) e que foi alimentado por ferramentas configuradas na MCP Toolbox for Databases.
8. (Opcional) Como implantar a MCP Toolbox for Databases e o agente no Cloud Run
Na seção anterior, usamos o terminal do Cloud Shell para iniciar o servidor da caixa de ferramentas do MCP e testamos as ferramentas com o agente. Isso estava sendo executado localmente no ambiente do Cloud Shell.
Você pode implantar o servidor da caixa de ferramentas do MCP e o agente nos serviços do Google Cloud que podem hospedar esses aplicativos para nós.
Hospedagem do servidor da caixa de ferramentas do MCP no Cloud Run
Primeiro, podemos começar com o servidor da caixa de ferramentas do MCP e hospedá-lo no Cloud Run. Isso nos daria um endpoint público que pode ser integrado a qualquer outro aplicativo e/ou aos aplicativos do agente também. As instruções para hospedar isso no Cloud Run estão aqui. Vamos analisar as etapas principais agora.
Inicie um novo terminal do Cloud Shell ou use um terminal existente. Acesse a pasta mcp-toolbox, em que o binário toolbox e tools.yaml estão presentes.
Execute os comandos a seguir (uma explicação é fornecida para cada comando):
Defina a variável PROJECT_ID para apontar para o ID do projeto do Google Cloud.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
Em seguida, verifique se os seguintes serviços do Google Cloud estão ativados no projeto.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
Vamos criar uma conta de serviço separada que vai atuar como a identidade do serviço da caixa de ferramentas que vamos implantar no Google Cloud Run. Também estamos garantindo que essa conta de serviço tenha as funções corretas, ou seja, a capacidade de acessar o Secret Manager e se comunicar com o Cloud SQL.
gcloud iam service-accounts create toolbox-identity
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/secretmanager.secretAccessor
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/cloudsql.client
Vamos fazer upload do arquivo tools.yaml como um secret. Como precisamos instalar a caixa de ferramentas no Cloud Run, vamos usar a imagem de contêiner mais recente para a caixa de ferramentas e definir isso na variável IMAGE.
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
A última etapa do comando de implantação conhecido no Cloud Run:
gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
Isso vai iniciar o processo de implantação do Toolbox Server com nosso tools.yaml configurado no Cloud Run. Se a implantação for bem-sucedida, você vai receber uma mensagem semelhante a esta:
Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.
OK Creating Revision...
OK Routing traffic...
OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app
Agora você pode acessar o Service URL listado acima no navegador. Ela vai mostrar a mensagem "Hello World" que vimos antes. Além disso, você pode acessar o seguinte URL para conferir as ferramentas disponíveis:
SERVICE URL/api/toolset
Você também pode acessar o Cloud Run no console do Google Cloud. O serviço da caixa de ferramentas vai aparecer na lista de serviços do Cloud Run.
Observação: se você quiser continuar executando o agente de hotel localmente e se conectar ao serviço do Cloud Run recém-implantado, basta fazer uma mudança no arquivo my-agents/hotel-agent-app/agent.py.
Em vez do seguinte:
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
Mude para o URL do serviço do Cloud Run, conforme mostrado abaixo:
toolbox = ToolboxSyncClient("CLOUD_RUN_SERVICE_URL")
Teste o aplicativo do agente usando adk run ou adk web, como vimos antes.
Como implantar o app Hotel Agent no Cloud Run
A primeira etapa é garantir que você fez a mudança em my-agents/hotel-agent-app/agent.py, conforme instruído acima, para apontar para o URL do serviço da caixa de ferramentas em execução no Cloud Run e não no host local.
Em um novo terminal do Cloud Shell ou em uma sessão de terminal atual, verifique se você está no ambiente virtual do Python correto que configuramos anteriormente.
Primeiro, vamos criar um arquivo requirements.txt na pasta my-agents/hotel-agent-app, conforme mostrado abaixo:
google-adk
toolbox-core
Navegue até a pasta my-agents e defina as seguintes variáveis de ambiente primeiro:
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_PATH="hotel-agent-app/"
export SERVICE_NAME="hotels-service"
export APP_NAME="hotels-app"
export GOOGLE_GENAI_USE_VERTEXAI=True
Por fim, vamos implantar o aplicativo do agente no Cloud Run usando o comando adk deploy cloud_run, conforme mostrado abaixo. Se for solicitado que você permita invocações não autenticadas ao serviço, forneça "y" como valor por enquanto.
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
Isso vai iniciar o processo de implantação do aplicativo do agente de hotel no Cloud Run. Ele vai fazer upload das fontes, empacotá-las em um contêiner do Docker, enviar para o Artifact Registry e implantar o serviço no Cloud Run. Isso pode levar alguns minutos.
Você vai ver uma mensagem semelhante a esta:
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250905_132636
Copying agent source code...
Copying agent source code completed.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250905_132636/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_PROJECT_ID] region [us-central1]
- Building and deploying... Uploading sources.
- Uploading sources...
. Building Container...
OK Building and deploying... Done.
OK Uploading sources...
OK Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds;region=us-central1/d1f7e76b-0587-4bb6-b9c0-bb4360c07aa0?project=415
458962931]. f
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00003-hrl] has been deployed and is serving 100 percent of traffic.
Service URL: <YOUR_CLOUDRUN_APP_URL>
INFO: Display format: "none"
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250905_132636
Quando a implantação for concluída, você vai receber um valor para o URL do serviço, que pode ser acessado no navegador para ver o mesmo aplicativo da Web que permitiu conversar com o agente de hotel, como vimos antes na configuração local.
9. Limpeza
Para evitar cobranças contínuas na sua conta do Google Cloud, exclua os recursos criados durante este workshop. Vamos excluir a instância do Cloud SQL e, opcionalmente, se você tiver implantado a caixa de ferramentas e o app Hotels no Cloud Run, também vamos excluir esses serviços.
Verifique se as seguintes variáveis de ambiente estão definidas corretamente, de acordo com seu projeto e região:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
Os dois comandos a seguir excluem os serviços do Cloud Run que implantamos:
gcloud run services delete toolbox --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
gcloud run services delete hotels-service --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
O comando a seguir exclui a instância do Cloud SQL:
gcloud sql instances delete hoteldb-instance
10. Parabéns
Parabéns! Você criou um agente usando o Kit de Desenvolvimento de Agentes (ADK) que utiliza a MCP Toolbox for Databases.