A criação de agentes de IA representa uma evolução significativa no desenvolvimento de software, permitindo que os sistemas realizem raciocínios complexos e operem com maior autonomia. No entanto, os modelos básicos que impulsionam esses sistemas são naturalmente limitados pelos dados de treinamento. Sem contexto externo, eles não têm consciência das condições em tempo real, como o clima atual, se uma empresa local está aberta no momento ou a rota mais eficiente para um destino.
Este documento detalha como preencher a lacuna entre o raciocínio estático e a realidade dinâmica, fundamentando seus agentes de IA com dados geoespaciais confiáveis do Google Maps. Você vai aprender por que o embasamento espacial é fundamental para tarefas do mundo real, como o Protocolo de Contexto de Modelo (MCP) simplifica a integração de ferramentas e como criar um agente de planejamento de viagens usando o MCP do Grounding Lite do Google Maps.
Por que os agentes precisam de embasamento de dados do mapa
A transição do software tradicional para fluxos de trabalho agênticos é uma mudança da engenharia determinística para a orquestração probabilística. Estamos passando de sistemas que apenas sabem coisas para mecanismos de execução proativos que realmente fazem coisas. Quando um aplicativo cruza essa linha e age no mundo físico, as apostas na precisão mudam completamente.
Os modelos de linguagem grandes (LLMs) entendem a lógica, mas a memória interna deles é um instantâneo histórico. Por exemplo, se um agente estiver gerenciando uma cadeia de suprimentos e confirmar incorretamente a disponibilidade de um fornecedor ou uma rota rodoviária, você terá desperdício de combustível, perda de SLA e interrupção real dos negócios. E, em arquiteturas multiagentes, você vai enfrentar um problema de alucinação em cascata. Se um agente na cadeia alucinar e passar dados errados para um segundo agente, todo o sistema começará a fazer compromissos no mundo real com base em uma mentira. A autonomia sem verdade se torna uma responsabilidade enorme.
O embasamento exige que o agente saia dos pesos de treinamento. Ao forçar a IA a buscar fatos verificáveis e em tempo real, como dados de lugares e de rotas, você dá ao agente olhos e ouvidos em tempo real, transformando um palpite estatístico em uma decisão operacional informada.
Por que o MCP
O Protocolo de Contexto de Modelo (MCP) é um padrão aberto criado para tornar as integrações de ferramentas e dados plug-and-play.
Historicamente, conectar um modelo de IA a APIs externas exigia a criação de wrappers rígidos e personalizados. Era necessário processar manualmente a formatação, a análise de erros e as traduções de chamadas de ferramentas para cada recurso individual.
O MCP padroniza essa camada de integração. Ao implementar um cliente do MCP, o aplicativo pode descobrir e executar ferramentas fornecidas pelo servidor de forma dinâmica usando um protocolo unificado. Isso muda o foco do desenvolvedor de escrever uma lógica de integração de API repetitiva para projetar redes agênticas de alto nível.
MCP do Grounding Lite do Google Maps
O MCP do Grounding Lite do Google Maps é um servidor MCP totalmente gerenciado e hospedado pelo Google que pode ser integrado diretamente a qualquer framework agêntico compatível.
Atualmente, o servidor oferece três ferramentas principais para embasamento:
- Pesquisar lugares: solicite informações sobre lugares e receba resumos de dados de lugares gerados por IA, bem como IDs de lugares, coordenadas de latitude e longitude e links do Google Maps para cada um dos lugares incluídos no resumo. Você pode usar os IDs de lugares e as coordenadas de latitude e longitude retornados com outras APIs da Plataforma Google Maps para mostrar lugares em um mapa.
- Consultar clima: solicite informações sobre o clima e retorne as condições atuais, previsões horárias e previsões diárias.
- Calcular rotas: solicite informações sobre rotas de carro ou a pé entre dois locais e retorne informações de distância e duração da rota.
Para acessar o serviço, você pode usar uma chave de API ou o OAuth. A Plataforma Google Maps oferece uma chave de API de demonstração sem custo financeiro, projetada especificamente para ajudar os desenvolvedores a começar a prototipar imediatamente.
Práticas recomendadas para integrar o MCP do Grounding do Maps
Para maximizar a relevância dos dados e eliminar alucinações estruturais, ancore as instruções do sistema do agente nessas estratégias principais: * Seja explícito e específico: instrua o agente a usar locais precisos. "Central Park, Nova York" gera resultados melhores do que "Nova York", assim como "Paris, França" evita confusão com Paris, Texas.
Divida consultas genéricas: para solicitações vagas como "ideias para um encontro", peça ao agente para decompor a tarefa em subpesquisas específicas, como "restaurantes românticos", "cinemas" ou "bares de coquetéis".
Primeiro a descoberta, depois a exploração: faça uma pesquisa de descoberta ampla primeiro (por exemplo, "restaurantes japoneses com entradas acessíveis abertos no domingo"). Apresente opções ao usuário e, em seguida, execute uma consulta de acompanhamento para buscar detalhes específicos, como um número de telefone do local escolhido.
Nunca alucine IDs de lugares: os IDs de lugares são o tecido conjuntivo essencial nos serviços da Plataforma Google Maps. Verifique se o agente sabe que só pode usar IDs de lugares retornados explicitamente pela ferramenta search_places, em vez de tentar gerar os próprios.
Implementar um agente de planejamento de viagens com o ADK do Google
Esta seção mostra como criar um agente de planejamento de viagens usando o framework do Kit de Desenvolvimento de Agente (ADK, na sigla em inglês) do Google. Se você não tiver o ADK instalado, consulte o documento de desenvolvimento do ADK do Google.
A integração do servidor MCP do Maps em um framework de agente como o ADK é simples. O ADK processa as complexidades do gerenciamento de contexto, permitindo que você se concentre no comportamento do agente.
O projeto de exemplo tem a seguinte estrutura:
travel-concierge-google-maps-mcp/
├── travel_planner_agent/
├── agent.py # main agent code
├── .env # API keys
├── __init__.py
├── skills/travel-concierge/
├── SKILL.md # Agent skill
Exemplo de agent.py. Edite-o com base nos seus casos de uso.
import os
import pathlib
import logging
from datetime import date
from dotenv import load_dotenv
from google.adk.agents.llm_agent import Agent
from google.adk.skills import load_skill_from_dir
from google.adk.tools import skill_toolset
from google.adk.tools.mcp_tool import McpToolset
from google.adk.planners import BuiltInPlanner
from google.genai import types
from google.adk.tools.mcp_tool.mcp_session_manager
import StreamableHTTPConnectionParams
load_dotenv()
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")
if not GOOGLE_MAPS_API_KEY:
raise ValueError("Missing GOOGLE_MAPS_API_KEY environment variable.")
current_date = date.today().strftime("%A, %B %d, %Y")
# AGENT & TOOL SETUP
BASE_SYSTEM_INSTRUCTION = f"""
You are a Premium Travel Orchestrator. Your sole purpose is to assist users with travel planning, location discovery, route mapping, weather checks, and culinary/cultural recommendations. The current system date is {current_date}.
# 1. OUT-OF-DOMAIN PROTOCOL (Strict Refusal)
You are strictly forbidden from answering queries unrelated to travel, geography, food, hospitality, or local experiences.
If a user asks about coding (e.g., Python bugs), math, writing essays, or general non-travel trivia:
- Politely decline.
- Explicitly state that your expertise is limited to travel and local discovery.
- Pivot by asking if they need help planning a trip or finding a great local spot.
# 2. TANGENTIAL KNOWLEDGE PROTOCOL (The "Tiramisu" Rule)
If a user asks a factual question about food, a cultural item, or a historical concept that *can* be tied to a physical location (e.g., "What is tiramisu?", "What is Gothic architecture?"):
- Provide a brief, helpful 1-2 sentence explanation of the concept.
- IMMEDIATELY pivot to your primary domain. Ask the user for their current location or target city so you can search for the best places to experience or eat that item.
# 3. TOOL EXECUTION BOUNDARIES
- NEVER call `lookup_weather` for general history, trivia, or factual questions.
- ONLY call `lookup_weather` if the user explicitly asks for the forecast, OR if they have confirmed they are actively planning an itinerary/trip for a specific date and destination.
"""
travel_skill = load_skill_from_dir(
pathlib.Path(__file__).parent / "skills" / "travel-concierge"
)
maps_mcp_toolset = McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://mapstools.googleapis.com/mcp",
headers={
"X-Goog-Api-Key": GOOGLE_MAPS_API_KEY,
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream"
}
)
)
my_skill_toolset = skill_toolset.SkillToolset(
skills=[travel_skill],
additional_tools=[maps_mcp_toolset]
)
root_agent = Agent(
model='gemini-flash-latest',
name='travel_planner_agent',
description="A highly capable assistant leveraging specialized modular skills and spatial tools.",
instruction=BASE_SYSTEM_INSTRUCTION,
planner=BuiltInPlanner(
thinking_config=types.ThinkingConfig(
include_thoughts=True
)
),
tools=[my_skill_toolset]
)
Exemplo de SKILL.md. Edite-o com base nos seus casos de uso.
name: travel-concierge
description:
Accesses real-time spatial data, weather, and traffic routing to design accurate itineraries and provide location-based information.
Use when: A user is planning a trip, creating a travel itinerary, mapping a route, asking about a city's history, discovering local foods, exploring basic geography trivia, or inquiring about the weather.
Dont use for: Tasks completely unrelated to travel, locations, geography, or weather, such as coding assistance, mathematical calculations, or personal finance.
metadata:
adk_additional_tools:
- search_places
- lookup_weather
- compute_routes
---
# Travel Concierge Workflow
You act as an elite, deeply consultative travel planner. You are responsible for designing logistically sound travel plans by strictly prioritizing your toolset over pre-trained memory.
To deliver a premium experience, you must manage the interaction in two distinct phases: Discovery and Execution.
## Phase 1: Discovery Dialogue & Briefing (First Turn)
When a user initiates a request but leaves critical logistical variables open, **do NOT generate a complete multi-stop itinerary or directions link immediately.** Instead, build a warm, conversational dialogue to lock in the baseline parameters.
1. **Conditional Weather Context Hook:** ONLY call `lookup_weather` if the user is actively planning a trip to a specific location on a specific date, OR if they explicitly ask for the weather. DO NOT check the weather for general questions about a city's history or local foods. If you do check the weather for a trip, share a brief summary of the conditions to justify your upcoming line of questioning.
2. **Targeted Consultation (Ask 2-3 Friendly Questions):**
- **Verify Arrival Point & Terminal:** Never assume an airport arrival. If they state an arrival time but no explicit location, set an internal baseline but explicitly ask them to confirm their exact station or airport terminal. **If they confirm an airport arrival, strictly verify whether it is a Domestic or International flight**, as clearing international customs and immigration requires adding a 60-to-90-minute buffer to the initial travel time before scheduling the first venue.
- **Verify User Preferences:** If food or activity interests are ambiguous or partial (e.g., "coffee and seafood"), acknowledge these directly and ask about their preferred style or pacing (e.g., casual local markets vs. seated upscale dining).
- **Anchor Point Checking:** Always ask if there is a specific bucket-list venue or seasonal sight they absolutely must visit so you can build the fixed timeline around it.
## Phase 2: Location Extraction & Validation
- Use `search_places` to verify destinations, opening hours, and location accuracy.
- **CRITICAL INPUT RULE:** You must ensure the `text_query` parameter contains explicit location keywords. If the user mentions "boutique hotels" or "seafood dinner", you must modify the query to include the city (e.g., text_query="boutique hotels in Sydney, Australia").
## Phase 3: Tool Execution & Itinerary Reveal (Subsequent Turns)
Once the user responds with their specific logistics, construct the definitive itinerary using your spatial grounding tools. When preferences remain broad, default to highly rated venues that match the verified weather conditions and current seasonality.
### 1. Location Validation (`search_places`)
- Verify all destinations, opening hours, and exact addresses.
- **CRITICAL INPUT RULE:** You must ensure the `text_query` parameter contains explicit location keywords. If the user requests "boutique hotels" or "seafood lunch", modify the query to append the target city/region (e.g., `text_query="seafood lunch in Sydney, Australia"`).
### 2. Logistical Reality (`compute_routes`)
- Ensure consecutive stops are logically possible by checking travel times and distances.
- Pass both `origin` and `destination` using verified addresses or Place IDs. If either is missing, halt and ask for clarification.
- Do NOT hallucinate Place ID. You must use the Place ID provided by `search_places`.
### 3. Itinerary Output Formatting
- **Route to Next Stop:** Between every single consecutive itinerary stop, you MUST output a dedicated sub-bullet detailing the transit path.
- This bullet must explicitly state the suggested travel mode (Walk, Transit, or Drive), the exact travel time in minutes verified by `compute_routes`, and a brief path description (e.g., *"Route to Next Stop: 12-minute walk via Market St"*).
- **Attribution:** Include inline or bracketed Google Maps URLs for recommended venues using data derived from the tool's attribution payloads. Do not guess links.
### 4. Multi-Stop Directions Link Generation
At the absolute end of your finalized itinerary response, compile all planned locations into a single, functional Google Maps Directions URL.
- **Format Constraint:** Build the URL using the base string: `https://www.google.com/maps/dir/`
- Append each venue name and full address sequentially, separated by a forward slash `/`, replacing spaces with `+` and encoding URL parameters where necessary.
- Example format: `https://www.google.com/maps/dir/Venue+One,+Address/Venue+Two,+Address/Venue+Three,+Address/`
- Present this link prominently with clear anchor text.
## Phase 4: Output Formatting & Source Attribution (CRITICAL)
- You must comply strictly with Google Maps Platform display guidelines.
- Every grounded piece of information (Places, Weather, Routes) must be immediately followed by its supporting source.
- For place details extracted via `search_places`, always map and output the exact URL provided in the `places.googleMapsLinks.placeUrl` payload. Do not invent links.
init.py
from . import agent
Executar o adk web e interagir
Para iniciar a interface da web padrão do ADK, execute este comando no diretório do projeto travel-concierge-google-maps-mcp:
adk web
Interagir na interface:
- Carregue a interface em http://127.0.0.1:8000 no navegador.
- Teste comandos como:
- "Estarei em São Francisco no sábado. Planeje uma viagem de um dia para mim."
- "Encontre cafés perto do Golden Gate Park e mostre os destaques do cardápio."
- "Receba rotas do GooglePlex para o SFO."
Quando o agente recebe o comando, o planejador avalia a intenção do usuário. Ele reconhece a necessidade de dados espaciais e climáticos e aciona de forma autônoma as ferramentas lookup_weather, search_places e compute_routes usando o servidor MCP. Em seguida, o agente sintetiza um itinerário baseado em fatos para o usuário.
Conclusão
A mudança para a IA agêntica está revelando recursos totalmente novos em logística, viagens e varejo. No entanto, a verdadeira autonomia exige uma base sólida de verdade.
Ao aproveitar o Protocolo de Contexto de Modelo com o Grounding Lite do Google Maps, você elimina o atrito das integrações de API personalizadas e oferece aos seus agentes os olhos e ouvidos em tempo real de que eles precisam. A ancoragem dos modelos em dados espaciais em tempo real garante que eles tomem decisões operacionais com base no que está acontecendo no mundo físico agora, e não em um instantâneo congelado dos dados de treinamento.
Próximas ações
- Leia a documentação para desenvolvedores do MCP do Grounding do Maps.
- Receba uma chave de API de demonstração.
- Saiba como implantar seu agente.
Principais autores:
Teresa Qin | Engenheira de DevX da Plataforma Google Maps