טוקן להמחשה חזותית של נתונים באמצעות סוכן AI

האסימון להצגה חזותית של נתונים אג'נטיים מאפשר לאפליקציה האג'נטית להציג רכיבים של Places UI Kit בשביל המקומות בתשובה של כלים אג'נטיים בממשק Maps (לשעבר Maps Grounding Lite) ללא עלות נוספת. כל קריאה מוצלחת לכלי search_places או search_along_route מחזירה אסימון שמזהה את המקומות בתשובה, גם למק"טים של Essentials וגם למק"טים של Pro. כשאפליקציית הלקוח מוסיפה את הטוקן ל-Maps JavaScript API, ל-Places SDK ל-Android או ל-Places SDK ל-iOS, לא מתבצע חיוב על בקשות של Places UI Kit למקומות האלה במשך 10 דקות אחרי הנפקת הטוקן.

איך זה עובד

הטוקן מקשר בין התשובה המעוגנת בנתונים לבין Place Details שמוצגים איתה:

  1. הסוכן מפעיל את הכלי search_places או search_along_route בשרת ה-MCP של "כלים אג'נטיים בממשק מפות Google". התשובה של הכלי כוללת את המקומות שתומכים בסיכום ואסימון בשדה contentToken.
  2. האפליקציה קוראת את האסימון מהתגובה של הכלי ושולחת אותו לאפליקציית הלקוח, יחד עם המזהים של המקומות שרוצים להציג.
  3. אפליקציית הלקוח מוסיפה את האסימון ל-Maps JavaScript API או מעבירה אותו בכל בקשה של רכיב לנייד, ויוצרת רכיבים של Places UI Kit בשביל המקומות האלה.
  4. Google Maps Platform מאמתת את האסימון בכל בקשה של Places UI Kit. אם האסימון תקין, הבקשה לא תחויב.

רכיבים נתמכים ב-Places UI Kit

Maps JavaScript API

האסימון חל על הרכיבים הבאים של Places UI Kit ב-Maps JavaScript API:

רכיב מק"ט
PlaceDetailsElement שאילתה ב-Places UI Kit
PlaceDetailsCompactElement שאילתה ב-Places UI Kit
AdvancedPlaceDetailsElement ‫Places UI Kit Pro (מתקדם)
AdvancedPlaceDetailsCompactElement ‫Places UI Kit Pro (מתקדם)
AdvancedPlaceListElement ‫Places UI Kit Pro (מתקדם)

Places SDK ל-Android

פונקציה קומפוזבילית או מקטע מק"ט
PlaceDetailsFragment שאילתה ב-Places UI Kit
PlaceDetailsCompactFragment שאילתה ב-Places UI Kit
AdvancedPlaceDetailsFragment ‫Places UI Kit Pro (מתקדם)
AdvancedPlaceDetailsCompactFragment ‫Places UI Kit Pro (מתקדם)
AdvancedPlaceListFragment ‫Places UI Kit Pro (מתקדם)
AdvancedPlaceDetails ‫Places UI Kit Pro (מתקדם)
AdvancedPlaceDetailsCompact ‫Places UI Kit Pro (מתקדם)
PlaceMarker ‫Places UI Kit Pro (מתקדם)

SDK של מקומות ל-iOS

Struct מק"ט
PlaceDetailsView שאילתה ב-Places UI Kit
PlaceDetailsCompactView שאילתה ב-Places UI Kit
AdvancedPlaceDetailsView ‫Places UI Kit Pro (מתקדם)
AdvancedPlaceDetailsCompactView ‫Places UI Kit Pro (מתקדם)
AdvancedPlaceListView ‫Places UI Kit Pro (מתקדם)
PlaceMarker ‫Places UI Kit Pro (מתקדם)

האסימון לא חל על בקשות אחרות, כמו בקשות מהרכיבים "חיפוש מקומות", "חיפוש מקומות מתקדם" ו"השלמה אוטומטית בסיסית למקומות", בקשות ל-Places API וטעינות של מפות. הבקשות האלה מחויבות בתעריפים רגילים.

רק התשובות של הכלים האג'נטיים ב-Maps Experiments כוללות את הטוקן. אם אתם מציגים מקומות מתשובה של "עיגון בעזרת מפות Google" באמצעות Places UI Kit, הבקשות האלה מחויבות בתעריפים רגילים.

לפני שמתחילים

לפני שמשתמשים בטוקן של Agentic Data Visualization, צריך להגדיר את הדברים הבאים:

  • פרויקט בענן של Google Cloud שבו מופעלים Maps Experience agent tools API‏ (mapstools.googleapis.com) ו-Places UI Kit API. מידע נוסף זמין במאמרים הגדרת מודלים גדולים של שפה (LLM) לשימוש בשרת MCP ותחילת השימוש ב-Places UI Kit ל-JavaScript, ל-Android או ל-iOS.
  • פרטי כניסה מהפרויקט הזה גם לקריאות לכלים האג'נטיים בממשק Maps וגם ל-Maps JavaScript API, ל-Places SDK ל-Android או ל-Places SDK ל-iOS. האסימון תקף רק לבקשות של Places UI Kit מהפרויקט שהאסימון הונפק בשבילו.
  • אפליקציית לקוח שטוענת את Maps JavaScript API מערוץ הבטא על ידי הגדרת v=beta. בנייד, צריך להשתמש ב-Places SDK ל-Android בגרסה 6.1.0 ואילך או ב-Places Swift SDK‏ (GooglePlacesSwift) בגרסה 11.4.0.

הצגת מקומות מתשובה מבוססת-נתונים

בקטעים הבאים מוסבר איך לקבל את הטוקן מהתגובה של הכלי ולהשתמש בו באפליקציית הלקוח. אם אתם משתמשים בערכת הכלים לסוכן AI ב-Maps (ניסיוני), הסוכן ולקוח האינטרנט שלה מטפלים בשלבים האלה בשבילכם.

קבלת הטוקן מהתשובה של הכלי

הכלים search_places ו-search_along_route מחזירים את האסימון בשדה contentToken. בתוצאה של בקשת MCP tools/call, השדה הזה נמצא ב-structuredContent. בתשובה מה-method ‏searchText או searchAlongRoute ב-REST, זהו שדה ברמה העליונה. תגובה מסוג search_places דומה לזו (תגובה מסוג search_along_route מחזירה כל מקום בתוך results[].place):

{
  "places": [
    {
      "place": "places/PLACE_ID",
      "id": "PLACE_ID"
    }
  ],
  "contentToken": "CONTENT_TOKEN"
}

הפלט הזה כולל את הערכים הבאים:

  • ‫PLACE_ID: מזהה המקום של מקום בתגובה.
  • ‫CONTENT_TOKEN: אסימון ההמחשה החזותית של הנתונים של הסוכן למקומות בתשובה. התייחסו לטוקן כמחרוזת אטומה ואל תשנו אותו.

אם התשובה לא כוללת מקומות, היא לא כוללת טוקן.

בקוד של האפליקציה, קוראים את האסימון מהתגובה של הכלי – לדוגמה, בקריאה חוזרת (callback) של כלי במסגרת של הנציג – ושולחים אותו לאפליקציית הלקוח עם מזהי המקומות. אל תסתמכו על כך שה-LLM יחזור על הטוקן בפלט שלו, כי המודל עשוי לשנות את הטוקן.

האסימון מכסה רק את המקומות בתגובה שלו. אם הנציג שלכם קורא ל-search_places או ל-search_along_route יותר מפעם אחת, צריך לשלוח כל אסימון לאפליקציית הלקוח.

לדוגמה, אם אתם משתמשים ב-Agent Development Kit (ADK) ל-Python, אתם יכולים לשמור כל אסימון בקריאה חוזרת (callback) אחרי הכלי:

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 במאמר הגדרת מודלי LLM לשימוש בשרת MCP.

הוספת הטוקן והצגת המקומות

Maps JavaScript API

באפליקציית הלקוח, מעבירים רשימה ניתנת לאיטרציה (כמו מערך) של מחרוזות טוקנים לא ריקות אל Settings.getInstance().addContentTokens() לפני שיוצרים רכיבים של Places UI Kit בשביל המקומות. השיטה מחזירה שגיאה אם מעבירים מחרוזת אחת ישירות או אם ה-iterable כולל מחרוזת ריקה. בדוגמה הבאה מוסיפים אסימון, ואז מציגים רכיב Place Details Compact לכל מקום:

// 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 שומר בזיכרון את הטוקנים שאתם מוסיפים לדף הנוכחי, ומסיר אותם באופן אוטומטי אחרי שהתוקף שלהם פג, כך שאתם לא צריכים להסיר בעצמכם טוקנים שפג תוקפם. אם מוסיפים אסימונים מיותר מתגובה אחת, ה-API שולח את כל האסימונים המאוחסנים עם כל בקשה מרכיב נתמך.

כדי להציג כמה מקומות ברכיב אחד, מגדירים את המאפיין places של רכיב רשימת המקומות המתקדמת למזהי המקומות מתגובה אחת או יותר שהוספתם את הטוקנים שלהן.

Places SDK ל-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))

‫Fragments‏ (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))

SDK של מקומות ל-iOS

ערכת ה-SDK מספקת מקרים ייעודיים של טיפוסים בני מנייה (enum) של 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
)

אימות טוקן

בקשה של Places UI Kit לא מחויבת אם מתקיימים כל התנאים הבאים:

  • אותו פרויקט בענן: האסימונים הונפקו לפרויקט בענן של Google שבבעלותו מפתח ה-API שמשמש לטעינת Maps JavaScript API,‏ Places SDK ל-Android או Places SDK ל-iOS.
  • מקומות מבוססים: כל מקום שהרכיב מבקש מכוסה על ידי אסימון אחד לפחות שנכלל בבקשה. רכיב יכול לכלול מקומות מכמה תשובות אם מוסיפים את האסימון מכל תשובה.
  • אסימונים בתוקף: לכל מקום, הבקשה נשלחת תוך 10 דקות מהמועד שבו הונפק אסימון שכולל את המקום.
  • רכיב נתמך: הבקשה מגיעה מרכיב נתמך של Places UI Kit.

רכיבים שאתם מגדירים עם מיקום במקום מקום, כמו PlaceDetailsLocationRequestElement, לא נכללים. אם רכיב Advanced Place List כולל מקום שלא נכלל, כל הבקשה מחויבת.

אם אחד מהתנאים לא מתקיים, הרכיב עדיין נטען, והבקשה מחויבת בתעריף הרגיל של המק"ט שלה. ב-Maps JavaScript API, ב-Places SDK ל-Android וב-Places SDK ל-iOS לא מוחזרת שגיאה כשהאסימון לא תקין.

מגבלות (Places SDK ל-Android ול-iOS בלבד)

  • אפשר להשתמש במקסימום 100 אסימונים ייחודיים לכל בקשה. אסימונים עודפים נחתכים ומופיעה אזהרה ביומן.
  • הגודל המקסימלי של כל אסימון הוא 2,048 בייטים בקידוד UTF-8. המערכת מתעלמת מטוקנים גדולים מדי, מציגה אזהרה ביומן ומתעלמת מטוקנים ריקים או כפולים.
  • שאילתות קואורדינטות (PlaceReference.Coordinates ו-PlaceIdentifier.coordinate) לא מקבלות אסימונים.
  • ב-iOS AdvancedPlaceListView, אם באחת מהשאילתות ברשימה חסר מזהה מקום או שם משאב, לא נשלחים אסימונים לרשימה.

חיוב

אתם משלמים על כל בקשה לכלים אג'נטיים בממשק Maps לפי התעריף הרגיל. בקשות של Places UI Kit שעוברות אימות טוקן לא מחויבות, אבל הן עדיין נספרות במכסה של Places UI Kit. בקשות של Places UI Kit שלא עוברות אימות טוקן, או בקשות עם טוקנים לא תקינים או שפג תוקפם, מחויבות בתעריף הרגיל של המק"ט Places UI Kit Query או Places UI Kit Pro (Advanced)‎.

למידע על מחירים, קראו את טבלת התמחור הראשית ואת טבלת התמחור בהודו.

דרישות השימוש

שימוש על ידי משתמש יחיד, בתגובה פעילה בלבד: אתם צריכים להשתמש באסימון להמחשת נתונים של סוכן רק כדי להציג רכיבים נתמכים של Places UI Kit לאותו משתמש קצה, ובמסגרת התגובה המיידית של הסוכן שיצרה את האסימון. אסור לשתף, לאסוף או לעשות שימוש חוזר בטוקנים בין כמה משתמשי קצה, או להשתמש בטוקן כדי להציג מקומות מחוץ לתגובה הזו (למשל ברשימות שמורות, בסימניות או בספריות שנשמרו במטמון).

השימוש בטוקן של Agentic Data Visualization כפוף לתנאים ולהגבלות של Google Maps Platform, כולל התנאים הספציפיים לשירות. דרישות הייחוס של הכלים האג'נטיים בממשק Maps חלות גם כאן.