エージェント データ可視化トークンを使用すると、エージェント アプリは、Maps Experience エージェント ツール（旧称 Maps Grounding Lite）のレスポンスに含まれる場所の Places UI キット 要素を追加料金なしで表示できます。search_places ツールへの呼び出しが成功するたびに、Essentials SKU と Pro SKU の両方で、レスポンス内の場所を識別するトークンが返されます。クライアント アプリが Maps JavaScript API にトークンを追加すると、トークンの発行後 10 分間は、それらの場所に対する Places UI キット のリクエストは課金されません。
仕組み
このトークンは、グラウンディングされたレスポンスを、それとともに表示する Place Details に接続します。
- エージェントは、Maps Experience エージェント ツール MCP サーバーの
search_placesツールを呼び出します。ツールのレスポンスには、要約をサポートする場所と、contentTokenフィールドのトークンが含まれます。 - アプリは、ツール レスポンスからトークンを読み取り、表示する場所の ID とともにクライアント アプリに送信します。
- クライアント アプリは、トークンを Maps JavaScript API に追加し、それらの場所の Places UI Kit 要素を作成します。
- Google Maps Platform は、Places UI キットのリクエストごとにトークンを検証します。トークンが有効な場合、リクエストは課金されません。
サポートされている Places UI キットの要素
このトークンは、Maps JavaScript API の次の Places UI キット要素に適用されます。
このトークンは、Place Search、Advanced Place Search、Basic Place Autocomplete 要素からのリクエスト、Places API リクエスト、地図の読み込みなど、他のリクエストには適用されません。これらのリクエストには標準料金が適用されます。
トークンが含まれるのは、Maps Experience エージェント ツールのレスポンスのみです。Google マップによるグラウンディングのレスポンスから Places UI キットを使用して場所を表示する場合、これらのリクエストは標準料金で課金されます。
始める前に
エージェント データ可視化トークンを使用する前に、次の設定を行います。
- Maps Experience Agent Tools API（
mapstools.googleapis.com）と Places UI Kit API が有効になっている Google Cloud プロジェクト。詳細については、MCP サーバーを使用するように LLM を構成すると Places UI キットを使ってみるをご覧ください。 - Maps Experience エージェント ツールの呼び出しと Maps JavaScript API の両方で使用する、そのプロジェクトの認証情報。トークンは、トークンが発行されたプロジェクトからの Places UI キット リクエストに対してのみ有効です。
v=betaを設定して、ベータ版チャンネルから Maps JavaScript API を読み込むクライアント アプリ。
グラウンディングされたレスポンスから場所を表示する
以降のセクションでは、ツール レスポンスからトークンを取得してクライアント アプリで使用する方法について説明します。Google マップ エージェント型 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 引数として渡し、保存されたトークンをエージェントのレスポンスとともにクライアント アプリに送信します。エージェントの完全な定義については、MCP サーバーを使用するように LLM を構成するの ADK の例をご覧ください。
トークンを追加して場所を表示する
クライアント アプリで、場所の Places UI Kit 要素を作成する前に、空でないトークン文字列のイテラブル（配列など）を Settings.getInstance().addContentTokens() に渡します。単一の文字列を直接渡した場合、またはイテラブルに空の文字列が含まれている場合、このメソッドはエラーをスローします。次の例では、トークンを追加してから、各場所の 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 は、サポートされている要素からの各リクエストとともに、保存されているすべてのトークンを送信します。
1 つの要素に複数の場所を表示するには、高度なプレイスリスト要素の places プロパティを、トークンを追加した 1 つ以上のレスポンスのプレイス ID に設定します。
トークン検証
次の条件をすべて満たす場合、Places UI キットのリクエストは課金されません。
- 同じプロジェクト: トークンは、Maps JavaScript API の読み込みに使用する API キーを所有する Google Cloud プロジェクトに発行されました。
- 根拠のある場所: 要素がリクエストするすべての場所が、追加した少なくとも 1 つのトークンでカバーされている。各レスポンスのトークンを追加すると、1 つの要素に複数のレスポンスの場所を含めることができます。
- 期限切れでないトークン: 各場所について、その場所をカバーするトークンが発行されてから 10 分以内にリクエストが行われている。
- サポートされている要素: リクエストがサポートされている Places UI キット要素から送信されている。
場所ではなく、PlaceDetailsLocationRequestElement などの位置情報で構成する要素は対象外です。Advanced Place List 要素に、対象外の場所が含まれている場合、リクエスト全体が課金対象となります。
いずれかの条件が満たされない場合でも、要素は読み込まれ、リクエストは SKU の標準料金で請求されます。トークンが無効な場合、Maps JavaScript API はエラーを返しません。
課金
Maps Experience エージェント ツール リクエストごとに、標準料金が適用されます。トークン検証に合格した Places UI キットのリクエストは課金されませんが、Places UI キットの割り当てにはカウントされます。トークン検証に合格しなかった Places UI キットのリクエストには、Places UI キットのクエリまたは Places UI キット Pro（Advanced）の SKU の標準料金が適用されます。
料金については、メインの料金表とインドの料金表をご覧ください。
使用要件
単一ユーザー、アクティブ レスポンスのみの使用: エージェント型データ可視化トークンは、サポートされている Places UI キット要素を同じエンドユーザーに表示する場合にのみ使用する必要があります。また、トークンを生成した即時のエージェント型レスポンス内でのみ使用する必要があります。複数のエンドユーザー間でトークンを共有、プール、再利用したり、トークンを使用してそのレスポンス以外の場所（保存済みリスト、ブックマーク、キャッシュされたディレクトリなど）に場所を表示したりすることはできません。
エージェント データ可視化トークンの使用には、サービス固有の規約を含む Google Maps Platform 利用規約が適用されます。Maps Experience エージェント ツールの帰属表示要件も適用されます。