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 de lugares, clima e rotas. Você pode testar o Maps Grounding Lite ativando-o em qualquer ferramenta que ofereça suporte a 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 por IA, além de IDs de lugares, 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 lugares e as coordenadas de latitude e longitude retornados com outras APIs da Plataforma Google Maps para mostrar lugares em um mapa.
Consultar clima: solicite informações sobre o clima e retorne as condições atuais, previsões horárias e 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.

**Observação** :o Maps Grounding Lite não fornece rotas detalhadas, direções, trânsito em tempo real ou informações de navegação.

A ativação do servidor MCP do Maps Grounding Lite permite que os LLMs chamem 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 pelo LLM pode não incluir as informações exatas retornadas pelo servidor MCP. Verifique a precisão da resposta gerada.

Testar o app de exemplo do Maps Grounding Lite (abrir em uma nova guia)

Faturamento e cotas

Como você é cobrado

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. Sua fatura mostra um item de linha para cada SKU, além das cobranças totais. Consulte a visão geral de relatórios para mais informações.

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

O Maps Grounding Lite também é oferecido nos pacotes Essentials e Pro Subscribe to save.

Cotas

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

Pesquisar lugares: 300 consultas por minuto por projeto.
Consultar 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. Esta seção descreve requisitos de uso de serviço adicional para o Maps Grounding Lite, incluindo LLMs compatíveis e requisitos de atribuição.

Requisitos para LLMs compatíveis

Você só pode 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 o Maps Grounding Lite. Não use o Maps Grounding Lite com modelos que usem os dados inseridos no modelo para treinamento de modelo 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 de ferramenta do Maps Grounding Lite inclui fontes. Ao apresentar resultados que usam ferramentas fornecidas pelo Maps Grounding Lite, inclua as fontes associadas do Google Maps de uma maneira que atenda aos seguintes requisitos:

As fontes do Google Maps precisam seguir imediatamente o conteúdo gerado que as fontes oferecem suporte. 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 oferecem suporte ao summary. Para places, os seguintes metadados são retornados:

place (nome do recurso)
id
location
googleMapsLinks

Para cada lugar, gere uma visualização 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 à fonte 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 com o serviço de API Maps Grounding Lite ativado, bem como uma chave de API ou um ID do cliente OAuth. Em seguida, você pode configurar LLMs para acessar o servidor MCP. O servidor MCP do Grounding Lite usa o transporte HTTP transmissível.

Ativar o serviço Maps Grounding Lite no seu projeto na nuvem do Google Cloud

Para ativar a API no seu projeto:

No console do Google Cloud, escolha o projeto que você quer usar para o Maps Grounding Lite.
Ative o faturamento para o projeto no Google Cloud Console.
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 Maps Grounding Lite API service no projeto na nuvem do Google Cloud e na chave.

Para autenticar usando uma chave de API:

Crie ou configure uma chave de API seguindo as etapas em Introdução à Plataforma Google Maps.
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 o OAuth

Você pode autenticar usando o OAuth criando credenciais do OAuth e transmitindo-as para o host ou aplicativo do servidor MCP.

Para autenticar usando o OAuth:

No console do Google Cloud, escolha o projeto que você quer usar para o Maps Grounding Lite.
No menu APIs e serviços, selecione Credenciais.
No menu superior, selecione Criar credenciais > ID do cliente OAuth.
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.
Na seção Métricas, clique em Criar um cliente OAuth.
Na tela Criar ID do cliente OAuth, selecione um tipo de aplicativo e insira um nome para o ID do cliente.
Especifique os detalhes adicionais relevantes para o tipo de aplicativo. Por exemplo, se você estiver criando um aplicativo da Web, adicione URIs autorizados para solicitações de navegador e servidor.
Depois que o cliente for criado, salve o ID e a chave secreta do cliente.
Ao configurar o host ou 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 uma chave secreta 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 o MCP em um aplicativo de IA application.

Configurar o Maps Grounding Lite com a CLI do Gemini

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

Depois de instalar a CLI do Gemini, você pode usar 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.

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

Comece a fazer perguntas relacionadas ao 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 seu agente com `McpToolset` para o Maps Grounding Lite

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

Definir variável de ambiente:
Defina sua chave de API do Google Maps como uma variável de ambiente no terminal:
```
export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
        
```
Executar adk web:
Execute o comando a seguir para iniciar a interface da Web do ADK:
```
adk web
        
```
Interagir na interface:
- Selecione o travel_planner_agent.
- Tente comandos como:
  - "Estarei em São Francisco amanhã. Como está o clima?"
  - "Encontre cafeterias perto do Golden Gate Park."
  - "Receba rotas do GooglePlex para o SFO."

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