يتيح رمز العرض المرئي للبيانات المستند إلى الذكاء الاصطناعي الوكيل لتطبيقك المستند إلى الذكاء الاصطناعي الوكيل عرض عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن للأماكن في ردّ أدوات الوكيل في "التجارب من خرائط Google" (المعروفة سابقًا باسم Maps Grounding Lite) بدون أي تكلفة إضافية. كل طلب ناجح إلى أداة search_places يعرض رمزًا مميزًا يحدّد الأماكن في الردّ، لكل من Essentials وPro. عندما يضيف تطبيق العميل الرمز المميّز إلى Maps JavaScript API، لا تتم فوترة طلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن لهذه الأماكن لمدة 10 دقائق بعد إصدار الرمز المميّز.
آلية العمل
يربط الرمز المميّز الردّ المستند إلى المصدر بتفاصيل المكان التي تعرضها معه:
- يستدعي الوكيل أداة
search_placesعلى خادم MCP الخاص بأدوات وكيل "تجربة خرائط Google". يتضمّن ردّ الأداة الأماكن التي تدعم الملخّص ورمزًا مميزًا في الحقلcontentToken. - يقرأ تطبيقك الرمز المميّز من استجابة الأداة ويرسله إلى تطبيق العميل، بالإضافة إلى أرقام تعريف الأماكن التي تريد عرضها.
- يضيف تطبيق العميل الرمز المميّز إلى Maps JavaScript API وينشئ عناصر حزمة أدوات واجهة المستخدم في "الأماكن" لتلك الأماكن.
- تتحقّق "منصة خرائط Google" من صحة الرمز المميّز مع كل طلب من حزمة أدوات "خرائط Google" الجاهزة للأماكن. إذا كان الرمز المميّز صالحًا، لن تتم فوترة الطلب.
عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن المتاحة
ينطبق الرمز المميّز على عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن التالية في Maps JavaScript API:
لا ينطبق الرمز المميّز على الطلبات الأخرى، مثل الطلبات الواردة من عناصر "البحث عن الأماكن" و"البحث المتقدّم عن الأماكن" و"الإكمال التلقائي الأساسي للأماكن" وطلبات Places API وعمليات تحميل الخرائط. ويتم تحصيل رسوم هذه الطلبات وفقًا للأسعار العادية.
تتضمّن ردود أدوات وكيل "التجارب من خرائط Google" فقط الرمز المميّز. إذا عرضت أماكن من ردّ "استخدام خرائط Google كمصدر" باستخدام حزمة أدوات "خرائط Google" الجاهزة للأماكن، تتم فوترة هذه الطلبات بالأسعار العادية.
قبل البدء
قبل استخدام رمز تصوّر البيانات المستند إلى الذكاء الاصطناعي الوكيل، عليك إعداد ما يلي:
- مشروع على Google Cloud تم فيه تفعيل واجهة برمجة التطبيقات Maps Experience agent tools API
(
mapstools.googleapis.com) وواجهة برمجة التطبيقات Places UI Kit API لمزيد من المعلومات، يُرجى الاطّلاع على ضبط النماذج اللغوية الكبيرة لاستخدام خادم MCP وبدء استخدام حزمة أدوات "خرائط Google" الجاهزة للأماكن. - Credentials from that project for both your Maps Experience agent tools calls and the Maps JavaScript API. لا يكون الرمز المميّز صالحًا إلا لطلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن من المشروع الذي تم إصدار الرمز المميّز له.
- تطبيق عميل يحمّل Maps JavaScript API من
القناة التجريبية من خلال
ضبط
v=beta.
عرض الأماكن من ردّ مستند إلى المصادر
توضّح الأقسام التالية كيفية الحصول على الرمز المميّز من استجابة الأداة واستخدامه في تطبيق العميل. إذا كنت تستخدم أدوات واجهة المستخدم الموجهة للوكلاء الذكيين في "خرائط Google" (ميزة تجريبية)، سيتولّى وكيلها وعميل الويب تنفيذ هذه الخطوات نيابةً عنك.
الحصول على الرمز المميّز من ردّ الأداة
تعرض أداة search_places الرمز المميّز في الحقل contentToken. في نتيجة طلب MCP tools/call، يكون هذا الحقل في structuredContent. تكون استجابة الأداة مشابهة لما يلي:
{ "places": [ { "place": "places/PLACE_ID", "id": "PLACE_ID", ... } ], ... "contentToken": "CONTENT_TOKEN" }
يتضمّن هذا الناتج القيم التالية:
-
PLACE_ID: رقم تعريف مكان في الردّ -
CONTENT_TOKEN: الرمز المميّز للعرض المرئي للبيانات المستند إلى الوكلاء للأماكن في الردّ يجب التعامل مع الرمز المميّز كسلسلة مبهمة وعدم تعديله.
إذا لم يتضمّن الردّ أي أماكن، لن يتضمّن الردّ رمزًا مميزًا.
في رمز تطبيقك، اقرأ الرمز المميّز من استجابة الأداة، على سبيل المثال، في استدعاء الأداة في إطار عمل الوكيل، وأرسِله إلى تطبيق العميل مع أرقام تعريف الأماكن. لا تعتمد على نموذج لغوي كبير لتكرار الرمز المميّز في ناتجه، لأنّ النموذج قد يغيّر الرمز المميّز.
يغطي الرمز المميّز الأماكن في الردّ الخاص به فقط. إذا استدعى الوكيل أداة search_places أكثر من مرة، أرسِل كل رمز مميّز إلى تطبيق العميل.
على سبيل المثال، إذا كنت تستخدم مجموعة تطوير الوكلاء (ADK) للغة Python، يمكنك حفظ كل رمز مميّز في دالة ردّ نداء بعد استخدام الأداة:
from typing import Any, Optional
from google.adk.tools.base_tool import BaseTool
from google.adk.tools.tool_context import ToolContext
def save_content_token(
tool: BaseTool,
args: dict[str, Any],
tool_context: ToolContext,
tool_response: dict[str, Any],
) -> Optional[dict[str, Any]]:
"""Saves the agentic data visualization token from a Maps tool response."""
structured_content = tool_response.get("structuredContent") or {}
token = structured_content.get("contentToken")
if token:
tokens = tool_context.state.get("content_tokens", [])
tool_context.state["content_tokens"] = tokens + [token]
# Return None to pass the original tool response to the model.
return None
مرِّر هذه الدالة كوسيطة after_tool_callback عند إنشاء الوكيل، ثم أرسِل الرموز المحفوظة إلى تطبيق العميل مع ردّ الوكيل. للاطّلاع على تعريفات الوكلاء الكاملة، يُرجى مراجعة أمثلة ADK في
ضبط النماذج اللغوية الكبيرة لاستخدام خادم MCP.
إضافة الرمز المميز وعرض الأماكن
في تطبيق العميل، مرِّر مصفوفة من سلاسل الرموز المميّزة غير الفارغة إلى Settings.getInstance().addContentTokens() قبل إنشاء عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن. تُظهر الطريقة خطأً إذا مررت سلسلة واحدة
مباشرة أو إذا كان التكرار يتضمن سلسلة فارغة. يضيف المثال التالي رمزًا مميزًا، ثم يعرض عنصر "تفاصيل المكان" (المصغّر) لكل مكان:
// The token and place IDs come from the search_places tool response.
async function displayGroundedPlaces(contentToken, placeIds) {
const {Settings} = await google.maps.importLibrary('core');
const {
PlaceDetailsCompactElement,
PlaceDetailsPlaceRequestElement,
PlaceStandardContentElement,
} = await google.maps.importLibrary('places');
// Add the token before you create Places UI Kit elements.
Settings.getInstance().addContentTokens([contentToken]);
const container = document.getElementById('agent-response');
for (const placeId of placeIds) {
const placeDetails = new PlaceDetailsCompactElement();
placeDetails.append(
new PlaceDetailsPlaceRequestElement({place: placeId}),
new PlaceStandardContentElement(),
);
container.append(placeDetails);
}
}
تنتهي صلاحية الرموز المميَّزة بعد 10 دقائق من إصدارها. تحتفظ Maps JavaScript API بالرموز المميّزة التي تضيفها في الذاكرة للصفحة الحالية وتزيلها تلقائيًا بعد انتهاء صلاحيتها، لذا لا تحتاج إلى إزالة الرموز المميّزة المنتهية الصلاحية بنفسك. إذا أضفت رموزًا مميّزة من أكثر من ردّ واحد، ترسل واجهة برمجة التطبيقات جميع الرموز المميّزة المخزّنة مع كل طلب من عنصر متوافق.
لعرض أماكن متعددة في عنصر واحد، اضبط السمة places في
عنصر قائمة الأماكن المتقدّمة
على أرقام تعريف الأماكن من ردّ واحد أو أكثر أضفت الرموز المميّزة الخاصة بها.
التحقّق من الرمز المميّز
لا تتم فوترة طلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن عند استيفاء جميع الشروط التالية:
- المشروع نفسه: تم إصدار الرموز المميّزة لمشروع Google Cloud الذي يملك مفتاح واجهة برمجة التطبيقات الذي تستخدمه لتحميل Maps JavaScript API.
- الأماكن المرتكزة: كل مكان يطلبه العنصر تتم تغطيته برمز مميّز واحد على الأقل أضفته. يمكن أن يتضمّن العنصر أماكن من ردود متعددة إذا أضفت الرمز المميّز من كل ردّ.
- الرموز المميّزة غير منتهية الصلاحية: يتم تقديم الطلب لكل مكان في غضون 10 دقائق من وقت إصدار الرمز المميّز الذي يغطي المكان.
- العنصر المتوافق: يأتي الطلب من عنصر متوافق في حزمة أدوات "خرائط Google" الجاهزة للأماكن.
ولا تشمل المقالة العناصر التي تضبطها باستخدام موقع جغرافي بدلاً من مكان، مثل PlaceDetailsLocationRequestElement. إذا كان عنصر "قائمة الأماكن المتقدّمة" يتضمّن أي مكان غير مشمول، تتم فوترة الطلب بالكامل.
في حال عدم استيفاء أي شرط، سيستمر تحميل العنصر، وستتم فوترة الطلب بالسعر العادي لرمز التخزين التعريفي الخاص به. لا تعرض Maps JavaScript API رسالة خطأ عندما يكون الرمز المميّز غير صالح.
الفوترة
يتم تحصيل رسوم منك مقابل كل طلب لأدوات وكيل "التجارب من خرائط Google" بالسعر العادي. لا تتم فوترة طلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن التي تجتاز التحقّق من الرمز المميّز، ولكنّها تُحتسب ضمن حصة حزمة أدوات "خرائط Google" الجاهزة للأماكن. يتم تحصيل رسوم مقابل طلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن التي لا تجتاز عملية التحقّق من الرمز المميّز وفقًا للسعر العادي لوحدة تخزين رمزية (SKU) لـ طلب حزمة أدوات "خرائط Google" الجاهزة للأماكن أو Places UI Kit Pro (Advanced).
للاطّلاع على الأسعار، يُرجى مراجعة جدول الأسعار الرئيسي وجدول الأسعار في الهند.
متطلبات الاستخدام
الاستخدام من قِبل مستخدم واحد فقط في الردّ النشط: يجب استخدام رمز مميّز لعرض البيانات بشكل مرئي من خلال وكيل فقط لعرض عناصر "حزمة أدوات خرائط Google الجاهزة للأماكن" المتوافقة للمستخدم النهائي نفسه وضمن الردّ الفوري من الوكيل الذي أنشأ الرمز المميّز. يجب عدم مشاركة الرموز المميّزة أو تجميعها أو إعادة استخدامها على مستوى عدة مستخدمين نهائيين، أو استخدام رمز مميّز لعرض الأماكن خارج هذا الردّ (مثل القوائم المحفوظة أو الإشارات المرجعية أو الأدلة المخزّنة مؤقتًا).
يخضع استخدامك لرمز تصوّر البيانات المستند إلى الذكاء الاصطناعي الوكيل لبنود خدمة "منصة خرائط Google"، بما في ذلك البنود الخاصة بالخدمة. تنطبق أيضًا متطلبات الإسناد لأدوات وكيل "تجربة خرائط Google".