代理数据可视化令牌

借助智能体数据可视化令牌,您的智能体应用可以免费显示地图体验智能体工具(以前称为 Maps Grounding Lite)响应中地点的地点界面套件元素。对于 Essentials 和 Pro SKU,每次成功调用 search_places 或 search_along_route 工具都会返回一个令牌,用于标识响应中的地点。当您的客户端应用将令牌添加到 Maps JavaScript API、Places SDK for Android 或 Places SDK for iOS 时,在令牌签发后的 10 分钟内,Places UI Kit 对这些地点的请求不会计费。

运作方式

该令牌会将接地回答与您随之显示的地点详情关联起来:

  1. 您的智能体调用地图体验智能体工具 MCP 服务器上的 search_places 或 search_along_route 工具。工具响应包含支持摘要的地点以及 contentToken 字段中的令牌。
  2. 您的应用会从工具响应中读取令牌,并将其与您要显示的地点 ID 一起发送到客户端应用。
  3. 您的客户端应用会将令牌添加到 Maps JavaScript API 或在每个移动组件请求中传递该令牌,并为这些地点创建 Places UI Kit 元素。
  4. Google Maps Platform 会在每次收到 Places UI Kit 请求时验证令牌。如果令牌有效,则系统不会对请求计费。

支持的 Places UI Kit 元素

Maps JavaScript API

该令牌适用于 Maps JavaScript API 中的以下 Places UI Kit 元素:

元素 SKU
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 for Android

Fragment/可组合函数 SKU
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(高级)

Places SDK for iOS

结构体 SKU
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 请求和地图加载。这些请求按标准费率计费。

只有地图实验专区智能体工具响应包含该令牌。如果您使用 Places UI Kit 显示 Grounding with Google Maps 响应中的地点,则这些请求将按标准费率计费。

准备工作

在使用智能体数据可视化令牌之前,请先完成以下设置:

  • 一个 Google Cloud 项目,其中已启用 Maps Experience 代理工具 API (mapstools.googleapis.com) 和 Places UI Kit API。如需了解详情,请参阅配置 LLM 以使用 MCP 服务器和开始使用 Places UI Kit for JavaScript、Android 或 iOS。
  • 该项目中用于地图体验智能体工具调用以及 Maps JavaScript API、Places SDK for Android 或 Places SDK for iOS 的凭证。令牌仅对来自令牌颁发项目的 Places UI Kit 请求有效。
  • 通过设置 v=beta 从 Beta 渠道加载 Maps JavaScript API 的客户端应用。对于移动设备,请使用 Places SDK for Android 6.1.0 或更高版本,或者 Places Swift SDK (GooglePlacesSwift) 11.4.0 版。

显示接地回答中的地点

以下部分介绍了如何从工具响应中获取令牌,并在客户端应用中使用该令牌。如果您使用地图智能体 UI 工具包(实验版),其智能体和 Web 客户端会为您处理这些步骤。

从工具响应中获取令牌

search_places 和 search_along_route 工具会在 contentToken 字段中返回令牌。在 MCP tools/call 请求的结果中,此字段位于 structuredContent 中。在 searchText 或 searchAlongRoute REST 方法的响应中,它是一个顶级字段。search_places 响应类似于以下内容(search_along_route 响应会返回 results[].place 中的每个地点):

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

此输出包括以下值:

  • PLACE_ID:响应中地点的地点 ID。
  • CONTENT_TOKEN:回答中地点的智能体数据可视化 token。将令牌视为不透明字符串,请勿对其进行修改。

如果响应不包含任何地点,则响应不包含令牌。

在应用代码中,从工具响应中读取令牌(例如,在代理框架中的工具回调中),并将其与地点 ID 一起发送到客户端应用。不要依赖 LLM 在其输出中重复该令牌,因为模型可能会更改该令牌。

一个令牌仅涵盖其自身响应中的地点。如果您的智能体代拨 search_places 或 search_along_route 多次,请将每个令牌发送到您的客户端应用。

例如,如果您使用适用于 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 示例。

添加令牌并显示地点

Maps JavaScript API

在客户端应用中,先将非空令牌字符串的可迭代对象(例如数组)传递给 Settings.getInstance().addContentTokens(),然后再为地点创建 Places UI Kit 元素。如果您直接传递单个字符串,或者可迭代对象包含空字符串,该方法会抛出错误。以下示例添加了一个令牌,然后为每个地点显示一个“地点详情(精简版)”元素:

// 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 属性设置为您添加了令牌的一个或多个响应中的地点 ID。

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

Fragment(PlaceDetailsFragment、PlaceDetailsCompactFragment、AdvancedPlaceDetailsFragment、AdvancedPlaceDetailsCompactFragment):

fragment.loadWithPlaceId(placeId, setOf(contentToken))
// Or: fragment.loadWithResourceName(resourceName, setOf(contentToken))

地点列表 fragment (AdvancedPlaceListFragment):

advancedPlaceListFragment.configureFromPlaceIds(placeIds, setOf(contentToken))
// Or: advancedPlaceListFragment.configureFromResourceNames(resourceNames, setOf(contentToken))

Places SDK for iOS

SDK 提供了专用的 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 Cloud 项目,该项目拥有您用于加载 Maps JavaScript API、Places SDK for Android 或 Places SDK for iOS 的 API 密钥。
  • 接地地点:元素请求的每个地点都至少由请求中包含的一个令牌覆盖。如果您添加每个响应中的令牌,则一个元素可以包含来自多个响应的地点。
  • 未过期的令牌:对于每个地点,请求是在涵盖该地点的令牌签发后的 10 分钟内发出的。
  • 受支持的元素:请求来自受支持的 Places UI Kit 元素或组件。

您使用位置(而非地点,例如 PlaceDetailsLocationRequestElement)配置的元素不在涵盖范围内。如果高级地点列表元素包含任何未涵盖的地点,则整个请求都会计费。

如果未满足任何条件,元素仍会加载,并且系统会按其 SKU 的标准费率对请求计费。当令牌无效时,Maps JavaScript API、Places SDK for Android 和 Places SDK for iOS 不会返回错误。

限制(仅限 Places SDK for Android 和 Places SDK for iOS)

  • 每个请求最多可包含 100 个唯一令牌。多余的 token 会被截断,并显示警告日志。
  • 每个令牌最多 2,048 个 UTF-8 字节。系统会丢弃过大的令牌并记录警告日志,同时忽略空白或重复的令牌。
  • 坐标查询(PlaceReference.Coordinates 和 PlaceIdentifier.coordinate)不接受词元。
  • 在 iOS AdvancedPlaceListView 上,如果列表中的任何查询缺少非空地点 ID 或资源名称,系统不会为该列表发送任何令牌。

结算

您需要按标准费率为每次地图体验智能体工具请求付费。 通过令牌验证的 Places UI Kit 请求不会计费,但仍会计入您的 Places UI Kit 配额。对于未通过令牌验证的 Places UI Kit 请求,或包含无效或过期令牌的请求,系统会按照 Places UI Kit 查询或 Places UI Kit Pro(高级版) SKU 的标准费率计费。

如需了解价格,请参阅主价格表和印度价格表。

使用要求

仅限单用户、主动响应使用:您只能使用智能体数据可视化令牌向同一最终用户显示受支持的 Places UI Kit 元素,并且只能在生成该令牌的即时智能体响应中使用。您不得在多个最终用户之间共享、汇集或重复使用令牌,也不得使用令牌显示该响应之外的地点(例如在已保存的列表、书签或缓存目录中)。

您在使用智能体数据可视化令牌时,需遵守《Google Maps Platform 服务条款》,包括服务专用条款。地图体验智能体工具的出处要求也适用。