این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

اتصال عامل‌های هوش مصنوعی به زمین با زمینه مکانی دنیای واقعی با استفاده از Maps Grounding Lite MCP، اتصال عامل‌های هوش مصنوعی به زمین با زمینه مکانی دنیای واقعی با استفاده از Maps Grounding Lite MCP

ساخت عامل‌های هوش مصنوعی نشان‌دهنده‌ی تکامل قابل توجهی در توسعه‌ی نرم‌افزار است که سیستم‌ها را قادر می‌سازد تا استدلال‌های پیچیده را انجام دهند و با استقلال بیشتری عمل کنند. با این حال، مدل‌های بنیادی که این سیستم‌ها را هدایت می‌کنند، به طور طبیعی توسط داده‌های آموزشی خود محدود می‌شوند. بدون زمینه‌ی خارجی، آن‌ها از شرایط بلادرنگ، مانند آب و هوای فعلی بیرون، اینکه آیا یک کسب و کار محلی در حال حاضر باز است یا خیر، یا کارآمدترین مسیر به یک مقصد، آگاهی ندارند.

این سند به تفصیل توضیح می‌دهد که چگونه می‌توان با اتصال عوامل هوش مصنوعی خود به داده‌های مکانی-مکانی قابل اعتماد از نقشه‌های گوگل، شکاف بین استدلال ایستا و واقعیت پویا را پر کرد. شما خواهید آموخت که چرا اتصال مکانی برای وظایف دنیای واقعی حیاتی است، چگونه پروتکل زمینه مدل (MCP) ادغام ابزار را ساده می‌کند و چگونه می‌توان با استفاده از Google Maps Grounding Lite MCP یک عامل برنامه‌ریزی سفر ساخت.

کارشناس برنامه‌ریزی سفر به دلیل نقص فنی در نقشه‌های MCP زمین‌گیر شد

چرا ماموران به داده‌های نقشه‌برداری زمینی نیاز دارند؟

گذار از نرم‌افزارهای سنتی به گردش‌های کاری عامل‌محور، تغییری از مهندسی قطعی به هماهنگی احتمالی است. ما در حال گذار از سیستم‌هایی هستیم که صرفاً چیزهایی را می‌دانند به موتورهای اجرایی پیشگیرانه که واقعاً کارها را انجام می‌دهند. وقتی یک برنامه از این مرز عبور می‌کند و در دنیای فیزیکی اقدامی انجام می‌دهد، اهمیت دقت کاملاً تغییر می‌کند.

مدل‌های زبان بزرگ (LLM) منطق را درک می‌کنند، اما حافظه داخلی آنها یک تصویر لحظه‌ای از گذشته است. به عنوان مثال، اگر یک عامل در حال مدیریت یک زنجیره تأمین باشد و به اشتباه در دسترس بودن یک تأمین‌کننده یا یک مسیر جاده‌ای را تأیید کند، شاهد هدر رفتن سوخت، از دست دادن SLA و اختلال واقعی در کسب‌وکار خواهید بود. و در معماری‌های چندعاملی، با مشکل توهم آبشاری روبرو خواهید شد. اگر یک عامل در زنجیره دچار توهم شود و داده‌های اشتباه را به عامل دوم منتقل کند، کل سیستم شروع به ایجاد تعهدات دنیای واقعی بر اساس یک دروغ می‌کند. استقلال بدون حقیقت به یک مسئولیت بزرگ تبدیل می‌شود.

اتصال به زمین، عامل را ملزم می‌کند که از وزن‌های آموزشی خود فراتر رود. با مجبور کردن هوش مصنوعی به دریافت حقایق زنده و قابل تأیید - مانند داده‌های مکان‌ها و داده‌های مسیریابی - شما به عامل، چشم و گوش بلادرنگ می‌دهید و یک حدس آماری را به یک تصمیم عملیاتی آگاهانه تبدیل می‌کنید.

چرا MCP

پروتکل زمینه مدل (MCP) یک استاندارد باز است که برای یکپارچه‌سازی ابزار و داده‌ها به صورت plug-and-play طراحی شده است.

از نظر تاریخی، اتصال یک مدل هوش مصنوعی به یک API خارجی نیاز به نوشتن بسته‌های نرم‌افزاری (wrappers) سفت و سخت و سفارشی داشت. شما مجبور بودید قالب‌بندی، تجزیه خطا و ترجمه‌های فراخوانی ابزار را برای هر قابلیت به صورت دستی مدیریت کنید.

MCP این لایه یکپارچه‌سازی را استانداردسازی می‌کند. با پیاده‌سازی یک کلاینت MCP، برنامه شما می‌تواند ابزارهای ارائه شده توسط سرور را به صورت پویا از طریق یک پروتکل یکپارچه کشف و اجرا کند. این امر تمرکز توسعه‌دهنده را از نوشتن منطق یکپارچه‌سازی تکراری API به طراحی شبکه‌های عامل‌گرای سطح بالا تغییر می‌دهد.

اتصال به زمین گوگل مپ لایت MCP

Google Maps Grounding Lite MCP یک سرور MCP کاملاً مدیریت‌شده و میزبانی‌شده توسط گوگل است که می‌تواند مستقیماً در هر چارچوب عاملیتی سازگار ادغام شود.

در حال حاضر، این سرور سه ابزار اصلی برای اتصال به زمین ارائه می‌دهد:

جستجوی مکان‌ها : اطلاعاتی در مورد مکان‌ها درخواست کنید و خلاصه داده‌های مکانی تولید شده توسط هوش مصنوعی، و همچنین شناسه‌های مکان، مختصات طول و عرض جغرافیایی و پیوندهای نقشه‌های گوگل برای هر یک از مکان‌های موجود در خلاصه را دریافت کنید. می‌توانید از شناسه‌های مکان و مختصات طول و عرض جغرافیایی بازگشتی با سایر APIهای پلتفرم نقشه‌های گوگل برای نمایش مکان‌ها روی نقشه استفاده کنید.
جستجوی آب و هوا : درخواست اطلاعات در مورد آب و هوا و ارائه شرایط فعلی، پیش‌بینی‌های ساعتی و پیش‌بینی‌های روزانه.
محاسبه مسیرها : درخواست اطلاعات در مورد مسیرهای رانندگی یا پیاده‌روی بین دو مکان و اطلاعات مسافت و مدت زمان مسیر رفت و برگشت.

برای دسترسی به این سرویس، می‌توانید از کلید API یا OAuth استفاده کنید. پلتفرم نقشه‌های گوگل یک کلید API آزمایشی رایگان ارائه می‌دهد که به‌طور خاص برای کمک به توسعه‌دهندگان جهت شروع فوری نمونه‌سازی اولیه طراحی شده است.

نقشه‌های اتصال به زمین معماری MCP

بهترین شیوه‌ها برای ادغام نقشه‌ها و اتصال به زمین در MCP

برای به حداکثر رساندن ارتباط داده‌ها و حذف توهمات ساختاری، دستورالعمل‌های سیستم عامل خود را حول این استراتژی‌های اصلی تنظیم کنید: * صریح و مشخص باشید : به عامل دستور دهید که از مکان‌های دقیق استفاده کند. "سنترال پارک، نیویورک" نتایج بهتری نسبت به "نیویورک" ارائه می‌دهد، همانطور که "پاریس، فرانسه" از سردرگمی با پاریس، تگزاس جلوگیری می‌کند.

تجزیه پرس‌وجوهای عمومی : برای درخواست‌های مبهمی مانند «ایده‌های قرار ملاقات شبانه»، از اپراتور بخواهید که وظیفه را به زیرجستجوهای خاص مانند «رستوران‌های رمانتیک»، «سینماها» یا «کافه‌های کوکتل» تجزیه کند.
اول کشف، بعد اکتشاف : ابتدا یک جستجوی اکتشافی گسترده انجام دهید (مثلاً "رستوران‌های ژاپنی با ورودی‌های مناسب برای افراد خاص، یکشنبه‌ها باز هستند"). گزینه‌هایی را به کاربر ارائه دهید و سپس یک پرس‌وجوی تکمیلی برای دریافت جزئیات خاص مانند شماره تلفن محل انتخاب شده اجرا کنید.
هرگز در مورد شناسه‌های مکان خیال‌پردازی نکنید : شناسه‌های مکان، بافت ارتباطی حیاتی در سراسر سرویس‌های پلتفرم نقشه‌های گوگل هستند. مطمئن شوید که نماینده شما می‌داند که فقط باید از شناسه‌های مکانی که صریحاً توسط ابزار search_places برگردانده می‌شوند استفاده کند، نه اینکه سعی کند شناسه‌های خودش را تولید کند.

پیاده‌سازی یک آژانس برنامه‌ریزی سفر با Google ADK

این بخش نحوه ساخت یک آژانس برنامه‌ریزی سفر با استفاده از چارچوب کیت توسعه عامل گوگل (ADK) را نشان می‌دهد. اگر ADK را نصب ندارید، به سند توسعه Google ADK مراجعه کنید.

ادغام سرور Maps MCP در یک چارچوب عامل مانند ADK ساده است. 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.

فایل .py برای شروع

from . import agent

اجرای adk web و تعامل با آن

برای شروع رابط کاربری وب پیش‌فرض ADK، این دستور را در دایرکتوری پروژه travel-concierge-google-maps-mcp اجرا کنید:

adk web

تعامل در رابط کاربری:

رابط کاربری را در آدرس http://127.0.0.1:8000 در مرورگر بارگذاری کنید.
پیشنهادهایی مانند موارد زیر را امتحان کنید:
- «من شنبه در سانفرانسیسکو خواهم بود. یک سفر یک روزه برای من برنامه‌ریزی کن.»
- «کافی شاپ‌های نزدیک پارک گلدن گیت را پیدا کنید و نکات برجسته منو را به من نشان دهید.»
- «از گوگل‌پلکس تا SFO مسیر پیدا کنید.»

وقتی عامل درخواست را دریافت می‌کند، برنامه‌ریز قصد کاربر را ارزیابی می‌کند. این برنامه نیاز به داده‌های مکانی و آب و هوایی را تشخیص می‌دهد و به طور خودکار ابزارهای lookup_weather، search_places و compute_routes را با استفاده از سرور MCP فعال می‌کند. سپس عامل یک برنامه سفر مبتنی بر واقعیت را برای کاربر ترکیب می‌کند.

نتیجه‌گیری

تغییر به سمت هوش مصنوعی عامل‌محور، قابلیت‌های کاملاً جدیدی را در لجستیک، سفر و خرده‌فروشی ایجاد می‌کند. با این حال، استقلال واقعی نیازمند پایه و اساس محکمی از حقیقت است.

با بهره‌گیری از پروتکل Model Context در کنار Google Maps Grounding Lite، شما مشکلات ناشی از ادغام APIهای سفارشی را از بین می‌برید و به نمایندگان خود چشم و گوش‌های بلادرنگ مورد نیازشان را می‌دهید. اتصال مدل‌های شما به داده‌های مکانی زنده تضمین می‌کند که آنها تصمیمات عملیاتی خود را بر اساس آنچه در حال حاضر در دنیای فیزیکی اتفاق می‌افتد، می‌گیرند - نه بر اساس یک تصویر لحظه‌ای منجمد از داده‌های آموزشی خود.

اقدامات بعدی

مستندات توسعه‌دهنده‌ی Maps Grounding MCP را مطالعه کنید.
یک کلید API آزمایشی دریافت کنید.
یاد بگیرید که چگونه عامل خود را مستقر کنید .

نویسندگان اصلی:

ترزا کین | مهندس DevX پلتفرم نقشه‌های گوگل