האסימון להצגה חזותית של נתונים מבוססי-סוכן מאפשר לאפליקציה מבוססת-הסוכן להציג רכיבים של Places UI Kit בשביל המקומות בתשובה של כלי הסוכן של Maps Experience (לשעבר Maps Grounding Lite) ללא עלות נוספת. כל קריאה מוצלחת לכלי search_places מחזירה טוקן שמזהה את המקומות בתגובה, גם למק"טים של Essentials וגם למק"טים של Pro. כשאפליקציית הלקוח מוסיפה את הטוקן ל-Maps JavaScript API, בקשות של Places UI Kit למקומות האלה לא מחויבות במשך 10 דקות אחרי הנפקת הטוקן.
איך זה עובד
הטוקן מקשר בין התשובה המעוגנת בנתונים ל-Place Details שמוצגים איתה:
- הנציג מפעיל את הכלי
search_placesבשרת ה-MCP של כלי הנציג של Maps Experience. התשובה של הכלי כוללת את המקומות שתומכים בסיכום ואסימון בשדהcontentToken. - האפליקציה קוראת את האסימון מהתגובה של הכלי ושולחת אותו לאפליקציית הלקוח, יחד עם המזהים של המקומות שרוצים להציג.
- אפליקציית הלקוח מוסיפה את האסימון ל-Maps JavaScript API ויוצרת רכיבים של Places UI Kit בשביל המקומות האלה.
- Google Maps Platform מאמתת את האסימון בכל בקשה של Places UI Kit. אם האסימון תקין, הבקשה לא מחויבת.
רכיבים נתמכים ב-Places UI Kit
האסימון חל על הרכיבים הבאים של Places UI Kit ב-Maps JavaScript API:
האסימון לא חל על בקשות אחרות, כמו בקשות מהרכיבים "חיפוש מקומות", "חיפוש מקומות מתקדם" ו"השלמה אוטומטית בסיסית למקומות", בקשות ל-Places API וטעינות של מפות. הבקשות האלה מחויבות בתעריפים רגילים.
רק התשובות של סוכני הכלים של Maps Experience כוללות את הטוקן. אם אתם מציגים מקומות מתשובה של "עיגון בעזרת מפות 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. - פרטי הכניסה מהפרויקט הזה גם לקריאות של כלי הסוכן של Maps Experience וגם ל-Maps JavaScript API. האסימון תקף רק לבקשות של Places UI Kit מהפרויקט שהאסימון הונפק בשבילו.
- אפליקציית לקוח שטוענת את Maps JavaScript API מערוץ הבטא על ידי הגדרת
v=beta.
הצגת מקומות מתשובה מעוגנת
בקטעים הבאים מוסבר איך לקבל את הטוקן מהתגובה של הכלי ולהשתמש בו באפליקציית הלקוח. אם אתם משתמשים בערכת הכלים לסוכן AI ב-Maps (ניסיוני), הסוכן ולקוח האינטרנט שלה מטפלים בשלבים האלה בשבילכם.
קבלת הטוקן מהתשובה של הכלי
הכלי search_places מחזיר את האסימון בשדה contentToken. בתוצאה של בקשת MCP tools/call, השדה הזה נמצא ב-structuredContent. התגובה של הכלי אמורה להיראות כך:
{ "places": [ { "place": "places/PLACE_ID", "id": "PLACE_ID", ... } ], ... "contentToken": "CONTENT_TOKEN" }
הפלט הזה כולל את הערכים הבאים:
-
PLACE_ID: מזהה המקום של מקום בתגובה. -
CONTENT_TOKEN: אסימון ההמחשה החזותית של נתוני הסוכן למקומות בתשובה. התייחסו לטוקן כמחרוזת אטומה ואל תשנו אותו.
אם התגובה לא כוללת מקומות, היא לא כוללת טוקן.
בקוד האפליקציה, קוראים את האסימון מהתגובה של הכלי – לדוגמה, בקריאה חוזרת (callback) של כלי במסגרת של הנציג – ושולחים אותו לאפליקציית הלקוח עם מזהי המקומות. אל תסתמכו על כך שה-LLM יחזור על הטוקן בפלט שלו, כי המודל עשוי לשנות את הטוקן.
הטוקן מכסה רק את המקומות בתגובה שלו. אם הנציג קורא לכלי search_places יותר מפעם אחת, צריך לשלוח כל אסימון לאפליקציית הלקוח.
לדוגמה, אם אתם משתמשים ב-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.
הוספת הטוקן והצגת המקומות
באפליקציית הלקוח, מעבירים רשימה ניתנת למעבר (כמו מערך) של מחרוזות טוקנים לא ריקות אל Settings.getInstance().addContentTokens() לפני שיוצרים רכיבים של Places UI Kit בשביל המקומות. השיטה מחזירה שגיאה אם מעבירים מחרוזת אחת ישירות או אם ה-iterable כולל מחרוזת ריקה. בדוגמה הבאה מוסיפים אסימון, ואז מציגים רכיב Place Details Compact לכל מקום:
// 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 בדף הנוכחי, ומוסרים אוטומטית אחרי שהתוקף שלהם פג, כך שאתם לא צריכים להסיר אותם בעצמכם. אם מוסיפים אסימונים מיותר מתגובה אחת, ה-API שולח את כל האסימונים השמורים עם כל בקשה מרכיב נתמך.
כדי להציג כמה מקומות ברכיב אחד, מגדירים את המאפיין places של רכיב רשימת מקומות מתקדמת למזהי המקומות מתגובה אחת או יותר שהוספתם את הטוקנים שלהן.
אימות טוקן
בקשה של Places UI Kit לא מחויבת אם מתקיימים כל התנאים הבאים:
- אותו פרויקט בענן: האסימונים הונפקו לפרויקט בענן ב-Google Cloud שבבעלותו מפתח ה-API שמשמש לטעינת Maps JavaScript API.
- מקומות מעוגנים: כל מקום שהרכיב מבקש מכוסה על ידי אסימון אחד לפחות שהוספתם. רכיב יכול לכלול מקומות מכמה תשובות אם מוסיפים את האסימון מכל תשובה.
- אסימונים בתוקף: לכל מקום, הבקשה נשלחת תוך 10 דקות מהמועד שבו הונפק אסימון שמכסה את המקום.
- רכיב נתמך: הבקשה מגיעה מרכיב נתמך של Places UI Kit.
רכיבים שאתם מגדירים עם מיקום במקום עם מקום, כמו PlaceDetailsLocationRequestElement, לא נכללים. אם רכיב Advanced Place List כולל מקום שלא נכלל, הבקשה כולה מחויבת.
אם אחד מהתנאים לא מתקיים, הרכיב עדיין נטען והבקשה מחויבת בתעריף הרגיל של המק"ט שלה. Maps JavaScript API לא מחזיר שגיאה כשהטוקן לא תקין.
חיוב
אתם משלמים על כל בקשה של כלי הסוכן של Maps Experience לפי התעריף הרגיל שלה. בקשות של Places UI Kit שעוברות אימות טוקן לא מחויבות, אבל הן עדיין נספרות במכסה של Places UI Kit. בקשות של Places UI Kit שלא עוברות אימות טוקן מחויבות לפי התעריף הרגיל של המק"ט Places UI Kit Query או Places UI Kit Pro (Advanced).
למידע על מחירים, קראו את טבלת התמחור הראשית ואת טבלת התמחור בהודו.
דרישות השימוש
שימוש על ידי משתמש יחיד, בתגובה פעילה בלבד: אתם צריכים להשתמש בטוקן של Agentic Data Visualization רק כדי להציג רכיבים נתמכים של Places UI Kit לאותו משתמש קצה, ובמסגרת התגובה המיידית של הסוכן שיצרה את הטוקן. אסור לשתף, לאסוף או לעשות שימוש חוזר בטוקנים בין כמה משתמשי קצה, או להשתמש בטוקן כדי להציג מקומות מחוץ לתגובה הזו (למשל ברשימות שמורות, בסימניות או בספריות שנשמרו במטמון).
השימוש בטוקן של סוכן ה-AI להמחשת נתונים כפוף לתנאים ולהגבלות של Google Maps Platform, כולל התנאים הספציפיים לשירות. דרישות הייחוס של כלי הסוכן של Maps Experience חלות גם כאן.