Grounding Lite do Maps

O Grounding Lite da Plataforma do Google Maps é um serviço com suporte ao Protocolo de Contexto de Modelo (MCP) que facilita o embasamento de 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, além de resolver nomes de locais e URLs do Google Maps para IDs de lugar. Para testar o Maps Grounding Lite, ative-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 de lugares gerados com 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.
• Consultar o clima: solicite informações sobre o clima e retorne as condições atuais, as previsões por hora e as previsões diárias.

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

• Resolver nomes e Resolver URLs do Maps: resolva nomes de locais, endereços e URLs do Google Maps para IDs de lugar. Para mais informações, consulte API Resolution.

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 como contexto, a resposta gerada pelo LLM pode não incluir as informações exatas retornadas pelo servidor MCP. Verifique se a resposta gerada está correta.

API Resolution

O Maps Grounding Lite oferece a API Resolution, que permite resolver textos de localização de formato livre e URLs para identificadores de lugar estruturados do Google Maps. A API Resolution está disponível como métodos REST e como ferramentas no servidor MCP do Maps Grounding Lite:

• Resolver nomes (REST, MCP): resolve um lote de nomes ou endereços de locais para entidades de lugar específicas no Google Maps. Isso é útil para embasar consultas de usuários não estruturadas em IDs de lugar estáveis.
• Resolver URLs do Maps (REST, MCP): resolve um lote de URLs do Google Maps para entidades de lugar específicas. Os formatos aceitos incluem URLs de lugares padrão e URLs encurtados.

Você pode usar os IDs de lugar retornados com outras APIs da Plataforma Google Maps. Cada resposta também inclui um link que salva os lugares resolvidos como uma lista no Google Maps.

Para mais informações, consulte a API Maps Tools Resolution.

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

Faturamento e cotas

Como a cobrança é feita

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 de cada SKU de produto é rastreado. A 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.

As solicitações para a API Resolution (ResolveNames e ResolveMapsUrls) são cobradas sem custo financeiro na SKU API Places Text Search Essentials (somente IDs).

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

Cotas

As cotas a seguir se aplicam às ferramentas e APIs fornecidas pelo Maps Grounding Lite:

• Pesquisar lugares: 300 consultas por minuto, por projeto.
• Pesquisa de clima: 300 consultas por minuto, por projeto.
• Calcular rotas: 300 consultas por minuto, por projeto.
• Resolver nomes: 600 consultas por minuto, por projeto.
• Resolver URLs do Maps: 600 consultas por minuto, por projeto.

Cada solicitação de API Resolution conta como uma consulta, independentemente de quantos itens ela contém.

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 de serviço para esse serviço. Nesta seção, descrevemos outros requisitos de uso do serviço para o Maps Grounding Lite, incluindo LLMs compatíveis e requisitos de atribuição de fonte.

Requisitos para LLMs compatíveis

Só é permitido 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 que você escolher. Antes de usar o Maps Grounding Lite, leia os Termos de Serviço de qualquer modelo que você pretenda usar com o Maps Grounding Lite. Não use o Maps Grounding Lite com modelos que usem os dados inseridos no modelo para treinamento ou melhoria. Você é responsável por garantir que o 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, é necessário incluir as fontes associadas do Google Maps de uma forma que atenda aos seguintes requisitos:

• As fontes do Google Maps precisam seguir imediatamente o conteúdo gerado que elas apoiam. Esse conteúdo gerado também é chamado de Saída embasada.
• As fontes do Google Maps precisam ser visíveis em uma interação do usuário.

Fontes para a ferramenta de pesquisa de lugares

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

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

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

• Atribua cada fonte ao Google Maps, seguindo as diretrizes de atribuição de texto do Maps Grounding Lite.
• Vincule à origem usando o places.googleMapsLinks.placeUrl da resposta.

Configurar LLMs para usar o servidor MCP

Para usar o Maps Grounding Lite, primeiro você precisa de um projeto na nuvem do Google Cloud 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, configure os LLMs para acessar o servidor MCP. O servidor MCP do Grounding Lite usa o 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 para 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 de 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 Primeiros passos com a Plataforma Google Maps.
2. Transmita a chave para o 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 OAuth

É possível autenticar usando o OAuth criando credenciais OAuth e transmitindo-as para o host MCP ou o aplicativo do servidor MCP.

Para autenticar usando o OAuth:

1. No console do Google Cloud, escolha o projeto que você quer usar para o Maps Grounding Lite.
2. No menu APIs e serviços, selecione Credenciais.
3. No menu superior, 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 de navegador e servidor.
8. Depois que o cliente for criado, salve o ID do cliente e a chave secreta.
9. Ao configurar o host ou o aplicativo do servidor MCP para acessar o Maps Grounding Lite, transmita o ID do cliente e a chave secreta do 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 da API Maps Grounding Lite ativado e credenciais válidas, como uma chave de API ou um ID do cliente OAuth e uma chave secreta, 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 o MCP em um aplicativo de IA.

Configurar o Grounding Lite com o Google 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 tiver sido bem-sucedida, você vai receber uma confirmação de que o servidor foi adicionado às suas configurações de 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 (5 tools)
   Tools:
   -   compute_routes
   -   lookup_weather
   -   resolve_maps_urls
   -   resolve_names
   -   search_places
   

3. Comece a Perguntar ao Maps com a CLI. Por exemplo, tente "Recomende alguns restaurantes em Mountain View", que deve chamar a ferramenta search_places em seu nome.

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

Nesta seção, mostramos como configurar o servidor MCP do Grounding Lite usando o Kit de Desenvolvimento de Agente (ADK) e Python, Java ou TypeScript.

# ./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"
                }
            )
        )
    ]
)
    

from . import agent
    

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

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 enviar feedback sobre o Maps Grounding Lite, use os seguintes formulários:

• Informar um bug
• Enviar uma solicitação de recurso
• Enviar feedback