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 süreçlerini gerçekleştirebilir ve daha fazla otonomiyle çalışabilir. Ancak bu sistemleri destekleyen temel modeller, doğal olarak eğitim verileriyle sınırlıdır. Harici bağlam olmadan, dışarıdaki hava durumu, yerel bir işletmenin şu anda açık olup olmadığı veya bir hedefe giden en verimli rota gibi gerçek zamanlı koşullardan haberdar olamazlar.
Bu belgede, yapay zeka temsilcilerinizi Google Haritalar'dan alınan güvenilir coğrafi verilerle destekleyerek statik akıl yürütme ile dinamik gerçeklik arasındaki boşluğu nasıl dolduracağınız ayrıntılı olarak açıklanmaktadır. Konumsal temellendirmenin gerçek dünyadaki görevler için neden kritik olduğunu, Model Context Protocol'ün (MCP) araç entegrasyonunu nasıl basitleştirdiğini ve Google Haritalar Grounding Lite MCP'yi kullanarak seyahat planlama temsilcisini nasıl oluşturacağınızı öğreneceksiniz.
Temsilcilerin neden harita verilerine dayalı temellendirmeye ihtiyacı var?
Geleneksel yazılımdan temsilci tabanlı iş akışlarına geçiş, deterministik mühendislikten olasılıksal düzenlemeye geçişi ifade eder. Yalnızca bilgi sahibi olan sistemlerden, işleri gerçekten yapan proaktif yürütme motorlarına geçiyoruz. Bir uygulama bu çizgiyi aşıp fiziksel dünyada harekete geçtiğinde 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 temsilci tedarik zincirini yönetiyorsa ve bir tedarikçinin müsaitlik durumunu veya bir yol rotasını yanlış onaylarsa yakıt israfı, HDS'nin kaçırılması ve gerçek bir iş kesintisiyle karşılaşırsınız. Çok aracılı mimarilerde ise zincirleme halüsinasyon sorunuyla karşılaşırsınız. Zincirdeki bir temsilci halüsinasyon görür ve ikinci bir temsilciye yanlış veri aktarırsa tüm sistem, bir yalana dayalı olarak gerçek dünyada taahhütlerde bulunmaya başlar. Doğruluk olmadan otonomi büyük bir sorumluluk haline gelir.
Temellendirme, temsilcinin eğitim ağırlıklarının dışına çıkmasını zorunlu kılar. Yapay zekayı, yer verileri ve rota verileri gibi doğrulanabilir, canlı bilgileri almaya zorlayarak temsilciye anlık gözler ve kulaklar verirsiniz. Böylece istatistiksel bir tahmini, bilinçli bir operasyonel karara dönüştürürsünüz.
Neden MCP?
Model Context Protocol (MCP), araç ve veri entegrasyonlarını tak-ç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. Uygulamanız, bir MCP istemcisi uygulayarak sunucu tarafından sağlanan araçları birleşik bir protokol aracılığıyla dinamik olarak keşfedebilir ve çalıştırabilir. Bu sayede geliştirici, tekrarlayan API entegrasyon mantığı yazmak yerine üst düzey temsilci ağları tasarlamaya odaklanabilir.
Google Haritalar Grounding Lite MCP
Google Haritalar Grounding Lite MCP, uyumlu herhangi bir ajan tabanlı çerçeveye doğrudan entegre edilebilen, Google tarafından barındırılan ve tümüyle yönetilen bir MCP sunucusudur.
Sunucu şu anda temellendirme için üç temel araç sunmaktadır:
- Yerler için arama yapma: Yerler hakkında bilgi isteyin ve yapay zeka tarafından oluşturulan yer verisi özetlerinin yanı sıra özete dahil edilen her yer için yer kimlikleri, enlem ve boylam koordinatları ve Google Haritalar bağlantıları alın. Döndürülen yer kimliklerini ve enlem/boylam koordinatlarını diğer Google Haritalar Platformu API'leriyle birlikte kullanarak yerleri haritada gösterebilirsiniz.
- Hava durumunu öğrenme: Hava durumu hakkında bilgi isteyin ve mevcut koşulları, saatlik tahminleri ve günlük tahminleri alın.
- Rotaları hesaplama: İki konum arasındaki sürüş veya yürüyüş rotaları hakkında bilgi isteyin ve rota mesafesi ile süre 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'sini Entegre Etmeyle İlgili En İyi Uygulamalar
Veri alaka düzeyini en üst düzeye çıkarmak ve yapısal halüsinasyonları ortadan kaldırmak için temsilcinizin sistem talimatlarını şu temel stratejilere dayandırın: * Açık ve net olun: Temsilciye tam konumları kullanmasını söyleyin. "New York" yerine "Central Park, New York" yazmak daha iyi sonuçlar verir. Benzer şekilde,"Paris, Fransa" yazmak da Paris, Teksas ile karışıklığı önler.
Genel sorguları parçalara ayırma: "Romantik akşam fikirleri" gibi belirsiz istekler için temsilciye, görevi "romantik restoranlar", "sinema salonları" veya "kokteyl barları" gibi belirli alt aramalara ayırmasını söyleyin.
Önce keşif, sonra ayrıntılı inceleme: Önce geniş kapsamlı bir keşif araması yapın (ör. "Pazar günleri açık olan ve engelsiz girişi bulunan Japon restoranları"). Kullanıcıya seçenekler sunun ve ardından seçilen mekanın telefon numarası gibi belirli ayrıntıları almak için bir takip sorgusu çalıştırın.
Yer kimliklerini asla uydurmayın: Yer kimlikleri, Google Haritalar Platformu hizmetleri arasındaki kritik bağlantı dokusudur. Temsilcinizin, 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 temsilcisinin nasıl oluşturulacağı gösterilmektedir. ADK yüklü değilse Google ADK geliştirici dokümanına bakın.
Haritalar MCP sunucusunu ADK gibi bir temsilci çerçevesine entegre etmek kolaydır. ADK, bağlam yönetiminin karmaşıklığını ele alarak temsilcinin 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şim kurma
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 adresindeki kullanıcı arayüzünü yükleyin.
- Şu gibi istemleri deneyin:
- "Cumartesi günü San Francisco'da olacağım. Benim için günübirlik gezi planla."
- "Golden Gate Parkı'nın yakınındaki kafeleri bul ve menüde öne çıkanları göster."
- "GooglePlex'ten SFO'ya yol tarifi al."
Temsilci istemi aldığında planlayıcı, kullanıcının niyetini değerlendirir. Konum ve hava durumu verilerine ihtiyaç duyulduğunu algılar ve MCP sunucusunu kullanarak lookup_weather, search_places ve compute_routes araçlarını otonom olarak tetikler. Ardından temsilci, 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 yepyeni olanaklar sunuyor. Ancak gerçek otonomi için sağlam bir doğruluk temeli gerekir.
Model Context Protocol'ü Google Haritalar Grounding Lite ile birlikte kullanarak özel API entegrasyonlarının zorluklarını ortadan kaldırabilir ve temsilcilerinize ihtiyaç duydukları gerçek zamanlı gözleri ve kulakları sağlayabilirsiniz. Modellerinizi canlı mekansal verilerle temellendirmek, operasyonel kararların eğitim verilerindeki donmuş bir anlık görüntüye göre değil, fiziksel dünyada şu anda olup bitenlere göre alınmasını sağlar.
Sonraki işlemler
- Maps Grounding MCP geliştirici belgelerini okuyun.
- Demo API anahtarı alın.
- Temsilcinizi nasıl dağıtacağınızı öğrenin.
Asıl yazarlar:
Teresa Qin | Google Haritalar Platformu DevX Mühendisi