تزويد وكلاء الذكاء الاصطناعي بسياق جغرافي مكاني من العالم الحقيقي باستخدام بروتوكول Model Context Protocol (MCP) في Maps Grounding Lite

يمثّل إنشاء وكلاء الذكاء الاصطناعي تطورًا كبيرًا في تطوير البرامج، ما يتيح للأنظمة إجراء عمليات استنتاج معقّدة والعمل بقدر أكبر من الاستقلالية. ومع ذلك، فإنّ النماذج الأساسية التي تشغّل هذه الأنظمة تكون مقيّدة بشكل طبيعي ببيانات التدريب الخاصة بها. وبدون سياق خارجي، لا يكون لديها علم بالظروف في الوقت الفعلي، مثل الطقس الحالي في الخارج، أو ما إذا كان نشاط تجاري محلي مفتوحًا الآن، أو المسار الأكثر فعالية للوصول إلى وجهة معيّنة.

توضّح هذه المستندات كيفية سدّ الفجوة بين الاستنتاج الثابت والواقع الديناميكي من خلال تزويد وكلاء الذكاء الاصطناعي ببيانات جغرافية مكانية موثوق بها من "خرائط Google". ستتعرّف على سبب أهمية التزويد بالبيانات الجغرافية المكانية للمهام في العالم الحقيقي، وكيف يسهّل "بروتوكول سياق النموذج" (MCP) عملية دمج الأدوات، وكيفية إنشاء وكيل لتخطيط السفر باستخدام Google Maps Grounding Lite MCP.

مخطّط وكيل تخطيط الرحلات
وكيل تخطيط الرحلات الذي تم تزويده ببيانات من Maps MCP

لماذا يحتاج الوكلاء إلى تزويدهم ببيانات الخرائط

إنّ الانتقال من البرامج التقليدية إلى سير العمل المستند إلى الوكلاء هو تحوّل من الهندسة الحتمية إلى التنسيق الاحتمالي. نحن ننتقل من الأنظمة التي تعرف الأشياء فقط إلى محركات التنفيذ الاستباقية التي تنفّذ الأشياء فعليًا. عندما يتجاوز أحد التطبيقات هذا الحد ويتخذ إجراءً في العالم المادي، تتغيّر المخاطر المتعلقة بالدقة تمامًا.

تفهم النماذج اللغوية الكبيرة المنطق، ولكن ذاكرتها الداخلية هي لقطة تاريخية. على سبيل المثال، إذا كان أحد الوكلاء يدير سلسلة إمداد وأكّد بشكل غير صحيح توفّر أحد المورّدين أو مسار طريق، فسيؤدي ذلك إلى إهدار الوقود وعدم الالتزام باتفاقية مستوى الخدمة وتعطيل النشاط التجاري بشكل حقيقي. وفي البُنى المتعدّدة الوكلاء، ستواجه مشكلة الهلوسة المتتالية. إذا هلوس أحد الوكلاء في السلسلة ونقل بيانات خاطئة إلى وكيل ثانٍ، سيبدأ النظام بأكمله في تقديم التزامات في العالم الحقيقي استنادًا إلى كذبة. يصبح الاستقلال بدون الحقيقة مسؤولية كبيرة.

يفرض التزويد بالبيانات على الوكيل تجاوز أوزان التدريب الخاصة به. من خلال إجبار الذكاء الاصطناعي على جلب الحقائق القابلة للتحقّق والمباشرة، مثل بيانات الأماكن وبيانات التوجيه، فإنّك تمنح الوكيل عينَين وأذنَين في الوقت الفعلي، ما يحوّل التخمين الإحصائي إلى قرار تشغيلي مستنِد إلى معلومات.

لماذا MCP

‫"بروتوكول سياق النموذج" (MCP) هو معيار مفتوح المصدر مصمّم لجعل عمليات دمج الأدوات والبيانات سهلة الاستخدام.

في السابق، كان ربط نموذج الذكاء الاصطناعي بواجهات برمجة تطبيقات خارجية يتطلّب كتابة أغلفة صارمة ومخصّصة. كان عليك التعامل يدويًا مع التنسيق وتحليل الأخطاء وترجمة طلبات الأدوات لكل إمكانية فردية.

يضع MCP معيارًا لطبقة الدمج هذه. من خلال تنفيذ عميل MCP، يمكن لتطبيقك اكتشاف الأدوات التي يوفّرها الخادم وتنفيذها ديناميكيًا من خلال بروتوكول موحّد. يؤدي ذلك إلى تحويل تركيز المطوّر من كتابة منطق دمج واجهة برمجة التطبيقات المتكرّر إلى تصميم شبكات وكلاء عالية المستوى.

‫Google Maps Grounding Lite MCP

‫Google Maps Grounding Lite MCP هو خادم MCP مُدار بالكامل ومستضاف على Google ويمكن دمجه مباشرةً في أي إطار عمل متوافق مستند إلى الوكلاء.

يوفّر الخادم حاليًا ثلاث أدوات أساسية للتزويد بالبيانات:

  • البحث عن أماكن: يمكنك طلب معلومات عن الأماكن والحصول على ملخّصات لبيانات الأماكن من إنشاء الذكاء الاصطناعي، بالإضافة إلى أرقام تعريف الأماكن وإحداثيات خطوط العرض والطول وروابط "خرائط Google" لكل مكان من الأماكن المضمّنة في الملخّص. يمكنك استخدام أرقام تعريف الأماكن وإحداثيات خطوط العرض والطول التي يتم عرضها مع واجهات برمجة تطبيقات "منصة خرائط Google" الأخرى لعرض الأماكن على الخريطة.
  • الاطّلاع على أحوال الطقس: يمكنك طلب معلومات عن الطقس وعرض الأحوال الحالية والتوقعات كل ساعة والتوقعات اليومية.
  • احتساب المسارات: يمكنك طلب معلومات عن مسارات القيادة أو المشي بين موقعَين وعرض معلومات عن مسافة المسار ومدته.

للوصول إلى الخدمة، يمكنك استخدام مفتاح واجهة برمجة التطبيقات أو بروتوكول OAuth. توفر "منصة خرائط Google" مفتاح واجهة برمجة تطبيقات تجريبية مجانيًا مصممًا خصيصًا لمساعدة المطورين في بدء إنشاء النماذج الأولية على الفور.

بنية Maps Grounding MCP
بنية Maps Grounding MCP

أفضل الممارسات لدمج Maps Grounding MCP

لتحقيق أقصى قدر من الملاءمة للبيانات وإزالة الهلوسات البنيوية، يجب تثبيت تعليمات نظام الوكيل حول هذه الاستراتيجيات الأساسية: * كن صريحًا ومحدّدًا: اطلب من الوكيل استخدام مواقع جغرافية دقيقة. تحقّق عبارة "Central Park, New York" نتائج أفضل من "New York"، تمامًا كما تمنع عبارة "Paris, France" الخلط بينها وبين Paris, Texas.

  • قسِّم طلبات البحث العامة: بالنسبة إلى الطلبات الغامضة، مثل "أفكار لقضاء ليلة ممتعة"، اطلب من الوكيل تقسيم المهمة إلى عمليات بحث فرعية محدّدة، مثل "مطاعم رومانسية" أو "دور سينما" أو "بارات كوكتيل".

  • بحث استكشاف أولاً، ثم الاستكشاف ثانيًا: يمكنك إجراء بحث استكشاف واسع النطاق أولاً (مثل "مطاعم يابانية ذات مداخل يسهل الوصول إليها ومفتوحة يوم الأحد"). اعرض الخيارات على المستخدم، ثم شغِّل طلب بحث للمتابعة لجلب تفاصيل محدّدة، مثل رقم هاتف المكان الذي تم اختياره.

  • لا تُنشئ أرقام تعريف الأماكن بشكل غير صحيح: أرقام تعريف الأماكن هي الرابط الأساسي بين خدمات "منصة خرائط Google". تأكّد من أنّ الوكيل يعرف أنّه يجب ألا يستخدم سوى أرقام تعريف الأماكن التي يعرضها صراحةً أداة search_places، بدلاً من محاولة إنشاء أرقام تعريف خاصة به.

تنفيذ وكيل لتخطيط السفر باستخدام Google ADK

يوضّح هذا القسم كيفية إنشاء وكيل لتخطيط السفر باستخدام إطار عمل Google Agent Development Kit (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.

init.py 

from . import agent

تشغيل adk web والتفاعل

لبدء واجهة مستخدم الويب التلقائية في ADK، شغِّل هذا الأمر في دليل مشروع travel-concierge-google-maps-mcp: 

adk web

التفاعل في واجهة المستخدم:

  • حمِّل واجهة المستخدم على http://127.0.0.1:8000 في المتصفّح.
  • جرِّب طلبات بحث مثل:
    • "سأكون في دبي يوم السبت. ساعِدني في التخطيط لرحلة ليوم واحد."
    • "ابحث عن مقاهٍ بالقرب من حديقة الصفا واعرض لي أبرز عناصر القائمة."
    • "احصل على الاتجاهات من GooglePlex إلى مطار دبي الدولي."

عندما يتلقّى الوكيل الطلب، يقيّم المخطِّط نية المستخدم. ويتعرّف على الحاجة إلى البيانات الجغرافية المكانية وبيانات الطقس، ويشغّل بشكل مستقل الأدوات lookup_weather وsearch_places وcompute_routes باستخدام خادم MCP. بعد ذلك، يُنشئ الوكيل خط سير مستندًا إلى الحقائق للمستخدم.

الخاتمة

يؤدي التحوّل نحو الذكاء الاصطناعي الوكيل إلى توفير إمكانات جديدة تمامًا في مجالات الخدمات اللوجستية والسفر والبيع بالتجزئة. ومع ذلك، يتطلّب الاستقلال الحقيقي أساسًا قويًا من الحقيقة.

من خلال الاستفادة من "بروتوكول سياق النموذج" إلى جانب Google Maps Grounding Lite، يمكنك إزالة المشاكل الناتجة عن عمليات دمج واجهات برمجة التطبيقات المخصّصة ومنح الوكلاء العينَين والأذنَين في الوقت الفعلي اللذين يحتاجون إليهما. يضمن تثبيت نماذجك في البيانات الجغرافية المكانية المباشرة اتخاذها قرارات تشغيلية استنادًا إلى ما يحدث في العالم المادي الآن، وليس استنادًا إلى لقطة ثابتة من بيانات التدريب الخاصة بها.

الإجراءات التالية

المؤلفون الرئيسيون:

Teresa Qin | مهندسة في فريق DevX في "منصة خرائط Google"