借助智能体数据可视化令牌，您的智能体应用可以免费显示地图体验智能体工具（以前称为 Maps Grounding Lite）响应中地点的地点界面套件元素。对于 Essentials 和 Pro SKU，每次成功调用 search_places 工具都会返回一个令牌，用于标识响应中的地点。当您的客户端应用将令牌添加到 Maps JavaScript API 后，在令牌签发后的 10 分钟内，针对这些地点的 Places UI Kit 请求不会计费。
运作方式
该令牌会将接地回答与您随之显示的地点详情关联起来：
- 您的智能体调用地图实验专区智能体工具 MCP 服务器上的
search_places工具。工具响应包含支持摘要的地点以及contentToken字段中的令牌。 - 您的应用会从工具响应中读取令牌，并将其与您要显示的地点 ID 一起发送到客户端应用。
- 您的客户端应用会将该令牌添加到 Maps JavaScript API，并为这些地点创建 Places UI Kit 元素。
- Google Maps Platform 会在每次收到 Places UI Kit 请求时验证令牌。如果令牌有效，则不会对请求计费。
支持的 Places UI Kit 元素
该令牌适用于 Maps JavaScript API 中的以下 Places UI Kit 元素：
该令牌不适用于其他请求，例如来自“地点搜索”“高级地点搜索”和“基本地点自动补全”元素的请求、Places API 请求以及地图加载。这些请求按标准费率计费。
只有地图实验专区代理工具响应包含该令牌。如果您使用 Places UI Kit 显示 Grounding with Google Maps 回答中的地点，则这些请求将按标准费率计费。
准备工作
在使用智能体数据可视化令牌之前，请先完成以下设置：
- 一个 Google Cloud 项目，其中已启用 Maps Experience 代理工具 API (
mapstools.googleapis.com) 和 Places UI Kit API。如需了解详情，请参阅配置 LLM 以使用 MCP 服务器和Places UI Kit 使用入门。 - 该项目的凭证，用于 Maps Experience 代理工具调用和 Maps JavaScript API。令牌仅对来自令牌颁发项目的 Places UI Kit 请求有效。
- 通过设置
v=beta从 Beta 渠道加载 Maps JavaScript API 的客户端应用。
显示接地回答中的地点
以下部分介绍了如何从工具响应中获取 token，并在客户端应用中使用该 token。如果您使用地图智能体 UI 工具包（实验版），其智能体和 Web 客户端会为您处理这些步骤。
从工具响应中获取令牌
search_places 工具会在 contentToken 字段中返回令牌。在 MCP tools/call 请求的结果中，此字段位于 structuredContent 中。工具响应类似于以下内容：
{ "places": [ { "place": "places/PLACE_ID", "id": "PLACE_ID", ... } ], ... "contentToken": "CONTENT_TOKEN" }
此输出包括以下值：
PLACE_ID：响应中地点的地点 ID。CONTENT_TOKEN：回答中地点的智能体数据可视化令牌。将令牌视为不透明字符串，请勿对其进行修改。
如果响应不包含任何地点，则响应不包含令牌。
在应用代码中，从工具响应中读取令牌（例如，在代理框架中的工具回调中），并将其与地点 ID 一起发送到客户端应用。不要依赖 LLM 在其输出中重复该令牌，因为模型可能会更改该令牌。
一个令牌仅涵盖其自身响应中的地点。如果您的智能体多次调用 search_places 工具，请将每个令牌发送到客户端应用。
例如，如果您使用适用于 Python 的智能体开发套件 (ADK)，则可以在工具后回调中保存每个令牌：
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 参数传递，然后将保存的令牌与代理的响应一起发送到客户端应用。如需查看完整的智能体定义，请参阅配置 LLM 以使用 MCP 服务器中的 ADK 示例。
添加令牌并显示地点
在客户端应用中，先将非空令牌字符串的可迭代对象（例如数组）传递给 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 属性设置为您添加了令牌的一个或多个响应中的地点 ID。
令牌验证
如果满足以下所有条件，则系统不会对 Places UI Kit 请求计费：
- 同一项目：令牌已颁发给 Google Cloud 项目，该项目拥有您用于加载 Maps JavaScript API 的 API 密钥。
- 接地位置：元素请求的每个位置都至少由您添加的一个令牌覆盖。如果您添加每个响应中的令牌，则一个元素可以包含来自多个响应的地点。
- 未过期的令牌：对于每个地点，请求是在涵盖该地点的令牌签发后 10 分钟内发出的。
- 支持的元素：请求来自支持的 Places UI Kit 元素。
您使用位置（而非地点，例如 PlaceDetailsLocationRequestElement）配置的元素不在此范围内。如果高级地点列表元素包含任何未涵盖的地点，则整个请求都会计费。
如果未满足任何条件，元素仍会加载，并且系统会按其 SKU 的标准费率对请求进行结算。如果令牌无效，Maps JavaScript API 不会返回错误。
结算
您需要按标准费率为每次 Maps Experience 代理工具请求付费。 通过令牌验证的 Places UI Kit 请求不会计费，但仍会计入您的 Places UI Kit 配额。对于未通过令牌验证的 Places UI Kit 请求，系统会按照 Places UI Kit 查询或 Places UI Kit Pro（高级版） SKU 的标准费率计费。
使用要求
仅限单用户、主动响应使用：您只能使用智能体数据可视化令牌向同一最终用户显示受支持的 Places UI Kit 元素，并且只能在生成该令牌的即时智能体响应中使用。您不得在多个最终用户之间共享、汇集或重复使用令牌，也不得使用令牌显示该回答之外的地点（例如在保存的列表、书签或缓存目录中）。
您在使用智能体数据可视化令牌时，需遵守《Google Maps Platform 服务条款》，包括服务专用条款。此外，还需遵守地图体验代理工具的出处要求。