يتيح رمز العرض المرئي للبيانات المستند إلى الذكاء الاصطناعي الوكيل لتطبيقك المستند إلى الذكاء الاصطناعي الوكيل عرض عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن للأماكن في ردّ أدوات تجربة الخرائط للوكلاء (المعروفة سابقًا باسم Maps Grounding Lite) بدون أي تكلفة إضافية. يؤدي كل طلب ناجح إلى
أداة search_places أو search_along_route إلى عرض رمز مميّز يحدّد
الأماكن في الردّ، لكل من رمزَي التخزين التعريفي Essentials وPro. عندما يضيف تطبيق العميل الرمز المميّز إلى Maps JavaScript API أو Places SDK for Android أو Places SDK for iOS، لا تتم فوترة طلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن لهذه الأماكن لمدة 10 دقائق بعد إصدار الرمز المميّز.
آلية العمل
يربط الرمز المميّز الردّ المستند إلى المصدر بتفاصيل المكان التي تعرضها معه:
- يستدعي الوكيل أداة
search_placesأوsearch_along_routeعلى خادم MCP الخاص بأدوات تجربة الخرائط للوكلاء. يتضمّن ردّ الأداة الأماكن التي تدعم الملخّص ورمزًا مميزًا في الحقلcontentToken. - يقرأ تطبيقك الرمز المميّز من استجابة الأداة ويرسله إلى تطبيق العميل، بالإضافة إلى أرقام تعريف الأماكن التي تريد عرضها.
- يضيف تطبيق العميل الرمز المميّز إلى Maps JavaScript API أو يمرّره في كل طلب من مكوّنات الأجهزة الجوّالة، وينشئ عناصر في حزمة أدوات "خرائط Google" الجاهزة للأماكن لهذه الأماكن.
- تتحقّق "منصة خرائط Google" من صحة الرمز المميّز مع كل طلب من حزمة أدوات "خرائط Google" الجاهزة للأماكن. إذا كان الرمز المميّز صالحًا، لن تتم فوترة الطلب.
عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن المتاحة
Maps JavaScript API
ينطبق الرمز المميّز على عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن التالية في Maps JavaScript API:
حزمة تطوير برامج الأماكن لأجهزة Android
حزمة تطوير برامج الأماكن لأجهزة iOS
لا ينطبق الرمز المميّز على الطلبات الأخرى، مثل الطلبات من عناصر "البحث عن الأماكن" و"البحث المتقدّم عن الأماكن" و"الإكمال التلقائي الأساسي للأماكن" وطلبات Places API وعمليات تحميل الخرائط. ويتم تحصيل رسوم هذه الطلبات وفقًا للأسعار العادية.
تتضمّن ردود أدوات التجارب من "خرائط Google" للوكلاء فقط الرمز المميّز. إذا عرضت أماكن من ردّ "استخدام خرائط Google كمصدر" باستخدام حزمة أدوات "خرائط Google" الجاهزة للأماكن، تتم فوترة هذه الطلبات بالأسعار العادية.
قبل البدء
قبل استخدام الرمز المميّز لتصوّر البيانات المستند إلى الذكاء الاصطناعي الوكيل، عليك إعداد ما يلي:
- مشروع على Google Cloud تم فيه تفعيل واجهة برمجة التطبيقات لأدوات وكيل "التجارب من خرائط Google"
(
mapstools.googleapis.com) وواجهة برمجة التطبيقات لحزمة أدوات "خرائط Google" الجاهزة للأماكن لمزيد من المعلومات، يُرجى الاطّلاع على ضبط النماذج اللغوية الكبيرة لاستخدام خادم MCP وبدء استخدام حزمة أدوات "خرائط Google" الجاهزة للأماكن في JavaScript أو Android أو iOS. - بيانات الاعتماد من هذا المشروع لكل من طلبات "أدوات تجربة الخرائط للوكلاء" وMaps JavaScript API أو Places SDK لأجهزة Android أو Places SDK لأجهزة iOS لا يكون الرمز المميّز صالحًا إلا لطلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن من المشروع الذي تم إصدار الرمز المميّز له.
- تطبيق عميل يحمّل Maps JavaScript API من القناة التجريبية من خلال ضبط
v=beta. بالنسبة إلى الأجهزة الجوّالة، استخدِم حزمة تطوير البرامج (SDK) للأماكن لنظام التشغيل Android، الإصدار 6.1.0 أو إصدار أحدث، أو حزمة تطوير البرامج (SDK) للأماكن في Swift (GooglePlacesSwift)، الإصدار 11.4.0.
عرض الأماكن من ردّ مستند إلى المصادر
توضّح الأقسام التالية كيفية الحصول على الرمز المميّز من استجابة الأداة واستخدامه في تطبيق العميل. إذا كنت تستخدم أدوات واجهة المستخدم الموجهة للوكلاء الذكيين في "خرائط Google" (ميزة تجريبية)، سيتولّى وكيلها وعميل الويب تنفيذ هذه الخطوات نيابةً عنك.
الحصول على الرمز المميّز من ردّ الأداة
تعرض الأداتان search_places وsearch_along_route الرمز المميّز في الحقل contentToken. في نتيجة طلب tools/call من MCP، يكون هذا الحقل
بتنسيق structuredContent. في الردّ من طريقة REST searchText أو searchAlongRoute، يكون هذا الحقل من المستوى الأعلى. يشبه الردّ بتنسيق search_places
ما يلي (يؤدي الردّ بتنسيق search_along_route إلى عرض كل مكان داخل
results[].place):
{ "places": [ { "place": "places/PLACE_ID", "id": "PLACE_ID" } ], "contentToken": "CONTENT_TOKEN" }
يتضمّن هذا الناتج القيم التالية:
-
PLACE_ID: رقم تعريف مكان في الردّ -
CONTENT_TOKEN: الرمز المميّز للعرض المرئي للبيانات المستند إلى الوكيل للأماكن في الردّ يجب التعامل مع الرمز المميّز كسلسلة مبهمة وعدم تعديله.
إذا لم يتضمّن الردّ أي أماكن، لن يتضمّن الردّ رمزًا مميزًا.
في رمز تطبيقك، اقرأ الرمز المميّز من استجابة الأداة، على سبيل المثال، في دالة ردّ نداء الأداة في إطار عمل الوكيل، وأرسِله إلى تطبيق العميل مع أرقام تعريف الأماكن. لا تعتمد على نموذج لغوي كبير لتكرار الرمز المميّز في ناتجه، لأنّ النموذج قد يغيّر الرمز المميّز.
يغطي الرمز المميّز الأماكن في الردّ الخاص به فقط. إذا اتصل وكيلك بـ search_places أو search_along_route أكثر من مرة، أرسِل كل رمز مميّز إلى تطبيق العميل.
على سبيل المثال، إذا كنت تستخدم Agent Development Kit (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.
إضافة الرمز المميّز وعرض الأماكن
Maps JavaScript API
في تطبيق العميل، مرِّر سلسلة قابلة للتكرار (مثل مصفوفة) من سلاسل الرموز المميّزة غير الفارغة إلى Settings.getInstance().addContentTokens() قبل إنشاء عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن. تعرض الطريقة خطأً إذا تم تمرير سلسلة واحدة مباشرةً أو إذا كانت السلسلة القابلة للتكرار تتضمّن سلسلة فارغة. يضيف المثال التالي رمزًا مميزًا، ثم يعرض عنصر "تفاصيل المكان" (المصغّر) لكل مكان:
// The token and place IDs come from the search_places or search_along_route 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 في
عنصر قائمة الأماكن المتقدّمة
على أرقام تعريف الأماكن من ردّ واحد أو أكثر أضفت الرموز المميّزة الخاصة بها.
حزمة تطوير برامج الأماكن لأجهزة Android
مرِّر contentTokens: Set<String> مباشرةً في كل طلب بحث عن مكوّن.
تنتهي صلاحية الرموز المميَّزة بعد 10 دقائق من إصدارها. لا تخزّن حزمة SDK الرموز المميّزة عبر الطلبات أو تتبُّع انتهاء الصلاحية.
Jetpack Compose (AdvancedPlaceDetails،
AdvancedPlaceDetailsCompact، PlaceMarker):
val placeRef = PlaceReference.PlaceId(
placeId = placeId,
contentTokens = setOf(contentToken),
)
// Or with a resource name:
// PlaceReference.ResourceName(resourceName = resourceName, contentTokens = setOf(contentToken))
الأجزاء (PlaceDetailsFragment وPlaceDetailsCompactFragment
وAdvancedPlaceDetailsFragment وAdvancedPlaceDetailsCompactFragment):
fragment.loadWithPlaceId(placeId, setOf(contentToken))
// Or: fragment.loadWithResourceName(resourceName, setOf(contentToken))
جزء قائمة الأماكن (AdvancedPlaceListFragment):
advancedPlaceListFragment.configureFromPlaceIds(placeIds, setOf(contentToken))
// Or: advancedPlaceListFragment.configureFromResourceNames(resourceNames, setOf(contentToken))
حزمة تطوير برامج الأماكن لأجهزة iOS
توفّر حزمة SDK حالات تعداد PlaceIdentifier مخصّصة (.placeIDWithTokens أو .resourceNameWithTokens) يتم تمريرها إلى أدوات الإعداد الحالية PlaceDetailsQuery(identifier:) وPlaceMarker(identifier:...).
تنتهي صلاحية الرموز المميَّزة بعد 10 دقائق من إصدارها. لا تخزّن حزمة SDK الرموز المميّزة عبر الطلبات أو تتبُّع انتهاء الصلاحية.
// Place Details and Advanced Place Details (full and compact):
@State var query = PlaceDetailsQuery(
identifier: .placeIDWithTokens(placeId, contentTokens: [contentToken])
)
// Or: .resourceNameWithTokens(resourceName, contentTokens: [contentToken])
// Advanced Place List:
@State var queries = [
PlaceDetailsQuery(
identifier: .placeIDWithTokens(placeId, contentTokens: [contentToken])
)
]
// Place Marker:
PlaceMarker(
identifier: .placeIDWithTokens(placeId, contentTokens: [contentToken]),
markerIcon: .type,
markerText: .rating
)
التحقّق من صحة الرمز المميّز
لا تتم فوترة طلب حزمة أدوات "خرائط Google" الجاهزة للأماكن عند استيفاء جميع الشروط التالية:
- المشروع نفسه: تم إصدار الرموز المميّزة لمشروع Google Cloud الذي يملك مفتاح واجهة برمجة التطبيقات المستخدَم لتحميل Maps JavaScript API أو Places SDK for Android أو Places SDK for iOS.
- الأماكن المحدّدة: كل مكان يطلبه العنصر تتم تغطيته برمز مميّز واحد على الأقل مضمّن في الطلب. يمكن أن يتضمّن العنصر أماكن من ردود متعددة إذا أضفت الرمز المميّز من كل رد.
- الرموز المميّزة غير منتهية الصلاحية: يتم تقديم الطلب لكل مكان في غضون 10 دقائق من وقت إصدار الرمز المميّز الذي يغطي المكان.
- العنصر المتوافق: يأتي الطلب من عنصر أو مكوّن متوافق في حزمة أدوات "خرائط Google" الجاهزة للأماكن.
لا يشمل ذلك العناصر التي تضبطها باستخدام موقع جغرافي بدلاً من مكان، مثل PlaceDetailsLocationRequestElement. إذا كان عنصر "قائمة الأماكن المتقدّمة" يتضمّن أي مكان غير مشمول، تتم فوترة الطلب بالكامل.
إذا لم يتم استيفاء أي شرط، سيتم تحميل العنصر، وستتم فوترة الطلب بالسعر العادي لرمز التخزين التعريفي الخاص به. لا تعرض واجهة برمجة التطبيقات Maps JavaScript API وحزمة تطوير البرامج بالاستناد إلى بيانات "الأماكن" لأجهزة Android وحزمة تطوير البرامج بالاستناد إلى بيانات "الأماكن" لأجهزة iOS أي خطأ عندما يكون الرمز المميّز غير صالح.
الحدود (حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لأجهزة Android وiOS فقط)
- هناك حدّ أقصى يبلغ 100 رمز مميّز فريد لكل طلب. ويتم اقتطاع الرموز الزائدة مع تسجيل تحذير.
- الحد الأقصى هو 2,048 بايت UTF-8 لكل رمز مميّز. يتم تجاهل الرموز المميزة الكبيرة الحجم مع تسجيل تحذير، ويتم تجاهل الرموز الفارغة أو المكررة.
- لا تقبل طلبات البحث عن الإحداثيات (
PlaceReference.CoordinatesوPlaceIdentifier.coordinate) الرموز المميّزة. - على نظام التشغيل iOS
AdvancedPlaceListView، إذا كان أي طلب بحث في القائمة لا يتضمّن رقم تعريف مكان أو اسم مورد غير فارغ، لن يتم إرسال أي رموز مميّزة للقائمة.
الفوترة
يتم الدفع مقابل كل طلب من "أدوات تجربة الخرائط للوكلاء" بالسعر العادي. لا تتم فوترة طلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن التي تجتاز التحقّق من الرمز المميّز، ولكنّها تُحتسب ضمن حصة حزمة أدوات "خرائط Google" الجاهزة للأماكن. يتم تحصيل رسوم من طلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن التي لا تجتاز عملية التحقّق من الرمز المميّز، أو الطلبات التي تتضمّن رموزًا مميّزة غير صالحة أو منتهية الصلاحية، وذلك بالسعر العادي لرمز التخزين التعريفي طلب حزمة أدوات "خرائط Google" الجاهزة للأماكن أو حزمة أدوات "خرائط Google" الجاهزة للأماكن Pro (متقدّمة).
للاطّلاع على الأسعار، يُرجى مراجعة جدول الأسعار الرئيسي وجدول الأسعار في الهند.
متطلبات الاستخدام
الاستخدام مخصّص لمستخدم واحد واستجابة نشطة فقط: يجب استخدام رمز مميّز لتصوّر البيانات المستندة إلى الوكيل فقط لعرض عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن المتوافقة للمستخدم النهائي نفسه وضمن الاستجابة الفورية المستندة إلى الوكيل التي أنشأت الرمز المميّز. يجب عدم مشاركة الرموز المميّزة أو تجميعها أو إعادة استخدامها على مستوى عدة مستخدمين نهائيين، أو استخدام رمز مميّز لعرض الأماكن خارج هذا الردّ (مثل القوائم المحفوظة أو الإشارات المرجعية أو الأدلة المخزّنة مؤقتًا).
يخضع استخدامك لرمز تصوّر البيانات المستند إلى الوكيل لبنود خدمة "منصة خرائط Google"، بما في ذلك البنود الخاصة بالخدمة. تنطبق أيضًا متطلبات الإسناد لأدوات تجربة الخرائط للوكلاء.