Token de visualización de datos de agentes

El token de visualización de datos de agentes permite que tu app de agentes muestre elementos del kit de IU de Places para los lugares en una respuesta de las herramientas de agentes de Experiencia de Maps (antes Maps Grounding Lite) sin costo adicional. Cada llamada exitosa a la herramienta de search_places devuelve un token que identifica los lugares en la respuesta, tanto para los SKU de Essentials como para los de Pro. Cuando tu app cliente agrega el token a la API de Maps JavaScript, las solicitudes del kit de IU de Places para esos lugares no se facturan durante 10 minutos después de que se emite el token.

Cómo funciona

El token conecta una respuesta fundamentada con los detalles del lugar que muestras con ella:

  1. Tu agente llama a la herramienta search_places en el servidor de MCP de herramientas de agentes de Maps Experience. La respuesta de la herramienta incluye los lugares que admiten el resumen y un token en el campo contentToken.
  2. Tu app lee el token de la respuesta de la herramienta y lo envía a tu app cliente, junto con los IDs de los lugares que deseas mostrar.
  3. Tu app cliente agrega el token a la API de Maps JavaScript y crea elementos del kit de IU de Places para esos lugares.
  4. Google Maps Platform valida el token con cada solicitud del kit de IU de Places. Si el token es válido, no se factura la solicitud.

Elementos compatibles del kit de IU de Places

El token se aplica a los siguientes elementos del kit de IU de Places en la API de Maps JavaScript:

Elemento SKU
PlaceDetailsElement Places UI Kit Query
PlaceDetailsCompactElement Places UI Kit Query
AdvancedPlaceDetailsElement Kit de IU de Places Pro (avanzado)
AdvancedPlaceDetailsCompactElement Kit de IU de Places Pro (avanzado)
AdvancedPlaceListElement Kit de IU de Places Pro (avanzado)

El token no se aplica a otras solicitudes, como las de los elementos Place Search, Advanced Place Search y Basic Place Autocomplete, las solicitudes a la API de Places y las cargas de mapas. Estas solicitudes se facturan según las tarifas estándar.

Solo las respuestas de las herramientas del agente de Maps Experience incluyen el token. Si muestras lugares de una respuesta de Fundamentación con Google Maps con el kit de IU de Places, esas solicitudes se facturan con las tarifas estándar.

Antes de comenzar

Antes de usar el token de visualización de datos de agentes, configura lo siguiente:

  • Un proyecto de Google Cloud con la API de herramientas de agentes de Maps Experience (mapstools.googleapis.com) y la API del kit de IU de Places habilitadas Para obtener más información, consulta Configura LLM para usar el servidor de MCP y Comienza a usar el kit de IU de Places.
  • Credenciales de ese proyecto para las llamadas de las herramientas de agente de Maps Experience y la API de Maps JavaScript Un token solo es válido para las solicitudes del kit de IU de Places del proyecto para el que se emitió.
  • Una app cliente que carga la API de Maps JavaScript desde el canal beta configurando v=beta

Muestra lugares de una respuesta fundamentada

En las siguientes secciones, se muestra cómo obtener el token de la respuesta de la herramienta y usarlo en tu app cliente. Si usas el kit de herramientas de IU de agentes de Maps (experimental), su agente y el cliente web se encargan de estos pasos por ti.

Obtén el token de la respuesta de la herramienta

La herramienta search_places devuelve el token en el campo contentToken. En el resultado de una solicitud tools/call de MCP, este campo está en structuredContent. La respuesta de la herramienta es similar a la siguiente:

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

En esta salida, se incluyen los siguientes valores:

  • PLACE_ID: Es el ID de lugar de un lugar en la respuesta.
  • CONTENT_TOKEN: Es el token de visualización de datos de agentes para los lugares de la respuesta. Trata el token como una cadena opaca y no lo modifiques.

Si la respuesta no incluye ningún lugar, tampoco incluirá un token.

En el código de tu app, lee el token de la respuesta de la herramienta (por ejemplo, en una devolución de llamada de la herramienta en tu framework de agentes) y envíalo a tu app cliente con los IDs de lugar. No confíes en que el LLM repetirá el token en su resultado, ya que el modelo podría cambiarlo.

Un token solo abarca los lugares de su propia respuesta. Si tu agente llama a la herramienta search_places más de una vez, envía cada token a tu app cliente.

Por ejemplo, si usas el Kit de desarrollo de agentes (ADK) para Python, puedes guardar cada token en una devolución de llamada posterior a la herramienta:

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

Pasa esta función como el argumento after_tool_callback cuando crees tu agente y, luego, envía los tokens guardados a tu app cliente con la respuesta del agente. Para ver las definiciones completas de los agentes, consulta los ejemplos del ADK en Configura LLM para usar el servidor de MCP.

Agrega el token y muestra los lugares

En tu app cliente, pasa un iterable (como un array) de cadenas de tokens no vacías a Settings.getInstance().addContentTokens() antes de crear elementos del kit de IU de Places para las ubicaciones. El método arroja un error si pasas una sola cadena directamente o si el iterable incluye una cadena vacía. En el siguiente ejemplo, se agrega un token y, luego, se muestra un 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);
  }
}

Los tokens vencen 10 minutos después de su emisión. La API de Maps JavaScript conserva los tokens que agregas en la memoria de la página actual y los quita automáticamente después de que vencen, por lo que no es necesario que quites los tokens vencidos por tu cuenta. Si agregas tokens de más de una respuesta, la API envía todos los tokens almacenados con cada solicitud de un elemento compatible.

Para mostrar varios lugares en un elemento, establece la propiedad places de un elemento de lista de lugares avanzada en los IDs de lugar de una o más respuestas cuyos tokens agregaste.

Validación de tokens

No se factura una solicitud del kit de IU de Places cuando se cumplen todas las condiciones siguientes:

  • Mismo proyecto: Los tokens se emitieron para el proyecto de Google Cloud propietario de la clave de API que usas para cargar la API de Maps JavaScript.
  • Lugares fundamentados: Cada lugar que solicita el elemento está cubierto por, al menos, un token que agregaste. Un elemento puede incluir lugares de varias respuestas si agregas el token de cada respuesta.
  • Tokens que no vencieron: Para cada lugar, la solicitud se realiza en un plazo de 10 minutos desde que se emitió un token que cubre el lugar.
  • Elemento compatible: La solicitud proviene de un elemento compatible del kit de IU de Places.

No se incluyen los elementos que configuras con una ubicación en lugar de un lugar, como con un PlaceDetailsLocationRequestElement. Si un elemento de Advanced Place List incluye algún lugar que no está cubierto, se factura toda la solicitud.

Si no se cumple alguna condición, el elemento se cargará de todos modos y la solicitud se facturará según la tarifa estándar de su SKU. La API de Maps JavaScript no devuelve un error cuando un token no es válido.

Facturación

Pagas por cada solicitud de herramientas de agentes de Experimentos de Maps según su tarifa estándar. Las solicitudes del kit de IU de Places que aprueban la validación de tokens no se facturan, pero se tienen en cuenta para tu cuota del kit de IU de Places. Las solicitudes del kit de IU de Places que no aprueban la validación de tokens se facturan con la tarifa estándar del SKU de Places UI Kit Query o Places UI Kit Pro (Advanced).

Para conocer los precios, consulta la tabla de precios principal y la tabla de precios de India.

Requisitos de uso

Uso exclusivo para un solo usuario y una respuesta activa: Debes usar un token de visualización de datos de agente solo para mostrar elementos compatibles del kit de IU de Places al mismo usuario final y dentro de la respuesta inmediata del agente que generó el token. No debes compartir, agrupar ni reutilizar tokens entre varios usuarios finales, ni usar un token para mostrar lugares fuera de esa respuesta (como en listas guardadas, favoritos o directorios almacenados en caché).

El uso que hagas del token de visualización de datos de agentes está sujeto a las Condiciones del Servicio de Google Maps Platform, incluidas las condiciones específicas del servicio. También se aplican los requisitos de atribución para las herramientas de agentes de Maps Experience.