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 voyages à l'aide d'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 d'Agent Starter Pack
  • Configurer l'agent pour qu'il utilise l'outil Ancrage Google Maps
  • Tester l'agent obtenu localement avec une interface Web

Prérequis

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

Cet atelier de programmation s'adresse aux développeurs intermédiaires qui connaissent un peu Python et Google Cloud, mais qui ne sont pas nécessairement des experts.

2. Avant de commencer

Créer un projet Google Cloud

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

Démarrer Cloud Shell

  1. Vérifiez l'authentification :
gcloud auth list
  1. Confirmez votre projet :
gcloud config get project
  1. Définissez-la si nécessaire :
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Activer les API

Exécutez la commande suivante pour activer toutes les API requises :

gcloud services enable \
  aiplatform.googleapis.com

3. Installer le pack de démarrage de l'agent

Le moyen le plus simple de commencer un projet ADK est d'utiliser l'Agent Starter Pack. Le Starter Pack Google Cloud Agent 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 pour la production sur Google Cloud.

  1. Assurez-vous que uv est installé, puis exécutez la commande create pour initialiser un projet d'agent :
uvx agent-starter-pack create
  1. 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 (le déploiement Cloud est désactivé pour le moment)
  • Région : us-central1

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

cd my-agent

4. Configurer l'ancrage

Agent Starter Pack génère un fichier GEMINI.md qui indique aux outils de programmation assistée par l'IA comment gérer votre projet. Nous mettrons à jour cette page pour inclure la documentation sur l'ancrage Google Maps.

  1. Ouvrez GEMINI.md dans votre éditeur.
  2. 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 programmation IA à comprendre la fonctionnalité d'ancrage.

5. Mettre à jour l'agent

Nous allons maintenant configurer l'agent pour qu'il agisse en tant que planificateur d'itinéraires, avec l'outil d'ancrage Google Maps.

  1. Ouvrez le fichier app/agent.py.
  2. 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 de Vertex AI.

6. Exécuter l'agent

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

  1. À partir de 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
  1. Ouvrez l'URL fournie dans le résultat du terminal dans votre navigateur.
  2. Testez l'agent en lui posant une question. Exemple :
  • "Organise un itinéraire d'une journée à San Francisco, y compris un bon restaurant italien."
  • "Je visite Tokyo. Peux-tu me proposer un itinéraire avec des monuments historiques intéressants et un restaurant de ramen très bien noté à l'ambiance chaleureuse ?"

Vous devriez obtenir un résultat 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 de l'itinéraire de l'agent

7. Valider l'ancrage dans le code

Pour confirmer par programmation que votre agent utilise bien 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 le grounding_chunks dans ces métadonnées et rechercher l'attribut maps.

Voici un exemple montrant comment vérifier l'attribut maps, comme vous pourriez le faire 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 les polylignes encodées

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

Vous pouvez trouver cette polyligne en vérifiant le texte de l'attribut maps de grounding_chunks. Voici un exemple de la façon dont vous pouvez le détecter :

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 les ressources créées lors de cet atelier de programmation ne soient facturées en permanence sur votre compte Google Cloud, supprimez-les.

  1. Si vous avez créé un projet dédié pour 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 avez créé un agent de planification d'itinéraire et l'avez ancré à l'aide des insights Google Maps.

Connaissances acquises

  • Créer un agent à l'aide d'Agent Starter Pack
  • Ajouter des outils d'ancrage à une définition d'agent ADK
  • Tester un agent ADK à l'aide du runner Web intégré

Étapes suivantes

  • Découvrir d'autres outils ADK et modèles d'intégration

Documents de référence