Membangun agen AI merupakan evolusi signifikan dalam pengembangan software, yang memungkinkan sistem melakukan penalaran kompleks dan beroperasi dengan otonomi yang lebih besar. Namun, model dasar yang menggerakkan sistem ini secara alami dibatasi oleh data pelatihannya. Tanpa konteks eksternal, model ini tidak memiliki pemahaman tentang kondisi real-time, seperti cuaca saat ini di luar, apakah bisnis lokal sedang buka saat ini, atau rute paling efisien ke tujuan.
Dokumen ini menjelaskan cara menjembatani kesenjangan antara penalaran statis dan realitas dinamis dengan melakukan grounding pada agen AI Anda menggunakan data geospasial tepercaya dari Google Maps. Anda akan mempelajari alasan pentingnya grounding spasial untuk tugas-tugas di dunia nyata, cara Model Context Protocol (MCP) menyederhanakan integrasi alat, dan cara membangun agen perencanaan perjalanan menggunakan MCP Google Maps Grounding Lite.
Mengapa agen memerlukan grounding data peta
Transisi dari software tradisional ke alur kerja agentic adalah pergeseran dari engineering deterministik ke orkestrasi probabilistik. Kita beralih dari sistem yang sekadar mengetahui berbagai hal ke mesin eksekusi proaktif yang benar-benar melakukan berbagai hal. Jika aplikasi melewati batas tersebut dan mengambil tindakan di dunia fisik, taruhan untuk akurasi akan berubah sepenuhnya.
Model Bahasa Besar (LLM) memahami logika, tetapi memori internalnya adalah snapshot historis. Misalnya, jika agen mengelola supply chain dan salah mengonfirmasi ketersediaan pemasok atau rute jalan, Anda akan mengalami pemborosan bahan bakar, SLA yang terlewat, dan gangguan bisnis yang nyata. Dalam arsitektur multi-agen, Anda akan menghadapi masalah halusinasi beruntun. Jika satu agen dalam rantai berhalusinasi dan meneruskan data yang salah ke agen kedua, seluruh sistem akan mulai membuat komitmen di dunia nyata berdasarkan kebohongan. Otonomi tanpa kebenaran menjadi kewajiban yang sangat besar.
Grounding mengharuskan agen untuk melangkah di luar bobot pelatihannya. Dengan memaksa AI mengambil fakta live yang dapat diverifikasi, seperti data Tempat dan data pemilihan rute, Anda memberi agen mata dan telinga real-time, sehingga mengubah tebakan statistik menjadi keputusan operasional yang tepat.
Mengapa MCP
Model Context Protocol (MCP) adalah standar terbuka yang dirancang untuk membuat integrasi alat dan data menjadi plug-and-play.
Sebelumnya, menghubungkan model AI ke API eksternal memerlukan penulisan wrapper kaku yang dibuat khusus. Anda harus menangani pemformatan, penguraian error, dan terjemahan panggilan alat secara manual untuk setiap kemampuan.
MCP menstandarkan lapisan integrasi ini. Dengan mengimplementasikan klien MCP, aplikasi Anda dapat menemukan dan menjalankan alat yang disediakan server secara dinamis melalui protokol terpadu. Hal ini mengalihkan fokus developer dari menulis logika integrasi API yang berulang ke mendesain jaringan agen tingkat tinggi.
MCP Google Maps Grounding Lite
Google Maps Grounding Lite MCP adalah server MCP yang dihosting oleh Google dan terkelola sepenuhnya, yang dapat diintegrasikan langsung ke framework agentic yang kompatibel.
Saat ini, server menyediakan tiga alat inti untuk grounding:
- Menelusuri tempat: Minta informasi tentang tempat dan dapatkan ringkasan data tempat yang dihasilkan AI, serta ID Tempat, koordinat lintang dan bujur, serta link Google Maps untuk setiap tempat yang disertakan dalam ringkasan. Anda dapat menggunakan ID Tempat serta koordinat lintang dan bujur yang ditampilkan dengan API Google Maps Platform lainnya untuk menampilkan tempat di peta.
- Mencari informasi cuaca: Meminta informasi tentang cuaca dan menampilkan kondisi saat ini, prakiraan cuaca per jam, dan prakiraan cuaca harian.
- Compute routes: Meminta informasi tentang rute mengemudi atau berjalan kaki antara dua lokasi dan menampilkan informasi jarak dan durasi rute.
Untuk mengakses layanan, Anda dapat menggunakan Kunci API atau OAuth. Google Maps Platform menyediakan kunci API Demo tanpa biaya yang dirancang khusus untuk membantu developer segera memulai pembuatan prototipe.
Praktik Terbaik untuk Mengintegrasikan MCP Grounding Maps
Untuk memaksimalkan relevansi data dan menghilangkan halusinasi struktural, fokuskan petunjuk sistem agen Anda pada strategi inti berikut: * Bersikaplah eksplisit dan spesifik: Instruksikan agen untuk menggunakan lokasi yang tepat. "Central Park, New York" memberikan hasil yang lebih baik daripada "New York", sama seperti "Paris, Prancis" mencegah kebingungan dengan Paris, Texas.
Menguraikan kueri umum: Untuk permintaan yang tidak jelas seperti "ide kencan malam", perintahkan agen untuk menguraikan tugas menjadi sub-penelusuran tertentu seperti "restoran romantis", "bioskop", atau "bar koktail".
Penemuan terlebih dahulu, eksplorasi kemudian: Lakukan penelusuran penemuan yang luas terlebih dahulu (misalnya, "Restoran Jepang dengan pintu masuk yang mudah diakses yang buka pada hari Minggu"). Menampilkan opsi kepada pengguna, lalu menjalankan kueri lanjutan untuk mengambil detail spesifik seperti nomor telepon untuk tempat yang dipilih.
Jangan pernah membuat ID Tempat fiktif: ID Tempat adalah jaringan penghubung yang penting di seluruh layanan Google Maps Platform. Pastikan agen Anda tahu bahwa agen hanya boleh menggunakan ID Tempat yang ditampilkan secara eksplisit oleh alat search_places, bukan mencoba membuat ID Tempat sendiri.
Mengimplementasikan agen perencanaan perjalanan dengan Google ADK
Bagian ini menunjukkan cara membuat agen perencanaan perjalanan menggunakan framework Google Agent Development Kit (ADK). Jika Anda belum menginstal ADK, lihat dokumen developer ADK Google.
Mengintegrasikan server MCP Maps ke dalam framework agen seperti ADK sangatlah mudah. ADK menangani kompleksitas pengelolaan konteks, sehingga Anda dapat berfokus pada perilaku agen.
Project contoh memiliki struktur berikut:
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
Contoh agent.py. Edit berdasarkan kasus penggunaan Anda.
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]
)
Contoh SKILL.md. Edit berdasarkan kasus penggunaan Anda.
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
Menjalankan adk web dan berinteraksi
Untuk memulai UI web ADK default, jalankan perintah ini di direktori project travel-concierge-google-maps-mcp:
adk web
Berinteraksi di UI:
- Muat UI di http://127.0.0.1:8000 di browser
- Coba perintah seperti:
- "Saya akan berada di San Francisco pada hari Sabtu. Rencanakan perjalanan sehari untuk saya."
- Cari kedai kopi di dekat Taman Golden Gate dan tunjukkan sorotan menu.
- "Dapatkan rute dari GooglePlex ke SFO."
Saat agen menerima perintah, perencana akan mengevaluasi niat pengguna. Model ini mengenali kebutuhan akan data spasial dan cuaca, serta secara mandiri memicu alat lookup_weather, search_places, dan compute_routes menggunakan server MCP. Kemudian, agen akan menyusun itinerari berbasis fakta untuk pengguna.
Kesimpulan
Pergeseran ke arah AI agentic membuka kemampuan yang sepenuhnya baru dalam logistik, perjalanan, dan retail. Namun, otonomi sejati memerlukan fondasi kebenaran yang kuat.
Dengan memanfaatkan Model Context Protocol bersama Grounding Google Maps Lite, Anda dapat menghilangkan hambatan integrasi API kustom dan memberikan kemampuan pengamatan real-time yang dibutuhkan agen Anda. Menghubungkan model Anda dengan data spasial langsung memastikan model tersebut membuat keputusan operasional berdasarkan apa yang terjadi di dunia fisik saat ini, bukan pada snapshot statis dari data pelatihannya.
Tindakan berikutnya
- Baca dokumentasi developer MCP Grounding Maps.
- Dapatkan kunci API demo.
- Pelajari cara men-deploy agen Anda.
Penulis utama:
Teresa Qin | Engineer DevX Google Maps Platform