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.0 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 vente, et à Google Maps pour l'analyse et la validation des emplacements réels.

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

Objectifs de l'atelier

Configurer les données : créez l'ensemble de données de base sur la boulangerie dans BigQuery.
Développer l'agent : créez un agent intelligent à l'aide d'Agent Development Kit (ADK).
Intégrer des outils : équipez l'agent avec les fonctionnalités BigQuery et Maps via le serveur MCP.
Analysez 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 pour 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

Dans la console Google Cloud, sur la page de sélection du 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 sur un projet.

Démarrer Cloud Shell

Cloud Shell est un environnement de ligne de commande exécuté dans Google Cloud et fourni avec les outils nécessaires.

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

Une fois connecté à Cloud Shell, exécutez la commande suivante pour vérifier votre authentification dans Cloud Shell :

gcloud auth list

Exécutez la commande suivante pour vérifier que votre projet est configuré pour être utilisé avec gcloud :

gcloud config get project

Vérifiez que le projet correspond à vos attentes, 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

Clonez le dépôt dans votre environnement Cloud Shell :

git clone https://github.com/google/mcp.git

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 autorisation est requise pour que l'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 les scripts de configuration

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 votre ID de projet et votre clé API Maps.

chmod +x setup/setup_env.sh
./setup/setup_env.sh

Exécutez le script d'installation de 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 renseigné avec les tables suivantes :

demographics : données de recensement et caractéristiques de la population par code postal.
bakery_prices : prix et détails des produits concurrents pour divers produits de boulangerie.
sales_history_weekly : performances des ventes hebdomadaires (quantité et revenus) par magasin et par produit.
foot_traffic : scores de trafic piétonnier estimés par code postal et heure de la journée.

Vérifiez que l'ensemble de données et les tables ont été créés en accédant à la console BigQuery dans votre projet Google Cloud :

5. Installer ADK

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

Créez un environnement virtuel :

python3 -m venv .venv

Activez l'environnement virtuel :

source .venv/bin/activate

Installez l'ADK :

pip install google-adk

Accédez au répertoire de l'agent :

cd adk_agent/

6. Inspecter l'application ADK

Cliquez sur le bouton 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.

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.0 Pro Preview).
tools.py : contient les définitions d'outils personnalisés.
.env : contient la configuration de votre projet et les secrets (comme les clés API) créés par le script de configuration.

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. Il 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-pro-preview.

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

root_agent = LlmAgent(
    model='gemini-3-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 les insights de BigQuery (pour les données) et de Maps (pour l'analyse des lieux).
Outils : les services 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 :

cd adk_agent

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

adk web

Une fois le serveur démarré, vous pouvez discuter avec votre agent en cliquant sur l'URL fournie pour lancer l'interface Web de l'ADK.

Interagissez avec l'agent en posant les questions suivantes. Vous devriez voir les outils concernés être appelés.

Trouve le quartier (macro) : "Je veux ouvrir une boulangerie à Paris. Trouve le code postal avec le score de trafic piétonnier matinal le plus élevé."

L'agent doit utiliser les outils get_table_info et execute_sql pour interroger la table "foot_traffic" dans BigQuery.

Valider la zone géographique (micro) : "Peux-tu rechercher les boulangeries dans ce code postal pour voir s'il est saturé ?"

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

Essayez ! Découvrez votre agent ADK en action grâce à ces exemples de questions :

"Je souhaite ouvrir ma quatrième boulangerie à Los Angeles. J'ai besoin d'un quartier où l'activité est matinale. Trouve le code postal dont le score de trafic piétonnier "matin" est le plus élevé."
"Peux-tu rechercher les boulangeries dans ce code postal pour voir si le marché est saturé ? S'il y en a trop, recherche les cafés spécialisés pour que je puisse me positionner à proximité et capter le trafic piétonnier."
"D'accord, et je veux positionner cela comme une marque haut de gamme. Quel est le prix maximal facturé pour un "pain au levain" dans la région métropolitaine de Los Angeles ?"
"Maintenant, j'aimerais obtenir une prévision des revenus pour décembre 2025. Consulte mon historique des ventes et extrais les données de mon magasin le plus performant pour la "miche de pain au levain". Génère une prévision pour décembre 2025 afin d'estimer la quantité que je vais vendre. Calculez ensuite le revenu total prévu 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."

8. Effectuer un nettoyage

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

Exécutez le script de nettoyage. Ce script supprimera 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 de localisation réel de Google Maps, vous avez créé un outil puissant capable d'effectuer des raisonnements commerciaux complexes, le tout grâce au protocole de contexte de modèle (MCP) 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 d'enveloppes 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 métier.