نشان دیداری‌سازی داده‌های عامل به برنامه عامل شما اجازه می‌دهد
عناصر کیت میانای کاربر «جاها» را
برای مکان‌های موجود در پاسخ
ابزارهای عامل «تجربه Maps» (قبلاً
Maps Grounding Lite) بدون هزینه اضافی نمایش دهد. هر تماس موفق به
ابزار search_places یک توکن برمی‌گرداند که مکان‌ها را در
پاسخ، هم برای SKUهای Essentials و هم Pro، شناسایی می‌کند. وقتی برنامه کارخواه شما
نشان را به Maps JavaScript API اضافه می‌کند، درخواست‌های «کیت میانای کاربر جاها» برای آن جاها
تا ۱۰ دقیقه پس‌از صدور نشان صورت‌حساب نمی‌شود.
روش کار
این کد پاسخ مستدل را به جزئیات مکانی که با آن نمایش می‌دهید متصل می‌کند:
- عامل شما ابزار
search_placesرا در ابزارهای عامل «تجربه Maps» سرور MCP فراخوانی می‌کند. پاسخ ابزار شامل مکان‌هایی است که از خلاصه پشتیبانی می‌کنند و یک ژتون در فیلدcontentToken. - برنامه شما کد را از پاسخ ابزار می‌خواند و آن را به‌همراه شناسه‌های مکان‌هایی که می‌خواهید نمایش دهید به برنامه کارخواه شما ارسال می‌کند.
- برنامه کارخواه شما این توکن را به Maps JavaScript API اضافه می‌کند و عناصر «کیت میانای کاربر جاها» را برای آن جاها ایجاد می‌کند.
- Google Maps Platform با هر درخواست «کیت میانای کاربر جاها» کد را اعتبارسنجی می‌کند. اگر توکن معتبر باشد، درخواست صورت‌حساب نمی‌شود.
عناصر پشتیبانی‌شده کیت میانای کاربر «جاها»
این توکن برای عناصر «کیت میانای کاربر جاها» در میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps اعمال می‌شود:
این کد برای درخواست‌های دیگر، مثل درخواست‌های عناصر «جستجوی جا»، «جستجوی پیشرفته جا»، و «تکمیل خودکار جا»ی پایه، درخواست‌های Places API، و بار کردن نقشه اعمال نمی‌شود. این درخواست‌ها با نرخ‌های استاندارد صورت‌حساب می‌شوند.
فقط پاسخ‌های ابزارهای نماینده «تجربه Maps» حاوی این کد هستند. اگر مکان‌های پاسخ «پایه‌مندسازی با Google Maps» را با «کیت میانای کاربر جاها» نمایش دهید، هزینه آن درخواست‌ها با نرخ استاندارد محاسبه می‌شود.
قبل‌از شروع
قبل‌از استفاده از کد داده‌نمایی عاملی، موارد زیر را راه‌اندازی کنید:
- پروژه Google Cloud با Maps Experience agent tools API
(
mapstools.googleapis.com) و Places UI Kit API فعال‌شده. برای اطلاعات بیشتر، پیکربندی مدل‌های زبانی بزرگ برای استفاده از سرور MCP و شروع به کار با کیت میانای کاربر «جاها» را ببینید. - اعتبارنامه‌های آن پروژه برای هر دو تماس ابزار نماینده «تجربه Maps» و Maps JavaScript API. یک توکن فقط برای درخواست‌های «کیت میانای کاربر جاها» از پروژه‌ای که توکن برای آن صادر شده است معتبر است.
- برنامه کارخواهی که Maps JavaScript API را از
کانال بتا با
تنظیم
v=betaبار می‌کند.
نمایش مکان‌ها از پاسخ مستند
بخش‌های زیر نشان می‌دهند که چگونه کد را از پاسخ ابزار دریافت کنید و از آن در برنامه کارخواه خود استفاده کنید. اگر از ابزار کار میانای کاربر عامل‌گرای Maps (آزمایشی) استفاده می‌کنید، عامل و کارخواه وب آن این مراحل را برای شما انجام می‌دهند.
دریافت کردن کد از پاسخ ابزار
ابزار search_places کد را در فیلد contentToken برمی‌گرداند. در
نتیجه درخواست MCP tools/call، این فیلد در structuredContent است. پاسخ
ابزار شبیه به این است:
{ "places": [ { "place": "places/PLACE_ID", "id": "PLACE_ID", ... } ], ... "contentToken": "CONTENT_TOKEN" }
این خروجی شامل مقادیر زیر است:
-
PLACE_ID: شناسه مکان مکانی در پاسخ. CONTENT_TOKEN: کد دیداری‌سازی داده‌های عاملی برای مکان‌های موجود در پاسخ. با این کد به‌عنوان رشته‌ای مبهم رفتار کنید و آن را تغییر ندهید.
اگر پاسخ شامل هیچ مکانی نباشد، پاسخ شامل هیچ نشانهای نیست.
در کد برنامه‌تان، توکن را از پاسخ ابزار بخوانید—برای مثال، در یک فراخوانی ابزار در چارچوب عاملتان—و آن را همراه با شناسه‌های مکان به برنامه مشتری‌تان ارسال کنید. به LLM برای تکرار کردن کد در خروجی‌اش تکیه نکنید، زیرا مدل ممکن است کد را تغییر دهد.
هر کد فقط مکان‌های موجود در پاسخ خودش را پوشش می‌دهد. اگر عاملتان ابزار
search_places را بیش‌از یک‌بار فراخوانی کرد، هرکدام از این توکن‌ها را به برنامه کارخواهتان ارسال کنید.
برای مثال، اگر از 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 را در
پیکربندی LLM برای استفاده از سرور MCP ببینید.
افزودن کد و نمایش مکان‌ها
در برنامه کارخواه، قبل‌از ایجاد عناصر «کیت میانای کاربر جاها» برای جاها، یک تکرارپذیر (مانند آرایه) از رشته‌های توکن غیرخالی را به Settings.getInstance().addContentTokens() ارسال کنید. اگر یک رشته تکی را مستقیماً ارسال کنید یا اگر تکرارپذیر شامل رشته خالی باشد، این روش خطا ایجاد می‌کند. مثال زیر یک توکن اضافه می‌کند و سپس عنصر «جزئیات جا» فشرده را برای هر جا نمایش می‌دهد:
// 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);
}
}
توکن‌ها ۱۰ دقیقه پس‌از صدور منقضی می‌شوند. Maps JavaScript API نشان‌هایی را که در حافظه صفحه فعلی اضافه می‌کنید نگه می‌دارد و پس‌از منقضی شدن، آن‌ها را به‌طور خودکار برمی‌دارد، بنابراین نیازی نیست نشانهای منقضی‌شده را خودتان بردارید. اگر از بیش‌از یک پاسخ، توکن اضافه کنید، API همه توکن‌های ذخیره‌شده را با هر درخواست از عنصر پشتیبانی‌شده ارسال می‌کند.
برای نمایش دادن چند مکان در یک عنصر، ویژگی places
عنصر «فهرست مکان پیشرفته»
را روی شناسه‌های مکان یک یا چند پاسخ که کدهایشان را اضافه کرده‌اید تنظیم کنید.
اعتبارسنجی کد
درخواست «کیت میانای کاربر جاها» درصورت برآورده شدن همه شرایط زیر صورت‌حساب نمی‌شود:
- پروژه یکسان: این توکن‌ها برای پروژه Google Cloud صادر شده‌اند که مالک کلید میانای برنامه‌سازی کاربردی است که برای بار کردن Maps JavaScript API استفاده می‌کنید.
- مکان‌های مستند: هر مکانی که عنصر درخواست می‌کند با حداقل یک کد که اضافه کرده‌اید پوشش داده می‌شود. اگر کد هر پاسخ را اضافه کنید، یک عنصر می‌تواند شامل مکان‌هایی از چندین پاسخ باشد.
- کدهای منقضی‌نشده: برای هر مکان، درخواست ظرف ۱۰ دقیقه از زمان صدور کدی که آن مکان را پوشش می‌دهد انجام می‌شود.
- عنصر پشتیبانی‌شده: درخواست از عنصر پشتیبانی‌شده کیت میانای کاربر «جاها» ارسال شده است.
عناصری که به‌جای مکان با موقعیت پیکربندی می‌کنید، مثل
PlaceDetailsLocationRequestElement، پوشش داده نمی‌شوند. اگر عنصر «فهرست مکان‌های پیشرفته»
شامل مکانی باشد که تحت پوشش نیست، کل درخواست صورت‌حساب می‌شود.
اگر هرکدام از شرایط برآورده نشود، عنصر همچنان بار می‌شود و درخواست با نرخ استاندارد برای SKU آن صورت‌حساب می‌شود. وقتی که یک کد معتبر نباشد، Maps JavaScript API خطایی را برنمی‌گرداند.
صورت‌حساب
برای هر درخواست ابزارهای عامل «تجربه Maps» با نرخ استاندارد آن پرداخت می‌کنید. درخواست‌های «کیت میانای کاربر جاها» که اعتبارسنجی کد را با موفقیت پشت سر می‌گذارند، صورت‌حساب دریافت نمی‌کنند، اما همچنان در سهمیه «کیت میانای کاربر جاها» شما لحاظ می‌شوند. درخواست‌های «کیت میانای کاربر جاها» که اعتبارسنجی کد را با موفقیت پشت سر نمی‌گذارند با نرخ استاندارد برای شناسه محصول پرس‌وجوی کیت میانای کاربر جاها یا کیت میانای کاربر جاها Pro (پیشرفته) صورت‌حساب می‌شوند.
برای قیمت‌ها، جدول قیمت‌گذاری اصلی و جدول قیمت‌گذاری هند را ببینید.
الزامات استفاده
فقط برای استفاده تک‌کاربره و پاسخ فعال: باید از یک توکن تجسم داده عاملی فقط برای نمایش عناصر پشتیبانی‌شده «کیت میانای کاربر جاها» به همان کاربر نهایی و در پاسخ عاملی فوری که توکن را تولید کرده است استفاده کنید. نباید نشان‌ها را بین چند کاربر نهایی هم‌رسانی کنید، جمع‌آوری کنید، یا مجدداً استفاده کنید، یا از نشان برای نمایش مکان‌های خارج از آن پاسخ استفاده کنید (مثلاً در فهرست‌های ذخیره‌شده، نشانک‌ها، یا دایرکتوری‌های ذخیره‌شده در حافظه نهان).
استفاده شما از توکن تجسم داده‌های عاملی تابع شرایط خدمات Google Maps Platform، ازجمله شرایط خاص سرویس است. الزامات ذکر منبع برای ابزارهای عامل «تجربه Maps» نیز اعمال می‌شود.