يمكنك استخدام المزيد من إمكانات أدوات وكيل "التجارب من خرائط Google" مع إصدار Pro SKU. يُرجى التواصل مع فريق المبيعات للحصول على إذن الوصول.

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

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

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

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

الأدوات

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

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

ملاحظة: لا توفّر أدوات وكيل "التجارب من خرائط Google" اتجاهات مفصّلة أو معلومات تنقّل. لا تأخذ المسارات المحسوبة بدون خيارات 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" لنماذج أو أُطر عمل وكلاء أخرى، أو للتحكّم المباشر في كل طلب أداة.

	أدوات موظّف دعم التجارب من "خرائط Google"		استخدام "خرائط Google" كمصدر
	رمز التخزين التعريفي لـ Essentials (المعروف سابقًا باسم Maps Grounding Lite)	رمز التخزين التعريفي لإصدار Pro	استخدام "خرائط Google" كمصدر
كيفية فوترة الطلبات	كل طلب أداة لا يستخدم خيار Pro	كل طلب أداة يستخدم خيار Pro: `include_extended_details`، أو `page_size` أعلى من 5، أو `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`، أو أكثر من 10 نقاط على المسار متوسطة	كل طلب بحث أو مطالبة مستندة إلى المصادر في "خرائط Google"، حسب المنصة والنموذج
النماذج والمنصات	أي نموذج أو إطار عمل وكيل متوافق مع MCP خادم MCP واحد ومجموعة واحدة من الأدوات وبيانات الاعتماد نفسها لكل من رمزَي التخزين التعريفيَين		نماذج Gemini في Gemini API وGoogle AI Studio وGemini Enterprise Agent Platform
ما تعرضه الأدوات	الحقائق الأساسية: تفاصيل الأماكن لما يصل إلى 5 أماكن لكل عملية بحث، ومسافة المسار ومدته بدون حركة المرور المباشرة، والطقس الحالي والتوقعات	كل الميزات في Essentials، بالإضافة إلى تفاصيل الأماكن الموسّعة (مثل الإحصاءات من المراجعات)، وما يصل إلى 10 أماكن لكل عملية بحث، والمسارات مع حركة المرور المباشرة، وما يصل إلى 25 نقطة على المسار متوسطة	تفاصيل الأماكن والإحصاءات من المراجعات ومعلومات المسار مع حركة المرور في الوقت الفعلي
أمثلة على الطلبات	الأسئلة الواقعية واللوجستية: العثور على المتاجر أو المؤسسات، وساعات العمل، والعناوين، وتقديرات المسافة أو مدة الرحلة	الأسئلة الذاتية أو العامة: الأجواء، والأطباق المميّزة، ونصائح الزوّار، والمقارنات بين 6 إلى 10 أماكن، ومدة الرحلة في حركة المرور الحالية	البحث الحواري والتخطيط لبرامج الرحلات واستكشاف الأماكن المحلية في Gemini
الرسوم البيانية في حزمة أدوات "خرائط Google" الجاهزة للأماكن	مُضمّن بدون أي تكلفة إضافية مع رمز العرض المرئي للبيانات المستند إلى الذكاء الاصطناعي الوكيل (نسخة حصرية)		يتم تحصيل الرسوم بشكل منفصل
الاستخدام المجاني في الشهر	‫10,000 طلب	‫5,000 طلب	يعتمد ذلك على المنصة والطراز. على سبيل المثال، في Gemini API، يتضمّن Gemini 3 والنماذج الأحدث 5,000 طلب بحث مجاني شهريًا. بعد ذلك، تبلغ تكلفة طلبات البحث 14 دولار أمريكي لكل 1,000 طلب.
سعر الدفع حسب الاستخدام	‫7.00 دولار أمريكي لكل 1,000 طلب، مع خصومات على الكميات	‫14.00 دولار أمريكي لكل 1,000 طلب تواصَل مع فريق المبيعات لمعرفة الأسعار حسب الحجم.
اشترِك لتوفير المال	مضمَّنة في خطتَي Essentials وPro	غير متاحة	غير متوفر
البدء	إعداد واحد لكل من رمزَي التخزين التعريفي: راجِع ضبط النماذج اللغوية الكبيرة لاستخدام خادم MCP. خلال فترة التوفّر العام المحدود، تتطلّب خيارات Pro أيضًا مشروعًا في قائمة Pro المسموح بها.		Gemini API أو Agent Platform

تعمل هذه الخيارات بالطريقة نفسها مع أيّ من رمزَي التخزين التعريفي: وسائل النقل وأوقات المغادرة ووقت الوصول والمسارات البديلة والخطوط المتعدّدة للمسارات وعمليات البحث عن حالة الطقس وواجهة برمجة التطبيقات Resolution API. ولا تغيّر رمز التخزين التعريفي الذي تتم فوترة الطلب بموجبه.

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

الأداة	إمكانية	Essentials	Pro
البحث عن أماكن	عدد الأماكن لكل طلب	5 كحدّ أقصى	من 6 إلى 10 (`page_size` من 6 إلى 10)
البحث عن أماكن	تفاصيل موسّعة عن الأماكن في ملخّصات البحث (إحصاءات من المراجعات، وأبرز عناصر القائمة، والأجواء، ومدى ازدحام المكان، ونصائح للزوّار، والمسافة أو مدة الرحلة لطلبات البحث عن الأماكن القريبة)	غير متوفر	تتوفّر هذه الميزة مع `include_extended_details`
احتساب المسارات	الإعدادات المفضّلة للتوجيه	لا يتم احتساب حركة المرور المباشرة	يأخذ في الاعتبار حركة المرور المباشرة أو بيانات النقل العام في الوقت الفعلي لمسارات النقل العام، مع `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`
احتساب المسارات	النقاط الوسيطة على المسار لكل مسار	ما يصل إلى 10	من 11 إلى 25 (أكثر من 10 `intermediate_waypoints`)
Lookup weather وResolution API	لا تتوفّر خيارات Pro. تتم فوترة جميع الطلبات ضمن رمز التخزين التعريفي لـ Essentials.

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

خيارات Pro خلال فترة التوفّر المحدود للجمهور العام

خلال فترة التوفّر العام المحدود، لا تتوفّر خيارات Pro إلا لمشاريع Google Cloud المُدرَجة في القائمة المسموح بها لـ Pro. يُرجى التواصل مع فريق المبيعات لطلب الوصول إلى هذه الميزة. بعد إدراج مشروع في القائمة المسموح بها، يمكن لكل مفتاح واجهة برمجة تطبيقات وعميل OAuth فيه استخدام خيارات Pro.

إذا لم يكن مشروعك مدرَجًا في القائمة المسموح بها بعد، يتم التعامل مع الطلبات التي تستخدم خيارات Pro على النحو التالي:

البحث عن أماكن: يتم تجاهل include_extended_details، ويحتوي الردّ على 5 أماكن كحدّ أقصى، حتى إذا ضبطت قيمة أعلى لـ page_size. تتم فوترة الطلب ضمن رمز التخزين التعريفي لـ Essentials.
احتساب المسارات: يتم التعامل مع ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL على أنّه ROUTING_PREFERENCE_TRAFFIC_UNAWARE، وتتم فوترة الطلب ضمن رمز التخزين التعريفي لـ Essentials. إذا كان الطلب يتضمّن أكثر من 10 نقاط وسيطة على المسار، سيظهر الخطأ INVALID_ARGUMENT.

للتحقّق مما إذا كان مشروعك مدرجًا في القائمة المسموح بها، أرسِل طلب search_places مع ضبط page_size على 10. استخدِم طلب بحث عامًا، مثل restaurants in Chicago. يمكن لمشروع مدرَج في القائمة المسموح بها عرض أكثر من 5 أماكن، ويتم تحصيل رسومها ضمن رمز التخزين التعريفي Pro. وتعرض المشاريع الأخرى 5 أماكن كحدّ أقصى.

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

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

أخبِر النموذج بالحالات التي تكون فيها خيارات Pro مناسبة. على سبيل المثال: "اضبط include_extended_details فقط عندما يسأل المستخدم عن المراجعات أو القوائم أو الأجواء". أو: "استخدِم ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL فقط عندما يطلب المستخدم معرفة مدة الرحلة الحالية".
لإبقاء الوكيل على رمز التخزين التعريفي Essentials، يجب توجيه النموذج لعدم استخدام خيار Pro مطلقًا. تتوفّر خيارات Pro في include_extended_details وpage_size لأكثر من 5 نقاط على المسار، وROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL، ولأكثر من 10 نقاط على المسار متوسطة. إذا كان بإمكان عميل MCP فرض قيود على وسيطات الأدوات، يمكنك أيضًا حظر هذه القيم في إعدادات الأداة.
يمكنك مراقبة استخدامك في تقارير الفوترة وضبط تنبيهات الميزانية.

Resolution API

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

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

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

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

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

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

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

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

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

الأداة	Essentials	Pro
`search_places`	أي طلب بدون خيار Pro: ‏`page_size` من 5 أو أقل، و`include_extended_details` غير محدّد أو `false`	تم ضبط `include_extended_details` على `true`، أو `page_size` من 6 إلى 10
`compute_routes`	أي طلب بدون خيار Pro: لم يتم ضبط `routing_preference` أو `ROUTING_PREFERENCE_TRAFFIC_UNAWARE`، و10 نقاط على المسار وسيطة أو أقل، مع أي وضع سفر	تم ضبط `routing_preference` على `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`، أو من 11 إلى 25 نقطة على المسار متوسطة
`lookup_weather`	كل طلب	—

لمعرفة أسعار Essentials، يُرجى الاطّلاع على تفاصيل رمز التخزين التعريفي في Essentials. يتم تحصيل رسوم طلبات Pro بقيمة 14.00 دولار أمريكي لكل 1,000 طلب بعد أول 5,000 طلب كل شهر. تواصَل مع فريق المبيعات لمعرفة الأسعار حسب الحجم.

خلال فترة التوفّر المحدود للجمهور العام، لا تسري خيارات Pro إلا على المشاريع المدرَجة في القائمة المسموح بها في Pro. لمعرفة التفاصيل، يُرجى الاطّلاع على خيارات Pro خلال فترة التوفّر المحدود للجمهور العام.

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

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

يتم أيضًا تضمين استخدام Essentials SKU في حزمتَي Essentials وPro الاشتراك للتوفير. لا يتم تضمين رمز التخزين التعريفي Pro في حزم "الاشتراك والتوفير".

الحِصص

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

البحث عن الأماكن: ‫300 طلب في الدقيقة لكل مشروع
البحث عن الطقس: ‫300 طلب في الدقيقة لكل مشروع
احتساب المسارات: ‫300 طلب في الدقيقة لكل مشروع
حلّ الأسماء: 600 طلب في الدقيقة لكل مشروع
Resolve Maps URLs‏: 600 طلب في الدقيقة لكل مشروع

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

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

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

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

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

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

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

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

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

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

مصادر أداة "البحث في الأماكن"

يوفّر حقل "places" في أداة "search_places" مصادر تدعم summary. بالنسبة إلى places، يتم عرض البيانات الوصفية التالية:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

في Google Cloud Console، اختَر المشروع الذي تريد استخدامه لأدوات وكيل "التجارب من خرائط Google".
في قائمة واجهات برمجة التطبيقات والخدمات، اختَر بيانات الاعتماد.
في القائمة في أعلى الشاشة، انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
إذا لم يتضمّن المشروع شاشة طلب موافقة تم ضبطها، انقر على ضبط شاشة طلب الموافقة واتّبِع التعليمات الظاهرة على الشاشة.
في قسم المقاييس، انقر على إنشاء عميل OAuth.
في شاشة إنشاء معرِّف عميل OAuth، اختَر نوع التطبيق وأدخِل اسمًا لمعرِّف العميل.
حدِّد التفاصيل الإضافية ذات الصلة بنوع تطبيقك. على سبيل المثال، إذا كنت تنشئ تطبيق ويب، أضِف معرّفات الموارد المنتظمة (URI) المصرَّح بها لطلبات المتصفّح والخادم.
بعد إنشاء العميل، احفظ معرّف العميل وسرّه.
عند ضبط إعدادات مضيف 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.

بعد تثبيت 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
```
إذا تم ضبط الإعدادات بنجاح، من المفترض أن تظهر لك رسالة تأكيد بأنّه تمت إضافة الخادم إلى إعدادات المستخدم.

للتحقّق من أنّ الخادم يعمل بشكل صحيح، شغِّل الأمر /mcp list:

> /mcp list

Configured MCP servers:

maps-experience-agent-tools-mcp - Ready (5 tools)
Tools:
-   compute_routes
-   lookup_weather
-   resolve_maps_urls
-   resolve_names
-   search_places

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

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

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

Python

يمكنك العثور على عملية تنفيذ كاملة لهذا المثال على GitHub في مستودع adk-samples.

الخطوة 1: تحديد وكيلك باستخدام أدوات وكيل "`McpToolset`" في "التجارب من خرائط Google"

عدِّل ملف agent.py. استبدِل YOUR_GOOGLE_MAPS_API_KEY بمفتاح واجهة برمجة التطبيقات الفعلي.

# ./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"
                }
            )
        )
    ]
)

الخطوة 2: التأكّد من توفّر `init.py`

تأكَّد من توفّر __init__.py في الدليل نفسه الذي يتضمّن agent.py:

from . import agent

الخطوة 3: تشغيل `adk web` والتفاعل معه

ضبط متغيّر البيئة:
اضبط مفتاح Google Maps API كمتغيّر بيئة في وحدة التحكّم:
```
export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
        
```
تشغيل adk web:
نفِّذ الأمر التالي لبدء واجهة الويب الخاصة بـ ADK:
```
adk web
        
```
التفاعل في واجهة المستخدم:
- اختَر "travel_planner_agent".
- جرِّب طلبات مثل:
  - "سأكون في دبي غدًا. ما حالة الطقس؟"
  - "أريد العثور على مقاهٍ بالقرب من حديقة الشلالات".
  - "أريد الحصول على الاتجاهات من GooglePlex إلى مطار سان فرانسيسكو الدولي".

جافا

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

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();
        }
    }
}

TypeScript

حدِّد وكيلاً لإعداد MCPToolset في TypeScript:

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: "SseConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            headers: {
                "X-Goog-Api-Key": googleMapsApiKey,
                "Content-Type": "application/json",
                "Accept": "application/json, text/event-stream"
            }
        })
    ],
});

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

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