代理資料視覺化權杖可讓代理應用程式顯示 Maps Experience 代理工具 (舊稱 Maps Grounding Lite) 回應中地點的 Places UI Kit 元素，不需額外付費。每次成功呼叫 search_places 工具，都會傳回一個權杖，用於識別回應中的地點，Essentials 和 Pro SKU 皆適用。用戶端應用程式將權杖新增至 Maps JavaScript API 後，Places UI Kit 針對這些地點提出的要求，在權杖核發後的 10 分鐘內不會計費。
運作方式
權杖會將基準化回覆連結至您顯示的 Place Details：
- 代理會在 Maps Experience 代理工具 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 元素：
這個權杖不適用於其他要求，例如來自 Place Search、Advanced Place Search 和 Basic Place Autocomplete 元素的要求、Places API 要求，以及地圖載入。這類要求會按標準費率計費。
只有 Maps Experience 代理工具的回應會包含權杖。如果您使用 Places UI Kit 顯示「利用 Google 地圖建立基準」回應中的地點，這些要求會按標準費率計費。
事前準備
使用代理式資料視覺化權杖前，請先完成下列設定：
- 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。
顯示有依據的回覆中的地點
以下各節說明如何從工具回應取得權杖，並在用戶端應用程式中使用。如果您使用地圖代理 UI 工具包 (實驗功能)，其代理和網頁用戶端會為您處理這些步驟。
從工具回應取得權杖
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 版 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 範例。
新增權杖並顯示地點
在用戶端應用程式中，先將非空白權杖字串的可疊代項目 (例如陣列) 傳遞至 Settings.getInstance().addContentTokens()，再為地點建立 Places UI Kit 元素。如果您直接傳遞單一字串，或可疊代項目包含空字串，這個方法會擲回錯誤。以下範例會新增權杖，然後顯示每個地點的 Place Details Compact 元素：
// 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 (Advanced) SKU 的標準費率計費。
使用方式規定
僅限單一使用者、主動回覆使用：您只能使用代理資料視覺化權杖，向同一位使用者顯示支援的 Places UI Kit 元素，且必須在產生權杖的代理回覆中立即顯示。您不得在多位使用者之間共用、彙整或重複使用權杖，也不得使用權杖顯示該回應以外的地點 (例如儲存的清單、書籤或快取目錄)。
使用代理資料視覺化權杖時，須遵守《Google Maps Platform 服務條款》，包括服務專屬條款。Maps Experience 代理工具的作者資訊相關規定也適用。