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 sobre o ADK para Python(*), que já vem com tudo o que você precisa, graças à CLI do Gemini.

Este codelab é dividido em dois 🏅 marcos:

1. Um programa de aprendizado comum e simples: configuração + recompensa instantânea.
2. Um caminho 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 um hackathon (com prêmios para as soluções mais criativas!)

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

O objetivo deste marco é criar um agente de viagens simples com o ADK, passo a passo. 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 em Python, entender o código e a documentação e fornecer o código mais recente/melhor para trabalhar com ele para seu objetivo.

Esta é uma parte guiada em que criamos um app totalmente funcional com pequenos incrementos simples. Isso geralmente leva cerca de uma hora (além do 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. Se você só usou o ADK com Python, este codelab é uma ótima oportunidade para testar o caminho em outra linguagem. Diga o que você achou pelo link de feedback abaixo.

Marco 2: ampliar o agente

Depois disso, vamos dar uma dúzia de opções (com diferentes níveis de dificuldade) para você ampliar o app como quiser. Isso permite que você explore diferentes aspectos (interface, operações, interações complexas de agentes 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:

• Conectar-se às APIs do Airbnb pelo MCP do Airbnb.
• Pesquisar on-line por informações atualizadas (clima, datas etc.)
• Executar ferramentas personalizadas.
• Crie imagens dos apartamentos/quartos usando o Nano Banana.

A CLI do Gemini vai orientar você em todo o processo: escrever/revisar o código e encontrar os documentos mais recentes 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 ..)
• Capacidade básica de programação em Python, TypeScript, Go ou Java.
• É altamente recomendável usar um ambiente de desenvolvimento integrado (Antigravity, VS Code, IntelliJ, vim).

Por que usar o ADK e a CLI do Gemini?

Alguns de vocês podem se perguntar: por que preciso usar o ADK (um SDK de criação de agentes) com um assistente de código agêntico local (como a CLI do Gemini)? O motivo é que as duas ferramentas são incrivelmente poderosas, mas a interação entre elas não é trivial. Muitas pessoas tentaram trabalhar com as duas em conjunto e falharam (principalmente devido a problemas de "loop em um loop"). Este codelab tem como objetivo 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 inteiramente 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 para desenvolvedores 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 o uv? Embora você possa usar o gerenciador do Python que preferir, o uv garante que a configuração de ENV/PATH para o Python seja igual para você e para a CLI do Gemini. Assim, sua experiência no 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, as instruções de instalação estã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 brew de acordo com os documentos oficiais.
2. No Windows, use chocolatey ou faça o download do executável em https://nodejs.org/en/download.

Para a etapa 4 (mais adiante), você também vai precisar instalar o npx. 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): autentique-se 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 o ambiente de trabalho

Você vai criar sua PRÓPRIA solução em mysolution/. Vamos criar a pasta e os dois arquivos necessários.

Agora você pode abrir seu ambiente de desenvolvimento integrado (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.

O uv sync não é estritamente necessário, mas, se ele falhar, você vai saber que precisa corrigir a instalação do Python ou do uv. Isso vai instalar o adk e outros scripts úteis na pasta ./.venv/bin/.

Para testar a 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/. O ambiente de desenvolvimento integrado também deve mostrar isso como nome raiz. Isso garante que a CLI do Gemini use a configuração correta. 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

O código está todo 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 que um código BOM seja escrito automaticamente sob sua direção.

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

É isso que queremos que você aprenda aqui. Você também pode testar todos 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 o agente de duas maneiras: CLI e Web.

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

Dica: para este exercício, use a Web para realizar qualquer tarefa (exceto testes de unidade). É incrível! Mantenha a CLI apenas para testes automatizados.

Um bom comando que testa corretamente as etapas 1, 2, 3 e 4 pode ser este (comando de teste inteligente):

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

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

Este é um comando inteligente, porque testa o tempo e os hotéis, falha de maneira diferente nas etapas 1, 2 e 3 e só é totalmente bem-sucedido na etapa 4. Você pode usar qualquer comando que quiser.

Execute-o 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 de teste" acima.

Ele provavelmente não vai saber datas específicas. Precisamos ensinar a ele como saber a data.

Na Web, faça o seguinte:

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

É necessário chamar adk web da pasta superior, de acordo com a versão da CLI.

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

5. Etapa 2: adicionar a ferramenta now()

Adicione esta função a agent.py logo 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-o novamente e faça a mesma pergunta. Agora ele deve saber a data (bom) e ser vago sobre os 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 o foco: google_search

google_search. Isso permite que nosso agente acesse informações em tempo real na 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 do 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 especialistas. Para uma integração mais avançada (usando google_search e now juntos), verifique 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 avançado: o padrão Modelo como ferramenta usando o Protocolo de Contexto de Modelo (MCP).

Para manter o foco nas capacidades avançadas do MCP, vamos substituir novamente 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

Para esta etapa, é necessário que o npx esteja instalado no sistema. O restante é igual ao que foi descrito acima.

Avisos/erros

1. Se você receber um erro de restrição robots.txt, poderá corrigir o MCP com uma diretiva de ignorar robots. 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 para saber como aumentar o tempo limite para, por exemplo, 30 segundos. Ou use a CLI do Gemini para fazer isso. Em 3dec25m, o Cloud Shell apresentou 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. 🏅 Marco 1 concluído!

🏅 Parabéns! 🏅 Agora você é especialista em ADK! Você concluiu a primeira parte do workshop e criou e testou agentes de IA com ferramentas personalizadas, integradas e 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 as horas 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: use a vibe coding (programação assistida por IA) para criar com o ADK usando a CLI do Gemini

Agora vamos entrar na parte interessante do workshop.

1. verifique se você git commit o código em um local seguro. Você pode bifurcar o código original ou criar uma ramificação. Não se preocupe, a CLI do Gemini é ótima para ajudar você com isso.
2. Encontre uma 💡 ideia para implementar. Você pode conferir as ideias abaixo, encontrar uma por conta própria ou pedir 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, você já pode 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 um emoji de hotel, seguido pelo preço e por emojis de 1 a 5 estrelas com 🌕🌕🌕🌗🌑 para fazer metades também!).
3. 🟢 [fácil] Mude o comando para ensinar o que você está procurando ou não (aceita animais de estimação, sem andar térreo, silencioso, perto de transporte público etc.) e teste. Talvez adicionar uma classificação pessoal, como "uma classificação de YOUR_NAME de 1 a 10" com base no que foi dito acima, e classificar por essa classificação.
4. 🟢 [fácil] Tem algum operador na sala? Implantar no Cloud Run. Ou para o Vertex AI Agent Engine. Sabia que você pode integrar esse agente e chamá-lo diretamente do novo Gemini Enterprise?
5. 🟢 [fácil] Integre o adk run ao 🍌 MCP do NanoBanana. Requer uma chave de API Gemini. Aqui você pode criar imagens, mas não visualizá-las. Veja abaixo uma variante mais difícil.
6. 🟡 [médio] Crie um subagente que faça o HotelSearch e crie um BudgetAgent ou um LocationAgent que possa se concentrar e iterar sobre hotéis respeitando suas necessidades de localização, por exemplo, "a não mais que X km de LOCAL". Se a API não permitir isso, pode haver alguma troca de informações com a ajuda da Pesquisa Google. Observação: a CLI do Gemini pode ajudar você.
7. 🟡 [médio] Implemente um AirbnbReviewAgent que acesse as avaliações e resuma os pontos positivos e negativos em alguns marcadores codificados por cores para 1 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] Integrar com o A2A. Transforme-o em um agente A2A! Peça ajuda à CLI do Gemini.
9. 🔴 [complexo] É possível integrar com o Flights ou outra funcionalidade do MCP para criar um agente de viagens multifuncional e multifacetado.
10. 🔴 [complexo] Integrar a Web do ADK ao 🍌 MCP do NanoBanana. Este é mais difícil do que o anterior, e você pode encontrar algumas dicas em https://github.com/palladius/ai-friendly-agents/issues/11. Isso levou 3 horas de idas e vindas com a CLI do Gemini, o Gemini 3 e nós dois lendo documentos/códigos do rag/.

Precisa de mais inspiração?

1. Confira o tutorial oficial do ADK para ter algumas ideias.
2. Peça à CLI do Gemini para encontrar ideias analisando a documentação em rag/: um comando possível seria: 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 RAG do ADK

Para programar uma funcionalidade com vibe coding, recomendamos que você baixe todo o ADK Python (observação: isso pode ser adaptado facilmente para 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 consiga ler esses arquivos, enquanto eles são ignorados pelo Git com segurança. Tecnicamente, você também pode reexibir 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 tiver curiosidade, confira como fiz isso analisando GEMINI.md e WORKSHOP_PLAN.md nesta pasta.

Lições aprendidas

Aprendemos a combinar o ADK com a CLI do Gemini

Leituras adicionais

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