Créer un agent de planification d'itinéraire avec ADK et l'ancrage Google Maps

1. Introduction

Dans cet atelier de programmation, vous allez créer un agent de planification de voyage à l'aide de l'Agent Development Kit (ADK) et l'ancrer avec Google Maps. Vous allez demander à l'agent de générer des itinéraires touristiques et des recommandations de restaurants, en exploitant les données réelles de Google Maps.

Objectifs de l'atelier

Initialiser un projet d'agent à l'aide de l'Agent Starter Pack
Configurer l'agent pour qu'il utilise l'outil Google Maps Grounding
Tester l'agent obtenu localement avec une interface Web

Ce dont vous avez besoin

Un navigateur Web (par exemple, Chrome)
Un projet Google Cloud avec facturation activée

Cet atelier de programmation est destiné aux développeurs intermédiaires qui connaissent Python et Google Cloud, mais qui ne sont pas nécessairement des experts.

2. Avant de commencer

Créer un projet Google Cloud

Dans la console Google Cloud, sur la page du sélecteur de projet, sélectionnez ou créez un projet Google Cloud.
Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée pour un projet.

Démarrer Cloud Shell

Vérifiez l'authentification :

gcloud auth list

Confirmez votre projet :

gcloud config get project

Définissez-le si nécessaire :

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Activer les API

Exécutez cette commande pour activer toutes les API requises :

gcloud services enable \
  aiplatform.googleapis.com

3. Installer l'Agent Starter Pack

Le moyen le plus simple de commencer un projet ADK consiste à utiliser l'Agent Starter Pack. Google Cloud Agent Starter Pack est un outil d'interface de ligne de commande (CLI) Open Source conçu pour accélérer le développement et le déploiement d'agents d'IA générative prêts à la production sur Google Cloud.

Assurez-vous que uv est installé, puis exécutez la commande create pour initialiser un nouveau projet d'agent :

uvx agent-starter-pack create

Si uv n'est pas installé, vous pouvez utiliser pip :

# Create and activate a Python virtual environment
python -m venv .venv && source .venv/bin/activate

# Install the agent starter pack
pip install --upgrade agent-starter-pack

# Create a new agent project
agent-starter-pack create

Pour en savoir plus, consultez le dépôt agent-starter-pack.

Lorsque vous y êtes invité, fournissez les options suivantes pour configurer votre projet pour le développement local avec une interface React :

Modèle d'agent : adk (Simple React Agent)
Déploiement : none (déploiement Cloud désactivé pour le moment)
Région : us-central1

Cela génère une structure de répertoire de projet contenant la logique principale de votre agent, des tests et un guide GEMINI.md. Accédez à votre nouveau répertoire :

cd my-agent

4. Configurer l'ancrage

L'Agent Starter Pack génère un fichier GEMINI.md qui indique aux outils de codage assistés par IA comment gérer votre projet. Nous allons le mettre à jour pour inclure la documentation Google Maps Grounding.

Ouvrez GEMINI.md dans votre éditeur.
Ajoutez le lien de référence suivant sous la section ## Reference Documentation :

- **Google Maps Grounding**: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps

Ce contexte aidera les assistants de codage IA à comprendre la fonctionnalité d'ancrage.

5. Mettre à jour l'agent

Nous allons maintenant configurer l'agent pour qu'il agisse comme un planificateur d'itinéraire, avec l'outil Google Maps Grounding.

Ouvrez le fichier app/agent.py.
Remplacez l'intégralité du contenu de app/agent.py par le code suivant :

"""Agent application for the itinerary planner codelab."""

import os
import google.auth
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.adk.tools import google_maps_grounding
from google.genai import types

# Authenticate and set environment variables
_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

# Define the root agent
root_agent = Agent(
    name="itinerary_planner_agent",
    model=Gemini(
        model="gemini-2.5-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=(
        "You are an itinerary planner agent. Help users plan their trips by"
        " recommending restaurants and scenic routes. Use the"
        " google_maps_grounding tool to get both restaurant recommendations and"
        " route recommendations based on user preferences. When calling for"
        " restaurant recommendation, prompt the tool to tell you about the vibe"
        " of the place. When calling for routes with multiple legs, describe"
        " each of those legs with a brief sentence. Always describe the key"
        " landmarks along the route in one brief sentence."
    ),
    # Add the Google Maps Grounding tool to the agent
    tools=[google_maps_grounding],
)

app = App(
    root_agent=root_agent,
    name="app",
)

Ce code configure un agent basé sur gemini-2.5-flash qui utilise l'outil google_maps_grounding pour récupérer des informations actuelles sur les lieux et les itinéraires.

Pour afficher tous les modèles disponibles, consultez la documentation Vertex AI.

6. Exécuter l'agent

Une fois la logique de votre agent en place, essayez de le tester dans votre interface Web locale.

À la racine de votre répertoire my-agent, exécutez la commande suivante pour démarrer l'application Web :

uv run adk web

Ou, si vous utilisez un environnement virtuel :

adk web

Ouvrez l'URL fournie dans la sortie du terminal dans votre navigateur.
Testez l'agent en lui posant une question. Exemple :

"Planifie un itinéraire d'une journée à San Francisco, y compris un bon restaurant italien."
"Je visite Tokyo. Peux-tu me donner un itinéraire avec des monuments historiques intéressants et un restaurant de ramen très bien noté avec une ambiance chaleureuse ?"

Vous devriez voir une sortie semblable à un itinéraire détaillé enrichi d'avis réels et de descriptions d'itinéraires extraits directement de Google Maps.

Exemple de résultat d'itinéraire d'agent

7. Vérifier l'ancrage dans le code

Pour confirmer par programmation que votre agent utilise correctement l'ancrage Maps, vous pouvez inspecter les événements de réponse pour obtenir des métadonnées spécifiques à Maps.

Lorsque vous exécutez votre agent (par exemple, dans un script de test), il génère des événements contenant grounding_metadata. Vous pouvez parcourir les grounding_chunks dans ces métadonnées et rechercher l'attribut maps.

Voici un exemple montrant comment rechercher l'attribut maps, semblable à ce que vous pourriez utiliser dans un test automatisé :

async for event in runner.run_async(
    user_id="test_user",
    session_id=session.id,
    new_message=content,
):
    if event.grounding_metadata:
        if event.grounding_metadata.grounding_chunks:
            for chunk in event.grounding_metadata.grounding_chunks:
                # Check for the maps attribute to confirm maps grounding
                if hasattr(chunk, "maps") and chunk.maps:
                    print("SUCCESS: Maps grounding chunks detected in the response!")

8. Extraire des polylignes encodées

En plus de vérifier que l'ancrage s'est produit, vous pouvez extraire des données spécifiques telles que les itinéraires. Lorsque l'outil d'ancrage Maps renvoie des informations sur l'itinéraire, il inclut souvent une "polyligne encodée" qui peut être utilisée pour afficher l'itinéraire sur une interface Maps.

Vous pouvez trouver cette polyligne en vérifiant le texte dans l'attribut maps des grounding_chunks. Voici un exemple de détection :

async for event in runner.run_async(
    user_id="test_user",
    session_id=session.id,
    new_message=content,
):
    if event.grounding_metadata:
        if event.grounding_metadata.grounding_chunks:
            for chunk in event.grounding_metadata.grounding_chunks:
                # Extract the encoded polyline from the maps chunk text
                if (
                    hasattr(chunk, "maps")
                    and chunk.maps
                    and hasattr(chunk.maps, "text")
                    and chunk.maps.text
                    and "Encoded Polyline" in chunk.maps.text
                ):
                    print("SUCCESS: Encoded Polyline detected in the response!")

9. Effectuer un nettoyage

Pour éviter que votre compte Google Cloud ne soit facturé en permanence, supprimez les ressources créées lors de cet atelier de programmation.

Si vous avez créé un projet dédié à cet atelier de programmation, supprimez-le entièrement :

gcloud projects delete $PROJECT_ID

Si vous avez utilisé un projet existant et que vous souhaitez le conserver, vous n'avez pas de ressources spécifiques à supprimer, car l'agent s'est exécuté localement et les API utilisées sont sans serveur.

10. Félicitations

Félicitations ! Vous venez de créer un agent de planification d'itinéraire et de l'ancrer à l'aide d'informations Google Maps.