Yapay zeka ajanları oluşturmak, yazılım geliştirme alanında önemli bir evrimi temsil eder. Bu sayede sistemler karmaşık akıl yürütme işlemleri gerçekleştirebilir ve daha bağımsız bir şekilde çalışabilir. Ancak bu sistemleri destekleyen temel modeller, eğitim verileriyle doğal olarak sınırlanır. Dış bağlam olmadan, dışarıdaki mevcut hava durumu, yerel bir işletmenin şu anda açık olup olmadığı veya bir hedefe ulaşmak için en verimli rota gibi anlık koşulların farkında olmazlar.
Bu belgede, yapay zeka aracılarınızı Google Haritalar'daki güvenilir coğrafi verilerle destekleyerek statik akıl yürütme ile dinamik gerçeklik arasındaki boşluğu nasıl kapatacağınız açıklanmaktadır. Mekansal temellendirmenin gerçek dünya görevleri için neden kritik olduğunu, Model Bağlam Protokolü'nün (MCP) araç entegrasyonunu nasıl basitleştirdiğini ve Google Haritalar Grounding Lite MCP'yi kullanarak seyahat planlama aracısı oluşturmayı öğreneceksiniz.
Temsilcilerin neden harita verisi temellendirmesine ihtiyacı var?
Geleneksel yazılımdan ajan tabanlı iş akışlarına geçiş, deterministik mühendislikten olasılıksal düzenlemeye geçiş anlamına gelir. Sadece bilgi sahibi olan sistemlerden, işleri gerçekten yapan proaktif yürütme motorlarına geçiyoruz. Bir uygulama bu sınırı aşıp fiziksel dünyada işlem yaptığında doğrulukla ilgili riskler tamamen değişir.
Büyük dil modelleri (LLM'ler) mantığı anlar ancak dahili bellekleri geçmişe ait bir anlık görüntüdür. Örneğin, bir tedarik zincirini yöneten bir temsilci, tedarikçinin stok durumunu veya bir yol güzergahını yanlışlıkla onaylarsa yakıt israfı, HDS'nin karşılanmaması ve işletmede gerçek bir aksama yaşanır. Çoklu aracı mimarilerinde ise halüsinasyonların birbirini tetiklediği bir sorunla karşılaşırsınız. Zincirdeki bir aracı halüsinasyon görerek ikinci bir aracıya yanlış veri iletirse sistemin tamamı yalanlara dayalı olarak gerçek dünyada taahhütlerde bulunmaya başlar. Gerçeklikten uzak özerklik büyük bir sorumluluk haline gelir.
Temellendirme, aracının eğitim ağırlıklarının dışına çıkmasını zorunlu kılar. Yapay zekayı, yer verileri ve yönlendirme verileri gibi doğrulanabilir ve güncel bilgileri getirmeye zorlayarak temsilciye anlık göz ve kulaklar kazandırırsınız. Böylece, istatistiksel bir tahmini bilgiye dayalı bir operasyonel karara dönüştürürsünüz.
Neden MCP?
Model Bağlam Protokolü (MCP), araç ve veri entegrasyonlarını tak ve çalıştır hale getirmek için tasarlanmış açık bir standarttır.
Geçmişte, bir yapay zeka modelini harici API'lere bağlamak için katı ve özel sarmalayıcılar yazmak gerekiyordu. Her bir özellik için biçimlendirme, hata ayrıştırma ve araç çağrısı çevirilerini manuel olarak yapmanız gerekiyordu.
MCP, bu entegrasyon katmanını standartlaştırır. MCP istemcisi uygulayarak uygulamanız, sunucu tarafından sağlanan araçları birleşik bir protokol aracılığıyla dinamik olarak keşfedip yürütebilir. Bu sayede geliştiricinin odak noktası, tekrarlayan API entegrasyon mantığı yazmaktan üst düzey ajan destekli ağlar tasarlamaya kayar.
Google Haritalar Grounding Lite MCP
Google Maps Grounding Lite MCP, doğrudan uyumlu herhangi bir aracı çerçevesine entegre edilebilen, Google tarafından barındırılan ve tamamen yönetilen bir MCP sunucusudur.
Sunucu şu anda temellendirme için üç temel araç sunmaktadır:
- Yerleri arama: Yerlerle ilgili bilgi isteyin ve yapay zeka tarafından oluşturulan yer verisi özetlerinin yanı sıra özetin içerdiği her yer için yer kimlikleri, enlem ve boylam koordinatları ile Google Haritalar bağlantılarını alın. Döndürülen yer kimliklerini ve enlem/boylam koordinatlarını, yerleri haritada göstermek için diğer Google Haritalar Platformu API'leriyle birlikte kullanabilirsiniz.
- Hava durumunu arama: Hava durumu hakkında bilgi isteyin ve mevcut koşulları, saatlik tahminleri ve günlük tahminleri döndürün.
- Rotaları hesaplama: İki konum arasındaki araba veya yaya rotaları hakkında bilgi isteyin ve rota mesafesi ile süresi bilgilerini döndürün.
Hizmete erişmek için API anahtarı veya OAuth kullanabilirsiniz. Google Haritalar Platformu, geliştiricilerin hemen prototip oluşturmaya başlamasına yardımcı olmak için özel olarak tasarlanmış ücretsiz bir Demo API anahtarı sunar.
Haritalar Temellendirme MCP'yi Entegre Etmeye Yönelik En İyi Uygulamalar
Veri alaka düzeyini en üst düzeye çıkarmak ve yapısal halüsinasyonları ortadan kaldırmak için aracınızın sistem talimatlarını şu temel stratejiler etrafında şekillendirin: * Açık ve net olun: Aracın tam konumları kullanmasını sağlayın. "New York" yerine "Central Park, New York" daha iyi sonuçlar verir. Aynı şekilde,"Paris, Fransa" da Paris, Teksas ile karışıklığı önler.
Genel sorguları ayrıntılandırın: "İlk buluşma için fikirler" gibi belirsiz isteklerde, görevleri "romantik restoranlar", "sinemalar" veya "kokteyl barları" gibi alt aramalara ayırması için istemi kullanın.
Önce keşif, sonra inceleme: Önce geniş kapsamlı bir keşif araması yapın (ör. "Pazar günü açık olan ve engelli girişine uygun Japon restoranları"). Kullanıcıya seçenekler sunun ve ardından seçilen mekanın telefon numarası gibi belirli ayrıntıları getirmek için bir takip sorgusu çalıştırın.
Yer kimliklerini asla uydurmayın: Yer kimlikleri, Google Haritalar Platformu hizmetleri arasında önemli bir bağlantı noktasıdır. Aracınızın, kendi yer kimliklerini oluşturmaya çalışmak yerine yalnızca search_places aracı tarafından açıkça döndürülen yer kimliklerini kullanması gerektiğini bildiğinden emin olun.
Google ADK ile seyahat planlama temsilcisi uygulama
Bu bölümde, Google Agent Development Kit (ADK) çerçevesini kullanarak seyahat planlama aracısı oluşturma işlemi gösterilmektedir. ADK yüklü değilse Google ADK geliştirici dokümanına bakın.
Haritalar MCP sunucusunu ADK gibi bir aracı çerçevesine entegre etmek kolaydır. ADK, bağlam yönetiminin karmaşıklığıyla ilgilenerek ajanın davranışına odaklanmanızı sağlar.
Örnek proje aşağıdaki yapıya sahiptir:
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
agent.py örneği. Kullanım alanlarınıza göre düzenleyin.
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]
)
SKILL.md örneği. Kullanım alanlarınıza göre düzenleyin.
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
Adk web'i çalıştırma ve etkileşimde bulunma
Varsayılan ADK web kullanıcı arayüzünü başlatmak için travel-concierge-google-maps-mcp proje dizininde şu komutu çalıştırın:
adk web
Kullanıcı arayüzünde etkileşim kurma:
- Tarayıcıda http://127.0.0.1:8000 adresinde kullanıcı arayüzünü yükleyin.
- Aşağıdaki gibi istemleri deneyin:
- "Cumartesi günü San Francisco'da olacağım. Benim için günübirlik gezi planla."
- "Golden Gate Park'ın yakınındaki kafeleri bul ve menüdeki öne çıkanları göster."
- "GooglePlex'ten SFO'ya yol tarifi al."
Temsilci istemi aldığında planlayıcı, kullanıcının amacını değerlendirir. Mekansal ve hava durumu verilerine ihtiyaç duyulduğunu algılar ve MCP sunucusunu kullanarak lookup_weather, search_places ve compute_routes araçlarını bağımsız olarak tetikler. Ardından, kullanıcı için gerçeklere dayalı bir seyahat planı oluşturur.
Sonuç
Ajan tabanlı yapay zekaya geçiş, lojistik, seyahat ve perakende sektörlerinde tamamen yeni özelliklerin önünü açıyor. Ancak gerçek özerklik için sağlam bir doğruluk temeli gerekir.
Model Bağlam Protokolü'nü Google Haritalar Grounding Lite ile birlikte kullanarak özel API entegrasyonlarının zorluğunu ortadan kaldırır ve ajanlarınıza ihtiyaç duydukları gerçek zamanlı gözleri ve kulakları verirsiniz. Modellerinizi canlı mekansal verilere dayandırmak, eğitim verisindeki dondurulmuş bir anlık görüntüye değil, şu anda fiziksel dünyada olanlara göre operasyonel kararlar vermelerini sağlar.
Sonraki işlemler
- Maps Grounding MCP geliştirici belgelerini okuyun.
- Demo API anahtarı alın.
- Aracınızı nasıl dağıtacağınızı öğrenin.
Başlıca yazarlar:
Teresa Qin | Google Haritalar Platformu Geliştirici Deneyimi Mühendisi