Créer un agent ADK Location Intelligence avec des serveurs MCP pour BigQuery et Google Maps

1. Introduction

Dans cet atelier de programmation, vous allez créer un agent avec ADK optimisé par Gemini 3.1 Pro. L'agent sera équipé d'outils provenant de deux serveurs MCP distants (hébergés par Google) pour accéder de manière sécurisée à BigQuery afin d'obtenir des données démographiques, tarifaires et de ventes, ainsi qu'à Google Maps pour l'analyse et la validation de lieux réels.

L'agent orchestre les requêtes entre l'utilisateur et les services Google Cloud pour résoudre des problèmes commerciaux liés à l'ensemble de données de boulangerie fictif.

82dd7bd2823a821b.png

Objectifs de l'atelier

  • Configurer les données : créez l'ensemble de données de boulangerie de base dans BigQuery.
  • Développer l'agent : créez un agent intelligent à l'aide de l'Agent Development Kit (ADK).
  • Intégrer des outils : équipez l'agent de fonctionnalités BigQuery et Maps via le serveur MCP.
  • Analyser le marché : interagissez avec l'agent pour évaluer les tendances et la saturation du marché.

Prérequis

  • Un navigateur Web tel que Chrome
  • Un projet Google Cloud dans lequel la facturation est activée ou un compte Gmail.

Cet atelier de programmation s'adresse aux développeurs de tous niveaux, y compris aux débutants. Vous utiliserez l'interface de ligne de commande dans Google Cloud Shell et le code Python pour le développement ADK. Vous n'avez pas besoin d'être un expert en Python, mais une compréhension de base de la lecture de code vous aidera à comprendre les concepts.

2. Avant de commencer

Créer un projet Google Cloud

  1. Dans la console Google Cloud, sur la page du sélecteur de projet, sélectionnez ou créez un projet Google Cloud.

a3dd2e6dddc8f691.png

  1. 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

Cloud Shell est un environnement de ligne de commande exécuté dans Google Cloud, qui est préchargé avec les outils nécessaires.

  1. Cliquez sur Activer Cloud Shell en haut de la console Google Cloud :

404e4cce0f23e5c5.png

  1. Une fois connecté à Cloud Shell, exécutez cette commande pour vérifier votre authentification dans Cloud Shell :
gcloud auth list
  1. Exécutez la commande suivante pour vérifier que votre projet est configuré pour être utilisé avec gcloud :
gcloud config get project
  1. Vérifiez que le projet est celui attendu, puis exécutez la commande ci-dessous pour définir l'ID de votre projet :
export PROJECT_ID=$(gcloud config get project)

3. Obtenir le code

Cloner le dépôt

  1. Clonez le dépôt dans votre environnement Cloud Shell :
git clone https://github.com/google/mcp.git
  1. Accédez au répertoire de démonstration :
cd mcp/examples/launchmybakery

S'authentifier

Exécutez la commande suivante pour vous authentifier à l'aide de votre compte Google Cloud. Cette opération est requise pour qu'ADK puisse accéder à BigQuery.

gcloud auth application-default login

Suivez les instructions pour terminer le processus d'authentification.

4. Configurer l'environnement et BigQuery

Exécuter des scripts d'installation

  1. Exécutez le script de configuration de l'environnement. Ce script active les API BigQuery et Google Maps, et crée un fichier .env avec l'ID de votre projet et la clé API Maps.
chmod +x setup/setup_env.sh
./setup/setup_env.sh
  1. Exécutez le script de configuration BigQuery. Ce script automatise la création du bucket Cloud Storage, l'importation des données et le provisionnement de l'ensemble de données et des tables BigQuery.
chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

Une fois le script terminé, l'ensemble de données mcp_bakery doit être créé et rempli avec les tables suivantes :

  • demographics : données de recensement et caractéristiques de la population par code postal.
  • bakery_prices : prix des concurrents et détails des produits pour divers produits de boulangerie.
  • sales_history_weekly : performances de ventes hebdomadaires (quantité et revenus) par magasin et par produit.
  • foot_traffic : scores estimés de fréquentation par code postal et par heure.
  1. Vérifiez que l'ensemble de données et les tables sont créés en accédant à la console BigQuery dans votre projet Google Cloud :

6bd0a0cd7522dd11.jpeg

5. Installer ADK

Maintenant que l'infrastructure est prête, créons un environnement Python virtuel et installons les packages requis pour ADK.

  1. Créez un environnement virtuel :
python3 -m venv .venv
  1. Activez l'environnement virtuel :
source .venv/bin/activate
  1. Installez ADK :
pip install google-adk==1.28.0
  1. Accédez au répertoire de l'agent :
cd adk_agent/

6. Inspecter l'application ADK

Cliquez sur le bouton Open Editor (Ouvrir l'éditeur) dans Cloud Shell pour ouvrir l'éditeur Cloud Shell et afficher le dépôt cloné dans le répertoire mcp/examples/launchmybakery.

a940b7eaf3c9f4b3.png

Le code de l'agent est déjà fourni dans le répertoire adk_agent/. Examinons la structure de la solution :

launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       ├── tools.py             # Custom tools for the agent
│       └── .env                 # Project configuration (created by setup script)
├── setup/                       # Infrastructure setup scripts
└── cleanup/                     # Infrastructure cleanup scripts

Fichiers clés dans mcp_bakery_app :

  • agent.py: logique de base définissant l'agent, ses outils et le modèle (Gemini 3.1 Pro Preview).
  • tools.py: contient toutes les définitions d'outils personnalisés.
  • .env: contient la configuration de votre projet et les secrets (tels que les clés API) créés par le script d'installation.

1. Initialisation de l'ensemble d'outils MCP :

Ouvrez maintenant adk_agent/mcp_bakery_app/tools.py dans l'éditeur pour comprendre comment les ensembles d'outils MCP sont initialisés.

Pour permettre à notre agent de communiquer avec BigQuery et Google Maps, nous devons configurer les clients MCP (Model Context Protocol).

Le code établit des connexions sécurisées aux serveurs MCP distants de Google à l'aide de StreamableHTTPConnectionParams.

def get_maps_mcp_toolset():
    dotenv.load_dotenv()
    maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
    
    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=MAPS_MCP_URL,
            headers={    
                "X-Goog-Api-Key": maps_api_key
            }
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools


def get_bigquery_mcp_toolset():   
        
    credentials, project_id = google.auth.default(
            scopes=["https://www.googleapis.com/auth/bigquery"]
    )

    credentials.refresh(google.auth.transport.requests.Request())
    oauth_token = credentials.token
        
    HEADERS_WITH_OAUTH = {
        "Authorization": f"Bearer {oauth_token}",
        "x-goog-user-project": project_id
    }

    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=BIGQUERY_MCP_URL,
            headers=HEADERS_WITH_OAUTH
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools
  • Ensemble d'outils Maps : configure la connexion au serveur MCP Maps à l'aide de votre clé API.
  • Ensemble d'outils BigQuery : cette fonction configure la connexion au serveur MCP BigQuery. Elle utilise google.auth pour récupérer automatiquement vos identifiants Cloud, générer un jeton de support OAuth et l'injecter dans l'en-tête d'autorisation.

2. Définition de l'agent :

Ouvrez maintenant adk_agent/mcp_bakery_app/agent.py dans l'éditeur pour voir comment l'agent est défini.

LlmAgent est initialisé avec le modèle gemini-3.1-pro-preview.

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-3.1-pro-preview',
    name='root_agent',
    instruction=f"""
                Help the user answer questions by strategically combining insights from two sources:
                
                1.  **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the  mcp_bakery dataset. Do not use any other dataset.
                Run all query jobs from project id: {project_id}. 

                2.  **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
                    Include a hyperlink to an interactive map in your response where appropriate.
            """,
    tools=[maps_toolset, bigquery_toolset]
)
  • Instructions système : l'agent reçoit des instructions spécifiques pour combiner des insights provenant de BigQuery (pour les données) et de Maps (pour l'analyse de lieux).
  • Outils : les ensembles d'outils maps_toolset et bigquery_toolset sont attribués à l'agent, ce qui lui donne accès aux fonctionnalités des deux services.

L'agent respecte les instructions et les outils définis dans le dépôt. N'hésitez pas à modifier les instructions pour voir comment cela affecte le comportement de l'agent.

7. Discutez avec votre agent !

Revenez au terminal dans Cloud Shell et exécutez cette commande pour accéder au répertoire adk_agent (si ce n'est pas déjà fait) :

cd adk_agent/

Exécutez la commande suivante pour démarrer l'interface Web ADK. Cette commande lance un serveur Web léger pour héberger l'application de chat :

adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

Une fois le serveur démarré, le message suivant s'affiche dans Cloud Shell :

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Vous avez deux options pour accéder à l'interface utilisateur ADK :

Option 1 : Cliquez sur le lien local Cliquez sur le lien http://127.0.0.1:8000 qui s'affiche dans votre terminal Cloud Shell.

Option 2 : Utilisez l'aperçu sur le Web

  1. Cliquez sur le bouton Web Preview (Aperçu sur le Web) en haut à droite de Cloud Shell.
  2. Sélectionnez Change port (Modifier le port).
  3. Saisissez 8000 comme numéro de port, puis cliquez sur Change and Preview (Modifier et prévisualiser).

Capture d'écran montrant comment ouvrir l'UI ADK

Interagissez avec l'agent en posant les questions suivantes dans l'interface utilisateur Web. Vous devriez voir les outils pertinents être appelés.

  1. Rechercher le quartier (macro) : "Je souhaite ouvrir une boulangerie à Los Angeles. Trouve le code postal avec le score de fréquentation matinale le plus élevé."

5f2a48bebfc49709.png

L'agent doit utiliser des outils tels que get_table_info et execute_sql pour interroger la table foot_traffic dans BigQuery.

  1. Valider le lieu (micro) : "Peux-tu rechercher des boulangeries dans ce code postal pour voir s'il est saturé ?"

32796c9a8cefca7.png

L'agent doit utiliser les outils search places de l'ensemble d'outils Maps pour répondre à cette question.

À vous de jouer ! Consultez ces exemples de questions pour voir votre agent ADK en action :

  • "Je souhaite ouvrir ma quatrième boulangerie à Los Angeles. J'ai besoin d'un quartier où il y a de l'activité tôt le matin. Trouve le code postal avec le score de fréquentation matinale le plus élevé."
  • "Peux-tu rechercher des boulangeries dans ce code postal pour voir s'il est saturé ? S'il y en a trop, recherche des cafés spécialisés pour que je puisse m'installer à proximité et attirer des clients."
  • "D'accord, je veux positionner ma marque comme une marque haut de gamme. Quel est le prix maximal facturé pour un pain au levain dans la zone métropolitaine de Los Angeles ?"
  • "Je souhaite maintenant une prévision de revenus pour décembre 2025. Consulte mon historique des ventes et prends les données de mon magasin le plus performant pour le pain au levain. Exécute une prévision pour décembre 2025 afin d'estimer la quantité que je vais vendre. Calcule ensuite les revenus totaux prévus en utilisant un prix légèrement inférieur au prix premium que nous avons trouvé (utilisons 18 $)."
  • "Cela couvrira mon loyer. Enfin, vérifions la logistique. Trouve le "Restaurant Depot" le plus proche de la zone proposée et assure-toi que le temps de trajet est inférieur à 30 minutes pour le réapprovisionnement quotidien."

Lorsque vous avez terminé de tester votre agent, vous pouvez fermer l'interface Web ADK en appuyant sur Ctrl+C dans votre terminal Cloud Shell.

8. 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.

Exécutez le script de nettoyage. Ce script supprime l'ensemble de données BigQuery, le bucket Cloud Storage et les clés API créés lors de la configuration.

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

9. Félicitations

Mission accomplie ! Vous avez créé un agent d'intelligence géographique à l'aide de l'Agent Development Kit (ADK).

En comblant le fossé entre vos données "d'entreprise" dans BigQuery et le contexte géographique réel de Google Maps, vous avez créé un outil puissant capable de raisonnement commercial complexe, le tout optimisé par le protocole MCP (Model Context Protocol) et Gemini.

Ce que vous avez accompli :

  • Infrastructure as Code : vous avez provisionné une pile de données à l'aide des outils Google Cloud CLI.
  • Intégration MCP : vous avez connecté un agent d'IA à deux serveurs MCP distants distincts (BigQuery et Maps) sans écrire de wrappers d'API complexes.
  • Raisonnement unifié : vous avez créé un agent unique capable de combiner stratégiquement des insights provenant de deux domaines différents pour résoudre un problème commercial.

Documents de référence