O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Criar uma agência de viagens usando a Toolbox do MCP para bancos de dados e o Kit de desenvolvimento de agentes (ADK)

1. Introdução

Neste codelab, você vai criar um agente usando o Kit de Desenvolvimento de Agente (ADK), que utiliza o MCP Toolbox for Databases.

No codelab, você vai usar uma abordagem gradual da seguinte forma:

Provisione um banco de dados do Cloud SQL para PostgreSQL com o banco de dados de hotéis e dados de amostra.
Configure o MCP Toolbox for Databases, que dá acesso aos dados.
Projetar e desenvolver um agente usando o Kit de Desenvolvimento de Agente (ADK) que vai usar o MCP Toolbox para responder a consultas do usuário.
Conheça as opções para testar o agente e o MCP Toolbox for Databases 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.
Configurar o MCP Toolbox for Databases para a instância de banco de dados do Cloud SQL para PostgreSQL.
Projetar e desenvolver um agente usando o Kit de Desenvolvimento de Agente (ADK) para responder a consultas do usuário.
Teste o agente e a 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, criado para desenvolvedores de todos os níveis (inclusive 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.

Imagem do botão "Ativar o Cloud Shell"

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 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 à mostrada abaixo:

Operation "operations/..." finished successfully.

A alternativa ao comando gcloud é usar o console. Para isso, pesquise cada produto ou use 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. Criar 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 comando a seguir 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 nosso 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 de hotéis com dados de exemplo. 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 ver vários 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 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 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 suas ferramentas, oferecendo 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 o MCP Toolbox for Databases é o Cloud SQL, que provisionamos na seção anterior.

Como 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 do 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=1.13.1
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Agora temos a versão binária da caixa de ferramentas pronta para uso. Vamos validar se configuramos o binário da caixa de ferramentas corretamente e se ele indica a versão certa.

Execute o seguinte comando para determinar a versão da caixa de ferramentas:

./toolbox -v

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 é usando o 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 é: "nano tools.yaml".

Substitua o valor YOUR_PROJECT_ID pelo ID do projeto do Google Cloud.

kind: source
name: my-cloud-sql-source
type: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: postgres
---
kind: tool
name: search-hotels-by-name
type: 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 || '%';
---
kind: tool
name: search-hotels-by-location
type: 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;
---
kind: toolset
name: my_first_toolset
tools:
  - search-hotels-by-name
  - search-hotels-by-location

Entenda o arquivo brevemente:

Os Sources representam as diferentes fontes de dados com que uma ferramenta pode interagir. Uma origem representa uma fonte de dados com que uma ferramenta pode interagir. Você pode definir Sources como 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 Tools definem 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 definir Tools como um mapa na seção de ferramentas do arquivo tools.yaml. Normalmente, uma ferramenta precisa de uma fonte para agir. No nosso caso, estamos definindo duas ferramentas: search-hotels-by-name e search-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 chamado my_first_toolset, que contém as duas ferramentas definidas.

Salve o arquivo tools.yaml no editor nano seguindo estas etapas:

Pressione Ctrl + O (o comando "Salvar").
Ele vai pedir para você confirmar o "Nome do arquivo a ser gravado". Basta pressionar Enter.
Agora pressione Ctrl + X para sair.

Executar o servidor do MCP Toolbox for Databases

Execute o seguinte comando (na pasta mcp-toolbox) para iniciar o servidor:

./toolbox --config "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:

2026-09-26T14:00:35.898358+05:30 INFO "Starting MCP Toolbox for Databases version 1.13.1+binary.darwin.arm64.e14cda6" 
2026-09-26T14:00:39.571556+05:30 INFO "Initialized 1 sources: my-cloud-sql-source" 
2026-09-26T14:00:39.571634+05:30 INFO "Initialized 0 authServices: " 
2026-09-26T14:00:39.571648+05:30 INFO "Initialized 0 embeddingModels: " 
2026-09-26T14:00:39.571728+05:30 INFO "Initialized 2 tools: search-hotels-by-name, search-hotels-by-location" 
2026-09-26T14:00:39.571745+05:30 INFO "Initialized 0 prompts: " 
2026-09-26T14:00:39.571756+05:30 INFO "Initialized 0 resources: " 
2026-09-26T14:00:39.571767+05:30 INFO "Initialized 0 resource templates: " 
2026-09-26T14:00:39.571851+05:30 INFO "Initialized 2 groups: my_first_toolset, default" 
2026-09-26T14:00:39.571905+05:30 WARN "wildcard (*) allows any website to access the primitives. This creates a security risk regardless of whether you are in a production or local development environment. Recommended to use --allowed-origins with specific local addresses." 
2026-09-26T14:00:39.571939+05:30 WARN "wildcard (*) hosts allow any domain to access this resource, making it vulnerable to DNS rebinding attacks regardless of whether you are in a production or local development environment. For improved security, use the --allowed-hosts flag to specify trusted domains." 
2026-09-26T14:00:39.572261+05:30 INFO "Server ready to serve!"

O servidor da caixa de ferramentas do MCP é executado por padrão 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 --config "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 e defina a porta como 5000, conforme mostrado abaixo. Depois, clique em "Alterar e visualizar".

Isso vai gerar a seguinte saída:

Testar as ferramentas na interface da MCP Toolbox for Databases

A caixa de ferramentas oferece uma interface visual (interface 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 MCP Toolbox for Databases que você pode estar executando e execute o seguinte comando:

./toolbox --config "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.

2026-09-26T14:01:17.208487+05:30 INFO "Starting MCP Toolbox for Databases version 1.13.1+binary.darwin.arm64.e14cda6" 
2026-09-26T14:01:20.823447+05:30 INFO "Initialized 1 sources: my-cloud-sql-source" 
2026-09-26T14:01:20.82353+05:30 INFO "Initialized 0 authServices: " 
2026-09-26T14:01:20.823545+05:30 INFO "Initialized 0 embeddingModels: " 
2026-09-26T14:01:20.823629+05:30 INFO "Initialized 2 tools: search-hotels-by-name, search-hotels-by-location" 
2026-09-26T14:01:20.823649+05:30 INFO "Initialized 0 prompts: " 
2026-09-26T14:01:20.82366+05:30 INFO "Initialized 0 resources: " 
2026-09-26T14:01:20.823671+05:30 INFO "Initialized 0 resource templates: " 
2026-09-26T14:01:20.823745+05:30 INFO "Initialized 2 groups: my_first_toolset, default" 
2026-09-26T14:01:20.823795+05:30 WARN "wildcard (*) allows any website to access the primitives. This creates a security risk regardless of whether you are in a production or local development environment. Recommended to use --allowed-origins with specific local addresses." 
2026-09-26T14:01:20.823829+05:30 WARN "wildcard (*) hosts allow any domain to access this resource, making it vulnerable to DNS rebinding attacks regardless of whether you are in a production or local development environment. For improved security, use the --allowed-hosts flag to specify trusted domains." 
2026-09-26T14:01:20.824193+05:30 INFO "Server ready to serve!" 
2026-09-26T14:01:20.824231+05:30 INFO "Toolbox UI is up and running at: http://127.0.0.1:5000/ui"

Clique no URL da interface e confira se você tem o

/ui

no final do URL. Se você estiver executando isso no Cloud Shell, o redirecionamento do navegador fará com que /ui não apareça no final. Isso vai mostrar uma interface como esta:

Clique na opção "Ferramentas" à esquerda para conferir as ferramentas configuradas. No nosso caso, são 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 fornecendo os valores de parâmetro necessários e clicando em Executar ferramenta para ver o resultado. Confira um exemplo de execução abaixo:

Se voltarmos ao diagrama anterior (mostrado abaixo), já concluímos a configuração do banco de dados e do servidor MCP e temos dois caminhos pela frente:

Para entender como configurar o servidor MCP em um terminal / IDE com tecnologia de IA, acesse a etapa 6. Isso vai mostrar como integrar o servidor da MCP Toolbox ao Gemini CLI.
Para entender como usar o Agent Development Kit (ADK) using Python, escrever seus próprios agentes que podem usar a MCP Server Toolbox como uma ferramenta e responder a perguntas relacionadas ao conjunto de dados, acesse as etapas 7 e 8.

6. Como integrar a MCP Toolbox na CLI do Antigravity

A CLI do Antigravity é uma interface de usuário de terminal (TUI, na sigla em inglês) leve do Antigravity. Ele traz os mesmos recursos principais do Antigravity (como raciocínio em várias etapas, edição de vários arquivos, chamada de ferramentas e histórico de conversas) diretamente para o terminal. Você pode usar para tarefas de programação e não relacionadas a programação. Ele vem integrado a várias ferramentas e oferece suporte a servidores MCP.

Como temos um servidor MCP funcionando, o objetivo desta seção é configurar o servidor da MCP Toolbox for Databases na CLI do Antigravity e usar essa CLI para interagir com nossos dados.

A primeira etapa é confirmar se a caixa de ferramentas está funcionando em um dos terminais do Cloud Shell. Supondo que você esteja executando na porta padrão 5000, a interface do servidor MCP está disponível no seguinte endpoint: http://localhost:5000/mcp.

Abra um novo terminal e crie uma pasta chamada my-gemini-cli-project da seguinte maneira. Navegue até a pasta my-gemini-cli-project também.

mkdir my-agy-cli-project
cd my-agy-cli-project

Execute o comando a seguir para adicionar o servidor MCP à lista de servidores MCP configurados na CLI do Antigravity.

agy mcp add "MCPToolbox" "http://localhost:5000/mcp"

Confira a lista atual de servidores MCP configurados na CLI do Antigravity com o seguinte comando:

agy mcp list

O ideal é que você veja a MCPToolbox que configuramos com uma marcação verde ao lado, o que indica que a CLI do Gemini conseguiu se conectar ao servidor MCP.

NAME        TYPE  STATUS   COMMAND/URL
MCPToolbox  http  enabled  http://localhost:5000/mcp

Antes de lançar a CLI do Gemini, talvez seja interessante definir as seguintes variáveis de ambiente para ajudar a CLI do Gemini a encaminhar suas solicitações para o modelo correto.

export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=global

No mesmo terminal, verifique se você está na pasta my-agy-cli-project. Inicie a CLI do Antigravity com o comando agy.

Isso vai abrir a interface da CLI do Antigravity. Use o comando /mcp para conferir a lista de servidores MCP e as ferramentas. Por exemplo, confira uma amostra de saída:

MCP Servers
Plugins (~/.gemini/config/plugins)
>  ✓ MCPToolbox  Tools: search-hotels-by-location, search-hotels-by-name

Agora você pode dar qualquer um dos comandos:

Which hotels are there in Basel?
Tell me more about the Hyatt Regency?

Você vai descobrir que as consultas acima fazem com que a CLI do Antigravity selecione a ferramenta adequada da MCPToolbox. Ele vai pedir sua permissão para executar a ferramenta. Conceda a permissão necessária e você vai notar que os resultados são retornados do banco de dados.

7. 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 virtual do Python 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 junto 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.
  conformance  Conformance testing tools for ADK.
  create       Creates a new app in the current folder with prepopulated...
  deploy       Deploys agent to hosted environments.
  eval         Evaluates an agent given the eval sets.
  eval_set     Manage Eval Sets.
  migrate      ADK migration commands.
  optimize     Optimizes the root agent instructions using the GEPA...
  run          Runs an agent.
  telemetry    Manage telemetry settings.
  test         Runs pytest on agent test JSON files under the specified...
  web          Starts a FastAPI server with Web UI for agents.

Como criar nosso primeiro aplicativo de agente

Agora vamos usar adk para criar um scaffolding 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:

Escolha o modelo gemini-3.8-flash para o agente raiz.
Escolha Vertex AI para o back-end.
O ID do projeto padrão do Google vai aparecer. Selecione essa opção.
A região do projeto atual do Google Cloud vai aparecer. Digite global.

Choose a model for the root agent:
1. gemini-3.5-flash
2. gemini-3.8-flash
3. Other models (fill later)
Choose model (1, 2, 3): 2

1. Google AI
2. Vertex AI
3. Login with Google
Choose a backend (1, 2, 3): 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]: global

Agent created in <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app:
- .env
- .gitignore
- __init__.py
- agent.py

Observe a pasta em que um modelo padrão e os arquivos necessários para o agente foram criados. É possível ver os arquivos com o comando ls -al no terminal do diretório <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app.

Primeiro, o arquivo .env. Esse arquivo já foi criado, como mencionado anteriormente. Basta conferir o conteúdo dele, que é mostrado abaixo:

GOOGLE_GENAI_USE_ENTERPRISE=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 do projeto e do local 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 analisar o arquivo agent.py. O conteúdo é mostrado abaixo:

from google.adk.agents.llm_agent import Agent
root_agent = Agent(
    model='gemini-3.8-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 de 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 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 aqui.

Vamos modificar o código do agent.py da seguinte maneira:

from google.adk.agents.llm_agent import Agent

root_agent = Agent(
    model='gemini-3.8-flash',
    name='root_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 do terminal, execute o seguinte comando. Verifique 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 [61397]
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. O seguinte vai aparecer 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. Dê alguns comandos perguntando 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 é 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 encerrar a conversa.

8. 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, para que ele execute ações e interaja com o mundo além de suas 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-3.8-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 o MCP Toolbox for Databases.

Para isso, siga esta sequência:

Em um terminal do Cloud Shell, inicie o MCP Toolbox for Databases. Talvez ele já esteja sendo executado localmente na porta 5000, como testamos antes. Caso contrário, execute o seguinte comando (na pasta mcp-toolbox) para iniciar o servidor:

./toolbox --config "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.

Depois que o servidor do 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/

...
Running agent hotel_agent, type exit to exit.

[user]: what can you do for me?
[hotel_agent]: I can help you search for and find information about hotels! Specifically, I can:
* **Find hotels in a specific city or location:** Look up available hotels, sorted by price from least to most expensive.
* **Search for hotels by name:** Get details on a specific hotel you're interested in.
Feel free to tell me where you're planning to stay or which hotel you'd like to look up!

[user]: I would like to search for hotels?
[hotel_agent]: I'd be happy to help! 
Where are you planning to travel, or is there a specific hotel name you have in mind?

[user]: I am planning to travel to Basel
[hotel_agent]: Here are the hotels available in **Basel**, listed from least to most expensive:
1. **Holiday Inn Basel**
   * **Price Tier:** Upper Midscale
   * **Available Dates:** April 9, 2024 – April 24, 2024
2. **Hyatt Regency Basel**
   * **Price Tier:** Upper Upscale
   * **Available Dates:** April 2, 2024 – April 20, 2024
3. **Hilton Basel**
   * **Price Tier:** Luxury
   * **Available Dates:** April 20, 2024 – April 22, 2024
Would you like more details about any of these hotels, or do you have specific travel dates in mind?

[user]: 
. . .

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 local do nosso agente de hotel, que criamos usando o Kit de Desenvolvimento de Agente (ADK) e que foi alimentado por ferramentas configuradas no MCP Toolbox for Databases.

9. (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 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 MCP Toolbox e o agente nos serviços do Google Cloud que podem hospedar esses aplicativos.

Hospedagem do servidor da MCP Toolbox no Cloud Run

Primeiro, podemos começar com o servidor do MCP Toolbox e hospedá-lo no Cloud Run. Isso nos daria um endpoint público que podemos integrar 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 os papéis corretos, 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 familiar no Cloud Run:

gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--config=/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.

Você também pode acessar o Cloud Run no console do Google Cloud e encontrar o serviço da caixa de ferramentas 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 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 antes.

Como implantar o app do agente de hotel 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 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_ENTERPRISE=1

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

Após a implantação, 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 na configuração local.

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

11. Parabéns

Parabéns! Você criou um agente de viagens usando o Kit de Desenvolvimento de Agentes (ADK) que utiliza o MCP Toolbox for Databases. Você também aprendeu a conectar agentes aos seus próprios bancos de dados e, opcionalmente, instalar o agente e a caixa de ferramentas no Cloud Run.