Token wizualizacji danych agentowych umożliwia aplikacji agentowej bezpłatne wyświetlanie elementów interfejsu Places UI Kit w przypadku miejsc w odpowiedzi narzędzi agentowych Maps Experience (dawniej Maps Grounding Lite). Każde udane wywołanie narzędzia search_places zwraca token, który identyfikuje miejsca w odpowiedzi, zarówno w przypadku SKU Essentials, jak i Pro. Gdy aplikacja kliencka doda token do interfejsu Maps JavaScript API, żądania Places UI Kit dotyczące tych miejsc nie będą rozliczane przez 10 minut od wydania tokena.
Jak to działa
Token łączy odpowiedź opartą na faktach ze szczegółami miejsca, które wyświetlasz:
- Agent wywołuje narzędzie
search_placesna serwerze MCP narzędzi agenta Maps Experience. Odpowiedź narzędzia zawiera miejsca, które obsługują podsumowanie, oraz token w polucontentToken. - Aplikacja odczytuje token z odpowiedzi narzędzia i wysyła go do aplikacji klienckiej wraz z identyfikatorami miejsc, które chcesz wyświetlić.
- Aplikacja kliencka dodaje token do interfejsu Maps JavaScript API i tworzy elementy Places UI Kit dla tych miejsc.
- Google Maps Platform weryfikuje token przy każdym żądaniu Places UI Kit. Jeśli token jest ważny, żądanie nie jest rozliczane.
Obsługiwane elementy Places UI Kit
Token dotyczy tych elementów interfejsu Places UI Kit w Maps JavaScript API:
Token nie ma zastosowania do innych żądań, takich jak żądania z elementów wyszukiwania miejsc, zaawansowanego wyszukiwania miejsc i podstawowego autouzupełniania miejsc, żądania do interfejsu Places API i wczytywania map. Te żądania są rozliczane według standardowych stawek.
Token zawierają tylko odpowiedzi narzędzi agenta Maps Experience. Jeśli wyświetlasz miejsca z odpowiedzi powiązanej ze źródłami informacji przy użyciu Map Google za pomocą Places UI Kit, te żądania są rozliczane według standardowych stawek.
Zanim zaczniesz
Zanim użyjesz tokena wizualizacji danych agenta, skonfiguruj te elementy:
- Projekt Google Cloud z włączonym interfejsem Maps Experience agent tools API (
mapstools.googleapis.com) i interfejsem Places UI Kit API. Więcej informacji znajdziesz w artykułach Konfigurowanie LLM-ów do korzystania z serwera MCP i Pierwsze kroki z Places UI Kit. - dane logowania z tego projektu zarówno do wywołań narzędzi agenta Maps Experience, jak i do interfejsu Maps JavaScript API. Token jest ważny tylko w przypadku żądań Places UI Kit z projektu, dla którego został wydany.
- Aplikacja kliencka, która wczytuje interfejs Maps JavaScript API z wersji beta przez ustawienie
v=beta.
Wyświetlanie miejsc na podstawie odpowiedzi opartej na źródłach
W poniższych sekcjach dowiesz się, jak pobrać token z odpowiedzi narzędzia i użyć go w aplikacji klienckiej. Jeśli używasz zestawu agentowych narzędzi interfejsu Map (wersja eksperymentalna), jego agent i klient internetowy wykonają te czynności za Ciebie.
Pobieranie tokena z odpowiedzi narzędzia
Narzędzie search_places zwraca token w polu contentToken. W wyniku żądania MCP tools/call to pole znajduje się w structuredContent. Odpowiedź narzędzia jest podobna do tej:
{ "places": [ { "place": "places/PLACE_ID", "id": "PLACE_ID", ... } ], ... "contentToken": "CONTENT_TOKEN" }
Te dane wyjściowe zawierają te wartości:
PLACE_ID: identyfikator miejsca w odpowiedzi.CONTENT_TOKEN: token wizualizacji danych agentowych dla miejsc w odpowiedzi. Traktuj token jako nieprzezroczysty ciąg znaków i nie modyfikuj go.
Jeśli odpowiedź nie zawiera żadnych miejsc, nie zawiera też tokena.
W kodzie aplikacji odczytaj token z odpowiedzi narzędzia – na przykład w wywołaniu zwrotnym narzędzia w platformie agenta – i wyślij go do aplikacji klienckiej wraz z identyfikatorami miejsc. Nie polegaj na LLM, aby powtórzyć token w danych wyjściowych, ponieważ model może go zmienić.
Token obejmuje tylko miejsca w odpowiedzi, w której się znajduje. Jeśli agent wywoła narzędzie search_places więcej niż raz, wyślij każdy token do aplikacji klienckiej.
Jeśli na przykład używasz pakietu Agent Development Kit (ADK) w Pythonie, możesz zapisać każdy token w wywołaniu zwrotnym po użyciu narzędzia:
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
Przekaż tę funkcję jako argument after_tool_callback podczas tworzenia agenta, a następnie wyślij zapisane tokeny do aplikacji klienckiej z odpowiedzią agenta. Pełne definicje agentów znajdziesz w przykładach ADK w sekcji Konfigurowanie LLM do korzystania z serwera MCP.
Dodawanie tokena i wyświetlanie miejsc
W aplikacji klienckiej przekaż do Settings.getInstance().addContentTokens() iterowalny obiekt (np. tablicę) niepustych ciągów znaków tokenów, zanim utworzysz elementy interfejsu Places UI Kit dla miejsc. Metoda zgłasza błąd, jeśli bezpośrednio przekażesz pojedynczy ciąg znaków lub jeśli obiekt iterowalny zawiera pusty ciąg znaków. Ten przykład dodaje token, a następnie wyświetla element informacji o miejscu (kompaktowe) dla każdego miejsca:
// 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);
}
}
Tokeny wygasają po 10 minutach od ich wydania. Maps JavaScript API przechowuje dodane przez Ciebie tokeny w pamięci bieżącej strony i automatycznie usuwa je po wygaśnięciu, więc nie musisz samodzielnie usuwać wygasłych tokenów. Jeśli dodasz tokeny z więcej niż 1 odpowiedzi, interfejs API będzie wysyłać wszystkie przechowywane tokeny z każdym żądaniem z obsługiwanego elementu.
Aby wyświetlić kilka miejsc w jednym elemencie, ustaw właściwość places elementu Zaawansowana lista miejsc na identyfikatory miejsc z co najmniej 1 odpowiedzi, której tokeny zostały dodane.
Weryfikacja tokena
Żądanie do interfejsu Places UI Kit nie jest rozliczane, gdy spełnione są wszystkie te warunki:
- Ten sam projekt w chmurze: tokeny zostały wydane dla projektu Google Cloud, który jest właścicielem klucza interfejsu API używanego do wczytywania interfejsu Maps JavaScript API.
- Miejsca ugruntowane: każde miejsce, o które prosi element, jest objęte co najmniej 1 dodanym przez Ciebie tokenem. Element może zawierać miejsca z wielu odpowiedzi, jeśli dodasz token z każdej odpowiedzi.
- Tokeny, które nie wygasły: w przypadku każdego miejsca żądanie jest wysyłane w ciągu 10 minut od wydania tokena, który obejmuje to miejsce.
- Obsługiwany element: żądanie pochodzi z obsługiwanego elementu Places UI Kit.
Nie obejmuje to elementów, które konfigurujesz za pomocą lokalizacji, a nie miejsca, np. PlaceDetailsLocationRequestElement. Jeśli element zaawansowanej listy miejsc zawiera miejsce, które nie jest objęte, całe żądanie jest rozliczane.
Jeśli którykolwiek z warunków nie zostanie spełniony, element i tak się wczyta, a żądanie zostanie rozliczone według standardowej stawki dla danego SKU. Interfejs Maps JavaScript API nie zwraca błędu, gdy token jest nieprawidłowy.
Płatności
Za każde żądanie narzędzi agenta Maps Experience płacisz według standardowej stawki. Żądania do Places UI Kit, które przejdą weryfikację tokena, nie są rozliczane, ale nadal wliczają się do limitu Places UI Kit. Żądania Places UI Kit, które nie przejdą weryfikacji tokena, są rozliczane według standardowej stawki za SKU Zapytanie do Places UI Kit lub Places UI Kit Pro (Advanced).
Ceny znajdziesz w głównej tabeli cen i tabeli cen w Indiach.
Wymagania dotyczące użytkowania
Tylko do użytku przez jednego użytkownika i w ramach aktywnej odpowiedzi: tokena wizualizacji danych agenta możesz używać tylko do wyświetlania obsługiwanych elementów Places UI Kit temu samemu użytkownikowi i w ramach natychmiastowej odpowiedzi agenta, która wygenerowała token. Nie wolno udostępniać, łączyć ani ponownie używać tokenów dla wielu użytkowników ani używać tokena do wyświetlania miejsc poza tą odpowiedzią (np. na zapisanych listach, w zakładkach lub katalogach w pamięci podręcznej).
Korzystanie z tokena wizualizacji danych agentowych podlega Warunkom korzystania z usługi Google Maps Platform, w tym szczegółowym warunkom korzystania z usługi. Obowiązują też wymagania dotyczące podawania źródła w przypadku narzędzi agenta Maps Experience.