La creazione di agenti AI rappresenta un'evoluzione significativa nello sviluppo di software, consentendo ai sistemi di eseguire ragionamenti complessi e operare con maggiore autonomia. Tuttavia, i modelli di base che guidano questi sistemi sono naturalmente limitati dai loro dati di addestramento. Senza un contesto esterno, non sono consapevoli delle condizioni in tempo reale, come il meteo attuale, se un'attività locale è aperta in questo momento o il percorso più efficiente per raggiungere una destinazione.
Questo documento spiega in dettaglio come colmare il divario tra il ragionamento statico e la realtà dinamica basando gli agenti AI su dati geospaziali affidabili di Google Maps. Scoprirai perché il grounding spaziale è fondamentale per le attività reali, come il Model Context Protocol (MCP) semplifica l'integrazione degli strumenti e come creare un agente di pianificazione dei viaggi utilizzando il grounding di Google Maps Lite MCP.
Perché gli agenti hanno bisogno del grounding dei dati delle mappe
La transizione dal software tradizionale agli Agentic Workflows è un passaggio dall'engineering deterministico all'orchestrazione probabilistica. Stiamo passando da sistemi che si limitano a conoscere le cose a motori di esecuzione proattivi che le fanno effettivamente. Quando un'applicazione supera questa linea e agisce nel mondo fisico, la posta in gioco per l'accuratezza cambia completamente.
I modelli linguistici di grandi dimensioni (LLM) comprendono la logica, ma la loro memoria interna è un'istantanea storica. Ad esempio, se un agente gestisce una catena di fornitura e conferma erroneamente la disponibilità di un fornitore o un percorso stradale, si rischia di sprecare carburante, non rispettare lo SLA e causare una vera e propria interruzione dell'attività. Inoltre, nelle architetture multi-agente, si verificherà un problema di allucinazioni a cascata. Se un agente della catena ha un'allucinazione e trasmette dati errati a un secondo agente, l'intero sistema inizia a prendere impegni nel mondo reale basati su una menzogna. L'autonomia senza verità diventa una responsabilità enorme.
Il grounding impone all'agente di andare oltre i pesi di addestramento. Forzando l'AI a recuperare dati verificabili e in tempo reale, come i dati di Places e i dati di routing, fornisci all'agente occhi e orecchie in tempo reale, trasformando un'ipotesi statistica in una decisione operativa informata.
Perché MCP
Il Model Context Protocol (MCP) è uno standard aperto progettato per rendere plug-and-play le integrazioni di strumenti e dati.
In passato, per connettere un modello di AI ad API esterne era necessario scrivere wrapper rigidi e personalizzati. Dovevi gestire manualmente la formattazione, l'analisi degli errori e le traduzioni delle chiamate degli strumenti per ogni singola funzionalità.
L'MCP standardizza questo livello di integrazione. Implementando un client MCP, la tua applicazione può scoprire ed eseguire dinamicamente gli strumenti forniti dal server tramite un protocollo unificato. In questo modo, lo sviluppatore può concentrarsi sulla progettazione di reti agentiche di alto livello anziché sulla scrittura di logiche di integrazione delle API ripetitive.
Google Maps Grounding Lite MCP
Google Maps Grounding Lite MCP è un server MCP completamente gestito e ospitato da Google che può essere integrato direttamente in qualsiasi framework di agenti compatibile.
Al momento, il server fornisce tre strumenti principali per il grounding:
- Cerca luoghi: richiedi informazioni sui luoghi e ottieni riepiloghi dei dati sui luoghi generati dall'AI, nonché ID luogo, coordinate di latitudine e longitudine e link a Google Maps per ciascuno dei luoghi inclusi nel riepilogo. Puoi utilizzare gli ID luogo e le coordinate di latitudine e longitudine restituite con altre API di Google Maps Platform per mostrare i luoghi su una mappa.
- Cerca meteo: richiedi informazioni sul meteo e restituisci le condizioni attuali, le previsioni orarie e le previsioni giornaliere.
- Calcola percorsi: richiedi informazioni sui percorsi in auto o a piedi tra due località e restituisci informazioni sulla distanza e sulla durata del percorso.
Per accedere al servizio, puoi utilizzare una chiave API o OAuth. Google Maps Platform fornisce una chiave API demo senza costi, progettata specificamente per aiutare gli sviluppatori a iniziare immediatamente la prototipazione.
Best practice per l'integrazione dell'MCP di grounding di Maps
Per massimizzare la pertinenza dei dati ed eliminare le allucinazioni strutturali, ancora le istruzioni di sistema dell'agente a queste strategie di base: * Sii esplicito e specifico: istruisci l'agente a utilizzare posizioni esatte. "Central Park, New York" produce risultati migliori di "New York", così come "Parigi, Francia" evita la confusione con Parigi, Texas.
Suddividi le query generiche: per richieste vaghe come "idee per un appuntamento", chiedi all'agente di scomporre l'attività in ricerche secondarie specifiche come "ristoranti romantici", "cinema" o "cocktail bar".
Prima la scoperta, poi l'esplorazione: esegui prima una ricerca di scoperta generica (ad es. "ristoranti giapponesi con ingressi accessibili aperti la domenica"). Presenta le opzioni all'utente, quindi esegui una query di follow-up per recuperare dettagli specifici, come un numero di telefono per il luogo scelto.
Non inventare mai gli ID luogo: gli ID luogo sono il tessuto connettivo fondamentale tra i servizi di Google Maps Platform. Assicurati che l'agente sappia che deve utilizzare solo gli ID luogo restituiti esplicitamente dallo strumento search_places, anziché tentare di generarne di propri.
Implementa un agente di pianificazione dei viaggi con Google ADK
Questa sezione mostra come creare un agente di pianificazione dei viaggi utilizzando il framework Google Agent Development Kit (ADK). Se non hai installato l'ADK, consulta la documentazione per sviluppatori di Google ADK.
L'integrazione del server MCP di Maps in un framework di agenti come ADK è semplice. L'ADK gestisce le complessità della gestione del contesto, consentendoti di concentrarti sul comportamento dell'agente.
Il progetto di esempio ha la seguente struttura:
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
Esempio di agent.py. Modificalo in base ai tuoi casi d'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]
)
Esempio di SKILL.md. Modificalo in base ai tuoi casi d'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
Esegui adk web e interagisci
Per avviare l'interfaccia utente web ADK predefinita, esegui questo comando nella directory del progetto travel-concierge-google-maps-mcp:
adk web
Interagisci nell'interfaccia utente:
- Carica la UI all'indirizzo http://127.0.0.1:8000 nel browser
- Prova prompt come:
- "Sabato sarò a San Francisco. Pianifica una gita di un giorno per me."
- "Trova caffetterie vicino al Golden Gate Park e mostrami i piatti forti del menu."
- "Indicazioni stradali da Googleplex a SFO."
Quando l'agente riceve il prompt, il planner valuta l'intent dell'utente. Riconosce la necessità di dati spaziali e meteorologici e attiva autonomamente gli strumenti lookup_weather, search_places e compute_routes utilizzando il server MCP. L'agente sintetizza quindi un itinerario basato sui fatti per l'utente.
Conclusione
Il passaggio all'AI agentica sta sbloccando funzionalità completamente nuove nei settori della logistica, dei viaggi e della vendita al dettaglio. Tuttavia, la vera autonomia richiede una base di verità solida come una roccia.
Sfruttando il Model Context Protocol insieme a Grounding Lite di Google Maps, elimini l'attrito delle integrazioni API personalizzate e fornisci ai tuoi agenti gli occhi e le orecchie in tempo reale di cui hanno bisogno. Ancorando i modelli a dati spaziali in tempo reale, si garantisce che prendano decisioni operative basate su ciò che sta accadendo nel mondo fisico in questo momento, non su un'istantanea statica dei dati di addestramento.
Azioni successive
- Leggi la documentazione per lo sviluppo di Maps Grounding MCP.
- Ottieni una chiave API demo.
- Scopri come eseguire il deployment dell'agente.
Autori principali:
Teresa Qin | Google Maps Platform DevX Engineer