Токен визуализации данных агента позволяет вашему агентному приложению бесплатно показывать элементы Places UI Kit для мест в ответе инструментов агента Maps Experience (ранее – Maps Grounding Lite). Каждый успешный вызов инструмента search_places возвращает токен, который идентифицирует места в ответе, как для Essentials, так и для Pro. Когда клиентское приложение добавляет токен в Maps JavaScript API, запросы Places UI Kit для этих мест не оплачиваются в течение 10 минут после выпуска токена.
Принцип работы
Токен связывает обоснованный ответ с информацией о месте, которую вы показываете вместе с ним:
- Агент вызывает инструмент
search_placesна MCP-сервере инструментов агента Maps Experience. Ответ инструмента включает места, которые поддерживают краткий пересказ, и токен в полеcontentToken. - Ваше приложение считывает токен из ответа инструмента и отправляет его в клиентское приложение вместе с идентификаторами мест, которые вы хотите показать.
- Клиентское приложение добавляет токен в Maps JavaScript API и создает элементы Places UI Kit для этих мест.
- Платформа Google Карт проверяет токен при каждом запросе Places UI Kit. Если токен действителен, плата за запрос не взимается.
Поддерживаемые элементы Places UI Kit
Токен применяется к следующим элементам Places UI Kit в Maps JavaScript API:
Токен не применяется к другим запросам, например к запросам от элементов Place Search, Advanced Place Search и Basic Place Autocomplete, запросам Places API и загрузкам карт. За такие запросы взимается плата по стандартным тарифам.
Токен включают только ответы инструментов агента Maps Experience. Если вы показываете места из ответа функции обоснования с Google Картами с помощью Places UI Kit, то за эти запросы взимается плата по стандартным тарифам.
Подготовка
Прежде чем использовать токен визуализации данных, настройте следующее:
- Облачный проект 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.
Как показывать места из обоснованного ответа
В следующих разделах рассказывается, как получить токен из ответа инструмента и использовать его в клиентском приложении. Если вы используете агентный набор инструментов интерфейса Карт (экспериментальная функция), эти шаги за вас выполнят агент и веб-клиент.
Получите токен из ответа инструмента
Инструмент search_places возвращает токен в поле contentToken. В результатах запроса tools/call к MCP это поле находится в 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(), прежде чем создавать элементы Places UI Kit для мест. Если вы передадите одну строку напрямую или итерируемый объект будет содержать пустую строку, метод выдаст ошибку. В следующем примере добавляется токен, а затем для каждого места отображается компактный элемент с информацией о нем.
// 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 содержит хотя бы одно место, которое не входит в бесплатный лимит, оплачивается весь запрос.
Если какое-либо условие не выполняется, элемент все равно загружается, а за запрос взимается плата по стандартному тарифу для его SKU. Maps JavaScript API не возвращает ошибку, если токен недействителен.
Оплата
Вы платите за каждый запрос к инструментам агента Maps Experience по стандартному тарифу. Запросы Places UI Kit, прошедшие проверку токена, не оплачиваются, но учитываются в квоте Places UI Kit. Запросы Places UI Kit, не прошедшие проверку токена, оплачиваются по стандартному тарифу для кода Places UI Kit Query или Places UI Kit Pro (Advanced).
Цены указаны в основной таблице цен и таблице цен для Индии.
Требования к использованию
Использование только одним пользователем и только в активном ответе. Токен визуализации данных агента можно использовать только для показа поддерживаемых элементов Places UI Kit тому же конечному пользователю и только в рамках непосредственного ответа агента, который сгенерировал токен. Запрещается передавать, объединять или повторно использовать токены для нескольких конечных пользователей, а также использовать токен для показа мест за пределами ответа (например, в сохраненных списках, закладках или кешированных каталогах).
Использование токена визуализации данных агента регулируется Условиями использования платформы Google Карт, включая Условия использования сервиса. Также применяются требования по указанию авторства для инструментов агента Maps Experience.