Token de visualização de dados agênticos

O token de visualização de dados do agente permite que seu app 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 ou search_along_route 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 faturadas 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 ou search_along_route no servidor MCP de ferramentas de agente da Experiência do 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:

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 mapa. Essas solicitações são cobradas de acordo com as taxas padrão.

Somente as respostas das ferramentas de agentes do 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êntica, 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 de agentes Experimentos do Maps e 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 embasada

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

As ferramentas search_places e search_along_route retornam o token no campo contentToken. No resultado de uma solicitação tools/call do MCP, esse campo está em structuredContent. Em uma resposta do método REST searchText ou searchAlongRoute, é um campo de nível superior. Uma resposta search_places é semelhante ao seguinte (uma resposta search_along_route retorna cada lugar dentro de results[].place):

{
  "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 fizer uma ligação agêntica search_places ou search_along_route 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 interface 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 compacto de Place Details para cada lugar:

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

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 será faturada se todas as condições a seguir forem atendidas:

• Mesmo projeto: os tokens foram emitidos para o projeto do Google Cloud que possui a 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 agentes do Maps Experience 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 contam para sua 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 saber os 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 agêntico apenas para mostrar elementos compatíveis do Kit de Interface do Places ao mesmo usuário final e na resposta imediata do agente que gerou o token. Não compartilhe, agrupe ou reutilize tokens entre vários usuários finais nem use 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 agentes Experimentos do Maps também se aplicam.