Token de visualização de dados agênticos

Este produto ou recurso está em pré-lançamento (pré-GA). Os produtos e recursos em pré-GA têm suporte limitado, e é possível que as mudanças neles não sejam compatíveis com versões anteriores. Os produtos e recursos em pré-GA são cobertos pelos Termos de Serviço da Plataforma Google Maps. Para mais detalhes, consulte as descrições da fase de lançamento.

Observação: o token de visualização de dados agêntica só é compatível com apps da Web que usam a API Maps JavaScript. Em breve, o Kit de Interface do Places será compatível com os SDKs do Places para Android e iOS.

O token de visualização de dados do agente permite que seu app de agente mostre elementos do Kit de interface do Places para os lugares em uma resposta das ferramentas de agente do Maps Experience (antigo Maps Grounding Lite) sem custo financeiro adicional. Cada chamada bem-sucedida para a ferramenta search_places retorna um token que identifica os lugares na resposta, tanto para as SKUs Essentials quanto para as Pro. Quando o app cliente adiciona o token à API Maps JavaScript, as solicitações do Kit de Interface do Places para esses lugares não são cobradas por 10 minutos após a emissão do token.

Como funciona

O token conecta uma resposta embasada aos Place Details que você mostra com ele:

1. Seu agente chama a ferramenta search_places no servidor MCP de ferramentas de agente da Experiência no Maps. A resposta da ferramenta inclui os lugares que dão suporte ao resumo e um token no campo contentToken.
2. O app lê o token da resposta da ferramenta e o envia ao app cliente, junto com os IDs dos lugares que você quer mostrar.
3. Seu app cliente adiciona o token à API Maps JavaScript e cria elementos do Places UI Kit para esses lugares.
4. A Plataforma Google Maps valida o token a cada solicitação do Kit de Interface do Places. Se o token for válido, a solicitação não será faturada.

Elementos compatíveis com o Kit de Interface do Places

O token se aplica aos seguintes elementos do Kit de Interface do Places na API Maps JavaScript:

Elemento	SKU
PlaceDetailsElement	Consulta do Kit de Interface do Places
PlaceDetailsCompactElement	Consulta do Kit de Interface do Places
AdvancedPlaceDetailsElement	Kit de Interface do Places Pro (avançado)
AdvancedPlaceDetailsCompactElement	Kit de Interface do Places Pro (avançado)
AdvancedPlaceListElement	Kit de Interface do Places Pro (avançado)

O token não se aplica a outras solicitações, como as dos elementos Place Search, Advanced Place Search e Basic Place Autocomplete, solicitações da API Places e carregamentos de mapas. Essas solicitações são faturadas com taxas padrão.

Somente as respostas das ferramentas do agente dos Experimentos do Maps incluem o token. Se você mostrar lugares de uma resposta do embasamento com o Google Maps usando o Kit de Interface do Places, essas solicitações serão cobradas de acordo com as taxas padrão.

Antes de começar

Antes de usar o token de visualização de dados agênticos, configure o seguinte:

• Um projeto do Google Cloud com a API Maps Experience Agent Tools (mapstools.googleapis.com) e a API Places UI Kit ativadas. Para mais informações, consulte Configurar LLMs para usar o servidor MCP e Começar a usar o kit de interface do Places.
• Credenciais desse projeto para as chamadas de ferramentas do agente da Experiência do Maps e para a API Maps JavaScript. Um token é válido apenas para solicitações do kit de interface do Places do projeto para o qual o token foi emitido.
• Um app cliente que carrega a API Maps JavaScript do canal Beta definindo v=beta.

Mostrar lugares de uma resposta fundamentada

As seções a seguir mostram como receber o token da resposta da ferramenta e usá-lo no app cliente. Se você usar o Maps Agentic UI Toolkit (experimental), o agente e o cliente da Web dele vão processar essas etapas para você.

Receber o token da resposta da ferramenta

A ferramenta search_places retorna o token no campo contentToken. No resultado de uma solicitação tools/call do MCP, esse campo está em structuredContent. A resposta da ferramenta é semelhante a esta:

{
  "places": [
    {
      "place": "places/PLACE_ID",
      "id": "PLACE_ID",
      ...
    }
  ],
  ...
  "contentToken": "CONTENT_TOKEN"
}

Esta saída inclui os seguintes valores:

• PLACE_ID: o ID de lugar de um lugar na resposta.
• CONTENT_TOKEN: o token de visualização de dados agênticos para os lugares na resposta. Trate o token como uma string opaca e não o modifique.

Se a resposta não incluir lugares, ela não vai incluir um token.

No código do app, leia o token da resposta da ferramenta, por exemplo, em um callback de ferramenta no framework do agente, e envie-o ao app cliente com os IDs de lugar. Não confie no LLM para repetir o token na saída, porque o modelo pode mudar o token.

Um token abrange apenas os lugares na própria resposta. Se o agente chamar a ferramenta search_places mais de uma vez, envie cada token para o app cliente.

Por exemplo, se você usar o Kit de Desenvolvimento de Agente (ADK) para Python, poderá salvar cada token em um callback pós-ferramenta:

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

Transmita essa função como o argumento after_tool_callback ao criar o agente e envie os tokens salvos para o app cliente com a resposta do agente. Para definições completas de agentes, consulte os exemplos do ADK em Configurar LLMs para usar o servidor MCP.

Adicionar o token e mostrar os lugares

No app cliente, transmita um iterável (como uma matriz) de strings de token não vazias para Settings.getInstance().addContentTokens() antes de criar elementos do Kit de IU do Places para os lugares. O método vai gerar um erro se você transmitir uma única string diretamente ou se o iterável incluir uma string vazia. O exemplo a seguir adiciona um token e exibe um elemento Place Details Compact para cada lugar:

// 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);
  }
}

Os tokens expiram 10 minutos após serem emitidos. A API Maps JavaScript mantém os tokens que você adiciona na memória da página atual e os remove automaticamente após a expiração. Assim, você não precisa remover os tokens expirados manualmente. Se você adicionar tokens de mais de uma resposta, a API vai enviar todos os tokens armazenados com cada solicitação de um elemento compatível.

Para mostrar vários lugares em um elemento, defina a propriedade places de um elemento de lista de lugares avançada como os IDs de lugar de uma ou mais respostas com os tokens que você adicionou.

Validação de token

Uma solicitação do Kit de Interface do Places não é faturada quando todas as seguintes condições são atendidas:

• Mesmo projeto: os tokens foram emitidos para o projeto do Google Cloud que é proprietário da chave de API usada para carregar a API Maps JavaScript.
• Locais fundamentados: todos os locais solicitados pelo elemento são cobertos por pelo menos um token que você adicionou. Um elemento pode incluir lugares de várias respostas se você adicionar o token de cada uma delas.
• Tokens não expirados: para cada lugar, a solicitação é feita em até 10 minutos após a emissão de um token que abrange o lugar.
• Elemento compatível: a solicitação vem de um elemento compatível do Kit de Interface do Places.

Os elementos que você configura com um local em vez de um lugar, como com um PlaceDetailsLocationRequestElement, não são cobertos. Se um elemento da Lista de Lugares Avançada incluir algum lugar que não esteja coberto, toda a solicitação será faturada.

Se alguma condição não for atendida, o elemento ainda será carregado, e a solicitação será cobrada pela taxa padrão da SKU. A API Maps JavaScript não retorna um erro quando um token é inválido.

Faturamento

Você paga por cada solicitação de ferramentas de agente da Experiência do Maps de acordo com a taxa padrão. As solicitações do Kit de Interface do Places que passam pela validação de token não são cobradas, mas ainda são contabilizadas na cota do Kit de Interface do Places. As solicitações do Kit de Interface do Places que não passam na validação do token são faturadas com a taxa padrão da SKU Consulta do Kit de Interface do Places ou Kit de Interface do Places Pro (avançado).

Para preços, consulte a tabela de preços principal e a tabela de preços da Índia.

Requisitos de uso

Uso exclusivo para um único usuário e resposta ativa: use um token de visualização de dados com agentes apenas para mostrar elementos compatíveis do Kit de Interface do Places ao mesmo usuário final e na resposta com agentes imediata que gerou o token. Não é permitido compartilhar, agrupar ou reutilizar tokens entre vários usuários finais nem usar um token para exibir lugares fora dessa resposta (como em listas salvas, favoritos ou diretórios em cache).

O uso do token de visualização de dados agênticos está sujeito aos Termos de Serviço da Plataforma Google Maps, incluindo os termos específicos do serviço. Os requisitos de atribuição para as ferramentas de agente dos Experimentos do Maps também se aplicam.