Como criar um agente de viagens simples com o ADK e a CLI do Gemini

1. Introdução

Última atualização:22/06/2026

Criar um agente simples de viagens com o ADK

Este é o workshop do ADK em Python(*), que já vem com tudo o que você precisa, graças à CLI do Gemini!

Este codelab está dividido em dois marcos 🏅:

1. Um programa de aprendizado comum e simples: configuração + gratificação instantânea.
2. Um programa personalizado em que você escolhe uma missão para resolver com a ajuda da CLI do Gemini

A segunda parte torna este codelab perfeito para uma hackathon (e há prêmios para as soluções mais criativas).

Marco 1: seu primeiro agente com o ADK e a CLI do Gemini

O objetivo desta etapa é criar um agente de viagens simples com o ADK. Para isso, primeiro vamos configurar a CLI do Gemini para que ela nos ajude a programar com o ADK. Assim, seu shell local poderá escolher a versão mais recente do ADK do Python, adaptar o código e a documentação e fornecer o código mais recente/melhor para trabalhar com ele e alcançar seu objetivo.

Esta é uma parte guiada manualmente em que criamos um app totalmente funcional com incrementos pequenos e simples. Isso geralmente leva cerca de uma hora (mais o tempo de instalação).

Observação (*): embora o codelab pressuponha que você esteja usando o ADK do Python, é possível fazer isso funcionar com Go, Java ou TypeScript com pouquíssimas mudanças. Na verdade, se você só usou o ADK com Python, este codelab é uma ótima chance de testar o caminho em uma linguagem diferente. Conte para nós o que você achou usando o link de feedback abaixo.

Marco 2: estender seu agente

Depois disso, oferecemos uma dúzia de opções (de dificuldade variada) para estender o app do jeito que você quiser. Isso permite explorar diferentes aspectos (UI, operações, interações complexas do agente etc.).

O que você vai criar

Neste codelab, você vai criar um app de agente de viagens usando o ADK e a CLI do Gemini. Esse app vai:

• Conecte-se às APIs do Airbnb pelo MCP do Airbnb.
• Pesquisar informações atualizadas on-line (previsão do tempo, datas etc.)
• Executar ferramentas personalizadas.
• Crie imagens dos apartamentos/quartos usando o NanoBanana.

A CLI do Gemini vai orientar você em tudo isso: escrever/revisar código e encontrar a documentação mais recente em um espelho local do repositório do ADK (em Python ou na sua linguagem favorita).

O que você vai aprender

• Como criar um app com o ADK
• Como usar a CLI do Gemini para programar apps com base em documentos locais.
• Como interagir com um servidor MCP para se conectar a fontes de dados externas em tempo real, como esta:

O que é necessário

• Um computador que permite instalar pacotes (por exemplo, npm install ..)
• Habilidade básica de programação em Python, TypeScript, Go ou Java.
• Recomendamos o uso de um ambiente de desenvolvimento integrado (Antigravity, vscode, IntelliJ, vim).

Por que usar o ADK + a CLI do Gemini?

Algumas pessoas podem se perguntar: por que preciso usar o ADK (um SDK de criação de agentes) junto com um assistente de código de agente local (como a CLI do Gemini)? O motivo é que as duas ferramentas são muito poderosas, mas a interação entre elas não é trivial. Muitas pessoas tentaram trabalhar com as duas em conjunto e não conseguiram, principalmente devido a problemas de "loop em um loop". Este codelab tenta compartilhar algumas dicas sobre como tornar essa coexistência possível.

2. Etapas da configuração

Escolha uma das seguintes opções: Configuração do ambiente no seu ritmo se quiser executar este codelab na sua própria máquina ou Iniciar o Cloud Shell se quiser executar este codelab totalmente na nuvem.

Configuração de ambiente autoguiada

1. Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.

• O Nome do projeto é o nome de exibição para os participantes do projeto. É uma string de caracteres não usada pelas APIs do Google e pode ser atualizada quando você quiser.
• O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Cloud gera automaticamente uma string exclusiva. Em geral, não importa o que seja. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, normalmente identificado como PROJECT_ID. Se você não gostar do ID gerado, crie outro aleatório. Se preferir, teste o seu e confira se ele está disponível. Ele não pode ser mudado após essa etapa e permanece durante o projeto.
• Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.

Atenção: o ID do projeto é globalmente exclusivo e não pode ser usado por outras pessoas após a seleção. Você é o único usuário com esse ID. Mesmo que um projeto seja excluído, o ID não poderá ser usado novamente.

Observação: se você usa uma conta do Gmail, defina o local padrão como Sem organização. Se você usa uma conta do Google Workspace, escolha um local adequado para a organização.

2. Em seguida, ative o faturamento no console do Cloud para usar os recursos/APIs do Cloud. A execução deste codelab não vai ser muito cara, se tiver algum custo. Para encerrar os recursos e evitar cobranças além deste tutorial, exclua os recursos criados ou exclua o projeto. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.

Inicie o Cloud Shell

Embora o Google Cloud e o Spanner possam ser operados remotamente do seu laptop, neste codelab usaremos o Google Cloud Shell, um ambiente de linha de comando executado no Cloud.

No Console do Google Cloud, clique no ícone do Cloud Shell na barra de ferramentas superior à direita:

O provisionamento e a conexão com o ambiente levarão apenas alguns instantes para serem concluídos: Quando o processamento for concluído, você verá algo como:

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste codelab, todo o trabalho pode ser feito com um navegador. Você não precisa instalar nada.

3. Pré-requisitos (instalação)

Observação:se você decidir executar este codelab no Cloud Shell, o Python, o uv e a CLI do Gemini (gemini) já estarão pré-instalados.

Para este tutorial, você precisa instalar:

1. Python e uv

python e uv (gerenciador de pacotes para Python). Isso é necessário para o ADK. Verifique se o uv está instalado:

$ curl -LsSf https://astral.sh/uv/install.sh | sh

Por que uv? Embora seja possível usar o gerenciador do Python que você preferir, o uso do uv garante que a configuração ENV/PATH do Python seja igual para você e para a CLI do Gemini. Assim, sua experiência de shell será praticamente a mesma da CLI do Gemini. Se você usar virtualenv , por exemplo, a CLI do Gemini será forçada a fazer coisas como "source .env/venv/bin/activate && my-original-command" para imitar seu ambiente.

2. CLI do Gemini

Para a CLI do Gemini, confira as instruções de instalação aqui: https://github.com/google-gemini/gemini-cli .

# Note: This requires having npm or npx installed.
npm install -g @google/gemini-cli

1. No Mac, use o brew conforme os documentos oficiais.
2. No Windows, use chocolatey ou baixe o executável em https://nodejs.org/en/download

Para a etapa 4 (mais adiante), você também vai precisar do npx instalado. npm e npx devem ser incluídos naturalmente como parte da CLI do Gemini. Se não, peça ajuda à CLI do Gemini.

Authentication

Você precisa de um projeto do Google Cloud com a Vertex AI ativada ou de uma chave de API do Google AI Studio.

Opção A (recomendada para o workshop): exporte sua chave de API:

export GOOGLE_API_KEY="your-api-key"

Opção B (Vertex AI): autenticar com a gcloud:

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
export GOOGLE_GENAI_USE_VERTEXAI=true
gcloud auth application-default login

Configurar seu ambiente de trabalho

Você vai criar SUA PRÓPRIA solução em mysolution/. Por isso, vamos criar a pasta e os dois arquivos necessários.

Agora é possível abrir o IDE (Visual Studio Code, IntelliJ, RubyMine etc.) e a pasta.

# 1. Find an empty directory, and download this repo.
git clone https://github.com/palladius/adk-gemini-cli-workshop
cd adk-gemini-cli-workshop/

# 2. Create your solution empty skeleton
mkdir -p mysolution/
touch mysolution/__init__.py mysolution/agent.py

# 3. This installs ADK and MCP via `uv` by reading pyproject.toml
uv init
uv sync

# 4. Call Gemini CLI
gemini  # This runs Gemini CLI under the adk-gemini-cli-workshop/ folder.
# Login with your GMail account.

A sincronização do uv não é estritamente necessária, mas, se ela falhar, você precisará corrigir a instalação do Python ou do uv. Isso vai instalar adk e outros scripts úteis na pasta ./.venv/bin/.

Para testar sua configuração, basta executar make test-step1 e verificar se você não recebe um 403 PERMISSION DENIED..

Importante. Verifique se você está executando a CLI do Gemini na pasta 📁 adk-gemini-cli-workshop/. Além disso, a IDE vai mostrar isso como nome da raiz. Isso garante que a CLI do Gemini escolha a configuração certa. Você sempre pode adicionar pastas externas usando /dir add /your/other/folder, mas 📁 adk-gemini-cli-workshop/ oferece o melhor local inicial.

Soluções disponíveis

Todo o código está contido em 📂 steps/. Você pode copiar o código de lá.

Este codelab não ensina a escrever um bom código do ADK, mas sim a configurar seu ambiente para gerar um código BOM automaticamente sob sua direção.

1. Como instalar o software
2. configurar / fazer funcionar e
3. entrar em um ciclo de feedback justo

É isso que queremos que você aprenda aqui. Você também pode testar todas ao mesmo tempo usando o $ make web-4steps.

4. Etapa 1: agente básico

Vamos começar criando um agente básico que pode conversar.

Edite o arquivo chamado mysolution/__init__.py adicionando o seguinte conteúdo:

from .agent import root_agent

Simples assim! Isso permite que o ADK saiba onde seu código está: em agent.py.

Edite o arquivo chamado mysolution/agent.py adicionando o seguinte conteúdo:

from google.adk.agents import Agent

root_agent = Agent(
    name="travel_basic",
    model="gemini-2.5-flash",
    instruction="You are a helpful travel assistant." +
    "You can help with general travel advice based on your knowledge.",
)

Testar o agente

Isso é válido para todas as etapas. O ADK permite testar seu agente de duas maneiras: CLI e Web.

• A CLI é ideal para testes rápidos e automatizados.
• A Web é a melhor opção para ver visualmente o que está acontecendo, usar o microfone (!) e resolver problemas.

Dica: para fins deste exercício, use a Web para realizar qualquer ação, exceto testes de unidade. É incrível! Mantenha a CLI apenas para testes automatizados.

Um bom comando que testa adequadamente as etapas 1 a 4 pode ser este (comando inteligente de "teste decisivo"):

Olá, quero reservar um hotel em Paris para amanhã à noite, uma noite, no centro da cidade. De preferência perto da Gare de Lyon. Orçamento: menos de 200 euros por noite.

1. Me diga qual é o AAAAMMDD e o dia da semana de amanhã.
2. Me diga quais hotéis você vê para amanhã (pelo menos três). Quero ver: > preço, endereço, alguma classificação (no formato XX/YY, por exemplo, "4,7/5" do Google Hotéis, Booking ou Airbnb), número de avaliações. Apresente-as em formato TABULAR. O ideal é que o nome do hotel esteja vinculado a algum tipo de URL dele (não adicione uma coluna de URL). Verifique se o link é legítimo (funciona e a página aponta para informações sobre o hotel).

Esse é um comando inteligente porque testa horários e hotéis e vai falhar de maneira diferente nas etapas 1,2 e 3,tendo sucesso total apenas na etapa 4. É claro que você pode usar qualquer comando que quiser.

Execute no bash (CLI):

# 1. If ADK was installed:
adk run mysolution/
# ... but if you get: -bash: adk: command not found"
# 2. Call ADK cli script through UV to avoid python install nightmares.
uv run adk run mysolution/

Tente usar o "comando litmus" acima.

É provável que ele não consiga saber datas específicas. Precisamos ensinar a data para ele.

Na Web, faça o seguinte:

1. uv run adk web . : executa todos os agentes nessa pasta. Você quer apontar para a subpasta "mysolution/"
2. escolha mysolution/ no canto superior direito (veja a imagem ao lado).
3. Faça sua pergunta por texto ou microfone, algo como "comando de teste".

Observação: é necessário chamar adk web da pasta superior, de acordo com a versão da CLI.

Confira uma possível solução, com uma semi-alucinação de data. Observação: três dos cinco links para reserva estão funcionando. Está indo bem.

5. Etapa 2: adicionar a ferramenta now()

Adicione essa função a agent.py imediatamente antes da definição de root_agent:

from datetime import datetime

def now() -> dict:
    """Returns the current date and time."""
    my_datetime = ... # Ask Gemini CLI to help you!
    return {
        "status": "success",
        "current_time": my_datetime
    }

Atualize a definição do agente para incluir a ferramenta:

  # file XXX.py

  root_agent = Agent(
        name="..",
        model="..",
        instruction="..",
        tools=[now] # <== This is the only line you want to add.
    )

Execute de novo e faça a mesma pergunta. Agora ele deve saber a data (bom) e ser vago sobre hotéis (ruim).

Você também pode testar com algo assim:

# Let's pretend we're in Milan. This should call the tool
# and respond correctly (possibly with some TZ math issues)
echo "What time is it in Milan?" | uv run adk run mysolution/

6. Etapa 3: vamos mudar de assunto: google_search

google_search. Isso permite que nosso agente acesse informações em tempo real da Web.

Observação: 🚨 os modelos gemini-2.x não podem misturar nativamente a Pesquisa Google com ferramentas personalizadas. Consulte o problema nº 969. Por isso, vamos substituir now() por google_search para simplificar. Mais detalhes: ISSUES.md.

Sua tarefa é modificar o agente da etapa 2. Em vez de usar a ferramenta now, você vai importar e usar a ferramenta google_search da biblioteca ADK.

# Full Code: `steps/step03_search/agent.py`
# Remember to REMOVE the now() tool here. See above why.
from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="travel_agent",
    model="gemini-2.5-flash",
    tools=[google_search],
    instruction="""You are a travel agent.
Your job is to help the user plan a trip.
You have access to a search engine.
If you don't know the answer, you can use the search engine.
When you are done, reply with "DONE".""",
)

Como executar

Igual à etapa 1.

Somente para especialistas. Para uma integração mais avançada (usando google_search e now juntos), confira o código em steps/step03b_search_and_tool/agent.py e execute-o com make run-step3b. Isso é totalmente opcional.

7. Etapa 4: uma ferramenta mais sofisticada: MCP

Agora que já vimos as ferramentas personalizadas e integradas, vamos passar para algo mais poderoso: o padrão Modelo como uma ferramenta usando o Protocolo de Contexto de Modelo (MCP).

Para manter esta etapa focada nos recursos avançados do MCP, vamos substituir mais uma vez nossa ferramenta anterior (google_search). Vamos reintroduzir nossa ferramenta simples now para ser executada com a ferramenta airbnb_mcp. Isso demonstra como um agente pode usar várias ferramentas compatíveis (neste caso, um FunctionTool e um MCPToolset) para realizar tarefas complexas.

# Full Code: steps/step04_mcp/agent.py
# ... Imports as before
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

def now() -> dict:
    # ... as before

# Configure the Airbnb MCP Toolset
airbnb_mcp = MCPToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command='npx',
            args=["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"],
        ),
    )
)

root_agent = Agent(
    name="travel_mcp",
    model="gemini-2.5-flash",
    instruction="You are a helpful travel assistant. You can find accommodation using Airbnb, and have access to the current time.",
    tools=[now, airbnb_mcp],
)

Como executar

Esta etapa exige que o npx esteja instalado no seu sistema. No restante, é igual ao que foi explicado acima.

Ressalvas/ erros

1. Se você receber um erro de restrição robots.txt, corrija o MCP com uma diretiva de ignorar robôs. Leia a documentação para mais detalhes: https://github.com/openbnb-org/mcp-server-airbnb
2. Se você receber um erro timeout (5 segundos é muito pouco para o Airbnb receber respostas), consulte a documentação do ADK sobre como aumentar o tempo limite para, digamos, 30 segundos. Ou use a CLI do Gemini para fazer isso. Em 3dec25m, o Cloud Shell me deu um erro de tempo limite. Corrigi o erro, mas ainda recebi erros até forçar a versão anterior: args=["-y", "@openbnb/mcp-server-airbnb@0.1.2", "--ignore-robots-txt"].

8. 🏅 Meta 1 concluída!

🏅 Parabéns! 🏅 Agora você é um especialista em ADK! Você concluiu a primeira parte do workshop e criou e testou agentes de IA com ferramentas personalizadas, ferramentas integradas e ferramentas avançadas do MCP. Agora você já pode criar seus próprios agentes incríveis com o Kit de Desenvolvimento de Agente do Google.

Agora você tem um agente de viagens funcional que sabe a hora e pode pesquisar na Web. O céu é o limite!

Agora é hora de adicionar uma funcionalidade extra com a "CLI do Gemini".

9. 🏅 Marco 2: vibe coding com o ADK usando a CLI do Gemini

Agora vamos para a parte interessante do workshop.

1. git commit o código em um lugar seguro. Você pode fazer um fork do código original ou criar uma ramificação. Não se preocupe, a CLI do Gemini é ótima para ajudar você nessa etapa.
2. Encontre uma 💡 ideia para implementar. Confira as ideias abaixo, encontre uma por conta própria ou peça ao Gemini para analisar a documentação em rag/ e propor algumas ideias inteligentes.
3. Siga os pré-requisitos para garantir que o Gemini possa ler os documentos do ADK. Depois disso, é só começar!

💡 Ideias

1. 🟢 [fácil] Você é poliglota? Você quer dar go, java ou TypeScript? Refatorar o código atual é muito simples. Basta baixar o ADK adequado e pedir para a CLI do Gemini fazer a tradução.
2. 🟢 [fácil] Adicione emojis ou especifique um formato de saída que você goste (por exemplo, uma tabela com o emoji de hotel, seguido do preço e de emojis de 1 a 5 estrelas com base em 🌕🌕🌕🌗🌑 para fazer metades também).
3. 🟢 [fácil] Mude o comando para ensinar ao modelo o que você está procurando ou não (aceita animais de estimação, não tem térreo, silencioso, perto de transporte público etc.) e teste. Talvez adicione uma classificação pessoal, como "uma classificação de YOUR_NAME de 1 a 10", com base no que foi dito acima, e classifique por essa avaliação.
4. 🟢 [fácil] Tem algum operador na sala? Implante no Cloud Run. Ou para o Vertex AI Agent Engine. Você sabia que pode integrar e chamar esse agente diretamente no novo Gemini Enterprise?
5. 🟢 [fácil] Integre o adk run com o 🍌 NanoBanana MCP. Requer uma chave da API Gemini. Aqui você poderá criar imagens, mas não visualizá-las. Confira abaixo uma variante mais difícil.
6. 🟡 [médio] Crie um subagente que faça a HotelSearch e crie um BudgetAgent ou um LocationAgent que possa dobrar e iterar em hotéis respeitando suas necessidades de localização, por exemplo, "não mais que X km de LOCALIZAÇÃO". Se a API não permitir isso, talvez haja uma troca de informações com a ajuda do Google Pesquisa. Observação: a CLI do Gemini pode ajudar você.
7. 🟡 [médio] Implemente um AirbnbReviewAgent que analise as avaliações e resuma os pontos positivos e negativos em alguns marcadores codificados por cores para um ou N hotéis resultantes de uma pesquisa. Você já tem dois ingredientes (GoogleSearch e MCP Airbnb). Agora, precisa conectar isso ao agente principal e talvez inventar algum tipo de protocolo para que eles se comuniquem.
8. 🟡 [médio] Integre com o A2A. Transforme em um agente A2A! De novo, peça ajuda à CLI do Gemini.
9. 🔴 [complexo] Você pode se integrar ao Flights ou a outras funcionalidades do MCP para criar um agente de viagens multifacetado e multifuncional.
10. 🔴 [complex] Integrate ADK web with 🍌 NanoBanana MCP. Essa opção é mais difícil que a anterior. Confira algumas dicas em https://github.com/palladius/ai-friendly-agents/issues/11. Isso levou 3 horas de conversa com a CLI do Gemini, o Gemini 3 e nós dois lendo documentos/códigos de rag/!

Precisa de mais inspiração?

1. Confira algumas ideias no tutorial oficial do ADK.
2. Peça à CLI do Gemini para encontrar ideias consultando a documentação em rag/. Um possível comando pode ser: Is there a feature in here which seems very succulent to you? Give me 3 proposals and let's implement together the one I choose.

Pré-requisitos para o ADK "RAG"

Para criar um código de vibe de uma funcionalidade, recomendamos que você baixe todo o ADK Python (observação: ele pode ser adaptado facilmente à sua linguagem favorita, como Java ou Go).

O código está em ./rag e pode ser baixado com ./download-adk.sh.

Como a pasta rag está listada no arquivo .gitignore, verifique se o .gemini/settings.json contém o seguinte:

{
 "context": {
   "includeDirectories": ["rag"]
 }
}

Por quê? Queremos que o Gemini possa ler esses arquivos, enquanto eles são ignorados com segurança pelo Git. Tecnicamente, também é possível mostrar todos os arquivos .gitignore definindo context.fileFiltering.respectGitIgnore como false, mas isso abre muito lixo de node_modules/ e __pycache__/. Portanto, a inclusão explícita de pastas é a opção preferida.

10. Próximas etapas

Curiosidade: este workshop foi criado com a ajuda da CLI do Gemini. Se quiser saber como eu fiz isso, confira os arquivos GEMINI.md e WORKSHOP_PLAN.md nesta pasta.

Lições aprendidas

Aprendemos a combinar o ADK com a CLI do Gemini

Mais informações

• Confira estes dois codelabs oficiais do Antigravity:
  • Como começar a usar o Google Antigravity
  • Criar com o Google Antigravity
  • Criar e implantar no Google Cloud com o Antigravity
• Confira algumas ideias no tutorial oficial do ADK.