Le jeton de visualisation des données agentiques permet à votre application agentique d'afficher des éléments du kit UI pour Places pour les lieux d'une réponse des outils d'agent Maps Experience (anciennement Maps Grounding Lite) sans frais supplémentaires. Chaque appel réussi à l'outil search_places renvoie un jeton qui identifie les lieux dans la réponse, pour les SKU Essentials et Pro. Lorsque votre application cliente ajoute le jeton à l'API Maps JavaScript, les requêtes du kit UI pour Places pour ces lieux ne sont pas facturées pendant 10 minutes après l'émission du jeton.
Fonctionnement
Le jeton associe une réponse ancrée aux détails du lieu que vous affichez avec :
- Votre agent appelle l'outil
search_placessur le serveur MCP des outils de l'agent Maps Experience. La réponse de l'outil inclut les lieux qui acceptent le résumé et un jeton dans le champcontentToken. - Votre application lit le jeton à partir de la réponse de l'outil et l'envoie à votre application cliente, ainsi que les ID des lieux que vous souhaitez afficher.
- Votre application cliente ajoute le jeton à l'API Maps JavaScript et crée des éléments du kit UI pour Places pour ces lieux.
- Google Maps Platform valide le jeton à chaque requête du Kit UI pour Places. Si le jeton est valide, la requête n'est pas facturée.
Éléments du Kit UI pour Places compatibles
Le jeton s'applique aux éléments suivants du Kit UI pour Places dans l'API Maps JavaScript :
Le jeton ne s'applique pas aux autres requêtes, telles que celles provenant des éléments Place Search, Advanced Place Search et Basic Place Autocomplete, des requêtes de l'API Places et des chargements de cartes. Ces requêtes sont facturées aux tarifs standards.
Seules les réponses des outils de l'agent Maps Experience incluent le jeton. Si vous affichez des lieux à partir d'une réponse d'ancrage avec Google Maps à l'aide du kit UI pour Places, ces requêtes sont facturées aux tarifs standards.
Avant de commencer
Avant d'utiliser le jeton de visualisation des données agentique, configurez les éléments suivants :
- Un projet Google Cloud avec l'API Maps Experience agent tools (
mapstools.googleapis.com) et l'API Kit UI pour Places activées. Pour en savoir plus, consultez Configurer les LLM pour utiliser le serveur MCP et Premiers pas avec le kit UI pour Places. - Les identifiants de ce projet pour les appels des outils de l'agent Maps Experience et l'API Maps JavaScript. Un jeton n'est valide que pour les requêtes du kit UI pour Places provenant du projet pour lequel le jeton a été émis.
- Une application cliente qui charge l'API Maps JavaScript à partir de la version bêta en définissant
v=beta.
Afficher des lieux à partir d'une réponse ancrée
Les sections suivantes expliquent comment obtenir le jeton à partir de la réponse de l'outil et l'utiliser dans votre application cliente. Si vous utilisez le Maps Agentic UI Toolkit (expérimental), son agent et son client Web gèrent ces étapes pour vous.
Obtenir le jeton à partir de la réponse de l'outil
L'outil search_places renvoie le jeton dans le champ contentToken. Dans le résultat d'une requête MCP tools/call, ce champ se trouve dans structuredContent. La réponse de l'outil est semblable à celle-ci :
{ "places": [ { "place": "places/PLACE_ID", "id": "PLACE_ID", ... } ], ... "contentToken": "CONTENT_TOKEN" }
Ce résultat inclut les valeurs suivantes :
PLACE_ID: ID de lieu d'un lieu dans la réponse.CONTENT_TOKEN: jeton de visualisation des données agentiques pour les lieux de la réponse. Traitez le jeton comme une chaîne opaque et ne le modifiez pas.
Si la réponse n'inclut aucun lieu, elle n'inclut pas de jeton.
Dans le code de votre application, lisez le jeton à partir de la réponse de l'outil (par exemple, dans un rappel d'outil dans votre framework d'agent) et envoyez-le à votre application cliente avec les ID de lieu. Ne comptez pas sur le LLM pour répéter le jeton dans sa sortie, car le modèle peut le modifier.
Un jeton ne couvre que les lieux de sa propre réponse. Si votre agent appelle l'outil search_places plusieurs fois, envoyez chaque jeton à votre application cliente.
Par exemple, si vous utilisez l'Agent Development Kit (ADK) pour Python, vous pouvez enregistrer chaque jeton dans un rappel après l'outil :
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
Transmettez cette fonction en tant qu'argument after_tool_callback lorsque vous créez votre agent, puis envoyez les jetons enregistrés à votre application cliente avec la réponse de l'agent. Pour obtenir des définitions d'agent complètes, consultez les exemples ADK dans Configurer les LLM pour qu'ils utilisent le serveur MCP.
Ajouter le jeton et afficher les lieux
Dans votre application cliente, transmettez un itérable (comme un tableau) de chaînes de jetons non vides à Settings.getInstance().addContentTokens() avant de créer des éléments du kit UI pour Places pour les lieux. La méthode génère une erreur si vous transmettez directement une seule chaîne ou si l'itérable inclut une chaîne vide. L'exemple suivant ajoute un jeton, puis affiche un élément Place Details Compact pour chaque lieu :
// 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);
}
}
Les jetons expirent 10 minutes après leur émission. L'API Maps JavaScript conserve les jetons que vous ajoutez en mémoire pour la page actuelle et les supprime automatiquement après leur expiration. Vous n'avez donc pas besoin de supprimer vous-même les jetons arrivés à expiration. Si vous ajoutez des jetons provenant de plusieurs réponses, l'API envoie tous les jetons stockés avec chaque requête provenant d'un élément compatible.
Pour afficher plusieurs lieux dans un seul élément, définissez la propriété places d'un élément Liste de lieux avancée sur les ID de lieu d'une ou de plusieurs réponses dont vous avez ajouté les jetons.
Validation des jetons
Une requête Places UI Kit n'est pas facturée lorsque toutes les conditions suivantes sont remplies :
- Même projet : les jetons ont été émis pour le projet Google Cloud propriétaire de la clé API que vous utilisez pour charger l'API Maps JavaScript.
- Lieux ancrés : chaque lieu demandé par l'élément est couvert par au moins un jeton que vous avez ajouté. Un élément peut inclure des lieux provenant de plusieurs réponses si vous ajoutez le jeton de chaque réponse.
- Jetons non arrivés à expiration : pour chaque lieu, la requête est effectuée dans les 10 minutes suivant l'émission d'un jeton couvrant le lieu.
- Élément compatible : la requête provient d'un élément compatible du Kit UI pour Places.
Les éléments que vous configurez avec un emplacement au lieu d'un lieu, par exemple avec un PlaceDetailsLocationRequestElement, ne sont pas couverts. Si un élément Advanced Place List inclut un lieu qui n'est pas couvert, l'intégralité de la requête est facturée.
Si l'une des conditions n'est pas remplie, l'élément se charge quand même et la requête est facturée au tarif standard de son SKU. L'API Maps JavaScript ne renvoie pas d'erreur lorsqu'un jeton n'est pas valide.
Facturation
Chaque requête d'outils d'agent Maps Experience vous est facturée au tarif standard. Les requêtes du Kit UI pour Places qui réussissent la validation du jeton ne sont pas facturées, mais elles sont comptabilisées dans votre quota du Kit UI pour Places. Les requêtes du Kit UI pour Places qui ne passent pas la validation du jeton sont facturées au tarif standard pour le SKU Places UI Kit Query ou Places UI Kit Pro (Advanced).
Pour connaître les tarifs, consultez la grille tarifaire principale et la grille tarifaire pour l'Inde.
Conditions d'utilisation
Utilisation réservée à un seul utilisateur et à une réponse active : vous ne devez utiliser un jeton de visualisation des données d'agent que pour afficher les éléments compatibles du kit UI pour Places au même utilisateur final et dans la réponse immédiate de l'agent qui a généré le jeton. Vous ne devez pas partager, regrouper ni réutiliser des jetons entre plusieurs utilisateurs finaux, ni utiliser un jeton pour afficher des lieux en dehors de cette réponse (par exemple, dans des listes enregistrées, des favoris ou des répertoires mis en cache).
Votre utilisation du jeton de visualisation des données agentiques est soumise aux Conditions d'utilisation de Google Maps Platform, y compris aux Conditions d'utilisation spécifiques au service. Les exigences d'attribution pour les outils d'agent Maps Experience s'appliquent également.