에이전트형 데이터 시각화 토큰을 사용하면 에이전트형 앱에서 추가 비용 없이 지도 환경 에이전트 도구 (이전의 Grounding Lite) 응답의 장소에 대한 장소 UI 키트 요소를 표시할 수 있습니다. search_places 도구를 성공적으로 호출할 때마다 Essentials 및 Pro SKU 모두에 대해 응답에서 장소를 식별하는 토큰이 반환됩니다. 클라이언트 앱이 Maps JavaScript API에 토큰을 추가하면 토큰이 발급된 후 10분 동안 해당 장소에 대한 장소 UI 키트 요청에 요금이 청구되지 않습니다.
작동 방식
토큰은 그라운딩된 대답을 함께 표시하는 장소 세부정보에 연결합니다.
- 에이전트가 지도 환경 에이전트 도구 MCP 서버에서
search_places도구를 호출합니다. 도구 응답에는 요약을 지원하는 장소와contentToken필드의 토큰이 포함됩니다. - 앱은 도구 응답에서 토큰을 읽고 표시하려는 장소의 ID와 함께 클라이언트 앱으로 전송합니다.
- 클라이언트 앱은 토큰을 Maps JavaScript API에 추가하고 해당 장소의 장소 UI 키트 요소를 만듭니다.
- Google Maps Platform은 각 장소 UI 키트 요청에서 토큰을 검증합니다. 토큰이 유효하면 요청에 대한 요금이 청구되지 않습니다.
지원되는 장소 UI 키트 요소
이 토큰은 Maps JavaScript API의 다음 장소 UI 키트 요소에 적용됩니다.
토큰은 장소 검색, 고급 장소 검색, 기본 장소 자동 완성 요소, Places API 요청, 지도 로드와 같은 다른 요청에는 적용되지 않습니다. 이러한 요청은 표준 요금으로 청구됩니다.
지도 환경 에이전트 도구 응답에만 토큰이 포함됩니다. 장소 UI 키트를 사용하여 Google 지도 기반 그라운딩 응답의 장소를 표시하는 경우 해당 요청은 표준 요율로 청구됩니다.
시작하기 전에
에이전트 데이터 시각화 토큰을 사용하기 전에 다음을 설정하세요.
- Maps Experience 에이전트 도구 API(
mapstools.googleapis.com) 및 장소 UI 키트 API가 사용 설정된 Google Cloud 프로젝트 자세한 내용은 MCP 서버를 사용하도록 LLM 구성 및 장소 UI 키트 시작하기를 참고하세요. - 지도 환경 에이전트 도구 호출과 Maps JavaScript API 모두에 대한 해당 프로젝트의 사용자 인증 정보 토큰은 토큰이 발급된 프로젝트의 장소 UI 키트 요청에만 유효합니다.
v=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용 에이전트 개발 키트 (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 예시를 참고하세요.
토큰 추가 및 장소 표시
클라이언트 앱에서 장소의 장소 UI 키트 요소를 만들기 전에 비어 있지 않은 토큰 문자열의 반복 가능한 객체 (예: 배열)를 Settings.getInstance().addContentTokens()에 전달합니다. 단일 문자열을 직접 전달하거나 이터러블에 빈 문자열이 포함된 경우 이 메서드는 오류를 발생시킵니다. 다음 예에서는 토큰을 추가한 다음 각 장소의 장소 세부정보 간소화 요소를 표시합니다.
// 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로 설정합니다.
토큰 검증
다음 조건이 모두 충족되면 장소 UI 키트 요청에 대한 요금이 청구되지 않습니다.
- 동일한 프로젝트: Maps JavaScript API를 로드하는 데 사용하는 API 키를 소유한 Google Cloud 프로젝트에 토큰이 발급되었습니다.
- 그라운딩된 장소: 요소가 요청하는 모든 장소는 추가한 토큰 중 하나 이상으로 처리됩니다. 각 응답의 토큰을 추가하면 요소에 여러 응답의 장소가 포함될 수 있습니다.
- 만료되지 않은 토큰: 각 장소에 대해 장소를 포함하는 토큰이 발급된 후 10분 이내에 요청이 이루어집니다.
- 지원되는 요소: 요청이 지원되는 장소 UI 키트 요소에서 발생합니다.
장소 대신 위치로 구성하는 요소(예: PlaceDetailsLocationRequestElement)는 포함되지 않습니다. 고급 장소 목록 요소에 포함되지 않은 장소가 포함된 경우 전체 요청에 요금이 청구됩니다.
조건이 충족되지 않으면 요소가 계속 로드되고 요청은 SKU의 표준 요율로 청구됩니다. Maps JavaScript API는 토큰이 유효하지 않을 때 오류를 반환하지 않습니다.
결제
각 지도 환경 에이전트 도구 요청에 대해 표준 요금이 부과됩니다. 토큰 유효성 검사를 통과하는 장소 UI 키트 요청은 청구되지 않지만 장소 UI 키트 할당량에 반영됩니다. 토큰 검증을 통과하지 못한 장소 UI 키트 요청에는 장소 UI 키트 쿼리 또는 장소 UI 키트 Pro (고급) SKU의 표준 요금이 청구됩니다.
사용 요구사항
단일 사용자, 활성 응답 전용: 에이전트 데이터 시각화 토큰은 동일한 최종 사용자에게 지원되는 장소 UI 키트 요소를 표시하고 토큰을 생성한 즉각적인 에이전트 응답 내에서만 사용해야 합니다. 여러 최종 사용자 간에 토큰을 공유, 풀링 또는 재사용하거나 토큰을 사용하여 해당 응답 외부의 장소 (예: 저장된 목록, 북마크 또는 캐시된 디렉터리)를 표시해서는 안 됩니다.
에이전트 데이터 시각화 토큰 사용에는 서비스별 약관을 포함한 Google Maps Platform 서비스 약관이 적용됩니다. 지도 환경 에이전트 도구의 저작자 표시 요구사항도 적용됩니다.