Narzędzia agenta Maps Experience

Narzędzia agenta Maps Experience (dawniej Maps Grounding Lite) to usługa Google Maps Platform z obsługą protokołu Model Context Protocol (MCP), która umożliwia grounding aplikacji AI za pomocą zaufanych danych geoprzestrzennych z Map Google. Serwer MCP udostępnia narzędzia, które umożliwiają LLM dostęp do danych o miejscach, pogodzie i trasach. Inne narzędzia rozpoznają nazwy miejsc i adresy URL Map Google jako identyfikatory miejsc. Możesz wypróbować narzędzia agenta Maps Experience, włączając je w dowolnym narzędziu obsługującym serwery MCP.

Narzędzia agenta Maps Experience to jedna usługa z 2 kodami SKU: Essentials i Pro. Każde żądanie jest rozliczane w ramach wersji Essentials, chyba że korzysta z opcji Pro. Opcje Pro dodają rozszerzone informacje o miejscu, więcej miejsc na wyszukiwanie, więcej przystanków pośrednich na trasie i wyznaczanie trasy z uwzględnieniem natężenia ruchu na żywo. W okresie ograniczonej GA opcje Pro są dostępne tylko w przypadku projektów znajdujących się na liście dozwolonych Pro. Oba SKU używają tego samego serwera MCP, narzędzi i danych logowania. Szczegółowe informacje znajdziesz w artykule Essentials i Pro.

Narzędzia

Narzędzia agenta Maps Experience umożliwiają LLM dostęp do tych funkcji Map Google:

  • Wyszukiwanie miejsc: proś o informacje o miejscach i otrzymuj podsumowania wygenerowane przez AI. Odpowiedź zawiera też identyfikatory miejsc, współrzędne i linki do Map Google dla każdego miejsca w podsumowaniu. Możesz używać identyfikatorów miejsc i współrzędnych z innymi interfejsami API Google Maps Platform, aby wyświetlać miejsca na mapie. W wersji Pro możesz prosić o rozszerzone informacje o miejscu, takie jak statystyki z opinii, i uzyskać do 10 miejsc na żądanie.
  • Sprawdzanie pogody: poproś o informacje o pogodzie i uzyskaj aktualne warunki, prognozy godzinowe i prognozy dzienne.

  • Obliczanie tras: poproś o trasę między miejscem początkowym a docelowym, opcjonalnie z przystankami pośrednimi, i uzyskaj odległość oraz czas trwania trasy. W przypadku wersji Pro trasy mogą uwzględniać aktualne warunki na drodze i zawierać więcej przystanków pośrednich.

  • Rozpoznawanie nazw i Rozpoznawanie adresów URL w Mapach: rozpoznawanie nazw lokalizacji, adresów i adresów URL w Mapach Google na podstawie identyfikatorów miejsc. Więcej informacji znajdziesz w artykule na temat interfejsu Resolution API.

Po włączeniu serwera MCP LLM-y mogą wywoływać jego narzędzia, aby uzyskać informacje o tych typach danych. LLM może wykorzystać te informacje jako kontekst. Jednak ostateczna odpowiedź może nie zawierać dokładnych informacji zwróconych przez serwer MCP. Sprawdź, czy wygenerowana odpowiedź jest poprawna.

Essentials i Pro

Essentials i Pro to 2 kody SKU tej samej usługi, a nie osobne usługi lub abonamenty. Żądanie jest rozliczane w ramach wersji Pro, gdy korzysta z opcji Pro. Wszystkie pozostałe żądania są rozliczane w ramach Essentials. Opcje Pro to zwykłe pola w żądaniu narzędzia, więc LLM może ich używać w Twoim imieniu. Agent może też używać obu SKU w tej samej rozmowie. Agent może na przykład użyć Essentials, aby znaleźć kawiarnie w pobliżu punktu orientacyjnego. Następnie może użyć modelu Pro, aby odpowiedzieć na kolejne pytanie dotyczące ich popisowych drinków i miejsc siedzących. Nie ma osobnego serwera MCP, punktu końcowego ani danych logowania dla wersji Pro.

Porównanie wersji Essentials, Pro i powiązanie ze źródłami informacji przy użyciu Map Google

powiązanie ze źródłami informacji przy użyciu Map Google to osobna usługa. Jest ona wbudowana w modele Gemini w Gemini API, Google AI Studio i Gemini Enterprise Agent Platform. Model decyduje, kiedy wysłać zapytanie do Map Google, i zwraca odpowiedzi oparte na faktach wraz z cytatami. Wybierz opcję powiązanie ze źródłami informacji przy użyciu Map Google, gdy tworzysz rozwiązanie na bazie Gemini i chcesz, aby model obsługiwał oparcie na faktach. Wybierz narzędzia agenta Maps Experience dla innych modeli lub platform agentów albo do bezpośredniego sterowania każdym wywołaniem narzędzia.

Narzędzia agenta Maps Experience Grounding z użyciem Map Google
Essentials SKU
(dawniej Maps Grounding Lite)		 Kod SKU Pro
Jak naliczane są opłaty za żądania Każda prośba o użycie narzędzia, która nie korzysta z opcji Pro Każde żądanie narzędzia, które korzysta z opcji Pro: include_extended_details, page_size powyżej 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL lub więcej niż 10 punktów pośrednich Każde zapytanie w Mapach Google lub prompt oparty na źródłach, w zależności od platformy i modelu
Modele i platformy Dowolny model lub platforma agentów obsługująca MCP. 1 serwer MCP, 1 zestaw narzędzi i te same dane logowania dla obu kodów SKU Modele Gemini w Gemini API, Google AI Studio i Gemini Enterprise Agent Platform
Dane zwracane przez narzędzia Najważniejsze informacje: informacje o miejscu dotyczące maksymalnie 5 miejsc na wyszukiwanie, odległość i czas trwania trasy bez informacji o ruchu w czasie rzeczywistym oraz aktualna pogoda i prognozy. Wszystkie funkcje wersji Essentials oraz rozszerzone informacje o miejscu (np. statystyki z opinii), do 10 miejsc na wyszukiwanie, trasy z informacjami o ruchu w czasie rzeczywistym i do 25 punktów pośrednich szczegółowe informacje o miejscu i statystyki z opinii oraz informacje o trasie z danymi o natężeniu ruchu w czasie rzeczywistym;
Przykładowe żądania pytania dotyczące faktów i logistyki: znajdowanie sklepów lub firm, godziny otwarcia, adresy oraz szacunkowe odległości lub czasy podróży; pytania subiektywne lub ogólne: atmosfera, dania popisowe, wskazówki dla odwiedzających, porównania 6–10 miejsc i czas podróży przy aktualnym natężeniu ruchu; Wyszukiwanie konwersacyjne, planowanie podróży i odkrywanie lokalnych miejsc w Gemini
Wizualizacje Places UI Kit Dostępne bez dodatkowych opłat z tokenem wizualizacji danych agentowych (wersja testowa) Rozliczane osobno
Bezpłatne wykorzystanie miesięcznie 10 000 żądań 5000 żądań Zależy to od platformy i modelu. Na przykład w Gemini API modele Gemini 3 i nowsze obejmują 5000 bezpłatnych zapytań miesięcznie. Po przekroczeniu tego limitu koszt wynosi 14 USD za 1000 zapytań.
Cena płatności według wykorzystania 7,00 USD za 1000 żądań, z rabatami ilościowymi 14,00 USD za 1000 żądań. Aby uzyskać informacje o cenach dla dużych firm, skontaktuj się z zespołem sprzedaży.
Abonamenty umożliwiające oszczędności Dostępne w pakietach Essentials i Pro Nie uwzględniono Niedostępne
Rozpocznij Jedna konfiguracja dla obu kodów SKU: zobacz Konfigurowanie LLM do korzystania z serwera MCP. W okresie ograniczonej GA opcje Pro wymagają też projektu na liście dozwolonych Pro. Gemini API lub Agent Platform

Te opcje działają tak samo w przypadku obu kodów SKU: środki transportu, godziny odjazdu i przyjazdu, trasy alternatywne, linie łamane trasy, wyszukiwanie informacji o pogodzie i interfejs Resolution API. Nie zmieniają one SKU, w ramach którego rozliczane jest żądanie.

Co jest rozliczane w ramach kodu SKU Pro

Narzędzie Możliwości Essentials Pro
Wyszukiwanie miejsc Liczba miejsc na żądanie maks. 5 6–10 (page_size od 6 do 10)
rozszerzone informacje o miejscu w podsumowaniach wyszukiwania (informacje z opinii, najważniejsze pozycje w menu, atmosfera, natężenie ruchu, wskazówki dla odwiedzających oraz odległość lub czas podróży w przypadku zapytań o bliskość); Niedostępne Dostępne w include_extended_details
Obliczanie tras Ustawienia routingu Nie uwzględnia aktualnego natężenia ruchu. Uwzględnia bieżące informacje o ruchu lub dane o transporcie publicznym w czasie rzeczywistym w przypadku tras transportu publicznego, z ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL
Punkty pośrednie na trasę Maksymalnie 10 11–25 (więcej niż 10 intermediate_waypoints)
Lookup weather i Resolution API Brak opcji Pro. Wszystkie żądania są rozliczane w ramach SKU Essentials.

Opcje żądania, które umożliwiają korzystanie z poszczególnych funkcji, znajdziesz w artykułach Wyszukiwanie miejsc i Obliczanie tras.

Opcje Pro podczas ograniczonego GA

W okresie ograniczonej ogólnej dostępności opcje Pro są dostępne tylko w projektach Google Cloud znajdujących się na liście dozwolonych Pro. Aby poprosić o dostęp, skontaktuj się z zespołem sprzedaży. Gdy projekt znajdzie się na liście dozwolonych, każdy klucz interfejsu API i klient OAuth w tym projekcie będzie mógł korzystać z opcji Pro.

Jeśli Twój projekt nie znajduje się jeszcze na liście dozwolonych, żądania, które używają opcji Pro, są obsługiwane w następujący sposób:

  • Wyszukiwanie miejsc: parametr include_extended_details jest ignorowany, a odpowiedź zawiera maksymalnie 5 miejsc, nawet jeśli ustawisz parametr page_size na wyższą wartość. Żądanie jest rozliczane w ramach kodu SKU Essentials.
  • Obliczanie tras: ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL jest traktowane jako ROUTING_PREFERENCE_TRAFFIC_UNAWARE, a żądanie jest rozliczane w ramach SKU Essentials. Żądanie z więcej niż 10 punktami pośrednimi zwraca błąd INVALID_ARGUMENT.

Aby sprawdzić, czy Twój projekt znajduje się na liście dozwolonych, wyślij żądanie search_places z parametrem page_size ustawionym na 10. Użyj ogólnego zapytania, np. restaurants in Chicago. Projekt na liście dozwolonych może zwrócić więcej niż 5 miejsc, które są rozliczane w ramach kodu SKU Pro. Inne projekty zwracają maksymalnie 5 miejsc.

Kontrolowanie korzystania z wersji Pro

Opcje Pro są domyślnie wyłączone. Model LLM ustawia je, gdy wymaga tego prośba użytkownika, a schemat narzędzia lub Twoje instrukcje na to zezwalają. Schemat narzędzia opisuje wartości page_size do 5 i maksymalnie 10 punktów pośrednich. Dlatego modele korzystają z wyższych limitów Pro tylko wtedy, gdy wymagają tego Twoje instrukcje. Aby zarządzać kosztami:

  • Powiedz modelowi, kiedy opcje Pro są odpowiednie. Na przykład: „Ustaw include_extended_details tylko wtedy, gdy użytkownik pyta o opinie, menu lub atmosferę”. Możesz też powiedzieć: „Używaj ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL tylko wtedy, gdy użytkownik pyta o aktualny czas podróży”.
  • Aby agent korzystał z SKU Essentials, poinstruuj model, aby nigdy nie używał opcji Pro. Opcje Pro to include_extended_details, page_size powyżej 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL i ponad 10 punktów pośrednich. Jeśli klient MCP może ograniczać argumenty narzędzi, możesz też zablokować te wartości w konfiguracji narzędzia.
  • Monitoruj wykorzystanie w raportach rozliczeniowych i ustaw alerty dotyczące budżetu.

Resolution API

Narzędzia agenta Maps Experience udostępniają interfejs Resolution API. Rozpoznaje tekst lokalizacji w formie swobodnej i adresy URL jako uporządkowane identyfikatory miejsc w Mapach Google. Interfejs Resolution API jest dostępny jako metody REST i narzędzia na serwerze MCP:

  • Rozpoznawanie nazw (REST, MCP): rozpoznawanie zbioru nazw lub adresów lokalizacji i przypisywanie ich do konkretnych miejsc w Mapach Google. Jest to przydatne do przekształcania nieuporządkowanych zapytań użytkowników w stabilne identyfikatory miejsc.
  • Resolve Maps URLs (REST, MCP): rozpoznaje grupę adresów URL Map Google jako konkretne elementy miejsca. Obsługiwane formaty obejmują standardowe adresy URL miejsc i skrócone adresy URL.

Zwróconych identyfikatorów miejsc możesz używać z innymi interfejsami API Google Maps Platform. Każda odpowiedź zawiera też link, który zapisuje znalezione miejsca jako listę w Mapach Google.

Więcej informacji znajdziesz w artykule Maps Tools Resolution API.

Wypróbuj przykładową aplikację (otwiera się w nowej karcie)

Rozliczenia i limity

Jak naliczane są opłaty

W modelu płatności według wykorzystania Google Maps Platform wykorzystanie narzędzi agenta Maps Experience jest obliczane dla każdego żądania. Każde żądanie odpowiada jednemu zdarzeniu rozliczeniowemu. Wykorzystanie jest śledzone dla każdego kodu SKU usługi. Na rachunku oprócz łącznych opłat widoczny jest element zamówienia dla każdego kodu SKU. Więcej informacji znajdziesz w omówieniu raportowania.

Każde żądanie wyszukiwania miejsc, obliczania tras lub sprawdzania pogody jest rozliczane w ramach dokładnie jednego kodu SKU, Essentials lub Pro. Żądanie, które korzysta z dowolnej opcji Pro, jest rozliczane w ramach kodu SKU Pro. Nigdy nie jest naliczana opłata za oba SKU, a liczba opcji Pro nie zmienia opłaty. Kod SKU zależy od tych opcji:

Narzędzie Essentials Pro
search_places Każda prośba bez opcji Pro: page_size o wartości 5 lub mniejszej oraz include_extended_details nieustawiona lub false include_extended_details: ustaw wartość true lub page_size od 6 do 10
compute_routes Dowolne żądanie bez opcji Pro: routing_preference nieustawione lub ROUTING_PREFERENCE_TRAFFIC_UNAWARE i maksymalnie 10 punktów pośrednich, z dowolnym trybem podróży routing_preference ustawione na ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL lub od 11 do 25 punktów pośrednich
lookup_weather Każda prośba –

Ceny wersji Essentials znajdziesz w artykule Szczegóły kodów SKU Essentials. Żądania Pro są rozliczane według stawki 14,00 USD za 1000 żądań po przekroczeniu pierwszych 5000 żądań w każdym miesiącu. Aby uzyskać informacje o cenach dla dużych firm, skontaktuj się z zespołem sprzedaży.

W okresie ograniczonej GA opcje Pro działają tylko w projektach z listy dozwolonych Pro. Więcej informacji znajdziesz w sekcji Opcje Pro w okresie ograniczonego dostępu.

Szczegółowe informacje o cenach znajdziesz w głównej tabeli cen i tabeli cen w Indiach.

Żądania do interfejsu Resolution API (ResolveNames i ResolveMapsUrls) są rozliczane bezpłatnie w ramach kodu SKU Places API – Wyszukaj tekst – Essentials (tylko identyfikatory).

Korzystanie z SKU Essentials jest też uwzględnione w pakietach Essentials i Pro Subskrybuj i oszczędzaj. Kod SKU Pro nie jest uwzględniony w pakietach „Subskrybuj i oszczędzaj”.

Limity

W przypadku narzędzi i interfejsów API udostępnianych przez narzędzia agenta Maps Experience obowiązują te limity:

  • Wyszukiwanie miejsc: 300 zapytań na minutę na projekt.
  • Wyszukiwanie informacji o pogodzie: 300 zapytań na minutę na projekt.
  • Obliczanie tras: 300 zapytań na minutę na projekt.
  • Rozpoznawanie nazw: 600 zapytań na minutę na projekt.
  • Resolve Maps URLs: 600 zapytań na minutę na projekt.

Limity są liczone na narzędzie i są współdzielone przez pakiety Essentials i Pro. Prośba o dostęp do wersji Pro wykorzystuje ten sam limit co prośba o dostęp do wersji Essentials w przypadku tego samego narzędzia.

Każde żądanie do interfejsu Resolution API liczy się jako jedno zapytanie, niezależnie od tego, ile elementów zawiera.

Zasady i warunki korzystania z usługi

Narzędzia agenta Maps Experience podlegają Warunkom korzystania z usługi Google Maps Platform, w tym szczegółowym warunkom korzystania z usługi. W tej sekcji opisano dodatkowe wymagania dotyczące korzystania z narzędzi agenta Maps Experience, w tym zgodne modele LLM i atrybucję źródła. Wymagania dotyczą wszystkich wyników, niezależnie od tego, w ramach którego kodu SKU jest rozliczane żądanie.

Wymagania dotyczące zgodnych modeli LLM

Narzędzi agenta Maps Experience możesz używać tylko z modelem LLM, który jest zgodny z Warunkami korzystania z usługi Google Maps Platform.

Na przykład musisz zadbać o to, aby treści Map Google nie były przechowywane w pamięci podręcznej ani w inny sposób, a także aby nie były używane do ulepszania wybranego przez Ciebie modelu LLM. Zanim zaczniesz korzystać z narzędzi agenta Maps Experience, musisz zapoznać się z Warunkami korzystania z usługi dotyczącymi każdego modelu, którego chcesz używać z tymi narzędziami. Nie wolno używać narzędzi agenta Maps Experience z żadnymi modelami, które wykorzystują dane wejściowe do trenowania lub ulepszania modelu. Ponosisz odpowiedzialność za zapewnienie, że korzystanie z modelu jest w pełni zgodne z ograniczeniami dotyczącymi treści Map Google określonymi w Warunkach korzystania z usługi Google Maps Platform, w tym w szczegółowych warunkach korzystania z usługi.

Wymagania dotyczące podawania źródeł w przypadku Map Google

Każda odpowiedź narzędzia z narzędzi agenta Maps Experience zawiera źródła. Gdy prezentujesz wyniki z narzędzi agenta Maps Experience, musisz uwzględnić powiązane źródła Map Google i spełnić te wymagania:

  • Źródła Map Google muszą znajdować się bezpośrednio po wygenerowanych treściach, które te źródła obsługują. Te wygenerowane treści są też nazywane uzasadnionymi danymi wyjściowymi.
  • Źródła Map Google muszą być widoczne w ramach jednej interakcji użytkownika.

Źródła narzędzia do wyszukiwania miejsc

Pole search_places narzędzia places zawiera źródła, które obsługują summary. W przypadku places zwracane są te metadane:

  • place (nazwa zasobu)
  • id
  • location
  • googleMapsLinks

W przypadku każdego miejsca musisz wygenerować podgląd linku, który spełnia te wymagania:

Te wymagania dotyczą też podsumowań, które zawierają rozszerzone informacje o miejscu z funkcji Pro, np. statystyki z opinii. Właściwość summary odwołuje się do każdego miejsca za pomocą indeksu zaczynającego się od zera, np. [0], który jest mapowany na wpis w places. Każde miejsce zawiera też element googleMapsLinks.reviewsUrl, który prowadzi do opinii o miejscu w Mapach Google. Użytkownicy mogą go kliknąć, aby zobaczyć opinie, na podstawie których powstała dana obserwacja.

Interfejsy głosowe

Jeśli aplikacja prezentuje wyniki narzędzi agenta Maps Experience za pomocą głosu, musisz też spełniać wymagania dotyczące interfejsów głosowych. Podsumowanie:

  • Źródła: wyświetlanie źródeł Map Google w interfejsie towarzyszącym, który pokazuje dosłowny zapis historyczny rozmowy głosowej.
  • Aktywne ujawnianie informacji: w momencie interakcji poinformuj użytkowników, że treści generowane przez AI mogą zawierać informacje z Map Google. Poinformuj też, że szczegółowe źródła są dostępne w interfejsie towarzyszącym. Możesz to zrobić na ekranie lub głosowo.
  • Stałe powiadomienie: zachowaj stałe wyjaśnienie, na przykład w menu ustawień głosu, że treści generowane przez AI mogą zawierać treści z Map Google.
  • Zapytania użytkowników: dokładnie odpowiadaj na pytania użytkowników dotyczące źródła treści i odsyłaj ich do interfejsu towarzyszącego, aby uzyskać szczegółowe informacje.

Konfigurowanie LLM pod kątem korzystania z serwera MCP

Aby korzystać z narzędzi agenta Maps Experience, musisz mieć projekt w chmurze Google Cloud z włączoną usługą interfejsu API narzędzi agenta Maps Experience. Potrzebujesz też klucza interfejsu API lub identyfikatora klienta OAuth. Następnie możesz skonfigurować LLM, aby miały dostęp do serwera MCP. Serwer MCP używa transportu HTTP z możliwością strumieniowego przesyłania danych.

Włącz narzędzia agenta Maps Experience w projekcie Google Cloud.

Aby włączyć interfejs API w projekcie:

  1. W konsoli Google Cloud wybierz projekt, którego chcesz używać do narzędzi agenta Maps Experience.
  2. Włącz rozliczenia za projekt w konsoli Google Cloud.
  3. Włącz narzędzia agenta Maps Experience w bibliotece interfejsów API konsoli Google Cloud.

Uwierzytelnianie za pomocą klucza interfejsu API

Możesz użyć istniejącego klucza interfejsu API z narzędziami agenta Maps Experience lub utworzyć nowy. W obu przypadkach włącz usługę interfejsu API Maps Experience agent tools zarówno w projekcie Google Cloud, jak i w kluczu.

Aby uwierzytelnić się za pomocą klucza interfejsu API:

  1. Utwórz lub skonfiguruj klucz interfejsu API, wykonując czynności opisane w artykule Pierwsze kroki z Google Maps Platform.
  2. Przekaż klucz do serwera MCP za pomocą nagłówka X-Goog-Api-Key. Musisz określić ten nagłówek jako niestandardowy nagłówek HTTP w konfiguracji narzędzia MCP LLM.

Uwierzytelnianie za pomocą OAuth

Możesz uwierzytelniać się za pomocą protokołu OAuth, tworząc dane uwierzytelniające OAuth i przekazując je do hosta MCP lub aplikacji serwera MCP.

Aby uwierzytelnić za pomocą protokołu OAuth:

  1. W konsoli Google Cloud wybierz projekt, którego chcesz używać z narzędziami agenta Maps Experience.
  2. W menu Interfejsy API i usługi wybierz Dane logowania.
  3. W górnym menu wybierz Utwórz dane logowania > Identyfikator klienta OAuth.
  4. Jeśli projekt nie ma skonfigurowanego ekranu zgody, kliknij Skonfiguruj ekran zgody i postępuj zgodnie z instrukcjami wyświetlanymi na ekranie.
  5. W sekcji Dane kliknij Utwórz klienta OAuth.
  6. Na ekranie Utwórz identyfikator klienta OAuth wybierz typ aplikacji i wpisz nazwę identyfikatora klienta.
  7. Podaj dodatkowe informacje, które są istotne dla Twojego typu aplikacji. Jeśli na przykład tworzysz aplikację internetową, dodaj autoryzowane identyfikatory URI dla żądań przeglądarki i serwera.
  8. Po utworzeniu klienta zapisz identyfikator klienta i obiekt tajny.
  9. Podczas konfigurowania aplikacji hosta MCP lub serwera MCP przekaż identyfikator klienta OAuth i tajny klucz. Musisz też poprosić o ten zakres: https://www.googleapis.com/auth/maps-platform.mapstools.

Więcej informacji znajdziesz w artykule o używaniu OAuth 2.0 do korzystania z interfejsów API Google.

Konfigurowanie LLM pod kątem dostępu do serwera MCP narzędzi agenta Maps Experience

Po włączeniu usługi narzędzi agenta Maps Experience i utworzeniu danych logowania możesz skonfigurować LLM, aby uzyskać dostęp do serwera MCP. Postępuj zgodnie z dokumentacją konfiguracji MCP LLM i użyj adresu URL serwera MCP: https://mapstools.googleapis.com/mcp

Więcej informacji znajdziesz w artykule o konfigurowaniu MCP w aplikacji AI.

Konfigurowanie narzędzi agenta Maps Experience za pomocą interfejsu wiersza poleceń Gemini

W tej sekcji znajdziesz przykład konfigurowania serwera MCP narzędzi agenta Maps Experience za pomocą interfejsu wiersza poleceń Gemini. Więcej informacji znajdziesz w artykule na temat serwerów MCP z interfejsem wiersza poleceń Gemini.

  1. Po zainstalowaniu interfejsu wiersza poleceń Gemini uruchom gemini mcp add, aby skonfigurować serwer MCP:

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

    Jeśli konfiguracja się powiodła, powinno pojawić się potwierdzenie, że serwer został dodany do ustawień użytkownika.

  2. Aby sprawdzić, czy serwer działa prawidłowo, uruchom polecenie /mcp list:

    > /mcp list

Configured MCP servers:

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

  3. Zacznij zadawać pytania dotyczące Map za pomocą interfejsu wiersza poleceń. Spróbuj na przykład powiedzieć „Poleć mi restauracje w Mountain View”, co powinno wywołać narzędzie search_places w Twoim imieniu.

Konfigurowanie narzędzi agenta Maps Experience za pomocą pakietu Agent Development Kit (ADK)

W tej sekcji pokazujemy, jak skonfigurować serwer MCP za pomocą pakietu Agent Development Kit (ADK) w języku Python, Java lub TypeScript.

Python

Pełną implementację tego przykładu znajdziesz na GitHubie w repozytorium adk-samples.

Krok 1. Zdefiniuj agenta za pomocą narzędzi agenta McpToolset for Maps Experience

Zmodyfikuj plik agent.py. Zastąp YOUR_GOOGLE_MAPS_API_KEY swoim kluczem interfejsu API.

# ./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"
                }
            )
        )
    ]
)
Krok 2. Sprawdź, czy istnieje __init__.py

Upewnij się, że masz plik __init__.py w tym samym katalogu co plik agent.py:

from . import agent
Krok 3. Uruchom adk web i wejdź w interakcję
  1. Ustaw zmienną środowiskową:
    Ustaw klucz interfejsu API Map Google jako zmienną środowiskową w terminalu: 
    export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
  2. Uruchom adk web:
    Uruchom to polecenie, aby uruchomić interfejs internetowy ADK: 
    adk web
  3. Interakcja w interfejsie:
    • Wybierz travel_planner_agent.
    • Wypróbuj prompty takie jak:
      • „Jutro będę w San Francisco. Jaka jest pogoda?”
      • „Znajdź kawiarnie w pobliżu parku Golden Gate”.
      • „Pokaż mi trasę dojazdu z Googleplexu na lotnisko Chopina”.

Java

Zdefiniuj agenta, który inicjuje McpToolset w języku Java. Jeśli nie używasz zmiennej środowiskowej, zastąp YOUR_GOOGLE_MAPS_API_KEY_HERE rzeczywistym kluczem interfejsu API.

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

Zdefiniuj agenta, który inicjuje MCPToolset w 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"
            }
        })
    ],
});

Przesyłanie opinii

Aby przesłać opinię o narzędziach agenta w Maps Experience, użyj tych formularzy: