Token di visualizzazione dei dati agentica

Il token di visualizzazione dei dati agentica 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 o search_along_route 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:

1. L'agente chiama lo strumento search_places o search_along_route sul server MCP degli strumenti dell'agente Maps Experience. La risposta dello strumento include i luoghi che supportano il riepilogo e un token nel campo contentToken.
2. 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.
3. La tua app client aggiunge il token all'API Maps JavaScript e crea elementi del kit UI di Places per questi luoghi.
4. 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 dei tool di 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 degli agenti, 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 ai tool agentici di Experimente Maps sia per l'API Maps JavaScript. Un token è valido solo per le richieste Places UI Kit del 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

Gli strumenti search_places e search_along_route restituiscono il token nel campo contentToken. Nel risultato di una richiesta MCP tools/call, questo campo è in structuredContent. In una risposta dal metodo REST searchText o searchAlongRoute, è un campo di primo livello. Una risposta search_places è simile alla seguente (una risposta search_along_route restituisce ogni luogo all'interno di results[].place):

{
  "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 l'agente effettua chiamate agentiche search_places o search_along_route 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

Nell'app client, passa un iterabile (ad esempio un array) di stringhe di token non vuote a Settings.getInstance().addContentTokens() prima di creare 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 or search_along_route 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ù di una risposta, 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 di 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 fatturata l'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 tool agentici 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 principali 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 agentica è soggetto ai Termini di servizio di Google Maps Platform, inclusi i Termini specifici dei servizi. Si applicano anche i requisiti di attribuzione per i tool agentici di Maps Experience.