La creación de agentes de IA representa una evolución significativa en el desarrollo de software, ya que permite que los sistemas realicen razonamientos complejos y operen con mayor autonomía. Sin embargo, los modelos fundamentales que impulsan estos sistemas están naturalmente limitados por sus datos de entrenamiento. Sin contexto externo, no tienen conocimiento de las condiciones en tiempo real, como el clima actual, si un negocio local está abierto en este momento o la ruta más eficiente para llegar a un destino.
En este documento, se detalla cómo cerrar la brecha entre el razonamiento estático y la realidad dinámica fundamentando tus agentes de IA con datos geoespaciales confiables de Google Maps. Aprenderás por qué la fundamentación espacial es fundamental para las tareas del mundo real, cómo el Protocolo de contexto del modelo (MCP) simplifica la integración de herramientas y cómo compilar un agente de planificación de viajes con el MCP de Google Maps Grounding Lite.
Por qué los agentes necesitan fundamentación de datos de mapas
La transición del software tradicional a los flujos de trabajo de agentes es un cambio de la ingeniería determinística a la organización probabilística. Estamos pasando de sistemas que simplemente saben cosas a motores de ejecución proactivos que realmente hacen cosas. Cuando una aplicación cruza esa línea y toma medidas en el mundo físico, los riesgos de la precisión cambian por completo.
Los modelos de lenguaje grandes (LLM) comprenden la lógica, pero su memoria interna es una instantánea histórica. Por ejemplo, si un agente administra una cadena de suministro y confirma de forma incorrecta la disponibilidad de un proveedor o una ruta, se desperdiciará combustible, no se cumplirá el ANS y se producirá una interrupción real del negocio. Y en las arquitecturas multiagente, te enfrentarás a un problema de alucinaciones en cascada. Si un agente de la cadena alucina y pasa datos incorrectos a un segundo agente, todo el sistema comienza a asumir compromisos en el mundo real basados en una mentira. La autonomía sin verdad se convierte en una enorme responsabilidad.
El grounding exige que el agente se salga de sus pesos de entrenamiento. Al obligar a la IA a recuperar hechos verificables y en vivo, como datos de Lugares y datos de rutas, le das al agente ojos y oídos en tiempo real, lo que transforma una suposición estadística en una decisión operativa fundamentada.
Por qué usar el MCP
El Protocolo de contexto del modelo (MCP) es un estándar abierto diseñado para que las integraciones de herramientas y datos sean plug-and-play.
Históricamente, conectar un modelo de IA a APIs externas requería escribir wrappers rígidos y personalizados. Tenías que controlar manualmente el formato, el análisis de errores y las traducciones de llamadas a herramientas para cada capacidad individual.
MCP estandariza esta capa de integración. Si implementas un cliente de MCP, tu aplicación puede descubrir y ejecutar herramientas proporcionadas por el servidor de forma dinámica a través de un protocolo unificado. Esto cambia el enfoque del desarrollador de escribir lógica de integración de APIs repetitiva a diseñar redes basadas en agentes de alto nivel.
MCP de Google Maps Grounding Lite
El servidor de MCP de Google Maps Grounding Lite es un servidor de MCP completamente administrado y alojado en Google que se puede integrar directamente en cualquier framework de agentes compatible.
Actualmente, el servidor proporciona tres herramientas principales para la fundamentación:
- Buscar lugares: Solicita información sobre lugares y obtén resúmenes de datos de lugares generados por IA, así como IDs de lugar, coordenadas de latitud y longitud, y vínculos de Google Maps para cada uno de los lugares incluidos en el resumen. Puedes usar los IDs de lugar y las coordenadas de latitud y longitud que se devuelven con otras APIs de Google Maps Platform para mostrar lugares en un mapa.
- Buscar el clima: Solicita información sobre el clima y muestra las condiciones actuales, los pronósticos por hora y los pronósticos diarios.
- Calcular rutas: Solicita información sobre rutas en automóvil o a pie entre dos ubicaciones y devuelve información sobre la distancia y la duración de la ruta.
Para acceder al servicio, puedes usar una clave de API o OAuth. Google Maps Platform proporciona una clave de API de demostración sin costo diseñada específicamente para ayudar a los desarrolladores a comenzar a crear prototipos de inmediato.
Prácticas recomendadas para integrar el MCP de fundamentación de Maps
Para maximizar la relevancia de los datos y eliminar las alucinaciones estructurales, centra las instrucciones del sistema de tu agente en estas estrategias principales: * Sé explícito y específico: Indica al agente que use ubicaciones precisas. "Central Park, Nueva York" genera mejores resultados que "Nueva York", al igual que "París, Francia" evita la confusión con París, Texas.
Desglosar búsquedas genéricas: Para solicitudes vagas como "ideas para una noche de citas", indica al agente que descomponga la tarea en subbúsquedas específicas, como "restaurantes románticos", "cines" o "bares de cócteles".
Primero el descubrimiento, luego la exploración: Primero, realiza una búsqueda de descubrimiento amplia (p.ej., "Restaurantes japoneses con entradas accesibles que abren los domingos"). Presenta opciones al usuario y, luego, ejecuta una consulta de seguimiento para recuperar detalles específicos, como un número de teléfono del lugar elegido.
Nunca alucines IDs de lugar: Los IDs de lugar son el tejido conectivo fundamental en todos los servicios de Google Maps Platform. Asegúrate de que tu agente sepa que solo debe usar los IDs de lugar que devuelve explícitamente la herramienta search_places, en lugar de intentar generar los suyos propios.
Implementa un agente de planificación de viajes con el ADK de Google
En esta sección, se muestra cómo construir un agente de planificación de viajes con el framework del Kit de desarrollo de agentes (ADK) de Google. Si no tienes instalado el ADK, consulta el documento para desarrolladores del ADK de Google.
Integrar el servidor MCP de Maps en un framework de agentes como el ADK es sencillo. El ADK se encarga de las complejidades de la administración del contexto, lo que te permite enfocarte en el comportamiento del agente.
El proyecto de ejemplo tiene la siguiente estructura:
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
Ejemplo de agent.py. Edítalo según tus 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]
)
Muestra de SKILL.md. Edítala según tus 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
Ejecuta adk web y realiza interacciones
Para iniciar la IU web predeterminada del ADK, ejecuta este comando en el directorio del proyecto travel-concierge-google-maps-mcp:
adk web
Interactúa en la IU:
- Carga la IU en http://127.0.0.1:8000 en el navegador.
- Prueba instrucciones como las siguientes:
- "Estaré en San Francisco el sábado. Planifica una excursión de un día para mí".
- "Busca cafeterías cerca del parque Golden Gate y muéstrame los aspectos más destacados del menú".
- "Obtén instrucciones sobre cómo llegar desde Googleplex hasta SFO".
Cuando el agente recibe la instrucción, el planificador evalúa la intención del usuario. Reconoce la necesidad de datos espaciales y meteorológicos, y activa de forma autónoma las herramientas lookup_weather, search_places y compute_routes con el servidor de MCP. Luego, el agente sintetiza un itinerario basado en hechos para el usuario.
Conclusión
El cambio hacia la IA de agentes está generando capacidades completamente nuevas en los sectores de logística, viajes y venta minorista. Sin embargo, la verdadera autonomía requiere una base sólida de verdad.
Si aprovechas el Protocolo de contexto del modelo junto con Grounding Lite de Google Maps, eliminas la fricción de las integraciones de APIs personalizadas y les brindas a tus agentes los ojos y oídos en tiempo real que necesitan. Anclar tus modelos en datos espaciales en tiempo real garantiza que tomen decisiones operativas basadas en lo que sucede en el mundo físico en este momento, no en una instantánea congelada de sus datos de entrenamiento.
Próximas acciones
- Lee la documentación para desarrolladores del MCP de Maps Grounding.
- Obtén una clave de API de demostración.
- Obtén más información para implementar tu agente.
Autores principales:
Teresa Qin | Ingeniera de DevX de Google Maps Platform