Building AI agents represents a significant evolution in software development, enabling systems to perform complex reasoning and operate with greater autonomy. However, the foundational models driving these systems are naturally constrained by their training data. Without external context, they lack awareness of real-time conditions, such as the current weather outside, whether a local business is open right now, or the most efficient route to a destination.
This document details how to bridge the gap between static reasoning and dynamic reality by grounding your AI agents with trusted geospatial data from Google Maps. You'll learn why spatial grounding is critical for real-world tasks, how the Model Context Protocol (MCP) simplifies tool integration, and how to build a travel-planning agent using Google Maps Grounding Lite MCP.
Why do agents need map data grounding
The transition from traditional software to agentic workflows is a shift from deterministic engineering to probabilistic orchestration. We are moving from systems that merely know things to proactive execution engines that actually do things. When an application crosses that line and takes action in the physical world, the stakes for accuracy change entirely.
Large Language Models (LLMs) understand logic, but their internal memory is a historical snapshot. For example, if an agent is managing a supply chain and incorrectly confirms a supplier’s availability or a road route, you are looking at wasted fuel, missed SLA, and genuine business disruption. And in multi-agent architectures, you will face a cascading hallucination problem. If one agent in the chain hallucinates and passes wrong data to a second agent, the whole system starts making real-world commitments based on a lie. Autonomy without truth becomes a massive liability.
Grounding mandates that the agent steps outside its training weights. By forcing the AI to fetch verifiable, live facts - like Places data and routing data - you give the agent real-time eyes and ears, transforming a statistical guess into an informed operational decision.
Why MCP
The Model Context Protocol (MCP) is an open standard designed to make tool and data integrations plug-and-play.
Historically, connecting an AI model to an external APIs required writing rigid, bespoke wrappers. You had to manually handle formatting, error parsing, and tool-call translations for every individual capability.
MCP standardizes this integration layer. By implementing an MCP client, your application can discover and execute server-provided tools dynamically via a unified protocol. This shifts the developer’s focus from writing repetitive API integration logic to designing high-level agentic networks.
Google Maps Grounding Lite MCP
Google Maps Grounding Lite MCP is a fully managed, Google-hosted MCP server that can be integrated directly into any compatible agentic framework.
Currently, the server provides three core tools for grounding:
- Search places: Request information about places and get AI-generated place data summaries, as well as Place IDs, latitude and longitude coordinates, and Google Maps links for each of the places included in the summary. You can use the returned Place IDs and latitude and longitude coordinates with other Google Maps Platform APIs to show places on a map.
- Lookup weather: Request information about weather and return current conditions, hourly forecasts, and daily forecasts.
- Compute routes: Request information about driving or walking routes between two locations and return route distance and duration information.
To access the service, you can use either an API Key or OAuth. Google Maps Platform provides a no-cost Demo API key specifically designed to help developers start prototyping immediately.
Best Practices for Integrating Maps Grounding MCP
To maximize data relevance and eliminate structural hallucinations, anchor your agent's system instructions around these core strategies: * Be explicit and specific: Instruct the agent to use precise locations. "Central Park, New York" yields better results than "New York," just as "Paris, France" prevents confusion with Paris, Texas.
Break down generic queries: For vague requests like "date night ideas," prompt the agent to decompose the task into specific sub-searches like "romantic restaurants," "movie theaters," or "cocktail bars."
Discovery first, exploration second: Do a broad discovery search first (e.g., "Japanese restaurants with accessible entrances open on Sunday"). Present options to the user, and then run a follow-up query to fetch specific details like a phone number for the chosen venue.
Never hallucinate Place IDs: Place IDs are the critical connective tissue across Google Maps Platform services. Ensure your agent knows it must only use Place IDs explicitly returned by the search_places tool, rather than attempting to generate its own.
Implement a travel planning agent with Google ADK
This section shows how to construct a travel planning agent using the Google Agent Development Kit (ADK) framework. If you don't have the ADK installed, see the Google ADK dev doc.
Integrating the Maps MCP server into an agent framework like the ADK is straightforward. The ADK handles the complexities of context management, letting you focus on the agent's behavior.
The sample project has the following structure:
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
Sample of agent.py. Edit it based on your use cases.
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]
)
Sample of SKILL.md. Edit it based on your use cases.
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
Run adk web and interact
To start the default ADK web UI, run this command in the travel-concierge-google-maps-mcp project directory:
adk web
Interact in the UI:
- Load the UI at http://127.0.0.1:8000 in the browser
- Try prompts like:
- "I will be in San Francisco on Saturday. Plan a day trip for me."
- "Find coffee shops near Golden Gate Park and show me the menu highlights."
- "Get directions from GooglePlex to SFO."
When the agent receives the prompt, the planner evaluates the user's intent. It recognizes the need for spatial and weather data and autonomously triggers the lookup_weather, search_places, and compute_routes tools using the MCP server. The agent then synthesizes a fact-based itinerary for the user.
Conclusion
The shift toward agentic AI is unlocking entirely new capabilities in logistics, travel, and retail. However, true autonomy requires a rock-solid foundation of truth.
By leveraging the Model Context Protocol alongside Google Maps Grounding Lite, you eliminate the friction of bespoke API integrations and give your agents the real-time eyes and ears they need. Anchoring your models in live spatial data ensures they make operational decisions based on what is happening in the physical world right now - not on a frozen snapshot from their training data.
Next actions
- Read the Maps Grounding MCP developer documentation.
- Get a demo API key.
- Learn how to deploy your agent.
Principal authors:
Teresa Qin | Google Maps Platform DevX Engineer