Grounding Lite do Maps

O Grounding Lite da Plataforma Google Maps é um serviço com suporte ao Protocolo de Contexto de Modelo (MCP) que facilita o embasamento dos seus aplicativos de IA com dados geoespaciais confiáveis do Google Maps. O servidor MCP oferece ferramentas que permitem que os LLMs acessem recursos para lugares, clima e rotas. Você pode testar o Maps Grounding Lite ativando-o em qualquer ferramenta compatível com servidores MCP.

Ferramentas

O Maps Grounding Lite oferece ferramentas que permitem que os LLMs acessem os seguintes recursos do Google Maps:

  • Pesquisar lugares: solicite informações sobre lugares e receba resumos de dados gerados por IA, além de IDs de lugar, coordenadas de latitude e longitude e links do Google Maps para cada um dos lugares incluídos no resumo. Você pode usar os IDs de lugar e as coordenadas de latitude e longitude retornados com outras APIs da Plataforma Google Maps para mostrar lugares em um mapa.
  • Pesquisar clima: solicita informações sobre o clima e retorna as condições atuais, previsões horárias e diárias.

  • Calcular rotas: solicita informações sobre rotas de carro ou a pé entre dois locais e retorna informações sobre a distância e a duração do trajeto.

Ao ativar o servidor MCP do Maps Grounding Lite, os LLMs podem chamar as novas ferramentas expostas pelo servidor para retornar mais informações de embasamento para os tipos de dados listados acima. Embora o LLM possa usar essas informações adicionais para contexto, a resposta gerada por ele pode não incluir as informações exatas retornadas pelo servidor do MCP. Verifique a precisão da resposta gerada.

Teste o app de exemplo Maps Grounding Lite (abre em uma nova guia)

Faturamento e cotas

Como é feita a cobrança

Com o modelo de pagamento por uso da Plataforma Google Maps, o uso do Maps Grounding Lite é calculado para cada solicitação, em que cada solicitação representa um evento de faturamento. O uso é rastreado para cada SKU de produto. Sua fatura mostra um item de linha para cada SKU, além das cobranças totais. Consulte a Visão geral dos relatórios para mais informações.

Consulte a tabela de preços principal e a tabela de preços da Índia para mais detalhes.

O Grounding Lite do Maps também é oferecido nos pacotes Assine para salvar Essentials e Pro.

Cotas

As seguintes cotas se aplicam às ferramentas fornecidas pelo Maps Grounding Lite:

  • Pesquisar lugares: 300 consultas por minuto, por projeto.
  • Pesquisar clima: 300 consultas por minuto, por projeto.
  • Calcular rotas: 300 consultas por minuto, por projeto.

Políticas e Termos de Serviço

O Maps Grounding Lite está sujeito aos Termos de Serviço da Plataforma Google Maps, incluindo os termos específicos do serviço. Nesta seção, descrevemos requisitos de uso do serviço adicional para o Maps Grounding Lite, incluindo LLMs compatíveis e requisitos de atribuição de fonte.

Requisitos para LLMs compatíveis

Só é possível usar o Maps Grounding Lite com um LLM que esteja em conformidade com os Termos de Serviço da Plataforma Google Maps.

Por exemplo, você é responsável por garantir que o conteúdo do Google Maps não seja armazenado em cache, armazenado ou usado para melhorar o LLM escolhido. Antes de usar o Maps Grounding Lite, revise os Termos de Serviço de qualquer modelo que você pretende usar com ele. Não use o Maps Grounding Lite com modelos que usam os dados inseridos para treinamento de modelo ou melhoria. Você é responsável por garantir que seu uso do modelo esteja em total conformidade com as restrições de conteúdo do Google Maps nos Termos de Serviço da Plataforma Google Maps, incluindo os termos específicos do serviço.

Requisitos de atribuição para fontes do Google Maps

Cada resposta da ferramenta do Maps Grounding Lite inclui fontes. Ao apresentar resultados que usam ferramentas fornecidas pelo Maps Grounding Lite, você precisa incluir as fontes associadas do Google Maps de uma forma que atenda aos seguintes requisitos:

  • As fontes do Google Maps precisam aparecer imediatamente após o conteúdo gerado que elas embasam. Esse conteúdo gerado também é chamado de saída embasada.
  • As fontes do Google Maps precisam estar visíveis em uma interação do usuário.

Fontes da ferramenta Pesquisar lugares

O campo places da ferramenta search_places fornece fontes que apoiam o summary. Para places, os seguintes metadados são retornados:

  • place (nome do recurso)
  • id
  • location
  • googleMapsLinks

Para cada lugar, é necessário gerar uma prévia de link que atenda a estes requisitos:

Configurar LLMs para usar o servidor MCP

Para usar o Maps Grounding Lite, primeiro você precisa de um projeto na nuvem do Google com o serviço de API Maps Grounding Lite ativado, além de uma chave de API ou um ID do cliente OAuth. Em seguida, é possível configurar LLMs para acessar o servidor MCP. O servidor MCP do Grounding Lite usa transporte HTTP transmissível.

Ative o serviço Maps Grounding Lite no seu projeto do Google Cloud.

Para ativar a API no seu projeto:

  1. No Console do Google Cloud, escolha o projeto que você quer usar com o Maps Grounding Lite.
  2. Ative o faturamento para o projeto no Console do Google Cloud.
  3. Ative o Maps Grounding Lite na biblioteca de APIs do console do Google Cloud.

Autenticar usando uma chave de API

Você pode usar uma chave de API atual com o Maps Grounding Lite ou criar uma nova, desde que ative o serviço da API Maps Grounding Lite no projeto na nuvem do Google Cloud e na chave.

Para autenticar usando uma chave de API:

  1. Crie ou configure uma chave de API seguindo as etapas em Como começar a usar a Plataforma Google Maps.
  2. Transmita a chave ao servidor MCP usando o cabeçalho X-Goog-Api-Key. É necessário especificar isso como um cabeçalho HTTP personalizado na configuração da ferramenta MCP do LLM.

Autenticar usando o OAuth

É possível autenticar usando o OAuth ao criar credenciais e transmiti-las para o host ou o aplicativo do servidor MCP.

Para autenticar usando o OAuth:

  1. No Console do Google Cloud, escolha o projeto que você quer usar com o Maps Grounding Lite.
  2. No menu API e serviços, selecione Credenciais.
  3. No menu da parte de cima, selecione Criar credenciais > ID do cliente OAuth.
  4. Se o projeto não tiver uma tela de permissão configurada, clique em Configurar tela de permissão e siga as instruções na tela.
  5. Na seção Métricas, clique em Criar cliente OAuth.
  6. Na tela Criar ID do cliente OAuth, selecione um tipo de aplicativo e insira um nome para o ID do cliente.
  7. Especifique os detalhes adicionais relevantes para seu tipo de aplicativo. Por exemplo, se você estiver criando um aplicativo da Web, adicione URIs autorizados para solicitações do navegador e do servidor.
  8. Depois que o cliente for criado, salve o ID e a chave secreta.
  9. Ao configurar o host ou o aplicativo do servidor MCP para acessar o Maps Grounding Lite, transmita o ID e a chave secreta do cliente OAuth. Você também precisa solicitar o seguinte escopo: https://www.googleapis.com/auth/maps-platform.mapstools.

Para mais informações, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.

Configurar LLMs para acessar o servidor MCP do Maps Grounding Lite

Depois de ter um projeto na nuvem do Google Cloud com o serviço API Maps Grounding Lite ativado e credenciais válidas, como uma chave de API ou um ID e segredo do cliente OAuth, você pode configurar LLMs para acessar o servidor MCP seguindo a documentação de configuração do MCP correspondente e usando o URL do servidor MCP do Maps Grounding Lite: https://mapstools.googleapis.com/mcp

Para mais informações, consulte Configurar a MCP em um aplicativo de IA.

Configurar o Grounding Lite do Maps com a CLI do Gemini

Esta seção mostra um exemplo de como configurar o servidor MCP do Maps Grounding Lite usando a CLI do Gemini. Para mais detalhes, consulte Servidores MCP com a CLI do Gemini.

  1. Depois de instalar a CLI do Gemini, use o comando "add" para configurar o servidor MCP do 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

    Se a configuração for bem-sucedida, você vai receber uma confirmação de que o servidor foi adicionado às configurações do usuário.

  2. Para validar se o servidor está funcionando corretamente, execute o comando /mcp list:

    > /mcp list

Configured MCP servers:

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

  3. Comece a fazer perguntas relacionadas ao Google Maps com a CLI. Por exemplo, tente "Recomende alguns restaurantes em Mountain View", que vai chamar a ferramenta search_places em seu nome.

Configurar o Grounding Lite com o Kit de Desenvolvimento de Agente (ADK)

Esta seção fornece exemplos que mostram como configurar o servidor MCP do Grounding Lite usando o Kit de Desenvolvimento de Agente (ADK) e Python, Java ou TypeScript.

Python

Etapa 1: definir o agente com McpToolset para o Grounding Lite do Google Maps

Modifique o arquivo agent.py. Substitua YOUR_GOOGLE_MAPS_API_KEY pela sua chave 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"
                }
            )
        )
    ]
)
Etapa 2: verificar se __init__.py existe

Verifique se você tem um __init__.py no mesmo diretório que o agent.py:

from . import agent
Etapa 3: executar adk web e interagir
  1. Definir variável de ambiente:
    Defina sua chave da API Google Maps como uma variável de ambiente no seu terminal: 
    export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
  2. Execute adk web:
    Execute o seguinte comando para iniciar a interface da web do ADK: 
    adk web
  3. Interaja na interface:
    • Selecione a travel_planner_agent.
    • Tente comandos como:
      • "Estarei em São Francisco amanhã. Como está o tempo?"
      • "Encontre cafés perto do Golden Gate Park."
      • "Quero rotas do GooglePlex para o aeroporto de São Francisco."

Java

Defina um agente que inicializa o McpToolset em Java. Substitua YOUR_GOOGLE_MAPS_API_KEY_HERE pela chave de API real que você recebeu se não usar uma variável de ambiente.

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

Defina um agente que inicializa o MCPToolset em 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"
            }
        })
    ],
});

Enviar comentários

Para compartilhar feedback sobre o Grounding Lite do Maps, use os seguintes formulários: