Maps Grounding Lite

Google Maps Platform Grounding Lite ist ein Dienst mit Unterstützung für das Model Context Protocol (MCP), mit dem Sie Ihre KI-Anwendungen ganz einfach mit vertrauenswürdigen geografischen Daten aus Google Maps fundieren können. Der MCP-Server stellt Tools bereit, mit denen LLMs auf Funktionen für Orte, Wetter und Routen zugreifen können. Sie können Maps Grounding Lite ausprobieren, indem Sie es in einem beliebigen Tool aktivieren, das MCP-Server unterstützt.

Tools

Maps Grounding Lite bietet Tools, mit denen LLMs auf die folgenden Google Maps-Funktionen zugreifen können:

• Orte suchen: Sie können Informationen zu Orten anfordern und KI-generierte Zusammenfassungen von Ortsdaten sowie Orts-IDs, Breiten- und Längengradkoordinaten und Google Maps-Links für jeden in der Zusammenfassung enthaltenen Ort abrufen. Sie können die zurückgegebenen Orts-IDs und Koordinaten des Breiten- und Längengrads mit anderen Google Maps Platform APIs verwenden, um Orte auf einer Karte darzustellen.
• Wetterinformationen abrufen: Informationen zum Wetter anfordern und aktuelle Bedingungen, stündliche Vorhersagen und Tagesvorhersagen zurückgeben.

• Routen berechnen: Informationen zu Fahr- oder Fußgängerrouten zwischen zwei Orten anfordern und Informationen zu Routenentfernung und -dauer zurückgeben.

  Hinweis :Maps Grounding Lite bietet keine detaillierte Routenführung, Wegbeschreibungen, Echtzeitverkehrsinformationen oder Navigationsinformationen.

Wenn Sie den Maps Grounding Lite MCP-Server aktivieren, können LLMs die neuen Tools aufrufen, die vom Server bereitgestellt werden, um zusätzliche Fundierungsdaten für die oben aufgeführten Datentypen zurückzugeben. Das LLM kann diese zusätzlichen Informationen zwar für den Kontext verwenden, die Antwort, die das LLM letztendlich generiert, enthält jedoch möglicherweise nicht die genauen Informationen, die vom MCP-Server zurückgegeben werden. Sie sollten die Richtigkeit der generierten Antwort überprüfen.

Maps Grounding Lite-Beispiel-App ausprobieren (in neuem Tab öffnen)

Abrechnung und Kontingente

Abrechnung

Beim „Pay as you go“-Preismodell der Google Maps Platform wird die Nutzung von Maps Grounding Lite für jede Anfrage berechnet. Jede Anfrage stellt ein Abrechnungsereignis dar. Die Nutzung wird für jede Produkt-SKU erfasst. Auf Ihrer Rechnung wird neben den Gesamtkosten eine Position für jede Artikelnummer aufgeführt. Weitere Informationen finden Sie unter Berichte – Übersicht.

Weitere Informationen zu den Preisen finden Sie in der Hauptpreistabelle und der Preistabelle für Indien.

Maps Grounding Lite ist auch über die Pakete „Essentials“ und „Pro“ mit der Option Abonnieren und sparen verfügbar.

Kontingente

Für die von Maps Grounding Lite bereitgestellten Tools gelten die folgenden Kontingente:

• Orte suchen: 300 Anfragen pro Minute und Projekt.
• Wetter abrufen: 300 Anfragen pro Minute und Projekt.
• Routen berechnen: 300 Anfragen pro Minute und Projekt.

Richtlinien und Nutzungsbedingungen

Maps Grounding Lite unterliegt den Nutzungsbedingungen für die Google Maps Platform, einschließlich der dienstspezifischen Nutzungsbedingungen für diesen Dienst. In diesem Abschnitt werden zusätzliche Dienstnutzungsanforderungen für Maps Grounding Lite beschrieben, einschließlich kompatibler LLMs und Anforderungen an die Quellenangabe.

Anforderungen an kompatible LLMs

Sie dürfen Maps Grounding Lite nur mit einem LLM verwenden, das den Nutzungsbedingungen für die Google Maps Platform entspricht.

Sie sind beispielsweise dafür verantwortlich, dass Google Maps-Inhalte nicht von dem von Ihnen ausgewählten LLM zwischengespeichert, gespeichert oder zur Verbesserung des LLM verwendet werden. Bevor Sie Maps Grounding Lite verwenden, müssen Sie die Nutzungsbedingungen für jedes Modell lesen, das Sie mit Maps Grounding Lite verwenden möchten. Sie dürfen Maps Grounding Lite nicht mit Modellen verwenden, bei denen die in das Modell eingegebenen Daten zum Trainieren oder Verbessern des Modells verwendet werden. Sie sind dafür verantwortlich, dass Ihre Nutzung des Modells vollständig den Beschränkungen für Google Maps-Inhalte in den Nutzungsbedingungen für die Google Maps Platform entspricht, einschließlich der dienstspezifischen Nutzungsbedingungen.

Anforderungen an die Quellenangabe für Google Maps-Quellen

Jede Tool-Antwort von Maps Grounding Lite enthält Quellenangaben. Wenn Sie Ergebnisse präsentieren, für die Tools von Maps Grounding Lite verwendet werden, müssen Sie die zugehörigen Google Maps-Quellen so angeben, dass die folgenden Anforderungen erfüllt sind:

• Die Google Maps-Quellen müssen direkt auf die generierten Inhalte folgen, die durch die Quellen belegt werden. Diese generierten Inhalte werden auch als fundierte Ausgabe bezeichnet.
• Die Google Maps-Quellen müssen innerhalb einer Nutzerinteraktion sichtbar sein.

Quellen für das Tool „Orte suchen“

Das Feld places des Tools search_places enthält Quellen, die die summary unterstützen. Für places werden die folgenden Metadaten zurückgegeben:

• place (Ressourcenname)
• id
• location
• googleMapsLinks

Für jeden Ort müssen Sie eine Linkvorschau generieren, die die folgenden Anforderungen erfüllt:

• Geben Sie für jede Quelle Google Maps als Quelle an. Halten Sie sich dabei an die Richtlinien für die Quellenangabe im Text für Maps Grounding Lite.
• Verlinken Sie die Quelle mit places.googleMapsLinks.placeUrl aus der Antwort.

LLMs für die Verwendung des MCP-Servers konfigurieren

Wenn Sie Maps Grounding Lite verwenden möchten, benötigen Sie zuerst ein Google Cloud-Projekt, in dem der API-Dienst Maps Grounding Lite aktiviert ist, sowie einen API-Schlüssel oder eine OAuth-Client-ID. Anschließend können Sie LLMs so konfigurieren, dass sie auf den MCP-Server zugreifen. Der Grounding Lite MCP-Server verwendet den streamfähigen HTTP-Transport.

Aktivieren Sie den Dienst Maps Grounding Lite in Ihrem Google Cloud-Projekt.

So aktivieren Sie die API für Ihr Projekt:

1. Wählen Sie in der Google Cloud Console das Projekt aus, das Sie für Maps Grounding Lite verwenden möchten.
2. Aktivieren Sie die Abrechnung für das Projekt in der Google Cloud Console.
3. Aktivieren Sie Maps Grounding Lite in der Google Cloud Console API-Bibliothek.

Mit einem API-Schlüssel authentifizieren

Sie können einen vorhandenen API-Schlüssel mit Maps Grounding Lite verwenden oder einen neuen erstellen, sofern Sie den Maps Grounding Lite-API-Dienst sowohl für das Google Cloud-Projekt als auch für den Schlüssel aktivieren.

Hinweis :Für Tests und Prototyping können Sie auch den Demoschlüssel für Google Maps kostenlos verwenden, ohne ein Rechnungskonto einzurichten.

So authentifizieren Sie sich mit einem API-Schlüssel:

1. Erstellen oder konfigurieren Sie einen API-Schlüssel, indem Sie der Anleitung unter Erste Schritte mit der Google Maps Platform folgen.
2. Übergeben Sie den Schlüssel mit dem X-Goog-Api-Key-Header an den MCP-Server. Sie müssen dies als benutzerdefinierten HTTP-Header in der MCP-Toolkonfiguration des LLM angeben.

Hinweis :Wenn Sie einen API-Schlüssel erstellen oder konfigurieren, sollten Sie die Verwendung des Schlüssels durch entsprechende Einschränkungen begrenzen. Weitere Informationen finden Sie unter API-Schlüssel einschränken.

Mit OAuth authentifizieren

Sie können sich mit OAuth authentifizieren, indem Sie OAuth-Anmeldedaten erstellen und an den MCP-Host oder die MCP-Serveranwendung übergeben.

So authentifizieren Sie sich mit OAuth:

1. Wählen Sie in der Google Cloud Console das Projekt aus, das Sie für Maps Grounding Lite verwenden möchten.
2. Wählen Sie im Menü APIs & Dienste die Option Anmeldedaten aus.
3. Wählen Sie im oberen Menü Anmeldedaten erstellen > OAuth-Client-ID aus.
4. Wenn für das Projekt kein Zustimmungsbildschirm konfiguriert ist, klicken Sie auf Zustimmungsbildschirm konfigurieren und folgen Sie der Anleitung auf dem Bildschirm.
5. Klicken Sie im Bereich Messwerte auf OAuth-Client erstellen.
6. Wählen Sie auf dem Bildschirm OAuth-Client-ID erstellen einen Anwendungstyp aus und geben Sie einen Namen für die Client-ID ein.
7. Geben Sie die zusätzlichen Details an, die für Ihren Anwendungstyp relevant sind. Wenn Sie beispielsweise eine Webanwendung erstellen, fügen Sie autorisierte URIs für Browser- und Serveranfragen hinzu.
8. Speichern Sie nach der Erstellung des Clients die Client-ID und das Secret.
9. Wenn Sie Ihren MCP-Host oder Ihre MCP-Serveranwendung für den Zugriff auf Maps Grounding Lite konfigurieren, übergeben Sie Ihre OAuth-Client-ID und Ihr Secret. Außerdem müssen Sie den folgenden Bereich anfordern: https://www.googleapis.com/auth/maps-platform.mapstools.

Weitere Informationen finden Sie unter Mit OAuth 2.0 auf Google APIs zugreifen.

LLMs für den Zugriff auf den Maps Grounding Lite-MCP-Server konfigurieren

Sobald Sie ein Google Cloud-Projekt mit aktiviertem Maps Grounding Lite API-Dienst und gültigen Anmeldedaten wie einem API-Schlüssel oder einer OAuth-Client-ID und einem entsprechenden Secret haben, können Sie LLMs für den Zugriff auf den MCP-Server konfigurieren. Folgen Sie dazu der entsprechenden MCP-Konfigurationsdokumentation und verwenden Sie die MCP-Server-URL für Maps Grounding Lite: https://mapstools.googleapis.com/mcp.

Weitere Informationen finden Sie unter MCP in einer KI-Anwendung konfigurieren.

Maps Grounding Lite mit der Gemini CLI konfigurieren

In diesem Abschnitt finden Sie ein Beispiel für die Konfiguration des Maps Grounding Lite-MCP-Servers mit der Gemini CLI. Weitere Informationen finden Sie unter MCP-Server mit der Gemini CLI.

1. Nachdem Sie die Gemini CLI installiert haben, können Sie den Befehl „add“ verwenden, um den Maps Grounding Lite-MCP-Server zu konfigurieren:

   gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-grounding-lite-mcp https://mapstools.googleapis.com/mcp
   

   Wenn die Konfiguration erfolgreich war, wird eine Bestätigung angezeigt, dass der Server Ihren Nutzereinstellungen hinzugefügt wurde.

2. Führen Sie den Befehl /mcp list aus, um zu prüfen, ob der Server ordnungsgemäß funktioniert:

   > /mcp list
   
   Configured MCP servers:
   
   maps-grounding-lite-mcp - Ready (3 tools)
   Tools:
   -   compute_routes
   -   lookup_weather
   -   search_places
   

3. Sie können jetzt über die CLI Fragen zu Google Maps stellen. Sie können beispielsweise „Empfiehl mir einige Restaurants in Mountain View“ eingeben. Dadurch wird das Tool „search_places“ in Ihrem Namen aufgerufen.

Hinweis :Informationen zum Konfigurieren einer Gemini CLI-Erweiterung für den Zugriff auf Maps Grounding Lite mit OAuth finden Sie im Abschnitt Gemini CLI in der MCP-Dokumentation zu Google Cloud.

Grounding Lite mit dem Agent Development Kit (ADK) konfigurieren

In diesem Abschnitt finden Sie Beispiele, die zeigen, wie Sie den Grounding Lite MCP-Server mit dem Agent Development Kit (ADK) und entweder Python, Java oder TypeScript konfigurieren.

Hinweis :Achten Sie darauf, dass Sie den Dienst „Maps Grounding Lite“ aktiviert und einen API-Schlüssel erhalten haben.

Python

Schritt 1: KI-Agent mit McpToolset für Google Maps Grounding Lite definieren

Ändern Sie die Datei agent.py. Ersetzen Sie YOUR_GOOGLE_MAPS_API_KEY durch Ihren tatsächlichen API-Schlüssel.

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

Schritt 2: Prüfen, ob __init__.py vorhanden ist

Achten Sie darauf, dass sich im selben Verzeichnis wie Ihre agent.py-Datei eine __init__.py befindet:

from . import agent
    

Schritt 3: adk web ausführen und interagieren

1. Umgebungsvariable festlegen:
   Legen Sie Ihren Google Maps API-Schlüssel als Umgebungsvariable in Ihrem Terminal fest:

   export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
           

2. adk web ausführen:
   Führen Sie den folgenden Befehl aus, um die ADK-Weboberfläche zu starten:

   adk web
           

3. Interaktion auf der Benutzeroberfläche:
   • Wählen Sie das travel_planner_agent aus.
   • Probieren Sie Prompts wie die folgenden aus:
     • „Ich bin morgen in San Francisco. Wie ist das Wetter?“
     • „Finde Cafés in der Nähe des Golden Gate Park.“
     • „Get directions from GooglePlex to SFO.“ (Route von GooglePlex zum Flughafen San Francisco)

Java

Definieren Sie einen Agenten, der McpToolset in Java initialisiert. Ersetzen Sie YOUR_GOOGLE_MAPS_API_KEY_HERE durch den tatsächlichen API-Schlüssel, den Sie erhalten haben, wenn Sie keine Umgebungsvariable verwenden.

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

Definieren Sie einen Agent, der MCPToolset in TypeScript initialisiert:

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"
            }
        })
    ],
});
    

Feedback geben

Wenn Sie Feedback zu Maps Grounding Lite geben möchten, verwenden Sie die folgenden Formulare:

• Fehler melden
• Feature Request senden
• Feedback geben