ساختن عامل‌های هوش مصنوعی نشان‌دهنده تحولی چشمگیر در توسعه نرم‌افزار است که به سیستم‌ها امکان می‌دهد استدلال‌های پیچیده انجام دهند و با خودمختاری بیشتری عمل کنند. بااین‌حال، مدل‌های بنیادی که این سیستم‌ها را هدایت می‌کنند به‌طور طبیعی توسط داده‌های آموزشی‌شان محدود می‌شوند. بدون بافت خارجی، آن‌ها از شرایط هم‌زمان آگاه نیستند، مثلاً آب‌وهوای فعلی بیرون، اینکه آیا کسب‌وکار محلی درحال‌حاضر باز است یا نه، یا کارآمدترین مسیر به مقصد.
این سند به‌طور مفصل توضیح می‌دهد که چگونه با زمینه‌سازی عامل‌های هوش مصنوعی خود با داده‌های زمین‌مکانی قابل‌اعتماد از Google Maps، فاصله بین استدلال ایستا و واقعیت پویا را پر کنید. با اهمیت زمینه‌سازی فضایی برای کارهای دنیای واقعی، نحوه ساده‌سازی ادغام ابزارها توسط Model Context Protocol (MCP)، و نحوه ساختن عامل برنامه‌ریزی سفر بااستفاده از Google Maps Grounding Lite MCP آشنا خواهید شد.
چرا عوامل به زمینه‌سازی داده‌های نقشه نیاز دارند
گذار از نرم‌افزار سنتی به گردش کارهای عامل‌گرا، تغییری از مهندسی قطعی به هماهنگ‌سازی احتمالی است. ما درحال حرکت از سیستم‌هایی هستیم که صرفاً چیزها را می‌دانند به موتورهای اجرای پیش‌کنشی که درواقع کارها را انجام می‌دهند. وقتی برنامه‌ای از این خط عبور می‌کند و در دنیای فیزیکی اقدام می‌کند، اهمیت دقت به‌طور کامل تغییر می‌کند.
«مدل‌های زبانی بزرگ» (LLM) منطق را درک می‌کنند، اما حافظه داخلی آن‌ها یک عکس آنی تاریخی است. برای مثال، اگر عاملی درحال مدیریت زنجیره تأمین باشد و به‌اشتباه دردسترس بودن تأمین‌کننده یا مسیر جاده‌ای را تأیید کند، با سوخت هدررفته، عدم رعایت «قرارداد سطح خدمات»، و اختلال واقعی در کسب‌وکار مواجه خواهید شد. و در معماری‌های چندعاملی، با مشکل کژپنداری آبشاری مواجه خواهید شد. اگر یکی از عامل‌ها در زنجیره دچار توهم شود و داده‌های نادرست را به عامل دوم منتقل کند، کل سیستم براساس یک دروغ شروع به ایجاد تعهدات در دنیای واقعی می‌کند. خودمختاری بدون حقیقت به یک مسئولیت بزرگ تبدیل می‌شود.
پایه‌سازی ایجاب می‌کند که عامل از وزن‌های آموزشی خود فراتر برود. با وادار کردن هوش مصنوعی به واکشی حقایق زنده و قابل‌تأیید (مانند داده‌های «مکان‌ها» و داده‌های مسیریابی)، به نماینده چشم و گوش هم‌زمان می‌دهید و حدس آماری را به تصمیم عملیاتی آگاهانه تبدیل می‌کنید.
چرا MCP
«پروتکل بافتار مدل» (MCP) یک استاندارد باز است که برای اتصال و استفاده آسان از ابزارها و یکپارچه‌سازی داده‌ها طراحی شده است.
در گذشته، متصل کردن مدل هوش مصنوعی به میاناهای برنامه‌سازی کاربردی خارجی مستلزم نوشتن پوشاننده‌های سفارشی و انعطاف‌ناپذیر بود. باید قالب‌بندی، تجزیه خطا، و ترجمه فراخوانی ابزار را برای هر قابلیت به‌طور جداگانه و دستی انجام می‌دادید.
«پروتکل زمینه‌ای مدل» این لایه ادغام را استانداردسازی می‌کند. با پیاده‌سازی کارخواه MCP، برنامه شما می‌تواند ابزارهای ارائه‌شده توسط سرور را به‌طور پویا ازطریق یک پروتکل یکپارچه کشف و اجرا کند. این امر تمرکز توسعه‌دهنده را از نوشتن منطق تکراری ادغام میانای برنامه‌سازی کاربردی به طراحی شبکه‌های عاملی سطح بالا تغییر می‌دهد.
Google Maps Grounding Lite MCP
Google Maps Grounding Lite MCP یک سرور MCP کاملاً مدیریت‌شده و با میزبانی Google است که می‌تواند مستقیماً در هر چارچوب عاملی سازگار ادغام شود.
درحال‌حاضر، سرور سه ابزار اصلی برای زمینه‌سازی ارائه می‌دهد:
- جستجوی مکان‌ها: اطلاعات مربوط به مکان‌ها را درخواست کنید و خلاصه‌های داده‌های مکان تولیدشده با هوش مصنوعی را دریافت کنید، همچنین شناسه‌های مکان، مختصات طول و عرض جغرافیایی، و پیوندهای Google Maps برای هریک از مکان‌های موجود در خلاصه را دریافت کنید. می‌توانید از «شناسه‌های مکان» و مختصات طول و عرض جغرافیایی برگردانده‌شده با دیگر میاناهای برنامه‌سازی کاربردی Google Maps Platform برای نمایش مکان‌ها روی نقشه استفاده کنید.
- جستجوی آب‌وهوا: درخواست اطلاعات درباره آب‌وهوا و برگرداندن شرایط فعلی، پیش‌بینی‌های ساعتی، و پیش‌بینی‌های روزانه.
- محاسبه مسیرها: درخواست اطلاعات درباره مسیرهای رانندگی یا پیاده‌روی بین دو مکان و برگرداندن اطلاعات مسافت و مدت مسیر.
برای دسترسی به این سرویس، می‌توانید از «کلید میانای برنامه‌سازی کاربردی» یا OAuth استفاده کنید. Google Maps Platform یک کلید میانای برنامه‌سازی کاربردی نسخه نمایشی رایگان ارائه می‌دهد که به‌طور خاص برای کمک به توسعه‌دهندگان در شروع فوری نمونه‌سازی اولیه طراحی شده است.
روال‌های مطلوب برای ادغام کردن MCP زمینه‌سازی Maps
برای به‌حداکثر رساندن ارتباط داده‌ها و حذف کژپنداری‌های ساختاری، دستورالعمل‌های سیستم عامل خود را حول این استراتژی‌های اصلی لنگر کنید: * صریح و مشخص باشید: به عامل دستور دهید از مکان‌های دقیق استفاده کند. «پارک ملت، تهران» نتایج بهتری نسبت به «تهران» ارائه می‌دهد، همان‌طور که «پاریس، فرانسه» از اشتباه گرفتن آن با پاریس، تگزاس جلوگیری می‌کند.
تجزیه کردن پُرسمان‌های عمومی: برای درخواست‌های مبهم مانند «ایده‌هایی برای قرار شبانه»، از نماینده بخواهید که تکلیف را به جستجوهای فرعی خاص مانند «رستوران‌های رمانتیک»، «سینماها»، یا «کافه کوکتل‌ها» تجزیه کند.
ابتدا کاوش، سپس کاوش عمیق‌تر: ابتدا جستجوی کاوشی گسترده‌ای انجام دهید (مثلاً «رستوران‌های ژاپنی با ورودی‌های دسترس‌پذیر که یکشنبه‌ها باز هستند»). گزینه‌ها را به کاربر ارائه دهید و سپس پُرسمان پیگیری را برای واکشی جزئیات خاص مانند شماره تلفن مکان انتخاب‌شده اجرا کنید.
هرگز شناسه مکان را توهم نزنید: شناسه‌های مکان بافت همبند حیاتی در سراسر سرویس‌های «پلاتفرم Google Maps» هستند. مطمئن شوید که نماینده شما می‌داند که باید فقط از «شناسه‌های مکان» که صریحاً توسط ابزار search_places برگردانده شده‌اند استفاده کند، نه اینکه خودش آن‌ها را تولید کند.
پیاده‌سازی کردن عامل برنامه‌ریزی سفر با Google ADK
این بخش نشان می‌دهد که چگونه بااستفاده از چارچوب Google Agent Development Kit (ADK) یک عامل برنامه‌ریزی سفر بسازید. اگر ADK را نصب نکرده‌اید، سند توسعه‌دهنده Google ADK را ببینید.
ادغام کردن سرور Maps MCP در چارچوب عاملی مانند ADK ساده است. کیت توسعه عامل پیچیدگی‌های مدیریت بافت را مدیریت می‌کند، و به شما اجازه می‌دهد روی رفتار عامل تمرکز کنید.
پروژه نمونه ساختار زیر را دارد:
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. آن را براساس موارد استفاده‌تان ویرایش کنید.
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. آن را براساس موارد استفاده خود ویرایش کنید.
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 و تعامل
برای شروع واسط کاربر وب ADK پیش‌فرض، این فرمان را در دایرکتوری پروژه travel-concierge-google-maps-mcp اجرا کنید:
adk web
تعامل در میانای کاربر:
- واسط کاربر را در http://127.0.0.1:8000 در مرورگر بار کنید
- پیام‌واره‌هایی مثل این را امتحان کنید:
- «شنبه در سان‌فرانسیسکو خواهم بود. یک سفر یک‌روزه برایم برنامه‌ریزی کن.»
- «قهوه‌سراهای نزدیک پارک گلدن گیت را پیدا کن و منوهای برجسته را به من نشان بده.»
- «مسیرهای GooglePlex به SFO را دریافت کن.»
وقتی عامل پیام‌واره را دریافت می‌کند، برنامه‌ریز قصد کاربر را ارزیابی می‌کند. این عامل نیاز به داده‌های فضایی و آب‌وهوا را تشخیص می‌دهد و به‌طور خودکار ابزارهای lookup_weather، search_places، و compute_routes را بااستفاده از سرور MCP راه‌اندازی می‌کند. سپس عامل یک برنامه سفر مبتنی بر واقعیت برای کاربر ترکیب می‌کند.
نتیجه‌گیری
گذار به‌سمت هوش مصنوعی عامل‌گرا قابلیت‌های کاملاً جدیدی را در لجستیک، سفر، و خرده‌فروشی باز می‌کند. بااین‌حال، خودمختاری واقعی نیازمند پایه‌ای محکم از حقیقت است.
با بهره‌گیری از Model Context Protocol در کنار Google Maps Grounding Lite، اصطکاک ادغام‌های میانای برنامه‌سازی کاربردی سفارشی را ازبین می‌برید و به عامل‌هایتان چشم و گوش هم‌زمان موردنیازشان را می‌دهید. لنگر انداختن مدل‌هایتان در داده‌های فضایی زنده تضمین می‌کند که آن‌ها تصمیمات عملیاتی را براساس آنچه درحال‌حاضر در دنیای فیزیکی اتفاق می‌افتد اتخاذ می‌کنند - نه براساس یک عکس آنی ثابت از داده‌های آموزشی‌شان.
کنش‌های بعدی
- اسناد توسعه‌دهنده MCP برای «زمینه‌سازی Maps» را بخوانید.
- کلید میانای برنامه‌سازی کاربردی نمایشی دریافت کنید.
- با نحوه استقرار نماینده آشنا شوید.
نویسندگان اصلی:
ترسا کین | مهندس DevX پلاتفرم Google Maps