Outils de l'agent Maps Experience

Les outils d'agent Maps Experience (anciennement Maps Grounding Lite) sont un service Google Maps Platform compatible avec le protocole MCP (Model Context Protocol) et REST pour ancrer vos applications d'IA avec des données géospatiales de confiance provenant de Google Maps. Ses outils permettent aux LLM d'accéder aux données sur les lieux, la météo, la qualité de l'air, le pollen et les itinéraires. D'autres outils permettent de résoudre les noms de lieux et les URL Google Maps en ID de lieu. Vous pouvez essayer les outils de l'agent Maps Experience en activant son serveur MCP dans n'importe quel outil compatible avec les serveurs MCP. Vous pouvez également appeler chaque outil en tant que méthode REST. Pour en savoir plus, consultez Appeler les outils avec REST.

Maps Experience Agent Tools est un produit qui se décline en deux SKU : Essentials et Pro. Chaque requête est facturée au tarif Essentials, sauf si elle utilise une option Pro. Les options Pro ajoutent la recherche de lieux le long d'un itinéraire, des détails étendus sur les lieux, plus de lieux par recherche, plus d'arrêts intermédiaires par itinéraire, le calcul d'itinéraire avec le trafic en temps réel, les prévisions de pollen et l'historique de la qualité de l'air. Les deux SKU utilisent les mêmes outils, le même serveur MCP, les mêmes méthodes REST et les mêmes identifiants. Pour en savoir plus, consultez Essentials et Pro.

Outils

Les outils d'agent Maps Experience permettent aux LLM d'accéder aux fonctionnalités Google Maps suivantes :

• Rechercher des lieux : demandez des informations sur des lieux et obtenez des résumés générés par l'IA. La réponse inclut également les ID de lieu, les coordonnées de latitude/longitude et les liens Google Maps pour chaque lieu du résumé. Vous pouvez utiliser les ID de lieu et les coordonnées de latitude/longitude avec d'autres API Google Maps Platform pour afficher des lieux sur une carte. Pour afficher ces lieux avec le Kit UI pour Places sans frais supplémentaires, utilisez le jeton de visualisation des données agentiques (preview). Avec Pro, vous pouvez demander des détails étendus sur les lieux, comme des insights issus des avis, et jusqu'à 10 lieux par requête.
• Recherche le long d'un itinéraire : recherchez des lieux le long d'un itinéraire de voyage (spécifié à l'aide d'un retrieval_token de compute_routes, route_endpoints ou encoded_polyline) et obtenez un résumé généré par l'IA, des détails sur les lieux, la distance et le temps de trajet du détour, ainsi qu'un jeton de visualisation des données agentique (preview). Chaque requête search_along_route est facturée sous le SKU Pro.
• Rechercher la météo : demandez les conditions environnementales d'un lieu, y compris la météo (conditions actuelles, historique horaire sur 24 heures et prévisions horaires et quotidiennes jusqu'à 10 jours) et la qualité de l'air actuelle ou prévue jusqu'à quatre jours. Avec Pro, vous pouvez également demander des prévisions polliniques quotidiennes sur cinq jours maximum (avec des détails sur les espèces végétales) et jusqu'à 30 jours d'historique horaire de la qualité de l'air.

• Calculer des itinéraires : demandez un itinéraire entre un point de départ et une destination, éventuellement avec des arrêts intermédiaires, et obtenez la distance et la durée de l'itinéraire, ainsi qu'un retrievalToken pour les itinéraires DRIVE que vous pouvez transmettre à search_along_route. Avec Pro, les itinéraires peuvent tenir compte des conditions de circulation en temps réel et inclure davantage d'arrêts intermédiaires.

• Résoudre les noms et Résoudre les URL Maps : résolvez les noms de lieux, les adresses et les URL Google Maps en ID de lieu. Pour en savoir plus, consultez API Resolution.

Une fois le serveur MCP activé, les LLM peuvent appeler ses outils pour obtenir des informations d'ancrage pour ces types de données. Le LLM peut utiliser ces informations pour le contexte. Toutefois, sa réponse finale peut ne pas inclure les informations exactes renvoyées par le serveur MCP. Vérifiez l'exactitude de la réponse générée.

Essentials et Pro

Essentials et Pro sont deux SKU du même produit, et non des produits ou des forfaits distincts. Une requête est facturée au tarif Pro lorsqu'elle utilise une option Pro. Toutes les autres requêtes sont facturées au tarif Essentials. Les options Pro sont des champs ordinaires de la requête d'outil. Un LLM peut donc les utiliser en votre nom. Un agent peut également utiliser les deux SKU dans la même conversation. Par exemple, un agent peut utiliser Essentials pour trouver des cafés à proximité d'un point de repère. Il peut ensuite utiliser Pro pour répondre à une question complémentaire sur les boissons phares et les places assises. Il n'existe pas de serveur, de point de terminaison ni d'identifiant MCP distincts pour Pro.

Comparer Essentials, Pro et l'ancrage avec Google Maps

L'ancrage avec Google Maps est un produit distinct. Il est intégré aux modèles Gemini dans l'API Gemini, Google AI Studio et Gemini Enterprise Agent Platform. Le modèle décide quand interroger Google Maps et renvoie des réponses ancrées avec des citations. Choisissez l'ancrage avec Google Maps lorsque vous développez sur Gemini et que vous souhaitez que le modèle gère l'ancrage. Choisissez Maps Experience Agent Tools pour d'autres modèles ou frameworks d'agent, ou pour contrôler directement chaque appel d'outil.

Le tableau suivant compare les SKU Essentials et Pro, ainsi que l'ancrage avec Google Maps :

Ces options fonctionnent de la même manière avec les deux SKU : modes de transport, heures de départ et d'arrivée, itinéraires alternatifs, polylignes d'itinéraire, recherches météorologiques, recherches sur la qualité de l'air actuelle et prévue (y compris les concentrations de polluants et les échelles d'IQA locales), systèmes d'unités météorologiques et API Resolution. Ils ne modifient pas le SKU sous lequel une requête est facturée.

Éléments facturés sous le SKU Pro

Le tableau suivant récapitule les fonctionnalités incluses dans Essentials et celles qui nécessitent le SKU Pro :

Pour connaître les options de requête qui activent chaque fonctionnalité, consultez Rechercher des lieux, Rechercher sur l'itinéraire, Calculer des itinéraires et Rechercher la météo.

Contrôler l'utilisation de Pro

Les options Pro sont désactivées par défaut sur les search_places, compute_routes et lookup_weather. Un LLM les définit ou appelle search_along_route lorsque la requête de l'utilisateur l'exige et que la description de l'outil ou vos instructions le permettent. Les descriptions des outils indiquent au modèle quelles options coûtent plus cher et quand les utiliser : un page_size supérieur à 5, des détails de lieu étendus, plus de 10 points de cheminement intermédiaires, un itinéraire tenant compte du trafic et search_along_route. Si vous appelez les outils avec REST, votre code définit chaque option. Pour gérer les coûts :

• Indiquez au modèle quand les options Pro sont appropriées. Par exemple : "Ne définis include_extended_details que lorsque l'utilisateur pose des questions sur les avis, les menus ou l'ambiance." Ou : "Utilisez ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL uniquement lorsque l'utilisateur demande un temps de trajet actuel." Ou : "N'appelez search_along_route que lorsque l'utilisateur demande des lieux le long d'un itinéraire." Ou : "Incluez POLLEN ou AIR_QUALITY avec un date ou un hour passé, uniquement lorsque l'utilisateur pose des questions sur le pollen, les allergies ou l'historique de la qualité de l'air."
• Pour conserver un agent sur le SKU Essentials, demandez au modèle de ne jamais appeler search_along_route ni d'utiliser une option Pro. Les options Pro sont include_extended_details, page_size supérieur à 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, plus de 10 points de cheminement intermédiaires, POLLEN dans capabilities, et un date ou hour passé avec AIR_QUALITY dans capabilities. Si votre client MCP peut restreindre les outils ou les arguments d'outils, vous pouvez également bloquer search_along_route et ces valeurs d'argument dans sa configuration d'outil.
• Surveillez le SKU Maps Grounding Pro dans vos rapports de facturation et définissez des alertes de budget.

API Resolution

Maps Experience Agent Tools fournit l'API Resolution. Il résout les textes et les URL de localisation de forme libre en identifiants de lieu Google Maps structurés. L'API Resolution est disponible sous forme de méthodes REST et d'outils sur le serveur MCP :

• Résoudre les noms (REST, MCP) : résolvez un lot de noms de lieux ou d'adresses en entités de lieux spécifiques sur Google Maps. Cet outil permet d'ancrer les requêtes utilisateur non structurées dans des ID de lieu stables.
• Résoudre les URL Maps (REST, MCP) : résolvez un lot d'URL Google Maps en entités de lieu spécifiques. Les formats acceptés incluent les URL de lieux standards et les URL raccourcies.

Vous pouvez utiliser les ID de lieu renvoyés avec d'autres API Google Maps Platform. Chaque réponse inclut également un lien qui enregistre les lieux résolus sous forme de liste dans Google Maps.

Pour en savoir plus, consultez API Maps Tools Resolution.

Essayer l'application exemple (ouvrir dans un nouvel onglet)

Facturation et quotas

Comment êtes-vous facturé ?

Avec le modèle de tarification à l'usage de Google Maps Platform, l'utilisation des outils de l'agent Maps Experience est calculée pour chaque requête. Chaque requête représente un événement de facturation. L'utilisation est suivie pour chaque SKU de produit. Votre facture affiche une ligne pour chaque SKU en plus du montant total de vos frais. Pour en savoir plus, consultez la présentation des rapports.

Chaque requête de recherche de lieux, de recherche le long d'un itinéraire, de calcul d'itinéraires ou de recherche de météo, via le serveur MCP ou avec REST, est facturée sous un seul SKU : Maps Grounding Essentials ou Maps Grounding Pro. Chaque requête search_along_route et toute requête utilisant une option Pro sont facturées sous le SKU Pro. Une requête n'est jamais facturée sous les deux SKU, et le nombre d'options Pro dans une requête ne modifie pas les frais. Pour connaître les fonctionnalités et les options qui déterminent le SKU de chaque outil, consultez Qu'est-ce qui est facturé sous le SKU Pro ?.

Les requêtes Maps Grounding Essentials sont facturées 7,00 $ pour 1 000 requêtes après les 10 000 premières requêtes chaque mois. Les requêtes Maps Grounding Pro sont facturées 14,00 $ pour 1 000 requêtes au-delà des 5 000 premières requêtes par mois. Les deux SKU bénéficient de remises sur volume pour une utilisation mensuelle plus élevée.

Pour en savoir plus sur les tarifs, consultez la grille tarifaire principale et la grille tarifaire pour l'Inde.

Les requêtes API de résolution (ResolveNames et ResolveMapsUrls) sont facturées sans frais sous le SKU API Places Text Search Essentials (IDs Only).

Si vous affichez les lieux d'une réponse search_places ou search_along_route avec le Kit UI pour Places, vous pouvez utiliser le jeton de visualisation des données agentique (preview) pour que ces requêtes du Kit UI pour Places ne soient pas facturées.

L'utilisation du SKU Essentials est incluse dans les forfaits Essentials et Pro S'abonner pour économiser. L'utilisation du SKU Pro est incluse dans le forfait Pro.

Quotas

Les quotas suivants s'appliquent aux outils et aux API fournis par Maps Experience Agent Tools :

• Recherche de lieux : 300 requêtes par minute pour chaque projet.
• Recherche le long d'un itinéraire : 300 requêtes par minute pour chaque projet.
• Recherche de météo : 300 requêtes par minute pour chaque projet.
• Calculer des itinéraires : 300 requêtes par minute pour chaque projet.
• Résoudre les noms : 600 requêtes par minute pour chaque projet.
• Résoudre les URL Maps : 600 requêtes par minute pour chaque projet.

Les quotas sont comptabilisés pour chaque outil et sont partagés par les SKU Essentials et Pro. Une requête Pro consomme le même quota qu'une requête Essentials pour le même outil.

Chaque requête API Resolution compte comme une seule requête, quel que soit le nombre d'éléments qu'elle contient.

Règles et conditions d'utilisation

Les outils d'agent Maps Experience sont soumis aux Conditions d'utilisation de Google Maps Platform, y compris aux Conditions spécifiques au service. Cette section décrit les exigences d'utilisation supplémentaires pour les outils d'agent Maps Experience, y compris les LLM compatibles et l'attribution de la source. Les exigences s'appliquent à tous les résultats, quel que soit le SKU sous lequel une requête est facturée.

Exigences concernant les LLM compatibles

Vous ne pouvez utiliser les outils d'agent Maps Experience qu'avec un LLM conforme aux conditions d'utilisation de Google Maps Platform.

Par exemple, vous devez vous assurer que le contenu Google Maps n'est pas mis en cache, stocké ou utilisé pour améliorer le LLM que vous choisissez d'utiliser. Avant d'utiliser les outils de l'agent Maps Experience, vous devez consulter les conditions d'utilisation de tout modèle que vous prévoyez d'utiliser avec les outils de l'agent Maps Experience. Vous ne devez pas utiliser les outils de l'agent Maps Experience avec des modèles qui utilisent les données saisies dans le modèle pour l'entraînement ou l'amélioration du modèle. Il vous incombe de vous assurer que votre utilisation du modèle respecte pleinement les restrictions concernant le contenu Google Maps dans les conditions d'utilisation de Google Maps Platform, y compris les conditions spécifiques au service.

Exigences d'attribution pour les sources Google Maps

Chaque réponse des outils de l'agent Maps Experience inclut des sources. Lorsque vous présentez des résultats provenant des outils de l'agent Maps Experience, vous devez inclure les sources Google Maps associées et respecter les exigences suivantes :

• Les sources Google Maps doivent suivre immédiatement le contenu généré qu'elles appuient. Ce contenu généré est également appelé résultat ancré.
• Les sources Google Maps doivent être visibles en une seule interaction de l'utilisateur.

Sources des outils "Rechercher des lieux" et "Rechercher sur l'itinéraire"

Le champ places de l'outil search_places et le champ results[].place de l'outil search_along_route fournissent des sources compatibles avec summary. Pour chaque lieu, les métadonnées suivantes sont renvoyées :

• place (nom de la ressource)
• id
• location
• googleMapsLinks
• attribution

Pour chaque lieu, vous devez générer un aperçu de lien qui répond aux exigences suivantes :

• Attribuez chaque source à Google Maps, conformément aux consignes d'attribution de texte pour les outils de l'agent Maps Experience.
• Lien vers la source à l'aide de googleMapsLinks.placeUrl à partir de la réponse.

Ces exigences s'appliquent également aux résumés qui incluent des détails étendus sur les lieux provenant de Pro, tels que des insights issus d'avis. summary cite chaque lieu avec un index de base zéro, tel que [0], qui correspond à une entrée dans places ou results. Chaque lieu inclut également googleMapsLinks.reviewsUrl, qui renvoie aux avis sur le lieu dans Google Maps. Les utilisateurs peuvent cliquer dessus pour voir les avis derrière un insight.

Interfaces vocales

Si votre application présente les résultats des outils de l'agent Maps Experience par commande vocale, vous devez également respecter les exigences concernant les interfaces à commande vocale. En résumé :

• Sourcing : affichez les sources Google Maps dans une UI associée qui présente un enregistrement historique textuel de la conversation vocale.
• Divulgation active : au moment de l'interaction, informez les utilisateurs que le contenu généré par l'IA peut inclure des informations provenant de Google Maps. Indiquez-lui également que des sources détaillées sont disponibles dans l'interface utilisateur associée. Vous pouvez le faire sur l'écran ou par commande vocale.
• Divulgation persistante : conservez une explication persistante, par exemple dans un menu de paramètres vocaux, indiquant que le contenu généré par l'IA peut inclure du contenu Google Maps.
• Demandes des utilisateurs : répondez précisément aux questions des utilisateurs sur la source du contenu et redirigez-les vers l'UI associée pour en savoir plus.

Configurer les LLM pour qu'ils utilisent le serveur MCP

Pour utiliser les outils de l'agent Maps Experience, vous devez disposer d'un projet Google Cloud dans lequel le service d'API Maps Experience agent tools est activé. Vous avez aussi besoin d'une clé API ou d'un ID client OAuth. Vous pouvez ensuite configurer les LLM pour qu'ils accèdent au serveur MCP. Le serveur MCP utilise le transport HTTP en flux continu.

Activez Maps Experience Agent Tools sur votre projet Google Cloud.

Pour activer l'API sur votre projet :

1. Dans la console Google Cloud, choisissez le projet que vous souhaitez utiliser pour les outils de l'agent Maps Experience.
2. Activez la facturation pour le projet dans la console Google Cloud.
3. Activez les outils de l'agent Maps Experience dans la bibliothèque d'API de la console Google Cloud.

S'authentifier à l'aide d'une clé API

Vous pouvez utiliser une clé API existante avec Maps Experience Agent Tools ou en créer une. Dans les deux cas, activez le service d'API Maps Experience agent tools sur le projet Google Cloud et la clé.

Pour vous authentifier à l'aide d'une clé API :

1. Créez ou configurez une clé API en suivant les étapes de la section Premiers pas avec Google Maps Platform.
2. Transmettez la clé au serveur MCP à l'aide de l'en-tête X-Goog-Api-Key. Vous devez le spécifier en tant qu'en-tête HTTP personnalisé dans la configuration de l'outil MCP du LLM.

S'authentifier avec OAuth

Vous pouvez vous authentifier à l'aide d'OAuth en créant des identifiants OAuth et en les transmettant à l'hôte MCP ou à l'application serveur MCP.

Pour vous authentifier à l'aide d'OAuth :

1. Dans la console Google Cloud, choisissez le projet que vous souhaitez utiliser pour les outils de l'agent Maps Experience.
2. Dans le menu API et services, sélectionnez Identifiants.
3. Dans le menu supérieur, sélectionnez Créer des identifiants > ID client OAuth.
4. Si l'écran de consentement n'est pas configuré pour le projet, cliquez sur Configurer l'écran de consentement, puis suivez les instructions à l'écran.
5. Dans la section Métriques, cliquez sur Créer un client OAuth.
6. Sur l'écran Créer un ID client OAuth, sélectionnez un type d'application et saisissez un nom pour l'ID client.
7. Spécifiez les détails supplémentaires pertinents pour votre type d'application. Par exemple, si vous créez une application Web, ajoutez des URI autorisés pour les requêtes du navigateur et du serveur.
8. Une fois votre client créé, enregistrez l'ID client et le code secret.
9. Lorsque vous configurez votre hôte MCP ou votre application de serveur MCP, transmettez votre ID client et votre code secret OAuth. Vous devez également demander le champ d'application suivant : https://www.googleapis.com/auth/maps-platform.mapstools.

Pour en savoir plus, consultez Utiliser OAuth 2.0 pour accéder aux API Google.

Configurer les LLM pour qu'ils accèdent au serveur MCP Maps Experience Agent Tools

Après avoir activé le service Outils de l'agent Maps Experience et créé des identifiants, vous pouvez configurer les LLM pour qu'ils accèdent au serveur MCP. Suivez la documentation de configuration MCP de votre LLM et utilisez l'URL du serveur MCP : https://mapstools.googleapis.com/mcp.

Pour en savoir plus, consultez Configurer le MCP dans une application d'IA.

Configurer les outils de l'agent Maps Experience avec Gemini CLI

Cette section fournit un exemple de configuration du serveur MCP des outils de l'agent Maps Experience à l'aide de la CLI Gemini. Pour en savoir plus, consultez Serveurs MCP avec Gemini CLI.

1. Après avoir installé Gemini CLI, exécutez gemini mcp add pour configurer le serveur 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
   

   Si la configuration a réussi, un message de confirmation s'affiche pour indiquer que le serveur a été ajouté à vos paramètres utilisateur.

2. Pour vérifier que le serveur fonctionne, exécutez la commande /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. Commencez à poser des questions sur Maps avec la CLI. Par exemple, essayez "Recommande-moi des restaurants à Mountain View", qui appelle l'outil search_places en votre nom.

Configurer les outils d'agent Maps Experience avec Agent Development Kit (ADK)

Cette section explique comment configurer le serveur MCP avec l'Agent Development Kit (ADK) en Python, Java ou 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"
                    }
                }
            }
        })
    ],
});
    

Appeler les outils avec REST

Chaque outil de Maps Experience Agent Tools est également disponible en tant que méthode REST. Appelez directement les méthodes REST lorsque vous souhaitez intégrer les outils à votre propre agent ou application. Par exemple, pour déclarer vos propres fonctions pour un modèle, choisissez les options que le modèle peut définir ou définissez des valeurs par défaut dans votre code.

Le tableau suivant liste la méthode REST pour chaque outil :

Une requête REST accepte les mêmes options que l'outil correspondant et renvoie la même réponse. Dans les corps de requête et de réponse REST, les noms de champs utilisent la casse camelCase (par exemple, textQuery au lieu de text_query). Les requêtes REST sont facturées sous les mêmes SKU, suivent les mêmes règles pour les options Pro et sont comptabilisées dans les mêmes quotas que les appels d'outils MCP.

Pour vous authentifier, utilisez le même projet Google Cloud et les mêmes identifiants que pour le serveur MCP. Pour connaître la procédure de configuration, consultez Configurer les LLM pour qu'ils utilisent le serveur MCP. Transmettez une clé API dans l'en-tête X-Goog-Api-Key ou un jeton d'accès OAuth avec le champ d'application https://www.googleapis.com/auth/maps-platform.mapstools dans l'en-tête Authorization.

L'exemple suivant appelle la méthode 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"

Remplacez API_KEY par votre clé API.

La réponse contient les mêmes champs summary, places et contentToken qu'un résultat d'outil search_places. Le guide de chaque outil présente une version REST de son exemple.

Envoyer des commentaires

Pour nous faire part de vos commentaires sur les outils Maps Experience Agent Tools, utilisez les formulaires suivants :

• Signaler un bug
• Envoyer une demande de fonctionnalité
• Envoyer un commentaire