أدوات موظّف دعم التجارب من "خرائط Google"

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

"أدوات تجربة الخرائط للوكلاء" هي منتج واحد يتضمّن رمزَي تخزين تعريفيَين: Essentials وPro. تتم فوترة كل طلب ضمن خطة Essentials ما لم يتم استخدام خيار Pro. تضيف خيارات Pro عمليات البحث عن الأماكن على طول المسار، وتفاصيل الأماكن الموسّعة، والمزيد من الأماكن لكل عملية بحث، والمزيد من محطات التوقف المؤقتة لكل مسار، والمسارات مع حركة المرور المباشرة، وتوقعات حبوب اللقاح، وجودة الهواء السابقة. يستخدم كلا رمزَي التخزين التعريفي الأدوات نفسها وخادم MCP وطرق REST وبيانات الاعتماد. لمعرفة التفاصيل، يُرجى الاطّلاع على Essentials وPro.

الأدوات

تتيح أدوات التجارب من "خرائط Google" للوكلاء للنماذج اللغوية الكبيرة الوصول إلى إمكانات "خرائط Google" التالية:

• البحث عن الأماكن: يمكنك طلب معلومات عن الأماكن والحصول على ملخّصات من إنشاء الذكاء الاصطناعي. يتضمّن الردّ أيضًا أرقام تعريف الأماكن وإحداثيات خطوط العرض/الطول وروابط إلى "خرائط Google" لكل مكان في الملخّص. يمكنك استخدام أرقام تعريف الأماكن وإحداثيات خطوط العرض/الطول مع واجهات برمجة التطبيقات الأخرى في "منصة خرائط Google" لعرض الأماكن على الخريطة. لعرض هذه الأماكن باستخدام حزمة أدوات "خرائط Google" الجاهزة للأماكن بدون أي تكلفة إضافية، استخدِم الرمز المميّز لتصوّر البيانات المستند إلى الذكاء الاصطناعي الوكيل (نسخة حصرية). باستخدام Pro، يمكنك طلب تفاصيل المكان الموسّعة، مثل إحصاءات من المراجعات، وما يصل إلى 10 أماكن لكل طلب.
• البحث على طول المسار: يمكنك العثور على أماكن على طول مسار الرحلة، والذي يتم تحديده باستخدام retrieval_token من compute_routes أو route_endpoints أو encoded_polyline، والحصول على ملخّص من إنشاء الذكاء الاصطناعي وتفاصيل المكان ومسافة الانعطاف ومدة الرحلة ورمز مميّز لتصوّر البيانات المستند إلى الوكيل (نسخة حصرية). تتم فوترة كل طلب من search_along_route ضمن رمز التخزين التعريفي Pro.
• البحث عن معلومات الطقس: يمكنك طلب معلومات عن الظروف البيئية لموقع جغرافي معيّن، بما في ذلك الطقس (الظروف الحالية، وسجلّ الطقس على مدار 24 ساعة، وتوقعات الطقس اليومية وكل ساعة لمدة تصل إلى 10 أيام) وجودة الهواء الحالية أو التوقعات لمدة تصل إلى 4 أيام. باستخدام الإصدار Pro، يمكنك أيضًا طلب توقّعات يومية لحبوب اللقاح لمدة تصل إلى 5 أيام (مع تفاصيل أنواع النباتات) وسجلّ جودة الهواء بالساعة لمدة تصل إلى 30 يومًا.

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

• حلّ الأسماء وحلّ عناوين URL في "خرائط Google": يمكنك حلّ أسماء المواقع الجغرافية وعناوينها وعناوين URL في "خرائط Google" إلى أرقام تعريف الأماكن. لمزيد من المعلومات، يُرجى الاطّلاع على Resolution API.

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

Essentials وPro

‫Essentials وPro هما رمزا تخزين تعريفيان للمنتج نفسه، وليسا منتجَين أو خطتَين منفصلَين. تتم فوترة الطلب ضمن Pro عندما يستخدم خيار Pro. ويتم تحصيل رسوم كل طلب آخر ضمن Essentials. خيارات Pro هي حقول عادية في طلب الأداة، لذا يمكن للنموذج اللغوي الكبير استخدامها نيابةً عنك. يمكن للوكيل أيضًا استخدام كلا رمزَي التخزين التعريفي في المحادثة نفسها. على سبيل المثال، قد يستخدم الوكيل Essentials للعثور على مقاهٍ بالقرب من أحد المعالم. قد يستخدم بعد ذلك Pro للإجابة عن سؤال متابعة حول المشروبات المميزة وأماكن الجلوس. لا يتوفّر خادم أو نقطة نهاية أو بيانات اعتماد منفصلة لبروتوكول MCP في Pro.

مقارنة بين Essentials وPro و"استخدام خرائط Google كمصدر"

استخدام "خرائط Google" كمصدر هو منتج منفصل. وهي مدمجة في نماذج Gemini في Gemini API وGoogle AI Studio وGemini Enterprise Agent Platform. يحدّد النموذج متى يجب إرسال طلب بحث إلى "خرائط Google" ويعرض إجابات مستندة إلى مصادر موثوقة مع اقتباسات. اختَر "استخدام خرائط Google كمصدر" إذا كنت تستخدم Gemini وتريد أن يتولّى النموذج عملية التحقّق من صحة الردود. يمكنك اختيار أدوات التجارب من "خرائط Google" للوكلاء لنماذج أو أُطر عمل أخرى للوكلاء، أو للتحكّم المباشر في كل طلب أداة.

يقارن الجدول التالي بين SKU Essentials وSKU Pro و"استخدام خرائط Google كمصدر":

تعمل هذه الخيارات بالطريقة نفسها مع أيّ من رمزَي التخزين التعريفي: أوضاع السفر وأوقات المغادرة ووقت الوصول والمسارات البديلة والخطوط المتعدّدة للمسارات وعمليات البحث عن الطقس وعمليات البحث عن جودة الهواء الحالية والمتوقّعة (بما في ذلك تركيزات الملوّثات ومقاييس مؤشر جودة الهواء المحلي) وأنظمة وحدات الطقس وResolution API. ولا تغيّر رمز التخزين التعريفي الذي تتم فوترة الطلب بموجبه.

ما يتم تحصيله ضمن رمز التخزين التعريفي Pro

يلخّص الجدول التالي الإمكانات المضمّنة في Essentials والإمكانات التي تتطلّب رمز التخزين التعريفي Pro:

للاطّلاع على خيارات الطلبات التي تفعّل كل ميزة، يُرجى مراجعة البحث عن الأماكن، البحث على طول المسار، احتساب المسارات، و البحث عن حالة الطقس.

التحكّم في استخدام Gemini Pro

تكون الخيارات الاحترافية غير مفعَّلة تلقائيًا على أجهزة search_places وcompute_routes وlookup_weather. يضبطها النموذج اللغوي الكبير أو يستدعي search_along_route عندما يتطلّب طلب المستخدم ذلك ويسمح به وصف الأداة أو تعليماتك. توضّح أوصاف الأدوات للنموذج الخيارات التي تكلّف أكثر ومتى يجب استخدامها: page_size أعلى من 5، وتفاصيل المكان الموسّعة، وأكثر من 10 نقاط على المسار متوسطة، والمسار المستند إلى حركة المرور، وsearch_along_route. إذا استدعيت الأدوات باستخدام REST، سيضبط الرمز كل خيار. لإدارة التكاليف:

• أخبِر النموذج بالحالات التي تكون فيها خيارات Pro مناسبة. على سبيل المثال: "اضبط include_extended_details فقط عندما يسأل المستخدم عن المراجعات أو قوائم الطعام أو الأجواء". أو: "استخدِم ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL فقط عندما يطلب المستخدم مدة الرحلة الحالية". أو: "يجب استدعاء search_along_route فقط عندما يطلب المستخدم أماكن على طول المسار". أو: "يُرجى تضمين POLLEN أو AIR_QUALITY مع date أو hour في الماضي، فقط عندما يسأل المستخدم عن حبوب اللقاح أو الحساسية أو جودة الهواء في الماضي".
• لإبقاء الوكيل ضمن رمز التخزين التعريفي Essentials، يجب توجيه النموذج بعدم الاتصال بـ search_along_route أو استخدام خيار Pro. تشمل خيارات Pro include_extended_details وpage_size أكثر من 5 وROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL وأكثر من 10 نقاط على المسار متوسطة وPOLLEN في capabilities وdate أو hour سابقة مع AIR_QUALITY في capabilities. إذا كان بإمكان عميل MCP حظر أدوات أو وسيطات أدوات، يمكنك أيضًا حظر search_along_route وقيم الوسيطات هذه في إعدادات الأداة.
• يمكنك مراقبة رمز التخزين التعريفي Maps Grounding Pro في تقارير الفوترة وضبط تنبيهات الميزانية.

Resolution API

توفّر أدوات التجارب من "خرائط Google" للوكلاء واجهة برمجة التطبيقات Resolution API. وتعمل على تحويل النصوص وعناوين URL التي تصف المواقع الجغرافية بشكل مرن إلى معرّفات أماكن منظَّمة في "خرائط Google". تتوفّر واجهة Resolution API كطُرق REST وكأدوات على خادم MCP:

• تحويل الأسماء (REST، MCP): تتيح لك هذه الطريقة تحويل مجموعة من أسماء المواقع الجغرافية أو العناوين إلى كيانات أماكن محدّدة على "خرائط Google". تساعد هذه الأداة في ربط طلبات البحث غير المنظَّمة التي يُجريها المستخدمون بأرقام تعريف أماكن ثابتة.
• Resolve Maps URLs (REST، MCP): تتيح لك هذه الطريقة حلّ مجموعة من عناوين URL في "خرائط Google" لكي تشير إلى كيانات أماكن محدّدة. تشمل التنسيقات المتوافقة عناوين URL العادية للأماكن وعناوين URL المختصرة.

يمكنك استخدام أرقام تعريف الأماكن التي تم عرضها مع واجهات برمجة تطبيقات أخرى في "منصة خرائط Google". يتضمّن كل ردّ أيضًا رابطًا يحفظ الأماكن التي تم حلّها كقائمة في "خرائط Google".

لمزيد من المعلومات، يُرجى الاطّلاع على Maps Tools Resolution API.

تجربة نموذج التطبيق (يفتح الرابط في علامة تبويب جديدة)

الفوترة والحصص

كيفية تحصيل الرسوم منك

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

تتم فوترة كل طلب من طلبات "البحث عن الأماكن" أو "البحث على طول المسار" أو "احتساب المسارات" أو "البحث عن حالة الطقس"، من خلال خادم MCP أو باستخدام REST، ضمن رمز تخزين تعريفي واحد: Maps Grounding Essentials أو Maps Grounding Pro. يتم إصدار فاتورة لكل طلب search_along_route وأي طلب يستخدم خيار Pro ضمن رمز التخزين التعريفي لـ Pro. لا تتم فوترة الطلب مطلقًا ضمن كلتا وحدتَي التخزين التعريفيتَين، ولا يؤدي عدد خيارات Pro في الطلب إلى تغيير الرسوم. للاطّلاع على الإمكانات والخيارات التي تحدّد رمز التخزين التعريفي لكل أداة، يُرجى مراجعة ما يتم تحصيله ضمن رمز التخزين التعريفي Pro.

يتم تحصيل رسوم طلبات Maps Grounding Essentials بقيمة 7.00 دولار أمريكي لكل 1,000 طلب بعد أول 10,000 طلب كل شهر. يتم تحصيل رسوم طلبات Maps Grounding Pro بقيمة 14 دولار أمريكي لكل 1,000 طلب بعد أول 5,000 طلب كل شهر. يوفّر كلا رمزَي التخزين التعريفي خصومات على الكميات عند زيادة الاستخدام الشهري.

يمكنك الاطّلاع على جدول الأسعار الرئيسي وجدول الأسعار في الهند لمعرفة تفاصيل الأسعار.

يتم إصدار فواتير طلبات Resolution API (ResolveNames وResolveMapsUrls) بدون أي رسوم ضمن رمز التخزين التعريفي Places API Text Search Essentials (IDs Only).

إذا كنت تعرض الأماكن من ردّ search_places أو search_along_route باستخدام حزمة أدوات "خرائط Google" الجاهزة للأماكن، يمكنك استخدام الرمز المميّز لتصوّر البيانات المستند إلى الوكيل (نسخة حصرية) لكي لا تتم فوترة طلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن هذه.

يتم تضمين استخدام رمز التخزين التعريفي Essentials في خطتَي Essentials وPro الاشتراك للتوفير. ويتم تضمين استخدام رمز التخزين التعريفي Pro في خطة Pro.

الحِصص

تنطبق الحصص التالية على الأدوات وواجهات برمجة التطبيقات التي توفّرها أدوات وكيل تجربة الخرائط:

• البحث عن الأماكن: ‫300 طلب في الدقيقة لكل مشروع
• البحث على طول المسار: ‫300 طلب في الدقيقة لكل مشروع
• البحث عن الطقس: ‫300 طلب في الدقيقة لكل مشروع
• احتساب المسارات: 300 طلب بحث في الدقيقة لكل مشروع
• حلّ الأسماء: 600 طلب في الدقيقة لكل مشروع
• حلّ عناوين URL في "خرائط Google": ‏600 طلب في الدقيقة لكل مشروع

يتم احتساب الحصص لكل أداة وتتم مشاركتها من خلال رمزَي التخزين التعريفي Essentials وPro. يستهلك طلب Pro الحصة نفسها التي يستهلكها طلب Essentials للأداة نفسها.

يتم احتساب كل طلب بيانات من واجهة برمجة التطبيقات Resolution كطلب بحث واحد، بغض النظر عن عدد العناصر التي يحتوي عليها.

السياسات وبنود الخدمة

تخضع أدوات التجارب من "خرائط Google" للوكلاء لبنود خدمة "منصة خرائط Google"، بما في ذلك البنود الخاصة بالخدمة. يصف هذا القسم متطلبات الاستخدام الإضافية لأدوات وكيل "التجارب من خرائط Google"، بما في ذلك النماذج اللغوية الكبيرة المتوافقة ومصادر المعلومات. تنطبق المتطلبات على جميع النتائج، بغض النظر عن رمز التخزين التعريفي الذي تتم فوترة الطلب بموجبه.

متطلبات نماذج اللغات الكبيرة المتوافقة

لا يجوز لك استخدام أدوات التجارب من "خرائط Google" للوكلاء إلا مع نموذج لغوي كبير متوافق مع بنود خدمة "منصة خرائط Google".

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

متطلبات تحديد المصدر لمصادر "خرائط Google"

يتضمّن كل ردّ من أدوات تجربة الخرائط للوكلاء المصادر. عند عرض نتائج من أدوات التجارب من "خرائط Google" للوكلاء، يجب تضمين مصادر "خرائط Google" المرتبطة بها واستيفاء المتطلبات التالية:

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

مصادر أداتَي "البحث عن أماكن" و"البحث على طول المسار"

يوفّر حقل places في أداة search_places وحقل results[].place في أداة search_along_route مصادر تدعم summary. لكل مكان، يتم عرض البيانات الوصفية التالية:

• place (اسم المرجع)
• id
• location
• googleMapsLinks
• attribution

لكل مكان، يجب إنشاء معاينة رابط تستوفي المتطلبات التالية:

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

تنطبق هذه المتطلبات أيضًا على الملخّصات التي تتضمّن تفاصيل أماكن موسّعة من Pro، مثل الإحصاءات من المراجعات. يستشهد summary بكل مكان باستخدام فهرس يستند إلى الصفر، مثل [0]، والذي يتم ربطه بإدخال في places أو results. يتضمّن كل مكان أيضًا googleMapsLinks.reviewsUrl، والذي يرتبط بمراجعات المكان على "خرائط Google". يمكن للمستخدمين متابعته للاطّلاع على المراجعات التي تستند إليها الإحصاءات.

واجهات تعتمد على الصوت أولاً

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

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

ضبط النماذج اللغوية الكبيرة لاستخدام خادم MCP

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

تفعيل أدوات تجربة الخرائط للوكلاء في مشروعك على Google Cloud

لتفعيل واجهة برمجة التطبيقات في مشروعك:

1. في Google Cloud Console، اختَر المشروع الذي تريد استخدامه لأدوات تجربة الخرائط للوكلاء.
2. فعِّل الفوترة للمشروع في Google Cloud Console.
3. فعِّل أدوات التجارب من "خرائط Google" للوكلاء في مكتبة واجهات برمجة التطبيقات في Google Cloud Console.

المصادقة باستخدام مفتاح واجهة برمجة التطبيقات

يمكنك استخدام مفتاح واجهة برمجة تطبيقات حالي مع أدوات التجارب من "خرائط Google" للوكلاء أو إنشاء مفتاح جديد. في كلتا الحالتَين، فعِّل خدمة واجهة برمجة التطبيقات أدوات تجربة الخرائط للوكلاء لكلّ من مشروع Google Cloud والمفتاح.

للمصادقة باستخدام مفتاح واجهة برمجة التطبيقات:

1. أنشئ مفتاح واجهة برمجة تطبيقات أو اضبطه باتّباع الخطوات الواردة في مقالة بدء استخدام "منصة خرائط Google".
2. مرِّر المفتاح إلى خادم MCP باستخدام العنوان X-Goog-Api-Key. يجب تحديد ذلك كعنوان HTTP مخصّص في إعدادات أداة MCP الخاصة بنموذج اللغة الكبير.

المصادقة باستخدام OAuth

يمكنك المصادقة باستخدام OAuth من خلال إنشاء بيانات اعتماد OAuth وتمريرها إلى مضيف MCP أو تطبيق خادم MCP.

للمصادقة باستخدام OAuth:

1. في Google Cloud Console، اختَر المشروع الذي تريد استخدامه لأدوات التجارب من "خرائط Google" للوكلاء.
2. في قائمة واجهات برمجة التطبيقات والخدمات، اختَر بيانات الاعتماد.
3. في القائمة في أعلى الشاشة، انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
4. إذا لم يتضمّن المشروع شاشة طلب موافقة تم ضبطها، انقر على ضبط شاشة طلب الموافقة واتّبِع التعليمات الظاهرة على الشاشة.
5. في قسم المقاييس، انقر على إنشاء عميل OAuth.
6. في شاشة إنشاء معرِّف عميل OAuth، اختَر نوع التطبيق وأدخِل اسمًا لمعرِّف العميل.
7. حدِّد التفاصيل الإضافية ذات الصلة بنوع تطبيقك. على سبيل المثال، إذا كنت تنشئ تطبيق ويب، أضِف معرّفات الموارد المنتظمة (URI) المصرَّح بها لطلبات المتصفّح والخادم.
8. بعد إنشاء العميل، احفظ معرّف العميل وسرّه.
9. عند ضبط إعدادات مضيف MCP أو تطبيق خادم MCP، عليك تمرير معرّف عميل OAuth والسرّ. يجب أيضًا طلب النطاق التالي: https://www.googleapis.com/auth/maps-platform.mapstools.

لمزيد من المعلومات، يُرجى الاطّلاع على استخدام بروتوكول OAuth 2.0 للوصول إلى Google APIs.

ضبط إعدادات النماذج اللغوية الكبيرة للوصول إلى خادم بروتوكول سياق النموذج (MCP) الخاص بأدوات التجارب من "خرائط Google" للوكلاء

بعد تفعيل خدمة التجارب من خرائط Google للوكلاء وإنشاء بيانات الاعتماد، يمكنك ضبط النماذج اللغوية الكبيرة للوصول إلى خادم بروتوكول سياق النموذج (MCP). اتّبِع مستندات إعدادات MCP الخاصة بنموذجك اللغوي الكبير واستخدِم عنوان URL لخادم MCP: https://mapstools.googleapis.com/mcp

لمزيد من المعلومات، يُرجى الاطّلاع على ضبط MCP في تطبيق مستند إلى الذكاء الاصطناعي.

ضبط أدوات التجارب من "خرائط Google" للوكلاء باستخدام Gemini CLI

يقدّم هذا القسم مثالاً على كيفية ضبط خادم بروتوكول سياق النموذج (MCP) لأدوات وكيل "التجارب من خرائط Google" باستخدام Gemini CLI. لمزيد من التفاصيل، يُرجى الاطّلاع على خوادم MCP مع Gemini CLI.

1. بعد تثبيت Gemini CLI، شغِّل gemini mcp add لضبط خادم MCP:

   gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-experience-agent-tools-mcp https://mapstools.googleapis.com/mcp
   

   إذا نجحت عملية الضبط، من المفترض أن تظهر لك رسالة تأكيد بأنّه تمت إضافة الخادم إلى إعدادات المستخدم.

2. للتحقّق من عمل الخادم، شغِّل الأمر /mcp list:

   > /mcp list
   
   Configured MCP servers:
   
   maps-experience-agent-tools-mcp - Ready (6 tools)
   Tools:
   -   compute_routes
   -   lookup_weather
   -   resolve_maps_urls
   -   resolve_names
   -   search_along_route
   -   search_places
   

3. ابدأ بطرح أسئلة متعلّقة بـ "اسأل خرائط Google" باستخدام واجهة سطر الأوامر. على سبيل المثال، يمكنك تجربة "اقتراح بعض المطاعم في الرياض"، ما يؤدي إلى استدعاء أداة search_places نيابةً عنك.

ضبط أدوات التجارب من "خرائط Google" للوكلاء باستخدام "حزمة تطوير الوكلاء" (ADK)

يوضّح هذا القسم كيفية ضبط خادم MCP باستخدام حزمة تطوير الوكلاء (ADK) في Python أو Java أو TypeScript.

# ./adk_agent_samples/mcp_agent/agent.py
import os
from google.adk.agents.llm_agent import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# Retrieve the API key from an environment variable or directly insert it.
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")
if not GOOGLE_MAPS_API_KEY:
    GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY_HERE"

if GOOGLE_MAPS_API_KEY == "YOUR_GOOGLE_MAPS_API_KEY_HERE":
    print("WARNING: GOOGLE_MAPS_API_KEY is not set.")

root_agent = Agent(
    model='gemini-flash-latest',
    name='travel_planner_agent',
    description='A helpful assistant for planning travel routes.',
    tools=[
        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"
                }
            )
        )
    ]
)
    

from . import agent
    

package agents;

import com.google.adk.agents.LlmAgent;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.SessionKey;
import com.google.adk.tools.mcp.McpToolset;
import com.google.adk.tools.mcp.StreamableHttpServerParameters;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import java.util.HashMap;
import java.util.Map;

public class MapsAgentCreator {
    public static void main(String[] args) {
        String googleMapsApiKey = System.getenv("GOOGLE_MAPS_API_KEY");
        if (googleMapsApiKey == null || googleMapsApiKey.trim().isEmpty()) {
            googleMapsApiKey = "YOUR_GOOGLE_MAPS_API_KEY_HERE";
            if ("YOUR_GOOGLE_MAPS_API_KEY_HERE".equals(googleMapsApiKey)) {
                System.out.println("WARNING: GOOGLE_MAPS_API_KEY is not set.");
            }
        }

        Map<String, String> headers = new HashMap<>();
        headers.put("X-Goog-Api-Key", googleMapsApiKey);
        headers.put("Content-Type", "application/json");
        headers.put("Accept", "application/json, text/event-stream");

        StreamableHttpServerParameters serverParams =
                StreamableHttpServerParameters.builder("https://mapstools.googleapis.com/mcp")
                        .headers(headers)
                        .build();

        try (McpToolset toolset = new McpToolset(serverParams)) {
            LlmAgent agent = LlmAgent.builder()
                    .model("gemini-flash-latest")
                    .name("travel_planner_agent")
                    .description("A helpful assistant for planning travel routes.")
                    .tools(toolset)
                    .build();

            System.out.println("Agent created: " + agent.name());

            InMemoryRunner runner = new InMemoryRunner(agent);
            String userId = "maps-user-" + System.currentTimeMillis();
            String sessionId = "maps-session-" + System.currentTimeMillis();
            String promptText =
                    "Please give me directions to the nearest pharmacy to Madison Square Garden.";

            SessionKey sessionKey = runner.sessionService()
                    .createSession(runner.appName(), userId, null, sessionId)
                    .blockingGet()
                    .sessionKey();
            System.out.println("Session created: " + sessionId + " for user: " + userId);

            Content promptContent = Content.fromParts(Part.fromText(promptText));
            System.out.println("\nSending prompt: \"" + promptText + "\" to agent...\n");

            runner.runAsync(sessionKey, promptContent)
                    .blockingForEach(event -> {
                        System.out.println("Event received: " + event.toJson());
                    });
        } catch (Exception e) {
            System.err.println("An error occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
    

import 'dotenv/config';
import {LlmAgent, MCPToolset} from "@google/adk";

const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY;
if (!googleMapsApiKey) {
    console.warn("WARNING: GOOGLE_MAPS_API_KEY is not set.");
    throw new Error(
        'GOOGLE_MAPS_API_KEY is not provided, please run "export GOOGLE_MAPS_API_KEY=YOUR_ACTUAL_KEY" to add that.'
    );
}

export const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "travel_planner_agent",
    description: "A helpful assistant for planning travel.",
    tools: [
        new MCPToolset({
            type: "StreamableHTTPConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            transportOptions: {
                requestInit: {
                    headers: {
                        "X-Goog-Api-Key": googleMapsApiKey,
                        "Content-Type": "application/json",
                        "Accept": "application/json, text/event-stream"
                    }
                }
            }
        })
    ],
});
    

استدعاء الأدوات باستخدام REST

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

يسرد الجدول التالي طريقة REST لكل أداة:

يستخدم طلب REST الخيارات نفسها التي تستخدمها الأداة المقابلة ويعرض الاستجابة نفسها. في نصوص طلبات واستجابات REST، تستخدم أسماء الحقول تنسيق Camel Case الصغير، على سبيل المثال، textQuery بدلاً من text_query. تتم فوترة طلبات REST ضمن رموز التخزين التعريفية نفسها، وتتّبع القواعد نفسها لخيارات Pro، ويتم احتسابها ضمن الحصص نفسها مثل طلبات أدوات MCP.

للمصادقة، استخدِم المشروع وبيانات الاعتماد نفسها على Google Cloud المستخدَمة في خادم MCP. للاطّلاع على خطوات الإعداد، يُرجى مراجعة مقالة ضبط النماذج اللغوية الكبيرة لاستخدام خادم MCP. مرِّر مفتاح واجهة برمجة التطبيقات في العنوان X-Goog-Api-Key أو مرِّر رمز الدخول OAuth مع النطاق https://www.googleapis.com/auth/maps-platform.mapstools في العنوان Authorization.

يستدعي المثال التالي طريقة searchText:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "coffee shops near Golden Gate Park"
}' \
"https://mapstools.googleapis.com/v1:searchText"

استبدِل API_KEY بمفتاح واجهة برمجة التطبيقات.

تحتوي الاستجابة على الحقول summary وplaces وcontentToken نفسها التي تظهر في نتيجة أداة search_places. يعرض دليل كل أداة نسخة REST من مثالها.

مشاركة الملاحظات

لمشاركة ملاحظات حول أدوات تجربة الخرائط للوكلاء، يُرجى استخدام النماذج التالية:

• الإبلاغ عن خطأ
• إرسال طلب ميزة
• تقديم الملاحظات