Maps Grounding Lite

Google Maps Platform Grounding Lite es un servicio con compatibilidad con el protocolo de contexto del modelo (MCP) que facilita la fundamentación de tus aplicaciones de IA con datos geoespaciales confiables de Google Maps. El servidor de MCP proporciona herramientas que permiten que los LLM accedan a capacidades para lugares, clima y rutas. Para probar Maps Grounding Lite, habilítalo en cualquier herramienta que admita servidores de MCP.

Herramientas

Maps Grounding Lite proporciona herramientas que permiten que los LLM accedan a las siguientes capacidades de Google Maps:

Buscar lugares: Solicita información sobre lugares y obtén resúmenes de datos de lugares generados por IA, así como IDs de lugar, coordenadas de latitud y longitud, y vínculos de Google Maps para cada uno de los lugares incluidos en el resumen. Puedes usar los IDs de lugar y las coordenadas de latitud y longitud que se muestran con otras APIs de Google Maps Platform para mostrar lugares en un mapa.
Consultar el clima: Solicita información sobre el clima y muestra las condiciones actuales, los pronósticos por hora y los pronósticos diarios.
Calcular rutas: Solicita información sobre rutas en auto o a pie entre dos ubicaciones y muestra información sobre la distancia y la duración de la ruta.

Nota: Maps Grounding Lite no proporciona información sobre rutas paso a paso, instrucciones sobre cómo llegar a un lugar, datos del tráfico en tiempo real ni información de navegación.

Si habilitas el servidor de MCP de Maps Grounding Lite, los LLM podrán llamar a las nuevas herramientas que expone el servidor para mostrar información de fundamentación adicional para los tipos de datos que se mencionaron anteriormente. Si bien el LLM puede usar esta información adicional para el contexto, es posible que la respuesta que genere el LLM no incluya la información exacta que muestra el servidor de MCP. Debes verificar la precisión de la respuesta generada.

Prueba la app de ejemplo de Maps Grounding Lite (se abre en una pestaña nueva)

Facturación y cuotas

Cómo se te factura

Con el modelo de precios de pago por uso de Google Maps Platform, el uso de Maps Grounding Lite se calcula para cada solicitud, en la que cada solicitud representa un evento de facturación. Se hace un seguimiento del uso de cada producto SKU. En tu factura, se muestra un elemento de una sola línea para cada SKU, además de los cargos totales. Consulta la descripción general de los informes para obtener más información.

Consulta la tabla de precios principal y la tabla de precios de India para obtener detalles sobre los precios.

Maps Grounding Lite también se ofrece a través de los paquetes Essentials y Pro Subscribe to save.

Cuotas

Se aplican las siguientes cuotas a las herramientas que proporciona Maps Grounding Lite:

Buscar lugares: 300 consultas por minuto, por proyecto
Consultar el clima: 300 consultas por minuto, por proyecto
Calcular rutas: 300 consultas por minuto, por proyecto

Políticas y Condiciones del Servicio

Maps Grounding Lite está sujeto a las Condiciones del Servicio de Google Maps Platform, incluidas las condiciones específicas del servicio para este servicio. En esta sección, se describen los requisitos adicionales de uso del servicio para Maps Grounding Lite, incluidos los LLM compatibles y los requisitos de atribución de fuentes.

Requisitos para LLM compatibles

Solo puedes usar Maps Grounding Lite con un LLM que cumpla con las Condiciones del Servicio de Google Maps Platform.

Por ejemplo, eres responsable de asegurarte de que el LLM que elijas usar no almacene en caché, almacene ni use el contenido de Google Maps para mejorarlo. Antes de usar Maps Grounding Lite, deberás revisar las Condiciones del Servicio de cualquier modelo que pretendas usar con Maps Grounding Lite. No debes usar Maps Grounding Lite con ningún modelo que use los datos ingresados en el modelo para el entrenamiento o la mejora de modelos. Eres responsable de asegurarte de que tu uso del modelo cumpla por completo con las restricciones sobre el contenido de Google Maps en las Condiciones del Servicio de Google Maps Platform, incluidas las condiciones específicas del servicio.

Requisitos de atribución para las fuentes de Google Maps

Cada respuesta de la herramienta de Maps Grounding Lite incluye fuentes. Cuando presentes resultados que usen herramientas proporcionadas por Maps Grounding Lite, debes incluir las fuentes de Google Maps asociadas de una manera que cumpla con los siguientes requisitos:

Las fuentes de Google Maps deben seguir inmediatamente al contenido generado que admiten las fuentes. Este contenido generado también se conoce como salida fundamentada.
Las fuentes de Google Maps deben poder verse en una interacción del usuario.

Fuentes de la herramienta Buscar lugares

El campo places de la herramienta search_places proporciona fuentes que admiten el summary. Para places, se muestra los siguientes metadatos:

place (nombre del recurso)
id
location
googleMapsLinks

Para cada lugar, debes generar una vista previa del vínculo que cumpla con estos requisitos:

Atribuye cada fuente a Google Maps, según los lineamientos de atribución de texto de Maps Grounding Lite.
Vincula a la fuente con places.googleMapsLinks.placeUrl de la respuesta.

Configura LLM para usar el servidor de MCP

Para usar Maps Grounding Lite, primero necesitas un proyecto de Google Cloud con el servicio de API de Maps Grounding Lite habilitado, así como una clave de API o un ID de cliente de OAuth. Luego, puedes configurar LLM para acceder al servidor de MCP. El servidor de MCP de Grounding Lite usa el transporte HTTP transmitible.

Habilita el servicio de Maps Grounding Lite en tu proyecto de Google Cloud

Para habilitar la API en tu proyecto, haz lo siguiente:

En la consola de Google Cloud, elige el proyecto que deseas usar para Maps Grounding Lite.
Habilita la facturación para el proyecto en la Google Cloud Console.
Habilita Maps Grounding Lite en la consola de Google Cloud biblioteca de API.

Autentica con una clave de API

Puedes usar una clave de API existente con Maps Grounding Lite o crear una nueva siempre que habilites el servicio de API deMaps Grounding Lite en el proyecto de Google Cloud y en la clave.

Para autenticar con una clave de API, haz lo siguiente:

Crea o configura una clave de API siguiendo los pasos que se indican en Comienza a usar Google Maps Platform.
Pasa la clave al servidor de MCP con el encabezado X-Goog-Api-Key. Debes especificarlo como un encabezado HTTP personalizado en la configuración de la herramienta de MCP del LLM.

Autentica con OAuth

Para autenticar con OAuth, crea credenciales de OAuth y pásalas al host de MCP o a la aplicación del servidor de MCP.

Para autenticar con OAuth, haz lo siguiente:

En la consola de Google Cloud, elige el proyecto que deseas usar para Maps Grounding Lite.
En el menú API y servicios, selecciona Credenciales.
En el menú superior, selecciona Crear credenciales > ID de cliente de OAuth.
Si el proyecto no tiene una pantalla de consentimiento configurada, haz clic en Configurar pantalla de consentimiento y sigue las instrucciones en pantalla.
En la sección Métricas, haz clic en Crear cliente de OAuth.
En la pantalla Crear ID de cliente de OAuth , selecciona un tipo de aplicación y, luego, ingresa un nombre para el ID de cliente.
Especifica los detalles adicionales que sean relevantes para tu tipo de aplicación. Por ejemplo, si creas una aplicación web, agrega URIs autorizadas para solicitudes del navegador y del servidor.
Una vez que se cree tu cliente, guarda el ID de cliente y el secreto.
Cuando configures tu host de MCP o la aplicación del servidor de MCP para acceder a Maps Grounding Lite, pasa tu ID de cliente y secreto de OAuth. También debes solicitar el siguiente alcance: https://www.googleapis.com/auth/maps-platform.mapstools.

Para obtener más información, consulta Usa OAuth 2.0 para acceder a las APIs de Google.

Configura LLM para acceder al servidor de MCP de Maps Grounding Lite

Una vez que tengas un proyecto de Google Cloud con el servicio de API de Maps Grounding Lite habilitado y credenciales válidas, como una clave de API o un ID de cliente y un secreto de OAuth, puedes configurar LLM para acceder al servidor de MCP. Para ello, sigue la documentación de configuración de MCP correspondiente y usa la URL del servidor de MCP de Maps Grounding Lite: https://mapstools.googleapis.com/mcp

Para obtener más información, consulta Configura MCP en una aplicación de IA aplicación.

Configura Maps Grounding Lite con la CLI de Gemini

En esta sección, se proporciona un ejemplo de cómo configurar el servidor de MCP de Maps Grounding Lite con la CLI de Gemini. Para obtener más detalles, consulta los servidores de MCP con la CLI de Gemini.

Una vez que instales la CLI de Gemini, puedes usar el comando add para configurar el servidor de MCP de Maps Grounding Lite:
```
gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-grounding-lite-mcp https://mapstools.googleapis.com/mcp
```
Si la configuración se realizó correctamente, deberías ver una confirmación de que el servidor se agregó a la configuración de usuario.

Para validar que el servidor funcione correctamente, ejecuta el comando /mcp list:

> /mcp list

Configured MCP servers:

maps-grounding-lite-mcp - Ready (3 tools)
Tools:
-   compute_routes
-   lookup_weather
-   search_places

Comienza a hacer preguntas relacionadas con Maps con la CLI. Por ejemplo, prueba "Recomiéndame algunos restaurantes en Mountain View", que debería llamar a la herramienta search_places en tu nombre.

Configura Grounding Lite con el Kit de desarrollo de agentes (ADK)

En esta sección, se proporcionan ejemplos que muestran cómo configurar el servidor de MCP de Grounding Lite con el Kit de desarrollo de agentes (ADK) y Python, Java o TypeScript.

Python

Paso 1: Define tu agente con `McpToolset` para Google Maps Grounding Lite

Modifica tu archivo agent.py. Reemplaza YOUR_GOOGLE_MAPS_API_KEY por tu clave de API real.

# ./adk_agent_samples/mcp_agent/agent.py
import os
from google.adk.agents.llm_agent import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# Retrieve the API key from an environment variable or directly insert it.
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")
if not GOOGLE_MAPS_API_KEY:
    GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY_HERE"

if GOOGLE_MAPS_API_KEY == "YOUR_GOOGLE_MAPS_API_KEY_HERE":
    print("WARNING: GOOGLE_MAPS_API_KEY is not set.")

root_agent = Agent(
    model='gemini-flash-latest',
    name='travel_planner_agent',
    description='A helpful assistant for planning travel routes.',
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url="https://mapstools.googleapis.com/mcp",
                headers={
                    "X-Goog-Api-Key": GOOGLE_MAPS_API_KEY,
                    "Content-Type": "application/json",
                    "Accept": "application/json, text/event-stream"
                }
            )
        )
    ]
)

Paso 2: Asegúrate de que exista `init.py`

Asegúrate de tener un __init__.py en el mismo directorio que tu agent.py:

from . import agent

Paso 3: Ejecuta `adk web` e interactúa

Establece la variable de entorno:
Establece tu clave de API de Google Maps como una variable de entorno en tu terminal:
```
export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
        
```
Ejecuta adk web:
Ejecuta el siguiente comando para iniciar la interfaz web del ADK:
```
adk web
        
```
Interactúa en la IU:
- Selecciona travel_planner_agent.
- Prueba instrucciones como las siguientes:
  - "Mañana estaré en San Francisco. ¿Cómo está el clima?"
  - "Busca cafeterías cerca de Golden Gate Park".
  - "Obtén instrucciones sobre cómo llegar desde GooglePlex hasta SFO".

Java

Define un agente que inicialice el McpToolset en Java. Reemplaza YOUR_GOOGLE_MAPS_API_KEY_HERE por la clave de API real que obtuviste si no usas una variable de entorno.

package agents;

import com.google.adk.agents.LlmAgent;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.SessionKey;
import com.google.adk.tools.mcp.McpToolset;
import com.google.adk.tools.mcp.StreamableHttpServerParameters;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import java.util.HashMap;
import java.util.Map;

public class MapsAgentCreator {
    public static void main(String[] args) {
        String googleMapsApiKey = System.getenv("GOOGLE_MAPS_API_KEY");
        if (googleMapsApiKey == null || googleMapsApiKey.trim().isEmpty()) {
            googleMapsApiKey = "YOUR_GOOGLE_MAPS_API_KEY_HERE";
            if ("YOUR_GOOGLE_MAPS_API_KEY_HERE".equals(googleMapsApiKey)) {
                System.out.println("WARNING: GOOGLE_MAPS_API_KEY is not set.");
            }
        }

        Map<String, String> headers = new HashMap<>();
        headers.put("X-Goog-Api-Key", googleMapsApiKey);
        headers.put("Content-Type", "application/json");
        headers.put("Accept", "application/json, text/event-stream");

        StreamableHttpServerParameters serverParams = StreamableHttpServerParameters.builder("https://mapstools.googleapis.com/mcp")
                .headers(headers)
                .build();

        try (McpToolset toolset = new McpToolset(serverParams)) {
            LlmAgent agent = LlmAgent.builder()
                    .model("gemini-flash-latest")
                    .name("travel_planner_agent")
                    .description("A helpful assistant for planning travel routes.")
                    .tools(toolset)
                    .build();

            System.out.println("Agent created: " + agent.name());

            InMemoryRunner runner = new InMemoryRunner(agent);
            String userId = "maps-user-" + System.currentTimeMillis();
            String sessionId = "maps-session-" + System.currentTimeMillis();
            String promptText = "Please give me directions to the nearest pharmacy to Madison Square Garden.";

            SessionKey sessionKey = runner.sessionService().createSession(runner.appName(), userId, null, sessionId).blockingGet().sessionKey();
            System.out.println("Session created: " + sessionId + " for user: " + userId);

            Content promptContent = Content.fromParts(Part.fromText(promptText));
            System.out.println("\nSending prompt: \"" + promptText + "\" to agent...\n");

            runner.runAsync(sessionKey, promptContent)
                    .blockingForEach(event -> {
                        System.out.println("Event received: " + event.toJson());
                    });
        } catch (Exception e) {
            System.err.println("An error occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

TypeScript

Define un agente que inicialice el MCPToolset en TypeScript:

import 'dotenv/config';
import {LlmAgent, MCPToolset} from "@google/adk";

const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY;
if (!googleMapsApiKey) {
    console.warn("WARNING: GOOGLE_MAPS_API_KEY is not set.");
    throw new Error('GOOGLE_MAPS_API_KEY is not provided, please run "export GOOGLE_MAPS_API_KEY=YOUR_ACTUAL_KEY" to add that.');
}

export const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "travel_planner_agent",
    description: "A helpful assistant for planning travel.",
    tools: [
        new MCPToolset({
            type: "SseConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            headers: {
                "X-Goog-Api-Key": googleMapsApiKey,
                "Content-Type": "application/json",
                "Accept": "application/json, text/event-stream"
            }
        })
    ],
});

Comparte tus comentarios

Para compartir comentarios sobre Maps Grounding Lite, usa los siguientes formularios: