Criar um agente de planejamento de itinerários com o ADK e o embasamento do Google Maps

1. Introdução

Neste codelab, você vai criar um agente de planejamento de viagens usando o Kit de Desenvolvimento de Agente (ADK, na sigla em inglês) e o Google Maps. Você vai solicitar ao agente que gere rotas panorâmicas e recomendações de restaurantes, aproveitando dados reais do Google Maps.

Atividades deste laboratório

• Inicializar um projeto de agente usando o pacote inicial do agente
• Configurar o agente para usar a ferramenta Google Maps Grounding
• Testar o agente resultante localmente com uma interface da Web

O que é necessário

• Um navegador da web, como o Chrome
• Tenha um projeto na nuvem do Google Cloud com o faturamento ativado.

Este codelab é destinado a desenvolvedores intermediários que têm alguma familiaridade com o Python e o Google Cloud, mas não são necessariamente especialistas.

2. Antes de começar

Criar um projeto do Google Cloud

1. No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
2. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como verificar se o faturamento está ativado em um projeto.

Iniciar o Cloud Shell

1. Verificar a autenticação:

gcloud auth list

2. Confirmar seu projeto:

gcloud config get project

3. Defina, se necessário:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Ativar APIs

Execute este comando para ativar todas as APIs necessárias:

gcloud services enable \
  aiplatform.googleapis.com

3. Instalar o pacote inicial do agente

A maneira mais fácil de iniciar um projeto do ADK é com o pacote inicial do agente. O pacote inicial do agente do Google Cloud é uma ferramenta de interface de linha de comando (CLI, na sigla em inglês) de código aberto projetada para acelerar o desenvolvimento e a implantação de agentes de IA generativa prontos para produção no Google Cloud.

1. Verifique se o uv está instalado e execute o comando de criação para inicializar um novo projeto de agente:

uvx agent-starter-pack create

Se você não tiver o uv instalado, poderá usar o pip:

# Create and activate a Python virtual environment
python -m venv .venv && source .venv/bin/activate

# Install the agent starter pack
pip install --upgrade agent-starter-pack

# Create a new agent project
agent-starter-pack create

Consulte o repositório agent-starter-pack para mais detalhes.

2. Quando solicitado, forneça as seguintes opções para configurar seu projeto para desenvolvimento local com um front-end React:

• Modelo de agente: adk (agente React simples)
• Implantação: none (implantação na nuvem desativada por enquanto)
• Região: us-central1

Isso vai gerar uma estrutura de diretório de projeto que contém a lógica principal do agente, testes e um guia GEMINI.md. Navegue até o novo diretório:

cd my-agent

4. Configurar o Grounding

O pacote inicial do agente gera um arquivo GEMINI.md que instrui as ferramentas de programação assistida por IA sobre como gerenciar seu projeto. Vamos atualizar isso para incluir a documentação do Google Maps Grounding.

1. Abra GEMINI.md no editor.
2. Adicione o seguinte link de referência na seção ## Reference Documentation:

- **Google Maps Grounding**: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps

Esse contexto vai ajudar qualquer assistente de programação de IA a entender o recurso de Grounding.

5. Atualizar o agente

Agora vamos configurar o agente para atuar como um planejador de itinerários, com a ferramenta Google Maps Grounding.

1. Abra o arquivo app/agent.py.
2. Substitua todo o conteúdo de app/agent.py pelo seguinte código:

"""Agent application for the itinerary planner codelab."""

import os
import google.auth
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.adk.tools import google_maps_grounding
from google.genai import types

# Authenticate and set environment variables
_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

# Define the root agent
root_agent = Agent(
    name="itinerary_planner_agent",
    model=Gemini(
        model="gemini-2.5-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=(
        "You are an itinerary planner agent. Help users plan their trips by"
        " recommending restaurants and scenic routes. Use the"
        " google_maps_grounding tool to get both restaurant recommendations and"
        " route recommendations based on user preferences. When calling for"
        " restaurant recommendation, prompt the tool to tell you about the vibe"
        " of the place. When calling for routes with multiple legs, describe"
        " each of those legs with a brief sentence. Always describe the key"
        " landmarks along the route in one brief sentence."
    ),
    # Add the Google Maps Grounding tool to the agent
    tools=[google_maps_grounding],
)

app = App(
    root_agent=root_agent,
    name="app",
)

Esse código configura um agente baseado em gemini-2.5-flash que usa a ferramenta google_maps_grounding para recuperar informações atuais sobre lugares e rotas.

Para conferir todos os modelos disponíveis, consulte a documentação da Vertex AI.

6. Executar o agente

Com a lógica do agente no lugar, tente testá-lo na interface da Web local.

1. Na raiz do diretório my-agent, execute o seguinte comando para iniciar o app da Web:

uv run adk web

ou, se estiver usando um ambiente virtual:

adk web

2. Abra o URL fornecido na saída do terminal no navegador.
3. Teste o agente fazendo uma pergunta. Exemplo:

• "Planeje um itinerário de um dia em São Paulo, incluindo um bom restaurante italiano."
• "Estou visitando Tóquio. Você pode me dar um itinerário com pontos históricos interessantes e um lugar de ramen bem avaliado com um ambiente aconchegante?"

Você vai ver uma saída semelhante a um itinerário detalhado enriquecido com avaliações reais e descrições de rotas extraídas diretamente do Google Maps.

7. Verificar o Grounding no código

Para confirmar programaticamente que o agente está usando o Grounding do Maps, inspecione os eventos de resposta para metadados específicos do Maps.

Quando você executa o agente (por exemplo, em um script de teste), ele gera eventos que contêm grounding_metadata. É possível iterar os grounding_chunks nesses metadados e verificar o atributo maps.

Confira um exemplo que demonstra como verificar o atributo maps, semelhante ao que você pode usar em um teste automatizado:

async for event in runner.run_async(
    user_id="test_user",
    session_id=session.id,
    new_message=content,
):
    if event.grounding_metadata:
        if event.grounding_metadata.grounding_chunks:
            for chunk in event.grounding_metadata.grounding_chunks:
                # Check for the maps attribute to confirm maps grounding
                if hasattr(chunk, "maps") and chunk.maps:
                    print("SUCCESS: Maps grounding chunks detected in the response!")

8. Extrair polilinhas codificadas

Além de verificar se o Grounding ocorreu, talvez você queira extrair dados específicos, como caminhos de rotas. Quando a ferramenta de Grounding do Maps retorna informações de rotas, ela geralmente inclui uma "polilinha codificada" que pode ser usada para renderizar a rota em um front-end de mapa.

Para encontrar essa polilinha, verifique o texto no atributo maps dos grounding_chunks. Confira um exemplo de como detectar isso:

async for event in runner.run_async(
    user_id="test_user",
    session_id=session.id,
    new_message=content,
):
    if event.grounding_metadata:
        if event.grounding_metadata.grounding_chunks:
            for chunk in event.grounding_metadata.grounding_chunks:
                # Extract the encoded polyline from the maps chunk text
                if (
                    hasattr(chunk, "maps")
                    and chunk.maps
                    and hasattr(chunk.maps, "text")
                    and chunk.maps.text
                    and "Encoded Polyline" in chunk.maps.text
                ):
                    print("SUCCESS: Encoded Polyline detected in the response!")

9. Limpar

Para evitar cobranças contínuas na sua conta do Google Cloud, exclua os recursos criados durante este codelab.

1. Se você criou um projeto dedicado para este codelab, exclua-o totalmente:

gcloud projects delete $PROJECT_ID

Se você usou um projeto atual e quer mantê-lo, não há recursos específicos para excluir, já que o agente foi executado localmente e as APIs usadas são sem servidor.

10. Parabéns

Parabéns! Você criou um agente de planejamento de itinerários e o fundamentou usando insights do Google Maps.

O que você aprendeu

• Como criar um novo agente usando o pacote inicial do agente
• Como adicionar ferramentas de Grounding a uma definição de agente do ADK
• Como testar um agente do ADK usando o executor da Web integrado

Próximas etapas

• Conheça outras ferramentas do ADK e padrões de integração

Documentos de referência

• Documentação do ADK
• Google Maps Grounding