Criar um agente de viagens usando o MCP Toolbox for Databases e o Kit de Desenvolvimento de Agentes (ADK)
Sobre este codelab
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.
No codelab, você vai usar uma abordagem detalhada 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 o MCP Toolbox para responder às consultas do usuário.
- Conheça as opções para testar o agente e a Toolbox do MCP para bancos de dados localmente e no Google Cloud pelo serviço do Cloud Run.
O que você aprenderá
- Projete, crie e implante um agente que vai responder às consultas do usuário sobre hotéis em um local ou pesquisar hotéis por nome.
O que você vai aprender
- Provisionar e preencher um banco de dados do Cloud SQL para PostgreSQL com dados de amostra.
- Configure a MCP Toolbox 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 o MCP Toolbox for Databases no ambiente local.
- (Opcional) Implante o agente e o 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, desenvolvido para desenvolvedores de todos os níveis (inclusive iniciantes), usa o Python no aplicativo de exemplo. No entanto, não é necessário ter conhecimento de Python 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 você já está autenticado e se o projeto está definido como seu ID 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 usando o comando mostrado abaixo. Isso pode levar alguns minutos. Tenha paciência.
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
Se o comando for executado com sucesso, uma mensagem semelhante à mostrada abaixo vai aparecer:
Operation "operations/..." finished successfully.
A alternativa ao comando gcloud é pelo console, pesquisando cada produto ou usando este link.
Se alguma API for perdida, você 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 \
--cpu=2 \
--memory=8GiB \
--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 receber uma saída que indica que o comando 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
Agora, vamos criar alguns dados de amostra para o agente de hotéis.
Acesse a página do Cloud SQL no console do Cloud.O hoteldb-instance vai aparecer pronto e criado. Clique no nome da instância (hoteldb-instance), conforme mostrado abaixo:
No menu à esquerda do Cloud SQL, acesse a opção de menu Cloud SQL Studio, conforme mostrado abaixo:
Você vai precisar fazer login no Cloud SQL Studio para receber 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 de hotéis 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-22', '2024-04-20', 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-24', '2024-04-05', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', 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 um número de registros na tabela de hotéis, conforme mostrado abaixo:
Concluímos o processo de configuração de uma instância do Cloud SQL e criamos nossos dados de amostra. Na próxima seção, vamos configurar o MCP Toolbox for Databases.
5. Configurar o MCP Toolbox for Databases
O MCP Toolbox for Databases é um servidor MCP de código aberto para bancos de dados. Ele foi projetado com qualidade de produção e nível empresarial em mente. Ele permite que você desenvolva ferramentas de maneira mais fácil, rápida e segura, lidando com complexidades como agrupamento de conexões, autenticação e muito mais.
A Toolbox ajuda a criar ferramentas de IA generativa que permitem que os 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 aprimorada: 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 ferramentas, fornecendo um local centralizado para armazenar e atualizar ferramentas, permitindo que você compartilhe ferramentas entre agentes e aplicativos e atualize essas ferramentas sem necessariamente implantar novamente o aplicativo.
Você pode ver que um dos bancos de dados compatíveis com a MCP Toolbox para bancos de dados é o Cloud SQL, e provisionamos isso na seção anterior.
Como instalar a caixa de ferramentas
Abra o Cloud Shell Terminal e crie uma pasta chamada mcp-toolbox.
mkdir mcp-toolbox
Acesse a pasta mcp-toolbox usando o comando mostrado abaixo:
cd mcp-toolbox
Instale a versão binária do MCP Toolbox for Databases usando o script abaixo:
export VERSION=0.3.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 forma de configurar a Toolbox é pelo arquivo tools.yaml. Crie um arquivo chamado tools.yaml na mesma pasta, ou seja, mcp-toolbox, cujo conteúdo é 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.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%';
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
Vamos entender o arquivo em resumo:
Sourcesrepresentam as diferentes fontes de dados com que uma ferramenta pode interagir. Uma fonte representa uma fonte de dados com que uma ferramenta pode interagir. É possível definirSourcescomo um mapa na seção de origens 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 fonte que aponta para a instância do Cloud SQL para PostgreSQL com as credenciais. Para mais informações, consulte a referência Origens.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 de ferramentas do arquivo tools.yaml. Normalmente, uma ferramenta precisa de uma fonte para funcionar. No nosso caso, estamos definindo duas ferramentas:search-hotels-by-nameesearch-hotels-by-locatione especificando a origem em que ela está agindo, 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 juntos. Isso pode ser útil para definir grupos diferentes 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 que definimos.
Executar o MCP Toolbox for Databases Server
Execute o comando abaixo (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. Confira um exemplo de saída abaixo:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
O servidor da MCP Toolbox é executado por padrão na porta 5000. Vamos usar o Cloud Shell para testar isso.
Clique em "Visualização da Web" no Cloud Shell, conforme mostrado abaixo:
Clique em Change port e defina a porta como 5000, conforme mostrado abaixo, e clique em "Change and Preview".
Isso vai gerar o seguinte resultado:
No URL do navegador, adicione o seguinte ao final do URL:
/api/toolset
Isso vai mostrar as ferramentas que estão configuradas no momento. Confira um exemplo de saída abaixo:
{
"serverVersion": "0.3.0+container.12222fe27ae070f2689a0632d60fda45412d1f97",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location.",
"parameters": [
{
"name": "location",
"type": "string",
"description": "The location of the hotel.",
"authSources": []
}
]
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"description": "The name of the hotel.",
"authSources": []
}
]
}
}
}
O MCP Toolkit for Databases descreve uma maneira Pythonic de validar e testar as ferramentas, que está documentada aqui. Vamos pular essa etapa e passar diretamente para o Kit de Desenvolvimento de Agentes (ADK, na sigla em inglês) na próxima seção, que vai usar essas ferramentas.
6. Como criar nosso agente com o Kit de desenvolvimento de agentes (ADK)
Instalar o Kit de desenvolvimento de agentes (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 virtual do Python usando venv da seguinte maneira:
python -m venv .venv
Ative o ambiente virtual da seguinte maneira:
source .venv/bin/activate
Instale os pacotes do ADK e do MCP Toolbox for Databases da seguinte maneira:
pip install google-adk toolbox-core
Agora você poderá 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:
--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 um nome de app **(hotel-agent-app)**conforme abaixo.
adk create hotel-agent-app
Siga as etapas e selecione o seguinte:
- Modelo 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.0-flash-001
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 [gcp-experiments-349209]:
Enter Google Cloud region [us-central1]:
Agent created in /home/romin/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.
O primeiro é o arquivo .env. O conteúdo é 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, além dos respectivos valores para o ID e o 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.0-flash-001',
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 programar com o ADK. De acordo com a 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 objetivos específicos. Os agentes podem realizar tarefas, interagir com usuários, usar ferramentas externas e se coordenar com outros agentes.
Especificamente, um LLMAgent, comumente conhecido como "Agente", 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, tornando-os ideais para tarefas flexíveis e centradas na linguagem. Saiba mais sobre os agentes de LLM aqui.
Vamos modificar o código do agent.py da seguinte maneira:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
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 existente, digite o seguinte comando. Verifique se você está na pasta mãe (my-agents) que contém a pasta hotel-agent-app.
adk web
Confira abaixo um exemplo de execução:
INFO: Started server process [5015]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://localhost:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
Clique no último link para abrir um console da Web e testar o agente. O seguinte será iniciado no navegador, conforme mostrado abaixo:
Observe que, no canto superior esquerdo, o hotel-agent-app foi identificado. Agora você pode começar a conversar com o agente. Forneça algumas perguntas sobre cidades. Confira um exemplo de conversa abaixo:
É possível encerrar o processo em execução no terminal do Cloud Shell (Ctrl-C).
Uma maneira alternativa de testar o agente é pelo 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. Como conectar nosso agente às 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 um recurso específico fornecido a um agente de IA, permitindo que ele realize ações e interaja com o mundo além das principais habilidades de geração de texto e raciocínio.
No nosso caso, vamos equipar nosso agente com as ferramentas que configuramos no MCP Toolbox for Databases.
Modifique o arquivo agent.py com o seguinte código:
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.0-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 configurado com a Toolbox 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 em execução localmente na porta 5000, como testamos anteriormente. Caso contrário, execute o seguinte comando (da 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. Confira um exemplo de saída abaixo:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
Depois que o servidor MCP for iniciado, em outro terminal, inicie o agente como fizemos anteriormente usando o comando adk run (da pasta my-agents) mostrado abaixo. Também é possível usar o comando adk web, se preferir.
$ 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 extrair 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 criado usando o Kit de Desenvolvimento de Agentes (ADK) e que foi alimentado por ferramentas configuradas no MCP Toolbox for Databases.
8. (Opcional) Implantar o 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 Toolbox do MCP e testamos as ferramentas com o agente. Ele estava sendo executado localmente no ambiente do Cloud Shell.
Você tem a opção de implantar o servidor do MCP Toolbox e o agente nos serviços do Google Cloud que podem hospedar esses aplicativos para nós.
Como hospedar o servidor da MCP Toolbox no Cloud Run
Primeiro, podemos começar com o servidor da MCP Toolbox e hospedar no Cloud Run. Isso nos daria um endpoint público que pode ser integrado a qualquer outro aplicativo e/ou aos aplicativos do agente. As instruções para hospedar isso no Cloud Run estão aqui. Vamos conferir as etapas principais.
Inicie um novo terminal do Cloud Shell ou use um terminal do Cloud Shell existente. Acesse a pasta mcp-toolbox, em que o binário toolbox e o tools.yaml estão presentes.
Execute os comandos a seguir (cada um deles tem uma explicação):
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 Toolbox que será implantado 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 segredo e, como precisamos instalar a Toolbox no Cloud Run, vamos usar a imagem de contêiner mais recente para a Toolbox 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 para o 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 servidor da Toolbox com o tools.yaml configurado para o Cloud Run. Se a implantação for bem-sucedida, uma mensagem semelhante a esta vai aparecer:
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. A mensagem "Hello World" que vimos anteriormente vai aparecer. Além disso, você também 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 e conferir o serviço da Toolbox disponível na lista de serviços no Cloud Run.
Observação: se você quiser executar o agente do 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 de:
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 anteriormente.
Como implantar o app Hotel Agent no Cloud Run
A primeira etapa é garantir que você fez a mudança no my-agents/hotel-agent-app/agent.py conforme instruído acima para apontar para o URL do serviço da Toolbox que está sendo executado no Cloud Run e não no host local.
Em um novo terminal do Cloud Shell ou em uma sessão do Terminal, 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 primeiro as seguintes variáveis de ambiente:
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 cloud_run adk deploy, conforme mostrado abaixo. Se você receber uma solicitação para permitir invocações não autenticadas ao serviço, informe "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 Hotel Agent no Cloud Run. Ele vai fazer upload das origens, empacotá-las em um contêiner do Docker, enviar isso para o Artifact Registry e implantar o serviço no Cloud Run. Isso pode levar alguns minutos. Tenha paciência.
Você vai receber uma mensagem semelhante a esta:
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250424_045623
Copying agent source code...
Copying agent source code complete.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250424_045623/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_GOOGLE_CLOUD_PROJECT] region [us-central1]
| Building and deploying... Uploading sources.
| Uploading sources...
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/b02f5a74-6da6-4367-aaba-0c8aa098edf5?project=415458962931].
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00002-cpm] has been deployed and is serving 100 percent of traffic.
Service URL: https://hotels-service-<SOME_ID>.us-central1.run.app
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250424_045623
Se a implantação for bem-sucedida, você vai receber um valor para o URL do serviço, que poderá ser acessado no navegador para acessar o mesmo aplicativo da Web que permitiu conversar com o agente do hotel, como vimos anteriormente na configuração local.
9. Parabéns
Parabéns! Você criou um agente usando o Kit de Desenvolvimento de Agentes (ADK) que utiliza o MCP Toolbox for Databases.