Il token di visualizzazione dei dati agentici consente alla tua app agentica di visualizzare gli elementi del Kit UI di Places per i luoghi in una risposta degli strumenti dell'agente di Maps Experience (precedentemente Maps Grounding Lite) senza costi aggiuntivi. Ogni chiamata riuscita allo strumento search_places restituisce un token che identifica i luoghi nella risposta, sia per gli SKU Essentials che per gli SKU Pro. Quando l'app client aggiunge il token all'API Maps JavaScript, le richieste di Places UI Kit per questi luoghi non vengono fatturate per 10 minuti dopo l'emissione del token.
Come funziona
Il token collega una risposta con grounding ai Place Details che mostri con questa:
- L'agente chiama lo strumento
search_placessul server MCP degli strumenti dell'agente Maps Experience. La risposta dello strumento include i luoghi che supportano il riepilogo e un token nel campocontentToken. - La tua app legge il token dalla risposta dello strumento e lo invia alla tua app client, insieme agli ID dei luoghi che vuoi visualizzare.
- La tua app client aggiunge il token all'API Maps JavaScript e crea elementi del Places UI Kit per questi luoghi.
- Google Maps Platform convalida il token con ogni richiesta di Places UI Kit. Se il token è valido, la richiesta non viene fatturata.
Elementi di Places UI Kit supportati
Il token si applica ai seguenti elementi di Places UI Kit nell'API Maps JavaScript:
Il token non si applica ad altre richieste, ad esempio quelle provenienti dagli elementi Place Search, Advanced Place Search e Basic Place Autocomplete, alle richieste dell'API Places e ai caricamenti delle mappe. Queste richieste vengono fatturate alle tariffe standard.
Solo le risposte degli strumenti dell'agente Experimente Maps includono il token. Se mostri i luoghi di una risposta di Grounding con Google Maps con Places UI Kit, queste richieste vengono fatturate alle tariffe standard.
Prima di iniziare
Prima di utilizzare il token di visualizzazione dei dati agentica, configura quanto segue:
- Un progetto Google Cloud con l'API Maps Experience Agent Tools (
mapstools.googleapis.com) e l'API Places UI Kit abilitate. Per saperne di più, consulta Configura gli LLM per l'utilizzo del server MCP e Inizia a utilizzare Places UI Kit. - Le credenziali di questo progetto sia per le chiamate degli strumenti dell'agente Experimente Maps sia per l'API Maps JavaScript. Un token è valido solo per le richieste del Places UI Kit provenienti dal progetto per cui è stato emesso.
- Un'app client che carica l'API Maps JavaScript dal canale beta impostando
v=beta.
Visualizza i luoghi da una risposta con grounding
Le sezioni seguenti mostrano come ottenere il token dalla risposta dello strumento e utilizzarlo nella tua app client. Se utilizzi il Maps Agentic UI Toolkit (sperimentale), l'agente e il client web gestiscono questi passaggi per te.
Ottieni il token dalla risposta dello strumento
Lo strumento search_places restituisce il token nel campo contentToken. Nel risultato di una richiesta MCP tools/call, questo campo si trova in structuredContent. La risposta dello strumento è simile alla seguente:
{ "places": [ { "place": "places/PLACE_ID", "id": "PLACE_ID", ... } ], ... "contentToken": "CONTENT_TOKEN" }
Questo output include i seguenti valori:
PLACE_ID: l'ID luogo di un luogo nella risposta.CONTENT_TOKEN: il token di visualizzazione dei dati agentici per i luoghi nella risposta. Tratta il token come una stringa opaca e non modificarlo.
Se la risposta non include luoghi, non include un token.
Nel codice dell'app, leggi il token dalla risposta dello strumento, ad esempio in un callback dello strumento nel framework dell'agente, e invialo all'app client con gli ID luogo. Non fare affidamento sull'LLM per ripetere il token nel suo output, perché il modello potrebbe modificarlo.
Un token copre solo i luoghi nella propria risposta. Se la chiamata agentica search_places chiama lo strumento più di una volta, invia ogni token alla tua app client.
Ad esempio, se utilizzi l'Agent Development Kit (ADK) per Python, puoi salvare ogni token in un callback post-strumento:
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
Passa questa funzione come argomento after_tool_callback quando crei l'agente, quindi invia i token salvati alla tua app client con la risposta dell'agente. Per le definizioni complete degli agenti, consulta gli esempi di ADK in Configura gli LLM per l'utilizzo del server MCP.
Aggiungi il token e visualizza i luoghi
Nella tua app client, passa un iterabile (ad esempio un array) di stringhe di token non vuote a Settings.getInstance().addContentTokens() prima di creare gli elementi del Places UI Kit per i luoghi. Il metodo genera un errore se passi direttamente una singola stringa o se l'iterable include una stringa vuota. L'esempio seguente aggiunge un token e poi visualizza un elemento Place Details Compact per ogni luogo:
// 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);
}
}
I token scadono 10 minuti dopo l'emissione. L'API Maps JavaScript conserva in memoria i token che aggiungi per la pagina corrente e li rimuove automaticamente dopo la scadenza, quindi non è necessario rimuovere manualmente i token scaduti. Se aggiungi token da più risposte, l'API invia tutti i token archiviati con ogni richiesta da un elemento supportato.
Per visualizzare più luoghi in un elemento, imposta la proprietà places di un
elemento Elenco di luoghi avanzato
sugli ID luogo di una o più risposte di cui hai aggiunto i token.
Convalida dei token
Una richiesta Places UI Kit non viene fatturata se vengono soddisfatte tutte le seguenti condizioni:
- Stesso progetto: i token sono stati emessi per il progetto Google Cloud proprietario della chiave API che utilizzi per caricare l'API Maps JavaScript.
- Luoghi con grounding: ogni luogo richiesto dall'elemento è coperto da almeno un token che hai aggiunto. Un elemento può includere luoghi di più risposte se aggiungi il token di ogni risposta.
- Token non scaduti: per ogni luogo, la richiesta viene effettuata entro 10 minuti dall'emissione di un token che copre il luogo.
- Elemento supportato: la richiesta proviene da un elemento Places UI Kit supportato.
Gli elementi che configuri con una località anziché con un luogo, ad esempio con un PlaceDetailsLocationRequestElement, non sono coperti. Se un elemento Advanced Place List include un luogo non coperto, viene addebitato l'importo dell'intera richiesta.
Se una condizione non viene soddisfatta, l'elemento viene comunque caricato e la richiesta viene fatturata alla tariffa standard per il relativo SKU. L'API Maps JavaScript non restituisce un errore quando un token non è valido.
Fatturazione
Paghi per ogni richiesta di strumenti per gli agenti di Experimente Maps alla tariffa standard. Le richieste di Places UI Kit che superano la convalida del token non vengono fatturate, ma vengono comunque conteggiate ai fini della quota di Places UI Kit. Le richieste di Places UI Kit che non superano la convalida del token vengono fatturate alla tariffa standard per lo SKU Places UI Kit Query o Places UI Kit Pro (Advanced).
Per i prezzi, consulta la tabella dei prezzi principale e la tabella dei prezzi per l'India.
Requisiti per l'utilizzo
Utilizzo esclusivo per un singolo utente e una risposta attiva: devi utilizzare un token di visualizzazione dei dati dell'agente solo per mostrare gli elementi supportati del Places UI Kit allo stesso utente finale e all'interno della risposta immediata dell'agente che ha generato il token. Non devi condividere, raggruppare o riutilizzare i token tra più utenti finali, né utilizzare un token per visualizzare luoghi al di fuori della risposta (ad esempio in elenchi salvati, preferiti o directory memorizzate nella cache).
L'utilizzo del token di visualizzazione dei dati agentici è soggetto ai Termini di servizio di Google Maps Platform, tra cui i Termini specifici dei servizi. Si applicano anche i requisiti di attribuzione per gli strumenti degli agenti di Maps Experience.