رمز مميّز لعرض البيانات مرئيًا باستخدام الذكاء الاصطناعي الوكيل

يتيح رمز العرض المرئي للبيانات المستند إلى الذكاء الاصطناعي الوكيل لتطبيقك المستند إلى الذكاء الاصطناعي الوكيل عرض عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن للأماكن في ردّ أدوات الوكيل في "تجارب من خرائط Google" (المعروفة سابقًا باسم Maps Grounding Lite) بدون أي تكلفة إضافية. يؤدي كل طلب ناجح إلى أداة search_places أو search_along_route إلى عرض رمز مميّز يحدّد الأماكن في الردّ، لكل من رمزَي التخزين التعريفي Essentials وPro. عندما يضيف تطبيق العميل الرمز المميّز إلى Maps JavaScript API، لا تتم فوترة طلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن لهذه الأماكن لمدة 10 دقائق بعد إصدار الرمز المميّز.

آلية العمل

يربط الرمز المميّز الردّ المستند إلى المصدر بتفاصيل المكان التي تعرضها معه:

1. يستدعي الوكيل أداة search_places أو search_along_route على خادم MCP لأدوات وكيل "التجارب من خرائط Google". يتضمّن ردّ الأداة الأماكن التي تدعم الملخّص ورمزًا مميزًا في الحقل contentToken.
2. يقرأ تطبيقك الرمز المميّز من استجابة الأداة ويرسله إلى تطبيق العميل، بالإضافة إلى أرقام تعريف الأماكن التي تريد عرضها.
3. يضيف تطبيق العميل الرمز المميّز إلى Maps JavaScript API وينشئ عناصر "حزمة أدوات واجهة المستخدم للأماكن" لتلك الأماكن.
4. تتحقّق "منصة خرائط Google" من صحة الرمز المميّز مع كل طلب من حزمة أدوات "خرائط Google" الجاهزة للأماكن. إذا كان الرمز المميّز صالحًا، لن تتم فوترة الطلب.

عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن المتاحة

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

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

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

قبل البدء

قبل استخدام الرمز المميّز لتصوّر البيانات المستند إلى الذكاء الاصطناعي الوكيل، عليك إعداد ما يلي:

• مشروع على Google Cloud تم فيه تفعيل واجهة برمجة التطبيقات لأدوات وكيل "التجارب من خرائط Google" (mapstools.googleapis.com) وواجهة برمجة التطبيقات لحزمة أدوات "خرائط Google" الجاهزة للأماكن لمزيد من المعلومات، يُرجى الاطّلاع على ضبط النماذج اللغوية الكبيرة لاستخدام خادم MCP وبدء استخدام حزمة أدوات "خرائط Google" الجاهزة للأماكن.
• بيانات الاعتماد من هذا المشروع لكل من طلبات أدوات التجارب من خرائط Google للوكلاء وMaps JavaScript API لا يكون الرمز المميّز صالحًا إلا لطلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن من المشروع الذي تم إصدار الرمز المميّز له.
• تطبيق عميل يحمّل Maps JavaScript API من القناة التجريبية من خلال ضبط v=beta.

عرض الأماكن من ردّ مستند إلى المصادر

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

إضافة الرمز المميّز وعرض الأماكن

في تطبيق العميل، مرِّر سلسلة قابلة للتكرار (مثل مصفوفة) من سلاسل الرموز المميّزة غير الفارغة إلى 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 في عنصر قائمة الأماكن المتقدّمة على أرقام تعريف الأماكن من ردّ واحد أو أكثر أضفت الرموز المميّزة الخاصة بها.

التحقّق من صحة الرمز المميّز

لا تتم فوترة طلب حزمة أدوات "خرائط Google" الجاهزة للأماكن عند استيفاء جميع الشروط التالية:

• المشروع نفسه: تم إصدار الرموز المميّزة لمشروع Google Cloud الذي يملك مفتاح واجهة برمجة التطبيقات الذي تستخدمه لتحميل Maps JavaScript API.
• الأماكن المرتكزة: تتم تغطية كل مكان يطلبه العنصر برمز مميّز واحد على الأقل أضفته. يمكن أن يتضمّن العنصر أماكن من ردود متعددة إذا أضفت الرمز المميّز من كل ردّ.
• الرموز المميّزة غير منتهية الصلاحية: يتم تقديم الطلب لكل مكان في غضون 10 دقائق من وقت إصدار الرمز المميّز الذي يغطي المكان.
• العنصر المتوافق: يأتي الطلب من عنصر متوافق في حزمة أدوات "خرائط Google" الجاهزة للأماكن.

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

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

الفوترة

يتم الدفع مقابل كل طلب لأدوات التجارب من "خرائط Google" بالسعر العادي. لا تتم فوترة طلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن التي تجتاز التحقّق من الرمز المميّز، ولكنّها تُحتسب ضمن حصة حزمة أدوات "خرائط Google" الجاهزة للأماكن. يتم تحصيل رسوم طلبات حزمة أدوات "خرائط Google" الجاهزة للأماكن التي لا تجتاز عملية التحقّق من الرمز المميّز وفقًا للسعر العادي لوحدة تخزين رمز المنتج (SKU) طلب حزمة أدوات "خرائط Google" الجاهزة للأماكن أو حزمة أدوات "خرائط Google" الجاهزة للأماكن Pro (متقدّمة).

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

متطلبات الاستخدام

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

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