Strumenti dell'agente Maps Experience

Gli strumenti dell'agente Maps Experience (in precedenza Maps Grounding Lite) sono un servizio di Google Maps Platform con supporto del Model Context Protocol (MCP) per basare le tue applicazioni di AI su dati geospaziali attendibili di Google Maps. Il server MCP fornisce strumenti che consentono agli LLM di accedere ai dati su luoghi, meteo e percorsi. Altri strumenti risolvono i nomi delle località e gli URL di Google Maps in ID luogo. Puoi provare gli strumenti dell'agente Experimente Maps attivandoli in qualsiasi strumento che supporti i server MCP.

Gli strumenti dell'agente Maps Experience sono un prodotto con due SKU: Essentials e Pro. Ogni richiesta viene fatturata in base a Essentials, a meno che non utilizzi un'opzione Pro. Le opzioni Pro aggiungono Place Details estesi, più Places per ricerca, più fermate intermedie per percorso e calcolo itinerario con traffico in tempo reale. Durante la fase di disponibilità generale limitata, le opzioni Pro sono disponibili solo per i progetti inclusi nella lista consentita Pro. Entrambi gli SKU utilizzano lo stesso server MCP, gli stessi strumenti e le stesse credenziali. Per maggiori dettagli, vedi Essentials e Pro.

Strumenti

Gli strumenti dell'agente Experimente Maps consentono agli LLM di accedere alle seguenti funzionalità di Google Maps:

  • Cerca luoghi: richiedi informazioni sui luoghi e ricevi riepiloghi creati con l'AI. La risposta include anche gli ID luogo, le coordinate e i link a Google Maps per ogni luogo nel riepilogo. Puoi utilizzare gli ID luogo e le coordinate con altre API di Google Maps Platform per mostrare i luoghi su una mappa. Con Pro, puoi richiedere dettagli dei luoghi estesi, ad esempio approfondimenti dalle recensioni, e fino a 10 luoghi per richiesta.
  • Cerca meteo: richiedi informazioni sul meteo e restituisci le condizioni attuali, le previsioni orarie e le previsioni giornaliere.

  • Calcola percorsi: richiedi un percorso tra un'origine e una destinazione, facoltativamente con tappe intermedie, e restituisci la distanza e la durata del percorso. Con Pro, i percorsi possono tenere conto delle condizioni del traffico in tempo reale e includere più fermate intermedie.

  • Risolvi i nomi e Risolvi gli URL di Maps: risolvi i nomi delle località, gli indirizzi e gli URL di Google Maps in ID luogo. Per saperne di più, consulta API Resolution.

Dopo aver attivato il server MCP, gli LLM possono chiamare i suoi strumenti per ottenere informazioni di grounding per questi tipi di dati. L'LLM può utilizzare queste informazioni per il contesto. Tuttavia, la sua risposta finale potrebbe non includere le informazioni esatte restituite dal server MCP. Devi verificare l'accuratezza della risposta generata.

Essentials e Pro

Essentials e Pro sono due SKU dello stesso prodotto, non prodotti o piani separati. Una richiesta viene fatturata in base a Pro quando utilizza un'opzione Pro. Tutte le altre richieste vengono fatturate in base a Essentials. Le opzioni Pro sono campi ordinari nella richiesta dello strumento, quindi un LLM può utilizzarle per tuo conto. Un agente può anche utilizzare entrambi gli SKU nella stessa conversazione. Ad esempio, un agente potrebbe utilizzare Essentials per trovare bar vicino a un punto di riferimento. Potrebbe poi utilizzare Pro per rispondere a una domanda aggiuntiva sui drink esclusivi e sui posti a sedere. Non esiste un server, un endpoint o una credenziale MCP separati per Pro.

Confronta Essentials, Pro e Grounding con Google Maps

Grounding con Google Maps è un prodotto separato. È integrato nei modelli Gemini nell'API Gemini, in Google AI Studio e in Gemini Enterprise Agent Platform. Il modello decide quando eseguire query su Google Maps e restituisce risposte fondate con citazioni. Scegli Grounding con Google Maps quando crei su Gemini e vuoi che il modello gestisca il grounding. Scegli gli strumenti dell'agente Maps Experience per altri modelli o framework di agenti o per il controllo diretto di ogni chiamata dello strumento.

Strumenti dell'agente Maps Experience Grounding con Google Maps
SKU Essentials
(precedentemente Maps Grounding Lite)		 SKU Pro
Come vengono fatturate le richieste Ogni richiesta di strumento che non utilizza un'opzione Pro Ogni richiesta di strumento che utilizza un'opzione Pro: include_extended_details, un page_size superiore a 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL o più di 10 waypoint intermedi Ogni query di Google Maps o prompt con grounding, a seconda della piattaforma e del modello
Modelli e piattaforme Qualsiasi framework di modelli o agenti che supporti MCP. Un server MCP, un set di strumenti e le stesse credenziali per entrambi gli SKU Modelli Gemini nell'API Gemini, in Google AI Studio e in Gemini Enterprise Agent Platform
Risultati degli strumenti Informazioni di base: dettagli dei luoghi per un massimo di 5 luoghi per ricerca, distanza e durata del percorso senza traffico in tempo reale, meteo attuale e previsioni Tutto ciò che è incluso in Essentials, oltre a Place Details estesi (ad esempio approfondimenti dalle recensioni), fino a 10 luoghi per ricerca, percorsi con traffico in tempo reale e fino a 25 tappe intermedie Place Details e insight dalle recensioni e informazioni sui percorsi con traffico in tempo reale
Richieste di esempio Domande oggettive e logistiche: trovare negozi o attività, orari di apertura, indirizzi e stime di distanza o tempo di percorrenza Domande soggettive o generiche: atmosfera, piatti tipici, consigli per i visitatori, confronti tra 6 e 10 luoghi e tempi di percorrenza nel traffico attuale Ricerca conversazionale, pianificazione di itinerari e scoperta di luoghi locali in Gemini
Visualizzazioni di Places UI Kit Incluso senza costi aggiuntivi con il token di visualizzazione dei dati agentica (anteprima) Fatturazione separata
Utilizzo senza costi al mese 10.000 richieste 5000 richieste Dipende dalla piattaforma e dal modello. Ad esempio, nell'API Gemini, Gemini 3 e i modelli più recenti includono 5000 query di ricerca senza costi al mese. Dopodiché, le query di ricerca costano 14 $per 1000.
Prezzo con pagamento a consumo 7,00 $ per 1000 richieste, con sconti per grandi volumi 14,00 $ per 1000 richieste. Contatta il team di vendita per i prezzi in base al volume.
Abbonati per risparmiare Incluso nei piani Essentials e Pro Non inclusa Non disponibile
Inizia Una configurazione per entrambi gli SKU: consulta Configura gli LLM per l'utilizzo del server MCP. Durante la fase di disponibilità generale limitata, le opzioni Pro richiedono anche un progetto nella lista consentita Pro. API Gemini o Agent Platform

Queste opzioni funzionano allo stesso modo con entrambi gli SKU: modalità di viaggio, orari di partenza e arrivo, percorsi alternativi, polilinee dei percorsi, ricerche meteo e API Resolution. Non modificano lo SKU in base al quale viene fatturata una richiesta.

Cosa viene fatturato con lo SKU Pro

Strumento Capacità Essentials Pro
Cerca luoghi Luoghi per richiesta Fino a 5 Da 6 a 10 (page_size da 6 a 10)
Place Details estesi nei riepiloghi di ricerca (insight dalle recensioni, punti salienti del menu, atmosfera, affollamento di un luogo, suggerimenti per i visitatori e distanza o tempo di percorrenza per le query di prossimità) Non disponibile Disponibile con include_extended_details
Compute Routes Preferenza di routing Non tiene conto del traffico in tempo reale Tiene conto del traffico in tempo reale o dei dati sul trasporto pubblico in tempo reale per i percorsi con il trasporto pubblico, con ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL
Tappe intermedie per percorso Fino a 10 Da 11 a 25 (più di 10 intermediate_waypoints)
API Lookup weather e Resolution Nessuna opzione Pro. Tutte le richieste vengono fatturate con lo SKU Essentials.

Per le opzioni di richiesta che attivano ogni funzionalità, consulta Cerca luoghi e Calcola percorsi.

Opzioni Pro durante la disponibilità generale limitata

Durante la fase di disponibilità generale limitata, le opzioni Pro sono disponibili solo per i progetti Google Cloud nella lista consentita Pro. Contatta il team di vendita per richiedere l'accesso. Una volta che un progetto è stato inserito nella lista consentita, ogni chiave API e client OAuth al suo interno può utilizzare le opzioni Pro.

Se il tuo progetto non è ancora nella lista consentita, le richieste che utilizzano le opzioni Pro vengono gestite come segue:

  • Ricerca di luoghi: include_extended_details viene ignorato e la risposta contiene al massimo 5 luoghi, anche se imposti un valore page_size più alto. La richiesta viene fatturata in base allo SKU Essentials.
  • Compute Routes: ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL viene trattato come ROUTING_PREFERENCE_TRAFFIC_UNAWARE e la richiesta viene fatturata con lo SKU Essentials. Una richiesta con più di 10 waypoint intermedi restituisce un errore INVALID_ARGUMENT.

Per verificare se il tuo progetto è incluso nella lista consentita, invia una richiesta search_places con page_size impostato su 10. Utilizza una query generica, ad esempio restaurants in Chicago. Un progetto nella lista consentita può restituire più di 5 luoghi, fatturati con lo SKU Pro. Gli altri progetti restituiscono al massimo 5 luoghi.

Controlla l'utilizzo di Pro

Le opzioni Pro sono disattivate per impostazione predefinita. Un LLM li imposta quando la richiesta dell'utente li richiede e lo schema dello strumento o le tue istruzioni lo consentono. Lo schema dello strumento descrive i valori page_size fino a 5 e un massimo di 10 tappe intermedie. Pertanto, i modelli utilizzano i limiti più elevati di Pro solo quando le tue istruzioni lo richiedono. Per gestire i costi:

  • Indica al modello quando sono appropriate le opzioni Pro. Ad esempio: "Imposta include_extended_details solo quando l'utente chiede informazioni su recensioni, menu o atmosfera". Oppure: "Utilizza ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL solo quando l'utente chiede un tempo di percorrenza attuale".
  • Per mantenere un agente nello SKU Essentials, indica al modello di non utilizzare mai un'opzione Pro. Le opzioni Pro sono include_extended_details, page_size sopra 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL e più di 10 waypoint intermedi. Se il tuo client MCP può limitare gli argomenti degli strumenti, puoi anche bloccare questi valori nella configurazione dello strumento.
  • Monitora l'utilizzo nei report sulla fatturazione e imposta avvisi relativi al budget.

API Resolution

Gli strumenti dell'agente Maps Experience forniscono l'API Resolution. Risolve il testo della posizione in formato libero e gli URL in identificatori di luoghi di Google Maps strutturati. L'API Resolution è disponibile come metodi REST e come strumenti sul server MCP:

  • Risolvi i nomi (REST, MCP): risolvi un batch di nomi o indirizzi di località in entità di luoghi specifiche su Google Maps. Questo è utile per basare le query utente non strutturate su ID luogo stabili.
  • Risolvi gli URL di Maps (REST, MCP): risolvi un batch di URL di Google Maps in entità di luoghi specifiche. I formati supportati includono URL di luoghi standard e URL abbreviati.

Puoi utilizzare gli ID luogo restituiti con altre API di Google Maps Platform. Ogni risposta include anche un link che salva i luoghi risolti come elenco in Google Maps.

Per saperne di più, consulta l'API Maps Tools Resolution.

Prova l'app di esempio (si apre in una nuova scheda)

Fatturazione e quote

Modalità di fatturazione

Con il modello di prezzi con pagamento a consumo di Google Maps Platform, l'utilizzo degli strumenti dell'agente Maps Experience viene calcolato per ogni richiesta. Ogni richiesta rappresenta un evento di fatturazione. L'utilizzo viene monitorato per ogni SKU del prodotto. La fattura mostra una voce per ogni SKU, oltre agli addebiti totali. Per saperne di più, consulta la panoramica dei report.

Ogni richiesta Search Places, Compute Routes o Lookup Weather viene fatturata in base a un solo SKU, Essentials o Pro. Una richiesta che utilizza un'opzione Pro viene fatturata con lo SKU Pro. La fatturazione non avviene mai per entrambi gli SKU e il numero di opzioni Pro non modifica l'addebito. Le seguenti opzioni determinano lo SKU:

Strumento Essentials Pro
search_places Qualsiasi richiesta senza un'opzione Pro: page_size pari o inferiore a 5 e include_extended_details non impostato o false include_extended_details impostato su true o page_size da 6 a 10
compute_routes Qualsiasi richiesta senza un'opzione Pro: routing_preference non impostata o ROUTING_PREFERENCE_TRAFFIC_UNAWARE e 10 o meno tappe intermedie, con qualsiasi modalità di viaggio routing_preference impostato su ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL o da 11 a 25 tappe intermedie
lookup_weather Ogni richiesta —

Per i prezzi di Essentials, consulta i dettagli dello SKU Essentials. Le richieste Pro vengono fatturate a 14,00 $per 1000 richieste dopo le prime 5000 richieste di ogni mese. Contatta il team di vendita per i prezzi in base al volume.

Durante la fase di disponibilità generale limitata, le opzioni Pro hanno effetto solo sui progetti inclusi nella lista consentita Pro. Per maggiori dettagli, consulta Opzioni Pro durante la disponibilità generale limitata.

Per i dettagli sui prezzi, consulta la tabella dei prezzi principale e la tabella dei prezzi per l'India.

Le richieste API di risoluzione (ResolveNames e ResolveMapsUrls) vengono fatturate senza addebiti nell'ambito dello SKU API Places Ricerca testuale Essentials (IDs Only).

L'utilizzo dello SKU Essentials è incluso anche nei pacchetti Abbonati per risparmiare Essentials e Pro. Lo SKU Pro non è incluso nei pacchetti Abbonati e risparmia.

Quote

Le seguenti quote si applicano agli strumenti e alle API forniti dagli strumenti dell'agente Maps Experience:

  • Ricerca luoghi: 300 query al minuto per progetto.
  • Ricerca meteo: 300 query al minuto per progetto.
  • Calcola percorsi: 300 query al minuto per progetto.
  • Risoluzione dei nomi: 600 query al minuto per progetto.
  • Resolve Maps URLs: 600 query al minuto per progetto.

Le quote vengono conteggiate per strumento e sono condivise dagli SKU Essentials e Pro. Una richiesta Pro consuma la stessa quota di una richiesta Essentials allo stesso strumento.

Ogni richiesta API Resolution viene conteggiata come una query, indipendentemente dal numero di elementi che contiene.

Norme e Termini di servizio

Gli strumenti dell'agente Maps Experience sono soggetti ai Termini di servizio di Google Maps Platform, inclusi i termini specifici del servizio. Questa sezione descrive i requisiti di utilizzo aggiuntivi per gli strumenti dell'agente Maps Experience, inclusi gli LLM compatibili e l'attribuzione della fonte. I requisiti si applicano a tutti i risultati, indipendentemente dallo SKU con cui viene fatturata una richiesta.

Requisiti per gli LLM compatibili

Puoi utilizzare gli strumenti dell'agente Maps Experience solo con un LLM conforme ai Termini di servizio di Google Maps Platform.

Ad esempio, sei responsabile di garantire che i Contenuti di Google Maps non vengano memorizzati nella cache, archiviati o utilizzati per migliorare l'LLM che scegli di utilizzare. Prima di utilizzare gli strumenti dell'agente Maps Experience, devi esaminare i Termini di servizio di qualsiasi modello che intendi utilizzare con gli strumenti dell'agente Maps Experience. Non devi utilizzare gli strumenti dell'agente Maps Experience con modelli che utilizzano i dati inseriti nel modello per l'addestramento o il miglioramento del modello. È tua responsabilità assicurarti che l'utilizzo del modello sia pienamente conforme alle limitazioni relative ai contenuti di Google Maps nei Termini di servizio di Google Maps Platform, inclusi i termini specifici del servizio.

Requisiti di attribuzione per le origini di Google Maps

Ogni risposta degli strumenti dell'agente Maps Experience include le fonti. Quando presenti i risultati degli strumenti dell'agente Maps Experience, devi includere le fonti di Google Maps associate e soddisfare i seguenti requisiti:

  • Le fonti di Google Maps devono seguire immediatamente i contenuti generati che supportano. Questi contenuti generati sono anche chiamati output con grounding.
  • Le fonti di Google Maps devono essere visualizzabili con una sola interazione dell'utente.

Fonti per lo strumento Cerca luoghi

Il campo places dello strumento search_places fornisce fonti che supportano la summary. Per places, vengono restituiti i seguenti metadati:

  • place (nome della risorsa)
  • id
  • location
  • googleMapsLinks

Per ogni luogo, devi generare un'anteprima del link che soddisfi i seguenti requisiti:

Questi requisiti si applicano anche ai riepiloghi che includono Place Details estesi da Pro, come gli insight delle recensioni. summary cita ogni luogo con un indice basato su zero, ad esempio [0], che rimanda a una voce in places. Ogni luogo include anche googleMapsLinks.reviewsUrl, che rimanda alle recensioni del luogo su Google Maps. Gli utenti possono seguirlo per visualizzare le recensioni alla base di un insight.

Interfacce voice-first

Se la tua app presenta i risultati degli strumenti dell'agente Maps Experience tramite voce, devi anche soddisfare i requisiti per le interfacce voice-first. In sintesi:

  • Sourcing: mostra le fonti di Google Maps in una UI complementare che mostra un registro storico letterale della conversazione vocale.
  • Informativa attiva: al momento dell'interazione, comunica agli utenti che i contenuti generati con l'AI potrebbero includere informazioni di Google Maps. Inoltre, comunica che le fonti dettagliate sono disponibili nell'UI complementare. Puoi farlo sullo schermo o tramite comandi vocali.
  • Informativa permanente: mantieni un'informativa permanente, ad esempio in un menu delle impostazioni vocali, che indichi che i contenuti generati con l'AI potrebbero includere contenuti di Google Maps.
  • Richieste degli utenti: rispondi con precisione alle domande degli utenti sulla fonte dei contenuti e indirizzali alla UI complementare per i dettagli.

Configura gli LLM per l'utilizzo del server MCP

Per utilizzare gli strumenti dell'agente Maps Experience, devi disporre di un progetto Google Cloud con il servizio API Strumenti dell'agente Maps Experience abilitato. Ti serve anche una chiave API o un ID client OAuth. Poi, puoi configurare gli LLM per accedere al server MCP. Il server MCP utilizza il trasporto HTTP trasmissibile in streaming.

Abilita gli strumenti dell'agente Maps Experience nel tuo progetto Google Cloud

Per abilitare l'API nel tuo progetto:

  1. Nella console Google Cloud, scegli il progetto che vuoi utilizzare per gli strumenti dell'agente Maps Experience.
  2. Abilita la fatturazione per il progetto nella console Google Cloud.
  3. Abilita gli strumenti dell'agente Experimente Maps nella libreria API della console Google Cloud.

Autenticati utilizzando una chiave API

Puoi utilizzare una chiave API esistente con gli strumenti dell'agente Maps Experience o crearne una nuova. In entrambi i casi, abilita il servizio API Maps Experience agent tools sia nel progetto Google Cloud sia nella chiave.

Per eseguire l'autenticazione utilizzando una chiave API:

  1. Crea o configura una chiave API seguendo i passaggi descritti in Inizia a utilizzare Google Maps Platform.
  2. Passa la chiave al server MCP utilizzando l'intestazione X-Goog-Api-Key. Devi specificarlo come intestazione HTTP personalizzata nella configurazione dello strumento MCP dell'LLM.

Autenticati utilizzando OAuth

Puoi eseguire l'autenticazione utilizzando OAuth creando credenziali OAuth e passandole all'applicazione host MCP o server MCP.

Per eseguire l'autenticazione utilizzando OAuth:

  1. Nella console Google Cloud, scegli il progetto che vuoi utilizzare per gli strumenti dell'agente Maps Experience.
  2. Nel menu API e servizi, seleziona Credenziali.
  3. Nel menu in alto, seleziona Crea credenziali > ID client OAuth.
  4. Se il progetto non ha una schermata per il consenso configurata, fai clic su Configura schermata per il consenso e segui le istruzioni sullo schermo.
  5. Nella sezione Metriche, fai clic su Crea client OAuth.
  6. Nella schermata Crea ID client OAuth, seleziona un tipo di applicazione e inserisci un nome per l'ID client.
  7. Specifica i dettagli aggiuntivi pertinenti al tipo di applicazione. Ad esempio, se stai creando un'applicazione web, aggiungi gli URI autorizzati per le richieste del browser e del server.
  8. Una volta creato il client, salva l'ID client e il secret.
  9. Quando configuri l'applicazione host MCP o server MCP, trasmetti l'ID client OAuth e il secret. Devi anche richiedere il seguente ambito: https://www.googleapis.com/auth/maps-platform.mapstools.

Per saperne di più, consulta Utilizzare OAuth 2.0 per accedere alle API di Google.

Configura gli LLM per accedere al server MCP degli strumenti dell'agente di Maps Experience

Dopo aver attivato il servizio Strumenti per gli agenti di Maps Experience e aver creato le credenziali, puoi configurare gli LLM per accedere al server MCP. Segui la documentazione di configurazione MCP del tuo LLM e utilizza l'URL del server MCP: https://mapstools.googleapis.com/mcp

Per saperne di più, consulta Configura MCP in un'applicazione AI.

Configura gli strumenti dell'agente Maps Experience con l'interfaccia a riga di comando di Gemini

Questa sezione fornisce un esempio di come configurare il server MCP degli strumenti dell'agente Maps Experience utilizzando Gemini CLI. Per maggiori dettagli, consulta la sezione Server MCP con l'interfaccia a riga di comando di Gemini.

  1. Dopo aver installato Gemini CLI, esegui gemini mcp add per configurare il server 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

    Se la configurazione è andata a buon fine, dovresti visualizzare una conferma che il server è stato aggiunto alle impostazioni utente.

  2. Per verificare che il server funzioni correttamente, esegui il comando /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. Inizia a porre domande relative a Maps con l'interfaccia a riga di comando. Ad esempio, prova "Consigliami alcuni ristoranti a Mountain View", che dovrebbe chiamare lo strumento search_places per tuo conto.

Configura gli strumenti dell'agente Maps Experience con l'Agent Development Kit (ADK)

Questa sezione mostra come configurare il server MCP con l'Agent Development Kit (ADK) in Python, Java o TypeScript.

Python

Puoi trovare un'implementazione completa di questo esempio su GitHub nel repository adk-samples.

Passaggio 1: definisci l'agente con McpToolset per gli strumenti dell'agente Maps Experience

Modifica il file agent.py. Sostituisci YOUR_GOOGLE_MAPS_API_KEY con la tua chiave API effettiva.

# ./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"
                }
            )
        )
    ]
)
Passaggio 2: assicurati che __init__.py esista

Assicurati di avere un __init__.py nella stessa directory del tuo agent.py:

from . import agent
Passaggio 3: esegui adk web e interagisci
  1. Imposta la variabile di ambiente:
    Imposta la chiave API di Google Maps come variabile di ambiente nel terminale: 
    export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
  2. Esegui adk web:
    Esegui il seguente comando per avviare l'interfaccia web ADK: 
    adk web
  3. Interagisci con la UI:
    • Seleziona la travel_planner_agent.
    • Prova prompt come:
      • "Domani sarò a San Francisco. Che tempo fa?"
      • "Trova caffetterie vicino al Golden Gate Park."
      • "Indicazioni stradali da GooglePlex a SFO."

Java

Definisci un agente che inizializza McpToolset in Java. Sostituisci YOUR_GOOGLE_MAPS_API_KEY_HERE con la chiave API effettiva che hai ottenuto se non utilizzi una variabile di ambiente.

package agents;

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

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

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

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

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

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

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

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

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

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

TypeScript

Definisci un agente che inizializza MCPToolset in 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"
            }
        })
    ],
});

Condivisione di feedback

Per condividere un feedback sugli strumenti per gli agenti di Maps Experience, utilizza i seguenti moduli: