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) i REST, która umożliwia grounding aplikacji AI za pomocą zaufanych danych geoprzestrzennych z Map Google. Narzędzia te umożliwiają LLM dostęp do danych o miejscach, pogodzie, jakości powietrza, stężeniu pyłków i trasach. Inne narzędzia rozpoznają nazwy lokalizacji i adresy URL Map Google jako identyfikatory miejsc. Możesz wypróbować narzędzia agentowe Maps Experience, włączając jego serwer MCP w dowolnym narzędziu, które obsługuje serwery MCP. Każde narzędzie możesz też wywołać jako metodę REST. Więcej informacji znajdziesz w artykule o wywoływaniu narzędzi za pomocą REST.

Narzędzia agentowe Maps Experience to jedna usługa z 2 kodami SKU: Essentials i Pro. Każde żądanie jest rozliczane w ramach Essentials, chyba że korzysta z opcji Pro. Opcje Pro dodają wyszukiwanie miejsc na trasie, rozszerzone informacje o miejscu, więcej miejsc na wyszukiwanie, więcej przystanków pośrednich na trasie, wyznaczanie trasy z uwzględnieniem informacji o ruchu w czasie rzeczywistym, prognozy stężenia pyłków i historyczne dane o jakości powietrza. Oba kody SKU używają tych samych narzędzi, serwera MCP, metod REST i danych logowania. Więcej informacji znajdziesz w artykule Essentials i Pro.

Narzędzia

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

• Wyszukiwanie miejsc: proś o informacje o miejscach i uzyskuj podsumowania wygenerowane przez AI. Odpowiedź zawiera też identyfikatory miejsc, współrzędne geograficzne i linki do Map Google dla każdego miejsca w podsumowaniu. Możesz używać identyfikatorów miejsc oraz współrzędnych szerokości i długości geograficznej z innymi interfejsami API Google Maps Platform, aby wyświetlać miejsca na mapie. Aby wyświetlać te miejsca za pomocą interfejsu Places UI Kit bez dodatkowych kosztów, użyj tokena wizualizacji danych agentowych (wersja testowa). W wersji Pro możesz poprosić o rozszerzone informacje o miejscu, takie jak statystyki z opinii, i uzyskać do 10 miejsc na żądanie.
• Wyszukiwanie na trasie: znajduj miejsca na trasie podróży określonej za pomocą retrieval_token z compute_routes, route_endpoints lub encoded_polyline i uzyskuj podsumowanie generowane przez AI, informacje o miejscu, odległość objazdu i czas podróży oraz token wizualizacji danych agenta (wersja testowa). Każde żądanie search_along_route jest rozliczane w ramach SKU Pro.
• Sprawdzanie pogody: poproś o informacje o warunkach środowiskowych w danej lokalizacji, w tym o pogodzie (aktualne warunki, historia godzinowa z 24 godzin oraz prognozy godzinowe i dzienne na okres do 10 dni) oraz o jakości powietrza (aktualna lub prognoza na okres do 4 dni). W wersji Pro możesz też poprosić o prognozy pylenia na maksymalnie 5 dni (ze szczegółowymi informacjami o gatunkach roślin) i historię jakości powietrza z ostatnich 30 dni z danymi godzinowymi.

• Obliczanie tras: poproś o trasę między miejscem początkowym a docelowym, opcjonalnie z przystankami pośrednimi, i uzyskaj odległość, czas trwania oraz retrievalToken dla DRIVE tras, które możesz przekazać do search_along_route. W 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 potrzeby identyfikatorów miejsc. Więcej informacji znajdziesz w artykule na temat interfejsu Resolution API.

Po włączeniu serwera MCP LLM 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ź poprawność wygenerowanej odpowiedzi.

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 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ł powiązanie ze źródłami informacji. Wybierz narzędzia agentowe Maps Experience dla innych modeli lub platform agentowych albo do bezpośredniego sterowania każdym wywołaniem narzędzia.

W tabeli poniżej porównujemy SKU Essentials, SKU Pro i powiązanie ze źródłami informacji przy użyciu Map Google:

Te opcje działają tak samo w przypadku obu kodów SKU: tryby podróży, godziny wyjazdu i przyjazdu, trasy alternatywne, linie łamane trasy, wyszukiwanie informacji o pogodzie, wyszukiwanie informacji o aktualnej i prognozowanej jakości powietrza (w tym stężenia zanieczyszczeń i lokalne skale AQI), systemy jednostek pogodowych i interfejs Resolution API. Nie zmieniają one SKU, w ramach którego rozliczane jest żądanie.

Co jest rozliczane w ramach kodu SKU Pro

W tabeli poniżej znajdziesz podsumowanie funkcji dostępnych w Essentials oraz funkcji, które wymagają kodu SKU Pro:

Opcje żądania, które umożliwiają korzystanie z poszczególnych funkcji, znajdziesz w sekcjach Wyszukiwanie miejsc, Wyszukiwanie na trasie, Obliczanie tras i Sprawdzanie pogody.

Kontrolowanie korzystania z wersji Pro

Opcje profesjonalne są domyślnie wyłączone na urządzeniach search_places, compute_routes i lookup_weather. Model LLM ustawia je lub wywołuje search_along_route, gdy wymaga tego prośba użytkownika, a opis narzędzia lub Twoje instrukcje na to zezwalają. Opisy narzędzi informują model, które opcje kosztują więcej i kiedy ich używać: page_size powyżej 5, rozszerzone informacje o miejscu, więcej niż 10 pośrednich punktów orientacyjnych, wyznaczanie trasy z uwzględnieniem natężenia ruchu i search_along_route. Jeśli wywołujesz narzędzia za pomocą REST, Twój kod ustawia każdą opcję. 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”. Możesz też powiedzieć: „Wywołaj search_along_route tylko wtedy, gdy użytkownik pyta o miejsca na trasie”. Możesz też powiedzieć: „Uwzględnij POLLEN lub AIR_QUALITY z poprzedniego date lub hour tylko wtedy, gdy użytkownik pyta o pyłki, alergie lub historyczną jakość powietrza”.
• Aby zachować agenta w SKU Essentials, poinstruuj model, aby nigdy nie wywoływał search_along_route ani nie używał opcji Pro. Opcje Pro to include_extended_details, page_size powyżej 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, więcej niż 10 pośrednich punktów trasy, POLLEN w capabilities oraz wcześniejsza date lub hour z AIR_QUALITY w capabilities. Jeśli Twój klient MCP może ograniczać narzędzia lub argumenty narzędzi, możesz też zablokować search_along_route i te wartości argumentów w konfiguracji narzędzia.
• Monitoruj kod SKU Maps Grounding Pro w raportach rozliczeniowych i ustaw alerty dotyczące budżetu.

Resolution API

Narzędzia agentowe Maps Experience udostępniają interfejs Resolution API. Przekształca tekst lokalizacji w formie swobodnej i adresy URL w 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 lokalizacji lub adresów i przypisywanie ich do konkretnych miejsc w Mapach Google. To narzędzie pomaga przekształcać nieuporządkowane zapytania 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 agentowych 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 widoczna jest pozycja dla każdego kodu SKU. Więcej informacji znajdziesz w artykule Raportowanie – omówienie.

Każde żądanie wyszukiwania miejsc, wyszukiwania na trasie, obliczania tras lub sprawdzania pogody wysyłane przez serwer MCP lub za pomocą REST jest rozliczane w ramach jednego SKU: Maps Grounding Essentials lub Maps Grounding Pro. Każde żądanie search_along_route i każde żądanie, które korzysta z opcji Pro, jest rozliczane w ramach kodu SKU Pro. Żądanie nigdy nie jest rozliczane w ramach obu kodów SKU, a liczba opcji Pro w żądaniu nie zmienia opłaty. Informacje o funkcjach i opcjach, które określają SKU każdego narzędzia, znajdziesz w artykule Co jest rozliczane w ramach SKU Pro.

Żądania Maps Grounding Essentials są rozliczane według stawki 7,00 USD za 1000 żądań po wykorzystaniu pierwszych 10 tys.żądań w każdym miesiącu. Żądania Maps Grounding Pro są rozliczane według stawki 14,00 USD za 1000 żądań po przekroczeniu pierwszych 5000 żądań w każdym miesiącu. Oba kody SKU mają rabaty ilościowe przy większym miesięcznym wykorzystaniu.

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 Text Search Essentials (IDs Only).

Jeśli wyświetlasz miejsca z odpowiedzi search_places lub search_along_route za pomocą Places UI Kit, możesz użyć tokena wizualizacji danych agentowych (wersja testowa), aby te żądania Places UI Kit nie były rozliczane.

Korzystanie z SKU Essentials jest uwzględnione w pakietach Essentials i Pro Subskrybuj i oszczędzaj. Korzystanie z SKU Pro jest uwzględnione w pakiecie Pro.

Limity

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

• Wyszukiwanie miejsc: 300 zapytań na minutę na projekt.
• Wyszukiwanie na trasie: 300 zapytań na minutę na projekt.
• Wyszukiwanie pogody: 300 zapytań na minutę na projekt.
• Obliczanie tras: 300 zapytań na minutę na projekt.
• Rozpoznawanie nazw: 600 zapytań na minutę na projekt.
• Rozwiązywanie adresów URL Map: 600 zapytań na minutę w każdym projekcie.

Limity są liczone dla każdego narzędzia i są współdzielone przez kody SKU 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 agentowe 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 zgodnych modeli LLM i atrybucji ź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 agentowych Maps Experience możesz używać tylko z dużym modelem językowym, 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 agentowych 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 warunkach dotyczących konkretnych usług.

Wymagania dotyczące podania źródła w przypadku Map Google

Każda odpowiedź narzędzi agentowych Maps Experience zawiera źródła. Gdy prezentujesz wyniki z narzędzi agentowych Maps Experience, musisz podać 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ędzi do wyszukiwania miejsc i wyszukiwania na trasie

Pole search_places narzędzia places i pole search_along_route narzędzia results[].place zawierają źródła, które obsługują summary. W przypadku każdego miejsca zwracane są te metadane:

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

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

• Przypisz każde źródło do Map Google zgodnie z wytycznymi dotyczącymi atrybucji tekstowej narzędzi agentowych Maps Experience.
• Połącz ze źródłem, używając googleMapsLinks.placeUrl z odpowiedzi.

Te wymagania dotyczą też podsumowań, które zawierają rozszerzone informacje o miejscu z wersji 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 lub results. 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ł dany trend.

Interfejsy głosowe

Jeśli aplikacja prezentuje wyniki narzędzi agentowych 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 agentowych Maps Experience, musisz mieć projekt w chmurze Google Cloud z włączoną usługą interfejsu API narzędzi agentowych 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 strumieniowego protokołu HTTP.

Włącz narzędzia agentowe 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ć z narzędziami agenta Maps Experience.
2. Włącz płatności za projekt w konsoli Google Cloud.
3. Włącz narzędzia agentowe Maps Experience w bibliotece interfejsów API w konsoli Google Cloud.

Uwierzytelnianie za pomocą klucza interfejsu API

Możesz użyć istniejącego klucza interfejsu API z narzędziami agentowymi Maps Experience lub utworzyć nowy. W obu przypadkach włącz usługę interfejsu API narzędzi agenta Maps Experience 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ć go 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 w przypadku 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 hosta MCP lub aplikacji serwera MCP przekaż identyfikator klienta OAuth i klucz tajny. 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 agentowych Maps Experience

Po włączeniu usługi narzędzi agentowych 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 agentowych 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, uruchom polecenie /mcp list:

   > /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
   

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 spowoduje wywołanie narzędzia search_places w Twoim imieniu.

Konfigurowanie narzędzi agentowych 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.

# ./adk_agent_samples/mcp_agent/agent.py
import os
from google.adk.agents.llm_agent import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# Retrieve the API key from an environment variable or directly insert it.
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")
if not GOOGLE_MAPS_API_KEY:
    GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY_HERE"

if GOOGLE_MAPS_API_KEY == "YOUR_GOOGLE_MAPS_API_KEY_HERE":
    print("WARNING: GOOGLE_MAPS_API_KEY is not set.")

root_agent = Agent(
    model='gemini-flash-latest',
    name='travel_planner_agent',
    description='A helpful assistant for planning travel routes.',
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url="https://mapstools.googleapis.com/mcp",
                headers={
                    "X-Goog-Api-Key": GOOGLE_MAPS_API_KEY,
                    "Content-Type": "application/json",
                    "Accept": "application/json, text/event-stream"
                }
            )
        )
    ]
)
    

from . import agent
    

package agents;

import com.google.adk.agents.LlmAgent;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.SessionKey;
import com.google.adk.tools.mcp.McpToolset;
import com.google.adk.tools.mcp.StreamableHttpServerParameters;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import java.util.HashMap;
import java.util.Map;

public class MapsAgentCreator {
    public static void main(String[] args) {
        String googleMapsApiKey = System.getenv("GOOGLE_MAPS_API_KEY");
        if (googleMapsApiKey == null || googleMapsApiKey.trim().isEmpty()) {
            googleMapsApiKey = "YOUR_GOOGLE_MAPS_API_KEY_HERE";
            if ("YOUR_GOOGLE_MAPS_API_KEY_HERE".equals(googleMapsApiKey)) {
                System.out.println("WARNING: GOOGLE_MAPS_API_KEY is not set.");
            }
        }

        Map<String, String> headers = new HashMap<>();
        headers.put("X-Goog-Api-Key", googleMapsApiKey);
        headers.put("Content-Type", "application/json");
        headers.put("Accept", "application/json, text/event-stream");

        StreamableHttpServerParameters serverParams =
                StreamableHttpServerParameters.builder("https://mapstools.googleapis.com/mcp")
                        .headers(headers)
                        .build();

        try (McpToolset toolset = new McpToolset(serverParams)) {
            LlmAgent agent = LlmAgent.builder()
                    .model("gemini-flash-latest")
                    .name("travel_planner_agent")
                    .description("A helpful assistant for planning travel routes.")
                    .tools(toolset)
                    .build();

            System.out.println("Agent created: " + agent.name());

            InMemoryRunner runner = new InMemoryRunner(agent);
            String userId = "maps-user-" + System.currentTimeMillis();
            String sessionId = "maps-session-" + System.currentTimeMillis();
            String promptText =
                    "Please give me directions to the nearest pharmacy to Madison Square Garden.";

            SessionKey sessionKey = runner.sessionService()
                    .createSession(runner.appName(), userId, null, sessionId)
                    .blockingGet()
                    .sessionKey();
            System.out.println("Session created: " + sessionId + " for user: " + userId);

            Content promptContent = Content.fromParts(Part.fromText(promptText));
            System.out.println("\nSending prompt: \"" + promptText + "\" to agent...\n");

            runner.runAsync(sessionKey, promptContent)
                    .blockingForEach(event -> {
                        System.out.println("Event received: " + event.toJson());
                    });
        } catch (Exception e) {
            System.err.println("An error occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
    

import 'dotenv/config';
import {LlmAgent, MCPToolset} from "@google/adk";

const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY;
if (!googleMapsApiKey) {
    console.warn("WARNING: GOOGLE_MAPS_API_KEY is not set.");
    throw new Error(
        'GOOGLE_MAPS_API_KEY is not provided, please run "export GOOGLE_MAPS_API_KEY=YOUR_ACTUAL_KEY" to add that.'
    );
}

export const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "travel_planner_agent",
    description: "A helpful assistant for planning travel.",
    tools: [
        new MCPToolset({
            type: "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"
                    }
                }
            }
        })
    ],
});
    

Wywoływanie narzędzi za pomocą REST

Każde narzędzie w narzędziach agentowych Maps Experience jest też dostępne jako metoda REST. Wywołuj metody REST bezpośrednio, gdy chcesz połączyć narzędzia z własnym agentem lub aplikacją – na przykład aby zadeklarować własne funkcje dla modelu, wybrać opcje, które model może ustawić, lub ustawić wartości domyślne w kodzie.

W tabeli poniżej znajdziesz metodę REST dla każdego narzędzia:

Żądanie REST przyjmuje te same opcje co odpowiadające mu narzędzie i zwraca tę samą odpowiedź. W treściach żądań i odpowiedzi REST nazwy pól są zapisywane w formacie lowerCamelCase, na przykład textQuery zamiast text_query. Żądania REST są rozliczane w ramach tych samych kodów SKU, podlegają tym samym zasadom dotyczącym opcji Pro i są wliczane do tych samych limitów co wywołania narzędzi MCP.

Do uwierzytelniania użyj tego samego projektu w chmurze Google Cloud i tych samych danych logowania co w przypadku serwera MCP. Instrukcje konfiguracji znajdziesz w artykule na temat konfigurowania LLM do korzystania z serwera MCP. Przekaż klucz interfejsu API w nagłówku X-Goog-Api-Key lub token dostępu OAuth z zakresem https://www.googleapis.com/auth/maps-platform.mapstools w nagłówku Authorization.

W tym przykładzie wywoływana jest metoda searchText:

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"

Zastąp API_KEY swoim kluczem interfejsu API.

Odpowiedź zawiera te same pola summary, places i contentToken co wynik narzędzia search_places. Przewodnik po każdym narzędziu zawiera wersję REST przykładu.

Przesyłanie opinii

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

• Zgłoś błąd
• Przesyłanie prośby o dodanie funkcji
• Przesyłanie opinii