エージェント データ可視化トークン

エージェント データ可視化トークンを使用すると、エージェント アプリは、Maps Experience エージェント ツール(旧称 Maps Grounding Lite)のレスポンスに含まれる場所の Places UI キット 要素を追加料金なしで表示できます。search_places ツールまたは search_along_route ツールへの呼び出しが成功するたびに、Essentials SKU と Pro SKU の両方で、レスポンス内の場所を識別するトークンが返されます。クライアント アプリが Maps JavaScript API、Places SDK for Android、または Places SDK for iOS にトークンを追加すると、Places UI キット によるそれらの場所のリクエストは、トークンの発行後 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 キットのリクエストごとにトークンを検証します。トークンが有効な場合、リクエストは課金されません。

サポートされている Places UI キットの要素

Maps JavaScript API

このトークンは、Maps JavaScript API の次の Places UI キット要素に適用されます。

要素 SKU
PlaceDetailsElement Places UI キットのクエリ
PlaceDetailsCompactElement Places UI キットのクエリ
AdvancedPlaceDetailsElement Places UI Kit Pro(高度)
AdvancedPlaceDetailsCompactElement Places UI Kit Pro(高度)
AdvancedPlaceListElement Places UI Kit Pro(高度)

Places SDK for Android

フラグメント / コンポーズ可能な関数 SKU
PlaceDetailsFragment Places UI キットのクエリ
PlaceDetailsCompactFragment Places UI キットのクエリ
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 キットのクエリ
PlaceDetailsCompactView Places UI キットのクエリ
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 Experience エージェント ツールのレスポンスのみです。Google マップによるグラウンディングのレスポンスから取得した場所を Places UI キットで表示する場合、これらのリクエストは標準料金で課金されます。

始める前に

エージェント データ可視化トークンを使用する前に、次の設定を行います。

  • Maps Experience Agent Tools API(mapstools.googleapis.com)と Places UI Kit API が有効になっている Google Cloud プロジェクト。詳細については、MCP サーバーを使用するように LLM を構成すると、JavaScript、Android、iOS 向けの Places UI キットのスタートガイドをご覧ください。
  • Maps Experience Agent Tools の呼び出しと、Maps JavaScript API、Places SDK for Android、または Places SDK for iOS の両方で使用する、そのプロジェクトの認証情報。トークンは、トークンが発行されたプロジェクトからの Places UI キット リクエストに対してのみ有効です。
  • v=beta を設定して、ベータ版チャンネルから Maps JavaScript API を読み込むクライアント アプリ。モバイルの場合は、Places SDK for Android バージョン 6.1.0 以降、または Places Swift SDK(GooglePlacesSwift)バージョン 11.4.0 を使用します。

グラウンディングされた回答から場所を表示する

以降のセクションでは、ツール レスポンスからトークンを取得し、クライアント アプリで使用する方法について説明します。Google マップ エージェント型 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 引数として渡し、保存されたトークンをエージェントのレスポンスとともにクライアント アプリに送信します。エージェントの完全な定義については、MCP サーバーを使用するように LLM を構成するの ADK の例をご覧ください。

トークンを追加して場所を表示する

Maps JavaScript API

クライアント アプリで、場所の Places UI Kit 要素を作成する前に、空でないトークン文字列のイテラブル(配列など)を Settings.getInstance().addContentTokens() に渡します。単一の文字列を直接渡した場合、またはイテラブルに空の文字列が含まれている場合、このメソッドはエラーをスローします。次の例では、トークンを追加してから、各場所の Place Details Compact 要素を表示します。

// 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 は、サポートされている要素からの各リクエストとともに、保存されているすべてのトークンを送信します。

1 つの要素に複数の場所を表示するには、Advanced Place List 要素の places プロパティを、トークンを追加した 1 つ以上のレスポンスのプレイス 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 には、既存の PlaceDetailsQuery(identifier:) および PlaceMarker(identifier:...) イニシャライザに渡される専用の PlaceIdentifier 列挙型ケース(.placeIDWithTokens または .resourceNameWithTokens)が用意されています。

トークンの有効期限は発行後 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 キットのリクエストは課金されません。

  • 同じプロジェクト: トークンは、Maps JavaScript API、Places SDK for Android、Places SDK for iOS の読み込みに使用する API キーを所有する Google Cloud プロジェクトに発行されました。
  • グラウンディングされた場所: 要素がリクエストするすべての場所が、リクエストに含まれる少なくとも 1 つのトークンでカバーされています。各レスポンスのトークンを追加すると、1 つの要素に複数のレスポンスの場所を含めることができます。
  • 期限切れでないトークン: 各場所について、その場所をカバーするトークンが発行されてから 10 分以内にリクエストが行われます。
  • サポートされている要素: リクエストがサポートされている Places UI キットの要素またはコンポーネントから送信されている。

PlaceDetailsLocationRequestElement など、場所ではなく位置情報で構成する要素は対象外です。Advanced Place List 要素に、対象外の場所が含まれている場合、リクエスト全体が課金対象となります。

いずれかの条件が満たされていない場合でも、要素は読み込まれ、リクエストは SKU の標準料金で請求されます。Maps JavaScript API、Places SDK for Android、Places SDK for iOS では、トークンが無効な場合でもエラーは返されません。

上限(Places SDK for Android と Places SDK for iOS のみ)

  • 1 回のリクエストにつき最大 100 個の一意のトークンを使用できます。過剰なトークンは切り捨てられ、警告ログが生成されます。
  • トークンあたりの最大サイズは 2,048 バイト(UTF-8)です。サイズが大きすぎるトークンは警告ログとともにドロップされ、空白または重複は無視されます。
  • 座標クエリ(PlaceReference.Coordinates と PlaceIdentifier.coordinate)はトークンを受け入れません。
  • iOS AdvancedPlaceListView では、リスト内のクエリに空でないプレイス ID またはリソース名がない場合、リストのトークンは送信されません。

課金

Maps Experience エージェント ツールのリクエストごとに、標準料金が適用されます。トークン検証に合格した Places UI キットのリクエストは課金されませんが、Places UI キットの割り当てにはカウントされます。トークン検証に合格しなかった Places UI キット リクエスト、または無効なトークンや期限切れのトークンを含むリクエストは、Places UI キット クエリまたは Places UI キット Pro(Advanced)の SKU の標準料金で課金されます。

料金については、メインの料金表とインドの料金表をご覧ください。

使用要件

単一ユーザー、アクティブ レスポンスのみで使用: エージェント型データ可視化トークンは、サポートされている Places UI キット 要素を同じエンドユーザーに表示する場合にのみ使用する必要があります。また、トークンを生成した即時のエージェント型レスポンス内でのみ使用する必要があります。複数のエンドユーザー間でトークンを共有、プール、再利用したり、トークンを使用してそのレスポンス以外の場所(保存済みリスト、ブックマーク、キャッシュされたディレクトリなど)に場所を表示したりすることはできません。

エージェント データ可視化トークンの使用には、サービス固有の規約を含む Google Maps Platform 利用規約が適用されます。Maps Experience Agent Tools の帰属表示の要件も適用されます。