代理資料視覺化權杖

代理資料視覺化權杖可讓代理應用程式顯示 Maps Experience 代理工具 (舊稱 Maps Grounding Lite) 回應中地點的 Places UI Kit 元素,不需額外付費。每次成功呼叫 search_places 或 search_along_route 工具,都會傳回一個權杖,用於識別回應中的地點,Essentials 和 Pro SKU 皆適用。用戶端應用程式將權杖新增至 Maps JavaScript API、Places SDK for Android 或 Places SDK for iOS 後,Places UI Kit 在權杖核發後的 10 分鐘內,不會對這些地點的要求收費。

運作方式

權杖會將基準化回覆連結至您顯示的 Place Details:

  1. 代理會在 Maps Experience 代理工具 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

片段/可組合函式 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 (進階)

該符記不適用於其他要求,例如來自 Place Search、Advanced Place Search 和 Basic Place Autocomplete 元素的要求、Places API 要求,以及地圖載入。這類要求會按標準費率計費。

只有 Maps Experiments 代理工具的回應會包含權杖。如果您使用 Places UI Kit 顯示「利用 Google 地圖建立基準」回應中的地點,這些要求會按標準費率計費。

事前準備

使用代理資料視覺化權杖前,請先完成下列設定:

  • 已啟用 Maps Experience 代理工具 API (mapstools.googleapis.com) 和 Places UI Kit API 的 Google Cloud 雲端專案。詳情 請參閱 「設定 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 工具包 (實驗功能),其代理和網頁用戶端會為您處理這些步驟。

從工具回應取得權杖

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:回覆中地點的代理資料視覺化權杖。請將權杖視為不透明字串,不要修改。

如果回應不含任何地點,則不會包含權杖。

在應用程式程式碼中,從工具回應讀取權杖 (例如在代理架構的工具回呼中),然後將權杖與地點 ID 一併傳送至用戶端應用程式。請勿依賴 LLM 在輸出內容中重複權杖,因為模型可能會變更權杖。

權杖只涵蓋其回應中的地點。如果代理多次呼叫 search_places 或 search_along_route,請將每個權杖傳送至用戶端應用程式。

舉例來說,如果您使用 Python 版 Agent Development Kit (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 元素。如果您直接傳遞單一字串,或可疊代項目包含空字串,這個方法會擲回錯誤。以下範例會新增權杖,然後顯示每個地點的 Place Details 密集元素:

// 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))

片段 (PlaceDetailsFragment、PlaceDetailsCompactFragment、AdvancedPlaceDetailsFragment、AdvancedPlaceDetailsCompactFragment):

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

Place List 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 和 iOS)

  • 每項要求最多可包含 100 個不重複權杖。多餘的權杖會遭到截斷,並記錄警告。
  • 每個權杖最多 2,048 個 UTF-8 位元組。系統會捨棄過大的權杖,並記錄警告,空白或重複的權杖則會忽略。
  • 座標查詢 (PlaceReference.Coordinates 和 PlaceIdentifier.coordinate) 不接受權杖。
  • 在 iOS AdvancedPlaceListView 上,如果清單中的任何查詢缺少非空白的地點 ID 或資源名稱,系統就不會傳送該清單的權杖。

帳單

每項 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 服務條款》,包括服務專屬條款。地圖體驗代理工具的出處標示規定也適用。