Mit dem Token für die agentische Datenvisualisierung kann Ihre agentische App Places UI Kit-Elemente für die Orte in einer Antwort von Maps Experience-Agententools (früher Maps Grounding Lite) ohne zusätzliche Kosten anzeigen. Bei jedem erfolgreichen Aufruf des search_places-Tools wird ein Token zurückgegeben, mit dem die Orte in der Antwort identifiziert werden, sowohl für die Essentials- als auch für die Pro-SKU. Wenn Ihre Client-App das Token der Maps JavaScript API hinzufügt, werden Places UI Kit-Anfragen für diese Orte 10 Minuten lang nach der Ausstellung des Tokens nicht in Rechnung gestellt.
Funktionsweise
Das Token verbindet eine fundierte Antwort mit den Place Details, die Sie damit anzeigen:
- Ihr Agent ruft das Tool
search_placesauf dem MCP-Server für Maps Experience-Agent-Tools auf. Die Toolantwort enthält die Orte, die die Zusammenfassung unterstützen, und ein Token im FeldcontentToken. - Ihre App liest das Token aus der Antwort des Tools und sendet es zusammen mit den IDs der Orte, die Sie anzeigen möchten, an Ihre Client-App.
- Ihre Client-App fügt das Token der Maps JavaScript API hinzu und erstellt Places UI Kit-Elemente für diese Orte.
- Die Google Maps Platform validiert das Token bei jeder Places UI Kit-Anfrage. Wenn das Token gültig ist, wird die Anfrage nicht in Rechnung gestellt.
Unterstützte Places UI Kit-Elemente
Das Token gilt für die folgenden Places UI Kit-Elemente in der Maps JavaScript API:
Das Token gilt nicht für andere Anfragen, z. B. Anfragen von den Elementen „Place Search“, „Advanced Place Search“ und „Basic Place Autocomplete“, Places API-Anfragen und Kartenaufrufe. Diese Anfragen werden zu Standardtarifen abgerechnet.
Das Token ist nur in Antworten von Maps Experience-Agent-Tools enthalten. Wenn Sie Orte aus einer Antwort von Fundierung mit Google Maps mit dem Places UI Kit anzeigen, werden diese Anfragen zu Standardtarifen abgerechnet.
Hinweis
Bevor Sie das agentische Datenvisualisierungs-Token verwenden können, müssen Sie Folgendes einrichten:
- Ein Google Cloud-Projekt, in dem die Maps Experience Agent Tools API (
mapstools.googleapis.com) und die Places UI Kit API aktiviert sind. Weitere Informationen finden Sie unter LLMs für die Verwendung des MCP-Servers konfigurieren und Erste Schritte mit dem Places UI Kit. - Anmeldedaten aus diesem Projekt sowohl für die Aufrufe der Maps Experience-Agent-Tools als auch für die Maps JavaScript API. Ein Token ist nur für Places UI Kit-Anfragen aus dem Projekt gültig, für das das Token ausgestellt wurde.
- Eine Client-App, die die Maps JavaScript API aus der Betaversion lädt, indem
v=betafestgelegt wird.
Orte aus einer fundierten Antwort anzeigen
In den folgenden Abschnitten wird beschrieben, wie Sie das Token aus der Toolantwort abrufen und in Ihrer Client-Anwendung verwenden. Wenn Sie das Maps Agentic UI Toolkit (experimentell) verwenden, werden diese Schritte vom Agenten und Webclient des Toolkits für Sie ausgeführt.
Token aus der Toolantwort abrufen
Das Tool search_places gibt das Token im Feld contentToken zurück. Im Ergebnis einer MCP-tools/call-Anfrage befindet sich dieses Feld in structuredContent. Die Antwort des Tools sieht in etwa so aus:
{ "places": [ { "place": "places/PLACE_ID", "id": "PLACE_ID", ... } ], ... "contentToken": "CONTENT_TOKEN" }
Diese Ausgabe enthält die folgenden Werte:
PLACE_ID: Die Orts-ID eines Orts in der Antwort.CONTENT_TOKEN: Das agentische Datenvisualisierungstoken für die Orte in der Antwort. Behandeln Sie das Token als intransparenten String und ändern Sie es nicht.
Wenn die Antwort keine Orte enthält, enthält sie auch kein Token.
Lesen Sie in Ihrem Anwendungscode das Token aus der Toolantwort, z. B. in einem Tool-Callback in Ihrem Agenten-Framework, und senden Sie es zusammen mit den Orts-IDs an Ihre Clientanwendung. Verlassen Sie sich nicht darauf, dass das LLM das Token in seiner Ausgabe wiederholt, da das Modell das Token ändern kann.
Ein Token deckt nur die Orte in der eigenen Antwort ab. Wenn Ihr Agent das Tool search_places mehrmals aufruft, senden Sie jedes Token an Ihre Client-Anwendung.
Wenn Sie beispielsweise das Agent Development Kit (ADK) für Python verwenden, können Sie jedes Token in einem After-Tool-Callback speichern:
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
Übergeben Sie diese Funktion als after_tool_callback-Argument, wenn Sie Ihren Agenten erstellen, und senden Sie die gespeicherten Tokens dann mit der Antwort des Agenten an Ihre Client-Anwendung. Vollständige Agentendefinitionen finden Sie in den ADK-Beispielen unter LLMs für die Verwendung des MCP-Servers konfigurieren.
Token hinzufügen und Orte anzeigen
Übergeben Sie in Ihrer Client-App ein iterierbares Objekt (z. B. ein Array) mit nicht leeren Token-Strings an Settings.getInstance().addContentTokens(), bevor Sie Places UI Kit-Elemente für die Orte erstellen. Die Methode gibt einen Fehler aus, wenn Sie einen einzelnen String direkt übergeben oder wenn das iterierbare Objekt einen leeren String enthält. Im folgenden Beispiel wird ein Token hinzugefügt und dann für jeden Ort ein kompaktes Place Details-Element angezeigt:
// 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);
}
}
Tokens laufen 10 Minuten nach ihrer Ausstellung ab. Die Maps JavaScript API speichert die von Ihnen hinzugefügten Tokens für die aktuelle Seite im Arbeitsspeicher und entfernt sie automatisch, wenn sie ablaufen. Sie müssen abgelaufene Tokens also nicht selbst entfernen. Wenn Sie Tokens aus mehreren Antworten hinzufügen, sendet die API alle gespeicherten Tokens mit jeder Anfrage von einem unterstützten Element.
Wenn Sie mehrere Orte in einem Element anzeigen möchten, legen Sie das Attribut places eines Elements für erweiterte Ortslisten auf die Orts-IDs aus einer oder mehreren Antworten fest, deren Tokens Sie hinzugefügt haben.
Tokenvalidierung
Eine Places UI Kit-Anfrage wird nicht in Rechnung gestellt, wenn alle folgenden Bedingungen erfüllt sind:
- Gleiches Projekt: Die Tokens wurden für das Google Cloud-Projekt ausgestellt, zu dem der API-Schlüssel gehört, den Sie zum Laden der Maps JavaScript API verwenden.
- Fundierte Orte: Jeder Ort, den das Element anfordert, wird durch mindestens ein von Ihnen hinzugefügtes Token abgedeckt. Ein Element kann Orte aus mehreren Antworten enthalten, wenn Sie das Token aus jeder Antwort hinzufügen.
- Nicht abgelaufene Tokens: Für jeden Ort wird die Anfrage innerhalb von 10 Minuten nach der Ausstellung eines Tokens gestellt, das den Ort abdeckt.
- Unterstütztes Element: Die Anfrage stammt von einem unterstützten Places UI Kit-Element.
Elemente, die Sie mit einem Standort anstelle eines Orts konfigurieren, z. B. mit einem PlaceDetailsLocationRequestElement, sind nicht abgedeckt. Wenn ein Element der erweiterten Ortsliste einen Ort enthält, der nicht abgedeckt ist, wird die gesamte Anfrage in Rechnung gestellt.
Wenn eine Bedingung nicht erfüllt ist, wird das Element trotzdem geladen und die Anfrage wird zum Standardtarif für die entsprechende SKU abgerechnet. Die Maps JavaScript API gibt keinen Fehler zurück, wenn ein Token ungültig ist.
Abrechnung
Sie bezahlen für jede Anfrage an die Agent-Tools von Maps Experience den Standardpreis. Places UI Kit-Anfragen, die die Tokenvalidierung bestehen, werden nicht in Rechnung gestellt, aber auf Ihr Places UI Kit-Kontingent angerechnet. Places UI Kit-Anfragen, die die Tokenvalidierung nicht bestehen, werden zum Standardtarif für die SKU Places UI Kit Query oder Places UI Kit Pro (Advanced) abgerechnet.
Die Preise finden Sie in der Hauptpreistabelle und der Preistabelle für Indien.
Nutzungsanforderungen
Nur für die Verwendung durch einen einzelnen Nutzer und für eine aktive Antwort: Sie dürfen ein Token für die agentische Datenvisualisierung nur verwenden, um unterstützte Places UI Kit-Elemente für denselben Endnutzer und innerhalb der unmittelbaren agentischen Antwort anzuzeigen, die das Token generiert hat. Sie dürfen Tokens nicht für mehrere Endnutzer freigeben, bündeln oder wiederverwenden oder ein Token verwenden, um Orte außerhalb dieser Antwort anzuzeigen (z. B. in gespeicherten Listen, Lesezeichen oder im Cache gespeicherten Verzeichnissen).
Ihre Nutzung des Tokens für die agentische Datenvisualisierung unterliegt den Nutzungsbedingungen für die Google Maps Platform, einschließlich der dienstspezifischen Bedingungen. Die Anforderungen an die Quellenangabe für Agent-Tools für Maps Experience gelten ebenfalls.