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 di Model Context Protocol (MCP) e REST per basare le tue applicazioni di AI su dati geospaziali affidabili di Google Maps. I suoi strumenti consentono agli LLM di accedere ai dati su luoghi, meteo, qualità dell'aria, pollini e percorsi. Altri strumenti risolvono i nomi delle località e gli URL di Google Maps in ID luogo. Puoi provare i tool agentici di Maps Experience attivando il relativo server MCP in qualsiasi strumento che supporti i server MCP. Puoi anche chiamare ogni strumento come metodo REST. Per maggiori dettagli, consulta Chiama gli strumenti con REST.

I tool agentici di 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 ricerche di luoghi lungo un percorso, dettagli estesi sui luoghi, più luoghi per ricerca, più fermate intermedie per percorso, routing con traffico in tempo reale, previsioni sui pollini e qualità dell'aria storica. Entrambi gli SKU utilizzano gli stessi strumenti, server MCP, metodi REST e credenziali. Per maggiori dettagli, vedi Essentials e Pro.

Strumenti

I tool agentici di Maps Experience consentono agli LLM di accedere alle seguenti funzionalità di Google Maps:

• Cerca luoghi: richiedi informazioni sui luoghi e ottieni riepiloghi creati con l'AI. La risposta include anche gli ID luogo, le coordinate di latitudine/longitudine e i link a Google Maps per ogni luogo nel riepilogo. Puoi utilizzare gli ID luogo e le coordinate di latitudine/longitudine con altre API di Google Maps Platform per mostrare i luoghi su una mappa. Per visualizzare questi luoghi con Places UI Kit senza costi aggiuntivi, utilizza il token di visualizzazione dei dati agentica (anteprima). Con Pro, puoi richiedere Place Details estesi, ad esempio informazioni dalle recensioni, e fino a 10 luoghi per richiesta.
• Cerca lungo il percorso: Trova luoghi lungo un percorso di viaggio, specificato utilizzando un retrieval_token da compute_routes, route_endpoints ​​o un encoded_polyline, e ottieni un riepilogo generato dall'IA, Place Details, distanza di deviazione e tempo di percorrenza, e un token di visualizzazione dati agentico (Anteprima). Ogni richiesta search_along_route viene fatturata con lo SKU Pro.
• Ricerca meteo: richiedi le condizioni ambientali di una località, tra cui il meteo (condizioni attuali, cronologia oraria di 24 ore e previsioni orarie e giornaliere fino a 10 giorni) e la qualità dell'aria attuale o prevista fino a 4 giorni. Con Pro, puoi anche richiedere previsioni giornaliere della concentrazione di pollini fino a 5 giorni (con dettagli sulle specie di piante) e fino a 30 giorni di cronologia della qualità dell'aria su base oraria.

• Calcola percorsi: richiedi un percorso tra un'origine e una destinazione, facoltativamente con tappe intermedie, e restituisci la distanza, la durata e un retrievalToken per i percorsi DRIVE che puoi passare a search_along_route. Con Pro, i percorsi possono tenere conto delle condizioni del traffico in tempo reale e includere più tappe 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. Verifica 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 nell'ambito di 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 sulle bevande d'autore e sui posti a sedere. Non esiste un server MCP, un endpoint o una credenziale 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 i tool agentici di Experimente Maps per altri modelli o framework di agenti o per il controllo diretto di ogni chiamata allo strumento.

La tabella seguente mette a confronto lo SKU Essentials, lo SKU Pro e il grounding con Google Maps:

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, ricerche sulla qualità dell'aria attuale e prevista (incluse le concentrazioni di inquinanti e le scale AQI locali), sistemi di unità meteo e l'API Resolution. Non modificano lo SKU in base al quale viene fatturata una richiesta.

Cosa viene fatturato con lo SKU Pro

La tabella seguente riassume le funzionalità incluse in Essentials e quelle che richiedono lo SKU Pro:

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

Controlla l'utilizzo di Pro

Le opzioni Pro sono disattivate per impostazione predefinita su search_places, compute_routes e lookup_weather. Un LLM li imposta o chiama search_along_route quando la richiesta dell'utente lo richiede e la descrizione dello strumento o le tue istruzioni lo consentono. Le descrizioni degli strumenti indicano al modello quali opzioni costano di più e quando utilizzarle: un page_size superiore a 5, Place Details estesi, più di 10 waypoint intermedi, routing basato sul traffico e search_along_route. Se chiami gli strumenti con REST, il tuo codice imposta ogni opzione. 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". Oppure: "Chiama search_along_route solo quando l'utente chiede luoghi lungo un percorso". In alternativa: "Includi POLLEN o AIR_QUALITY con un date o hour passato, solo quando l'utente chiede informazioni su polline, allergie o qualità dell'aria storica".
• Per mantenere un agente nello SKU Essentials, istruisci il modello in modo che non chiami mai search_along_route o utilizzi un'opzione Pro. Le opzioni Pro sono include_extended_details, page_size superiore a 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, più di 10 waypoint intermedi, POLLEN in capabilities e un date o hour passato con AIR_QUALITY in capabilities. Se il tuo client MCP può limitare gli strumenti o gli argomenti degli strumenti, puoi anche bloccare search_along_route e i valori di questi argomenti nella configurazione dello strumento.
• Monitora lo SKU Maps Grounding Pro nei report sulla fatturazione e imposta avvisi relativi al budget.

API Resolution

I tool agentici di 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 gruppo di nomi o indirizzi di località in entità di luoghi specifiche su Google Maps. Questo strumento aiuta a basare le query utente non strutturate su ID luogo stabili.
• Risolvi gli URL di Maps (REST, MCP): risolvi un gruppo 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 di Place Search, ricerca lungo il percorso, calcolo dei percorsi o ricerca del meteo, tramite il server MCP o con REST, viene fatturata con uno SKU: Maps Grounding Essentials o Maps Grounding Pro. Ogni richiesta search_along_route e qualsiasi richiesta che utilizza un'opzione Pro viene fatturata con lo SKU Pro. Una richiesta non viene mai fatturata con entrambi gli SKU e il numero di opzioni Pro in una richiesta non modifica l'addebito. Per le funzionalità e le opzioni che determinano lo SKU per ogni strumento, consulta Cosa viene fatturato con lo SKU Pro.

Le richieste di Maps Grounding Essentials vengono fatturate a 7,00 $per 1000 richieste dopo le prime 10.000 richieste di ogni mese. Le richieste di Maps Grounding Pro vengono fatturate a 14,00 $per 1000 richieste dopo le prime 5000 richieste di ogni mese. Entrambi gli SKU prevedono sconti per volume in caso di utilizzo mensile più elevato.

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 costi nell'ambito dello SKU API Places Ricerca testuale Essentials (IDs Only).

Se mostri i luoghi di una risposta search_places o search_along_route con Places UI Kit, puoi utilizzare il token di visualizzazione dei dati agentica (anteprima) in modo che le richieste di Places UI Kit non vengano fatturate.

L'utilizzo dello SKU Essentials è incluso nei piani Essentials e Pro Abbonati per risparmiare. L'utilizzo dello SKU Pro è incluso nel piano Pro.

Quote

Le seguenti quote si applicano agli strumenti e alle API forniti dai tool agentici di Experimente Maps:

• Ricerca luoghi: 300 query al minuto per ogni progetto.
• Ricerca lungo il percorso: 300 query al minuto per ogni progetto.
• Ricerca meteo: 300 query al minuto per ogni progetto.
• Calcola percorsi: 300 query al minuto per ogni progetto.
• Risoluzione dei nomi: 600 query al minuto per ogni progetto.
• Risolvi gli URL di Maps: 600 query al minuto per ogni progetto.

Le quote vengono conteggiate per ogni 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

I tool agentici di Maps Experience sono soggetti ai Termini di servizio di Google Maps Platform, inclusi i Termini specifici dei servizi. 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 i tool agentici di 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 i tool agentici di Maps Experience, devi esaminare i Termini di servizio di qualsiasi modello che intendi utilizzare con i tool agentici di 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 dei servizi.

Requisiti di attribuzione per le origini di Google Maps

Ogni risposta dei tool agentici di Maps Experience include le fonti. Quando presenti i risultati dei tool agentici di 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 gli strumenti Cerca luoghi e Cerca lungo il percorso

Il campo places dello strumento search_places e il campo results[].place dello strumento search_along_route forniscono fonti che supportano summary. Per ogni luogo vengono restituiti i seguenti metadati:

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

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

• Attribuisci ogni fonte a Google Maps, seguendo le linee guida per l'attribuzione del testo dei tool agentici di Maps Experience.
• Link alla fonte utilizzando googleMapsLinks.placeUrl dalla risposta.

Questi requisiti si applicano anche ai riepiloghi che includono Place Details estesi di Pro, come gli approfondimenti delle recensioni. summary cita ogni luogo con un indice basato su zero, ad esempio [0], che rimanda a una voce in places o results. 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 vocali

Se la tua app presenta i risultati dei tool agentici di 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 i tool agentici di Maps Experience, devi disporre di un progetto Google Cloud con il servizio API Tool agentici di Maps Experience abilitato. Ti serve anche una chiave API o un ID client OAuth. In seguito, puoi configurare gli LLM per accedere al server MCP. Il server MCP utilizza il trasporto HTTP trasmissibile in streaming.

Abilita i tool agentici di 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 i tool agentici di Experimente Maps nella libreria API della console Google Cloud.

Esegui l'autenticazione utilizzando una chiave API

Puoi utilizzare una chiave API esistente con i tool agentici di 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.

Esegui l'autenticazione 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, passa 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 dei tool agentici di Experimente Maps

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

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

Configura i tool agentici di Maps Experience con Gemini CLI

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

1. Dopo aver installato l'interfaccia a riga di comando di Gemini, 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, esegui il comando /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. Inizia a Chiedi a Maps con l'interfaccia a riga di comando. Ad esempio, prova "Consigliami alcuni ristoranti a Mountain View", che chiama lo strumento search_places per tuo conto.

Configura i tool agentici di 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.

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

Chiama gli strumenti con REST

Ogni strumento nei tool agentici di Maps Experience è disponibile anche come metodo REST. Chiama direttamente i metodi REST quando vuoi collegare gli strumenti al tuo agente o alla tua applicazione, ad esempio per dichiarare le tue funzioni per un modello, scegliere le opzioni che il modello può impostare o impostare valori predefiniti nel codice.

La tabella seguente elenca il metodo REST per ogni strumento:

Una richiesta REST accetta le stesse opzioni dello strumento corrispondente e restituisce la stessa risposta. Nei corpi delle richieste e delle risposte REST, i nomi dei campi utilizzano la notazione a cammello minuscola, ad esempio textQuery anziché text_query. Le richieste REST vengono fatturate con gli stessi SKU, seguono le stesse regole per le opzioni Pro e vengono conteggiate per le stesse quote delle chiamate allo strumento MCP.

Per l'autenticazione, utilizza lo stesso progetto e le stesse credenziali Google Cloud del server MCP. Per i passaggi di configurazione, consulta Configura gli LLM per l'utilizzo del server MCP. Passa una chiave API nell'intestazione X-Goog-Api-Key o un token di accesso OAuth con l'ambito https://www.googleapis.com/auth/maps-platform.mapstools nell'intestazione Authorization.

L'esempio seguente chiama il metodo 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"

Sostituisci API_KEY con la tua chiave API.

La risposta contiene gli stessi campi summary, places e contentToken di un risultato dello strumento search_places. La guida di ogni strumento mostra una versione REST del relativo esempio.

Condivisione di feedback

Per condividere un feedback sui tool agentici di Maps Experience, utilizza i seguenti moduli:

• Segnala un bug
• Invia una richiesta di funzionalità
• Inviare un feedback