Mit der Pro-SKU können Sie mehr Funktionen der Maps Experience Agent Tools nutzen. Informationen zu Pro

Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Tools für den Maps Experience-Agenten

Maps Experience-Agent-Tools (früher Maps Grounding Lite) ist ein Google Maps Platform-Dienst mit Model Context Protocol (MCP)- und REST-Unterstützung, mit dem Sie Ihre KI-Anwendungen mit vertrauenswürdigen Geodaten von Google Maps fundieren können. Mit den Tools können LLMs auf Daten zu Orten, Wetter, Luftqualität, Pollen und Routen zugreifen. Andere Tools lösen Ortsnamen und Google Maps-URLs in Orts-IDs auf. Sie können die Maps Experience Agent Tools ausprobieren, indem Sie den MCP-Server in einem Tool aktivieren, das MCP-Server unterstützt. Sie können jedes Tool auch als REST-Methode aufrufen. Weitere Informationen finden Sie unter Tools mit REST aufrufen.

Maps Experience Agent Tools ist ein Produkt mit zwei SKUs: Essentials und Pro. Jede Anfrage wird im Rahmen von Essentials abgerechnet, sofern keine Pro-Option verwendet wird. Mit den Pro-Optionen können Sie Orte entlang einer Route suchen, erweiterte Ortsdetails abrufen, mehr Orte pro Suche und mehr Zwischenstopps pro Route angeben, Routen mit Echtzeit-Verkehrsinformationen planen, Pollenflugvorhersagen abrufen und historische Luftqualitätsdaten einsehen. Beide SKUs verwenden dieselben Tools, denselben MCP-Server, dieselben REST-Methoden und dieselben Anmeldedaten. Weitere Informationen finden Sie unter Essentials und Pro.

Tools

Mit den Maps Experience Agent Tools können LLMs auf die folgenden Google Maps-Funktionen zugreifen:

Nach Orten suchen: Sie können Informationen zu Orten anfordern und KI-generierte Zusammenfassungen erhalten. Die Antwort enthält außerdem Orts-IDs, Breiten-/Längengradkoordinaten und Google Maps-URLs für jeden Ort in der Zusammenfassung. Sie können die Orts-IDs und die Koordinaten für den Breiten- und Längengrad mit anderen Google Maps Platform APIs verwenden, um Orte auf einer Karte anzuzeigen. Wenn Sie diese Orte mit dem Places UI Kit ohne zusätzliche Kosten anzeigen möchten, verwenden Sie das Agentic Data Visualization Token (Vorabversion). Mit Pro können Sie erweiterte Place Details wie Statistiken aus Rezensionen und bis zu 10 Orte pro Anfrage anfordern.
Entlang der Route suchen: Sie können Orte entlang einer Reiseroute finden, die mit einem retrieval_token aus compute_routes, route_endpoints oder einem encoded_polyline angegeben wird. Außerdem erhalten Sie eine KI-generierte Zusammenfassung, Ortsdetails, die Umwegstrecke und die Reisezeit sowie ein agentisches Datenvisualisierungstoken (Vorabversion). Jede search_along_route-Anfrage wird über die Pro-SKU abgerechnet.
Wetter abrufen: Frage die Umweltbedingungen für einen Ort ab, einschließlich Wetter (aktuelle Bedingungen, 24-Stunden-Verlauf und bis zu 10-Tage-Vorhersage pro Stunde und Tag) und aktuelle oder bis zu 4-Tage-Vorhersage der Luftqualität. Mit Pro können Sie auch tägliche Pollenflugvorhersagen für bis zu 5 Tage (mit Details zu Pflanzenarten) und stündliche Verlaufsdaten zur Luftqualität für bis zu 30 Tage anfordern.
Routen berechnen: Sie können eine Route zwischen einem Start- und einem Zielort anfordern, optional über Zwischenstopps. Zurückgegeben werden die Entfernung und Dauer der Route sowie ein retrievalToken für DRIVE-Routen, das Sie an search_along_route übergeben können. Mit Pro können Routen die aktuelle Verkehrslage berücksichtigen und mehr Zwischenstopps enthalten.

Hinweis: Die Maps Experience Agent Tools bieten keine detaillierten Wegbeschreibungen oder Navigationsinformationen. Bei Routen, die ohne Pro-Optionen berechnet werden, wird die aktuelle Verkehrslage nicht berücksichtigt.
Namen auflösen und Maps-URLs auflösen: Ortsnamen, Adressen und Google Maps-URLs in Orts-IDs auflösen. Weitere Informationen finden Sie unter Resolution API.

Nachdem Sie den MCP-Server aktiviert haben, können LLMs seine Tools aufrufen, um Fundierungsinformationen für diese Datentypen abzurufen. Das LLM kann diese Informationen als Kontext verwenden. Die endgültige Antwort enthält jedoch möglicherweise nicht die genauen Informationen, die der MCP-Server zurückgegeben hat. Prüfen Sie die Richtigkeit der generierten Antwort.

Essentials und Pro

Essentials und Pro sind zwei SKUs desselben Produkts, keine separaten Produkte oder Tarife. Eine Anfrage wird unter Pro abgerechnet, wenn sie eine Pro-Option verwendet. Alle anderen Anfragen werden unter Essentials abgerechnet. Pro-Optionen sind gewöhnliche Felder in der Toolanfrage, sodass ein LLM sie in Ihrem Namen verwenden kann. Ein Agent kann auch beide SKUs in derselben Unterhaltung verwenden. Ein Agent könnte beispielsweise Essentials verwenden, um Cafés in der Nähe einer Sehenswürdigkeit zu finden. Anschließend könnte Pro verwendet werden, um eine weiterführende Frage zu den Signature-Drinks und Sitzgelegenheiten zu beantworten. Es gibt keinen separaten MCP-Server, ‑Endpunkt oder ‑Anmeldedaten für Pro.

Essentials, Pro und Fundierung mit Google Maps vergleichen

Fundierung mit Google Maps ist ein separates Produkt. Sie ist in Gemini-Modelle in der Gemini API, in Google AI Studio und in der Gemini Enterprise Agent Platform integriert. Das Modell entscheidet, wann Google Maps abgefragt werden soll, und gibt fundierte Antworten mit Quellenangaben zurück. Wählen Sie die Fundierung mit Google Maps aus, wenn Sie auf Gemini aufbauen und möchten, dass das Modell die Fundierung übernimmt. Wählen Sie Maps Experience Agent Tools für andere Modelle oder Agent-Frameworks oder für die direkte Steuerung jedes Toolaufrufs aus.

In der folgenden Tabelle werden die Essentials-SKU, die Pro-SKU und die Fundierung mit Google Maps verglichen:

	Maps Experience Agent Tools		Fundierung mit Google Maps
	Essentials-SKU (früher Maps Grounding Lite)	Pro SKU	Fundierung mit Google Maps
Abrechnung von Anfragen	Jede Toolanfrage, bei der keine Pro-Option verwendet wird	Jede `search_along_route`-Anfrage oder jede Anfrage an ein anderes Tool, das eine Pro-Option verwendet. Weitere Informationen finden Sie unter Was wird unter der Pro-SKU abgerechnet?.	Jede Google Maps-Abfrage oder jeder fundierte Prompt, je nach Plattform und Modell
Modelle und Plattformen	Jedes Modell- oder Agenten-Framework, das MCP unterstützt oder REST APIs aufrufen kann. Ein Toolset und dieselben Anmeldedaten für beide SKUs		Gemini-Modelle in der Gemini API, in Google AI Studio und auf der Gemini Enterprise Agent Platform
Was die Tools zurückgeben	Wichtige Fakten: Ortsdetails für bis zu 5 Orte pro Suche, Routenentfernung und ‑dauer ohne Live-Verkehrsdaten, aktuelles Wetter und Vorhersagen (plus 24-Stunden-Wetterverlauf) sowie aktuelle oder vorhergesagte Luftqualität	Alles, was in Essentials enthalten ist, plus Orte entlang einer Route mit Umwegzeit und ‑entfernung, erweiterte Ortsdetails (z. B. Informationen aus Rezensionen), bis zu 10 Orte pro Suche, Routen mit Live-Verkehrsdaten, bis zu 25 Zwischenwegpunkte, Pollenflugvorhersagen und bis zu 30 Tage historische Luftqualitätsdaten	Ortsdetails und Informationen aus Rezensionen sowie Routeninformationen mit Echtzeit-Verkehrslage
Beispielanfragen	Faktische und logistische Fragen: Geschäfte oder Unternehmen finden, Öffnungszeiten, Adressen, Schätzungen zu Entfernung oder Fahrtzeit, aktuelles Wetter, 10-Tage-Wettervorhersagen und aktuelle oder 4-Tage-Luftqualitätsvorhersagen	Subjektive, allgemeine oder spezialisierte Fragen: Orte entlang einer Route, Atmosphäre, Spezialitäten, Tipps für Besucher, Vergleiche von 6 bis 10 Orten, Fahrtzeiten bei aktueller Verkehrslage, Pollen- und Allergievorhersagen sowie Luftqualitätshistorie der letzten 30 Tage	Konversationelle Suche, Reiseplanung und lokale Entdeckungen in Gemini
Places UI Kit-Visualisierungen	Ohne zusätzliche Kosten im Token für agentische Datenvisualisierung (Vorabversion) enthalten		Separat abgerechnet
Kostenlose monatliche Nutzung	10.000 Anfragen	5.000 Anfragen	Abhängig von der Plattform und dem Modell. In der Gemini API sind beispielsweise in Gemini 3 und neueren Modellen 5.000 Suchanfragen pro Monat kostenlos enthalten. Danach kosten Suchanfragen 14 $ pro 1.000 Anfragen.
Pay as you go-Preis	7,00 $ pro 1.000 Anfragen, mit Mengenrabatten	14,00 $ pro 1.000 Anfragen, mit Mengenrabatten
Jetzt abonnieren und sparen	In den Essentials- und Pro-Abos enthalten	Im Pro-Abo enthalten	Nicht verfügbar
Jetzt starten	Eine Einrichtung für beide SKUs: siehe LLMs für die Verwendung des MCP-Servers konfigurieren oder Tools mit REST aufrufen.		Gemini API oder Agent Platform

Diese Optionen funktionieren mit beiden SKUs gleich: Reisemodi, Abfahrts- und Ankunftszeiten, alternative Routen, Routen-Polylinien, Wetterabfragen, Abfragen der aktuellen und vorhergesagten Luftqualität (einschließlich Schadstoffkonzentrationen und lokaler AQI-Skalen), Wettereinheitensysteme und die Resolution API. Sie ändern nicht, unter welcher SKU eine Anfrage abgerechnet wird.

Was wird unter der Pro-SKU abgerechnet?

In der folgenden Tabelle sind die Funktionen zusammengefasst, die in Essentials enthalten sind, und die Funktionen, für die die Pro-SKU erforderlich ist:

Tool	Funktion	Essentials	Pro
Orte suchen	Orte pro Anfrage	Bis zu 5	6 bis 10 (`page_size` von 6 bis 10)
Orte suchen	Erweiterte Ortsdetails in Suchzusammenfassungen (Informationen aus Rezensionen, Highlights auf der Speisekarte, Atmosphäre, Besucheraufkommen, Tipps für Besucher sowie Entfernung oder Fahrtzeit bei Suchanfragen nach Orten in der Nähe)	Nicht verfügbar	Verfügbar mit `include_extended_details`
Entlang der Route suchen	Orte entlang einer Route, Umwegentfernung und Reisedauer sowie optionale erweiterte Place Details oder verkehrsabhängige Umwegzeiten	Nicht verfügbar	Für alle Anfragen gilt:
Routen berechnen	Routingeinstellung	Aktuelle Verkehrslage wird nicht berücksichtigt	Berücksichtigt die aktuelle Verkehrslage oder Echtzeitdaten für öffentliche Verkehrsmittel mit `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`
Routen berechnen	Wegpunkte entlang der Route pro Route	Bis zu 10	11 bis 25 (mehr als 10 `intermediate_waypoints`)
Wetter abrufen	Wetter	Aktuelles Wetter, stündliche und tägliche Vorhersagen (bis zu 10 Tage) und stündlicher Verlauf für bis zu 24 Stunden (`WEATHER` in `capabilities` oder Legacy-Anfragen, bei denen `capabilities`, `weather_options`, `air_quality_options` und `language_code` weggelassen werden)	Keine Pro-Optionen (alle `WEATHER`-Daten sind in Essentials enthalten)
	Luftqualität	Aktuelle Bedingungen, stündliche Ergebnisse für den ganzen Tag und stündliche Vorhersagen für bis zu 4 Tage (`AIR_QUALITY` in `capabilities`)	Historische Luftqualität bis zu 30 Tage in der Vergangenheit (`AIR_QUALITY` in `capabilities` mit einem `date` vor heute oder einem vergangenen `hour` in der Zeitzone des Standorts), wenn in der Antwort zurückgegeben
	Pollen	Nicht verfügbar	Tägliche Pollenflugvorhersagen für bis zu 5 Tage und Details zu Pflanzenarten (`POLLEN` in `capabilities`), sofern in der Antwort zurückgegeben
Resolution API	Keine Pro-Optionen. Alle Anfragen werden kostenlos unter der SKU Places API Text Search Essentials (IDs Only) abgerechnet.

Informationen zu den Anfrageoptionen, mit denen die einzelnen Funktionen aktiviert werden, finden Sie unter Orte suchen, Entlang der Route suchen, Routen berechnen und Wetter abrufen.

Pro-Nutzung steuern

Die Pro-Optionen sind auf dem search_places, compute_routes und lookup_weather standardmäßig deaktiviert. Ein LLM legt sie fest oder ruft search_along_route auf, wenn die Anfrage des Nutzers dies erfordert und die Toolbeschreibung oder Ihre Anweisungen dies zulassen. In den Toolbeschreibungen wird dem Modell mitgeteilt, welche Optionen mehr kosten und wann sie verwendet werden sollten: ein page_size über 5, erweiterte Place Details, mehr als 10 Zwischenwegpunkte, verkehrsabhängige Routenplanung und search_along_route. Wenn Sie die Tools mit REST aufrufen, werden alle Optionen in Ihrem Code festgelegt. So verwalten Sie die Kosten:

Teilen Sie dem Modell mit, wann Pro-Optionen angemessen sind. Beispiel: „Setze include_extended_details nur, wenn der Nutzer nach Rezensionen, Speisekarten oder der Atmosphäre fragt.“ Oder: „Verwende ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL nur, wenn der Nutzer nach der aktuellen Fahrtzeit fragt.“ Oder: „Rufe search_along_route nur auf, wenn der Nutzer nach Orten entlang einer Route fragt.“ Oder: „Füge POLLEN oder AIR_QUALITY mit einem vergangenen date oder hour nur hinzu, wenn der Nutzer nach Pollen, Allergien oder historischen Luftqualitätsdaten fragt.“
Wenn Sie einen KI-Agenten mit der Essentials-SKU verwenden möchten, weisen Sie das Modell an, niemals search_along_route aufzurufen oder eine Pro-Option zu verwenden. Die Pro-Optionen sind include_extended_details, page_size über 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, mehr als 10 Zwischenwegpunkte, POLLEN in capabilities und eine vergangene date oder hour mit AIR_QUALITY in capabilities. Wenn Ihr MCP-Client Tools oder Toolargumente einschränken kann, können Sie search_along_route und diese Argumentwerte auch in der Toolkonfiguration blockieren.
Behalten Sie die Maps Grounding Pro-SKU in Ihren Abrechnungsberichten im Auge und richten Sie Budgetbenachrichtigungen ein.

Resolution API

Maps Experience Agent Tools bietet die Resolution API. Sie löst Standorttext im freien Format und URLs in strukturierte Google Maps-Ortskennungen auf. Die Resolution API ist als REST-Methoden und als Tools auf dem MCP-Server verfügbar:

Namen auflösen (REST, MCP): Eine Gruppe von Standortnamen oder Adressen in bestimmte Ortseinheiten in Google Maps auflösen. Mit diesem Tool können unstrukturierte Nutzeranfragen in stabilen Orts-IDs fundiert werden.
Maps-URLs auflösen (REST, MCP): Lösen Sie einen Batch von Google Maps-URLs in bestimmte Ortselemente auf. Zu den unterstützten Formaten gehören Standard-Orts-URLs und gekürzte URLs.

Sie können die zurückgegebenen Orts-IDs mit anderen Google Maps Platform APIs verwenden. Jede Antwort enthält auch einen Link, über den die aufgelösten Orte als Liste in Google Maps gespeichert werden können.

Weitere Informationen finden Sie unter Maps Tools Resolution API.

Beispiel-App ausprobieren (wird in einem neuen Tab geöffnet)

Abrechnung und Kontingente

Abrechnung

Beim „Pay as you go“-Preismodell der Google Maps Platform wird die Nutzung von Agent-Tools für Maps Experience pro Anfrage berechnet. Jede Anfrage stellt ein Abrechnungsereignis dar. Die Nutzung wird jeweils pro Produkt-SKU erfasst. Ihre Rechnung enthält neben den Gesamtkosten eine Position für jede SKU. Weitere Informationen finden Sie in der Übersicht über die Berichterstellung.

Jede Anfrage vom Typ „Search places“, „Search along route“, „Compute routes“ oder „Lookup weather“ über den MCP-Server oder mit REST wird unter einer SKU abgerechnet: Maps Grounding Essentials oder Maps Grounding Pro. Jede search_along_route-Anfrage und jede Anfrage, die eine Pro-Option verwendet, wird über die Pro-SKU abgerechnet. Eine Anfrage wird nie unter beiden SKUs abgerechnet und die Anzahl der Pro-Optionen in einer Anfrage ändert nichts an den Kosten. Informationen zu den Funktionen und Optionen, die die SKU für jedes Tool bestimmen, finden Sie unter Was wird unter der Pro-SKU abgerechnet?.

Maps Grounding Essentials-Anfragen werden nach den ersten 10.000 Anfragen pro Monat mit 7,00 $ pro 1.000 Anfragen abgerechnet. Maps Grounding Pro-Anfragen werden nach den ersten 5.000 Anfragen pro Monat mit 14,00 $ pro 1.000 Anfragen abgerechnet. Für beide SKUs gibt es Mengenrabatte bei höherer monatlicher Nutzung.

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

Anfragen an die Resolution API (ResolveNames und ResolveMapsUrls) werden kostenlos über die SKU Places API Text Search Essentials (IDs Only) abgerechnet.

Wenn Sie die Orte aus einer search_places- oder search_along_route-Antwort mit dem Places UI Kit anzeigen, können Sie das agentische Datenvisualisierungstoken (Vorabversion) verwenden, damit diese Places UI Kit-Anfragen nicht in Rechnung gestellt werden.

Die Nutzung der Essentials-SKU ist in den Essentials- und Pro-Tarifen Abonnieren und sparen enthalten. Die Nutzung der Pro-SKU ist im Pro-Tarif enthalten.

Kontingente

Für die Tools und APIs, die von Maps Experience Agent Tools bereitgestellt werden, gelten die folgenden Kontingente:

Orte suchen: 300 Anfragen pro Minute und Projekt.
Entlang der Route suchen: 300 Anfragen pro Minute und Projekt.
Wetter abrufen: 300 Abfragen pro Minute und Projekt.
Routen berechnen: 300 Anfragen pro Minute und Projekt.
Namen auflösen: 600 Abfragen pro Minute und Projekt.
Resolve Maps URLs: 600 Anfragen pro Minute und Projekt.

Kontingente werden für jedes Tool gezählt und von den Essentials- und Pro-SKUs gemeinsam genutzt. Eine Pro-Anfrage verbraucht dasselbe Kontingent wie eine Essentials-Anfrage an dasselbe Tool.

Jede Resolution API-Anfrage zählt als eine Abfrage, unabhängig davon, wie viele Elemente sie enthält.

Richtlinien und Nutzungsbedingungen

Die Maps Experience Agent Tools unterliegen den Nutzungsbedingungen für die Google Maps Platform, einschließlich der dienstspezifischen Nutzungsbedingungen. In diesem Abschnitt werden zusätzliche Nutzungsanforderungen für Tools für Maps Experience-Agenten beschrieben, einschließlich kompatibler LLMs und Quellenangaben. Die Anforderungen gelten für alle Ergebnisse, unabhängig davon, über welche SKU eine Anfrage abgerechnet wird.

Anforderungen an kompatible LLMs

Sie dürfen die Maps Experience Agent Tools nur mit einem LLM verwenden, das den Nutzungsbedingungen der Google Maps Platform entspricht.

Sie sind beispielsweise dafür verantwortlich, dass Google Maps-Inhalte nicht von dem von Ihnen verwendeten LLM im Cache gespeichert, gespeichert oder zur Verbesserung des LLM verwendet werden. Bevor Sie die Maps Experience Agent Tools verwenden, müssen Sie die Nutzungsbedingungen für alle Modelle lesen, die Sie mit den Maps Experience Agent Tools verwenden möchten. Sie dürfen die Agent-Tools für Maps Experience nicht mit Modellen verwenden, die die in das Modell eingegebenen Daten für das Training oder die Verbesserung von Modellen nutzen. Sie sind dafür verantwortlich, dass Ihre Nutzung des Modells vollständig den Einschränkungen für Google Maps-Inhalte in den Nutzungsbedingungen der Google Maps Platform entspricht, einschließlich der dienstspezifischen Bedingungen.

Anforderungen an die Quellenangabe für Google Maps-Quellen

Jede Toolantwort von Maps Experience Agent Tools enthält Quellen. Wenn Sie Ergebnisse aus Maps Experience Agent Tools präsentieren, müssen Sie die zugehörigen Google Maps-Quellen angeben und die folgenden Anforderungen erfüllen:

Die Google Maps-Quellen müssen unmittelbar auf die generierten Inhalte folgen, die sie unterstützen. Diese generierten Inhalte werden auch als fundierte Ausgabe bezeichnet.
Die Google Maps-Quellen müssen innerhalb einer Nutzerinteraktion sichtbar sein.

Quellen für die Tools „Orte suchen“ und „Entlang der Route suchen“

Das Feld places des search_places-Tools und das Feld results[].place des search_along_route-Tools stellen Quellen bereit, die die summary unterstützen. Für jeden Ort werden die folgenden Metadaten zurückgegeben:

place (Ressourcenname)
id
location
googleMapsLinks
attribution

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

Geben Sie jede Quelle gemäß den Richtlinien für die Textquellenangabe für Maps Experience Agent Tools als Google Maps an.
Verlinken Sie die Quelle mit googleMapsLinks.placeUrl aus der Antwort.

Diese Anforderungen gelten auch für Zusammenfassungen, die erweiterte Ortsdetails aus Pro enthalten, z. B. Informationen aus Rezensionen. In der summary wird jeder Ort mit einem nullbasierten Index wie [0] angegeben, der einem Eintrag in places oder results zugeordnet ist. Jeder Ort enthält auch googleMapsLinks.reviewsUrl, das mit den Rezensionen des Ortes auf Google Maps verknüpft ist. Nutzer können ihm folgen, um die Rezensionen hinter einer Statistik zu sehen.

Sprachgesteuerte Benutzeroberflächen

Wenn Ihre App Ergebnisse der Maps Experience Agent Tools per Sprachausgabe ausgibt, müssen Sie auch die Anforderungen für Sprachschnittstellen erfüllen. Zusammenfassung:

Quellenangabe: Die Google Maps-Quellen müssen in einer Companion-Benutzeroberfläche angezeigt werden, die eine wortgetreue historische Aufzeichnung der Sprachunterhaltung enthält.
Aktive Offenlegung: Informieren Sie Nutzer zum Zeitpunkt der Interaktion darüber, dass KI-generierte Inhalte Informationen aus Google Maps enthalten können. Weisen Sie sie auch darauf hin, dass detaillierte Quellen in der Companion-UI verfügbar sind. Das geht über das Display oder per Sprachbefehl.
Dauerhafte Offenlegung: Behalten Sie eine dauerhafte Erklärung bei, z. B. in einem Menü für Spracheinstellungen, dass KI-generierte Inhalte Google Maps-Inhalte enthalten können.
Nutzeranfragen: Beantworte die Fragen der Nutzer zur Quelle des Inhalts genau und verweise sie auf die Companion-UI, um weitere Informationen zu erhalten.

LLMs für die Verwendung des MCP-Servers konfigurieren

Wenn Sie die Maps Experience Agent Tools verwenden möchten, benötigen Sie ein Google Cloud-Projekt, in dem der API-Dienst Maps Experience Agent Tools aktiviert ist. Außerdem benötigen Sie 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 MCP-Server verwendet den Streamable HTTP-Transport.

Aktivieren Sie Maps Experience Agent Tools in Ihrem Google Cloud-Projekt.

So aktivieren Sie die API in Ihrem Projekt:

Wählen Sie in der Google Cloud Console das Projekt aus, das Sie für die Agent-Tools für Maps Experience verwenden möchten.
Aktivieren Sie die Abrechnung für das Projekt in der Google Cloud Console.
Aktivieren Sie die Agent-Tools für Maps Experience in der API-Bibliothek der Google Cloud Console.

Mit einem API-Schlüssel authentifizieren

Sie können einen vorhandenen API-Schlüssel mit den Maps Experience Agent Tools verwenden oder einen neuen erstellen. Aktivieren Sie in beiden Fällen den API-Dienst Maps Experience Agent Tools sowohl für das Google Cloud-Projekt als auch für den Schlüssel.

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

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

Mit OAuth authentifizieren

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

So authentifizieren Sie sich mit OAuth:

Wählen Sie in der Google Cloud Console das Projekt aus, das Sie für die Agent-Tools für Maps Experience verwenden möchten.
Wählen Sie im Menü APIs und Dienste die Option Anmeldedaten aus.
Wählen Sie im Menü oben Anmeldedaten erstellen > OAuth-Client-ID aus.
Wenn für das Projekt kein Zustimmungsbildschirm konfiguriert ist, klicken Sie auf Zustimmungsbildschirm konfigurieren und folgen Sie der Anleitung auf dem Bildschirm.
Klicken Sie im Bereich Messwerte auf OAuth-Client erstellen.
Wählen Sie auf dem Bildschirm OAuth-Client-ID erstellen einen Anwendungstyp aus und geben Sie einen Namen für die Client-ID ein.
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.
Nachdem der Client erstellt wurde, speichern Sie die Client-ID und den Clientschlüssel.
Wenn Sie Ihre MCP-Host- oder MCP-Serveranwendung konfigurieren, übergeben Sie Ihre OAuth-Client-ID und Ihr OAuth-Secret. Außerdem müssen Sie den folgenden Bereich anfordern: https://www.googleapis.com/auth/maps-platform.mapstools.

Weitere Informationen finden Sie unter OAuth 2.0 für den Zugriff auf Google APIs verwenden.

LLMs für den Zugriff auf den MCP-Server für Maps Experience Agent Tools konfigurieren

Nachdem Sie den Dienst Maps Experience Agent Tools aktiviert und Anmeldedaten erstellt haben, können Sie LLMs für den Zugriff auf den MCP-Server konfigurieren. Folgen Sie der MCP-Konfigurationsdokumentation Ihres LLM und verwenden Sie die MCP-Server-URL: https://mapstools.googleapis.com/mcp

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

Maps Experience Agent Tools mit der Gemini CLI konfigurieren

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

Führen Sie nach der Installation der Gemini CLI gemini mcp add aus, um den MCP-Server zu konfigurieren:
```
gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-experience-agent-tools-mcp https://mapstools.googleapis.com/mcp
```
Wenn die Konfiguration erfolgreich war, sollten Sie eine Bestätigung sehen, dass der Server Ihren Nutzereinstellungen hinzugefügt wurde.

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

> /mcp list

Configured MCP servers:

maps-experience-agent-tools-mcp - Ready (6 tools)
Tools:
-   compute_routes
-   lookup_weather
-   resolve_maps_urls
-   resolve_names
-   search_along_route
-   search_places

Stellen Sie über die Befehlszeile Fragen zu Google Maps. Versuchen Sie es beispielsweise mit „Empfehle mir einige Restaurants in Mountain View“. Dadurch wird das Tool search_places in Ihrem Namen aufgerufen.

Maps Experience Agent Tools mit dem Agent Development Kit (ADK) konfigurieren

In diesem Abschnitt wird gezeigt, wie Sie den MCP-Server mit dem Agent Development Kit (ADK) in Python, Java oder TypeScript konfigurieren.

Python

Eine vollständige Implementierung dieses Beispiels finden Sie auf GitHub im adk-samples-Repository.

Schritt 1: KI-Agenten mit `McpToolset` für Maps Experience Agent Tools 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 eine __init__.py befindet:

from . import agent

Schritt 3: `adk web` ausführen und interagieren

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"
        
```
adk web ausführen:
Führen Sie den folgenden Befehl aus, um die ADK-Weboberfläche zu starten:
```
adk web
        
```
In der Benutzeroberfläche interagieren:
- 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 Parks.“
  - „Route vom Googleplex zum SFO“

Java

Definieren Sie einen Agenten, der den 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 Agenten, der den 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: "StreamableHTTPConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            transportOptions: {
                requestInit: {
                    headers: {
                        "X-Goog-Api-Key": googleMapsApiKey,
                        "Content-Type": "application/json",
                        "Accept": "application/json, text/event-stream"
                    }
                }
            }
        })
    ],
});

Tools mit REST aufrufen

Jedes Tool in den Maps Experience Agent Tools ist auch als REST-Methode verfügbar. Rufen Sie die REST-Methoden direkt auf, wenn Sie die Tools in Ihren eigenen Agent oder Ihre eigene Anwendung einbinden möchten. Sie können beispielsweise eigene Funktionen für ein Modell deklarieren, die Optionen auswählen, die das Modell festlegen kann, oder Standardwerte in Ihrem Code festlegen.

In der folgenden Tabelle sind die REST-Methoden für die einzelnen Tools aufgeführt:

Tool	REST-Methode
`search_places`	`POST https://mapstools.googleapis.com/v1:searchText`
`search_along_route`	`POST https://mapstools.googleapis.com/v1:searchAlongRoute`
`lookup_weather`	`POST https://mapstools.googleapis.com/v1:lookupWeather`
`compute_routes`	`POST https://mapstools.googleapis.com/v1:computeRoutes`
`resolve_names`	`POST https://mapstools.googleapis.com/v1:resolveNames`
`resolve_maps_urls`	`POST https://mapstools.googleapis.com/v1:resolveMapsUrls`

Eine REST-Anfrage verwendet dieselben Optionen wie das entsprechende Tool und gibt dieselbe Antwort zurück. In REST-Anfrage- und Antworttexten werden Feldnamen in Camel-Case-Schreibweise verwendet, z. B. textQuery anstelle von text_query. REST-Anfragen werden unter denselben SKUs abgerechnet, folgen denselben Regeln für Pro-Optionen und werden auf dieselben Kontingente wie MCP-Toolaufrufe angerechnet.

Verwenden Sie für die Authentifizierung dasselbe Google Cloud-Projekt und dieselben Anmeldedaten wie für den MCP-Server. Eine Anleitung zur Einrichtung finden Sie unter LLMs für die Verwendung des MCP-Servers konfigurieren. Übergeben Sie einen API-Schlüssel im X-Goog-Api-Key-Header oder ein OAuth-Zugriffstoken mit dem https://www.googleapis.com/auth/maps-platform.mapstools-Bereich im Authorization-Header.

Im folgenden Beispiel wird die Methode searchText aufgerufen:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "coffee shops near Golden Gate Park"
}' \
"https://mapstools.googleapis.com/v1:searchText"

Ersetzen Sie dabei API_KEY durch Ihren eigenen API-Schlüssel.

Die Antwort enthält dieselben Felder summary, places und contentToken wie ein search_places-Toolergebnis. In der Anleitung für jedes Tool wird eine REST-Version des Beispiels gezeigt.

Feedback geben

Wenn Sie Feedback zu den Maps Experience Agent Tools geben möchten, verwenden Sie die folgenden Formulare: