Tworzenie agentów AI to znaczący postęp w rozwoju oprogramowania, który umożliwia systemom złożone wnioskowanie i większą autonomię. Modele podstawowe, które napędzają te systemy, są jednak naturalnie ograniczone przez dane treningowe. Bez kontekstu zewnętrznego nie mają świadomości warunków w czasie rzeczywistym, takich jak aktualna pogoda, czy lokalna firma jest otwarta, czy też jaka jest najszybsza trasa do celu.
Z tego dokumentu dowiesz się, jak zlikwidować lukę między statycznym rozumowaniem a dynamiczną rzeczywistością, opierając agentów AI na zaufanych danych geoprzestrzennych z Map Google. Dowiesz się, dlaczego grounding przestrzenny jest niezbędny w przypadku zadań w świecie rzeczywistym, jak protokół Model Context Protocol (MCP) upraszcza integrację narzędzi oraz jak utworzyć agenta do planowania podróży przy użyciu protokołu Google Maps Grounding Lite MCP.
Dlaczego agenci potrzebują groundingu danych map
Przejście od tradycyjnego oprogramowania do przepływów pracy opartych na agentach to zmiana z deterministycznego inżynieringu na probabilistyczną orkiestrację. Przechodzimy od systemów, które po prostu coś wiedzą, do proaktywnych silników wykonawczych, które faktycznie coś robią. Gdy aplikacja przekracza tę granicę i podejmuje działania w świecie fizycznym, stawka dokładności całkowicie się zmienia.
Duże modele językowe (LLM) rozumieją logikę, ale ich pamięć wewnętrzna to migawka historyczna. Jeśli np. agent zarządza łańcuchem dostaw i nieprawidłowo potwierdzi dostępność dostawcy lub trasę drogową, spowoduje to marnowanie paliwa, niedotrzymanie umowy SLA i rzeczywiste zakłócenia w działalności. W architekturach wieloagentowych wystąpi problem kaskadowych halucynacji. Jeśli jeden agent w łańcuchu ma halucynacje i przekazuje nieprawidłowe dane drugiemu agentowi, cały system zaczyna podejmować zobowiązania w świecie rzeczywistym na podstawie kłamstwa. Autonomia bez prawdy staje się ogromnym obciążeniem.
Grounding wymaga, aby agent wyszedł poza swoje wagi treningowe. Zmuszając AI do pobierania weryfikowalnych faktów na żywo – takich jak dane o miejscach i dane o trasach – dajesz agentowi oczy i uszy w czasie rzeczywistym, przekształcając statystyczne przypuszczenie w świadomą decyzję operacyjną.
Dlaczego MCP
Protokół Model Context Protocol (MCP) to otwarty standard, który ma na celu ułatwienie integracji narzędzi i danych.
W przeszłości łączenie modelu AI z zewnętrznymi interfejsami API wymagało pisania sztywnych, niestandardowych otoczek. W przypadku każdej funkcji trzeba było ręcznie obsługiwać formatowanie, analizowanie błędów i tłumaczenie wywołań narzędzi.
MCP standaryzuje tę warstwę integracji. Dzięki wdrożeniu klienta MCP aplikacja może dynamicznie wykrywać i wykonywać narzędzia udostępniane przez serwer za pomocą ujednoliconego protokołu. Dzięki temu deweloper może skupić się na projektowaniu sieci agentów wysokiego poziomu, a nie na pisaniu powtarzalnej logiki integracji interfejsu API.
Google Maps Grounding Lite MCP
Google Maps Grounding Lite MCP to w pełni zarządzany serwer MCP hostowany przez Google, który można zintegrować bezpośrednio z dowolną zgodną strukturą agentów.
Obecnie serwer udostępnia 3 podstawowe narzędzia do groundingu:
- Wyszukiwanie miejsc: wysyłaj prośby o informacje o miejscach i otrzymuj podsumowania danych o miejscach wygenerowane przez AI, a także identyfikatory miejsc, współrzędne geograficzne i linki do Map Google dla każdego miejsca uwzględnionego w podsumowaniu. Zwrócone identyfikatory miejsc oraz współrzędne geograficzne możesz wykorzystać w innych interfejsach API Google Maps Platform, aby wyświetlać miejsca na mapie.
- Sprawdzanie pogody: wysyłaj prośby o informacje o pogodzie i otrzymuj aktualne warunki, prognozy godzinowe i progrozy dzienne.
- Obliczanie tras: wysyłaj prośby o informacje o trasach samochodowych lub pieszych między 2 lokalizacjami i otrzymuj informacje o odległości i czasie trwania trasy.
Aby uzyskać dostęp do usługi, możesz użyć klucza interfejsu API lub OAuth. Google Maps Platform udostępnia bezpłatny klucz interfejsu API do wersji demonstracyjnej, który został zaprojektowany specjalnie, aby pomóc deweloperom w natychmiastowym rozpoczęciu tworzenia prototypów.
Sprawdzone metody integracji groundingu w Mapach MCP
Aby zmaksymalizować trafność danych i wyeliminować halucynacje strukturalne, zakotwicz instrukcje systemowe agenta wokół tych podstawowych strategii: * Bądź wyraźny i konkretny: poinstruuj agenta, aby używał dokładnych lokalizacji. „Central Park, Nowy Jork” daje lepsze wyniki niż „Nowy Jork”, podobnie jak „Paryż, Francja” zapobiega pomyłce z Paryżem w Teksasie.
Dziel ogólne zapytania: w przypadku niejasnych zapytań, takich jak "pomysły na randkę", poproś agenta o podzielenie zadania na konkretne podwyszukiwania, np. "romantyczne restauracje", "kina" lub "bary koktajlowe".
Najpierw wyszukiwanie pośrednie, potem eksploracja: najpierw przeprowadź szerokie wyszukiwanie pośrednie (np. „restauracje japońskie z dostępnymi wejściami otwarte w niedzielę”). Przedstaw użytkownikowi opcje, a następnie uruchom zapytanie uzupełniające, aby pobrać konkretne informacje, np. numer telefonu wybranego miejsca.
Nigdy nie halucynuj identyfikatorów miejsc: identyfikatory miejsc to kluczowe połączenie między usługami Google Maps Platform. Upewnij się, że agent wie, że może używać tylko identyfikatorów miejsc wyraźnie zwracanych przez narzędzie search_places, a nie próbować generować własnych.
Implementowanie agenta do planowania podróży za pomocą pakietu Google ADK
W tej sekcji pokazujemy, jak utworzyć agenta do planowania podróży za pomocą pakietu Google Agent Development Kit (ADK). Jeśli nie masz zainstalowanego pakietu ADK, zapoznaj się z dokumentacją dla deweloperów Google ADK.
Integracja serwera Maps MCP z platformą agentów, taką jak ADK, jest prosta. Pakiet ADK obsługuje złożone zarządzanie kontekstem, dzięki czemu możesz skupić się na zachowaniu agenta.
Przykładowy projekt ma taką strukturę:
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
Przykład agent.py. Edytuj go na podstawie swoich przypadków użycia.
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]
)
Przykład SKILL.md. Edytuj go na podstawie swoich przypadków użycia.
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
Uruchom adk web i wejdź w interakcję
Aby uruchomić domyślny interfejs ADK web, uruchom to polecenie w katalogu projektu travel-concierge-google-maps-mcp:
adk web
Interakcja w interfejsie:
- Otwórz interfejs w przeglądarce pod adresem http://127.0.0.1:8000.
- Wypróbuj prompta, np.:
- „W sobotę będę w San Francisco. Zaplanuj mi jednodniową wycieczkę”.
- „Znajdź kawiarnie w pobliżu Golden Gate Park i pokaż mi najważniejsze pozycje w menu”.
- „Wyznacz trasę z GooglePlex do SFO”.
Gdy agent otrzyma prompta, planer oceni intencje użytkownika. Rozpozna potrzebę danych geoprzestrzennych i pogodowych oraz autonomicznie uruchomi narzędzia lookup_weather, search_places i compute_routes za pomocą serwera MCP. Następnie agent utworzy dla użytkownika plan podróży oparty na faktach.
Podsumowanie
Przejście na agentową AI otwiera zupełnie nowe możliwości w logistyce, podróżach i handlu detalicznym. Prawdziwa autonomia wymaga jednak solidnych podstaw prawdy.
Dzięki wykorzystaniu protokołu Model Context Protocol wraz z Google Maps Grounding Lite możesz wyeliminować problemy związane z niestandardowymi integracjami interfejsów API i zapewnić agentom oczy i uszy w czasie rzeczywistym. Zakotwiczenie modeli w danych geoprzestrzennych na żywo zapewnia, że będą one podejmować decyzje operacyjne na podstawie tego, co dzieje się w świecie fizycznym, a nie na podstawie zamrożonej migawki z danych treningowych.
Następne kroki
- Zapoznaj się z dokumentacją dla deweloperów dotyczącą groundingu w Mapach MCP.
- Pobierz klucz interfejsu API do wersji demonstracyjnej.
- Dowiedz się, jak wdrożyć agenta.
Główni autorzy:
Teresa Qin | Inżynier DevX w Google Maps Platform