Tutoriel Google ADK : créer un agent logistique avec un serveur MCP

Aujourd’hui, le plus grand obstacle à la construction d’agents d’IA sophistiqués n’est pas le modèle, mais l’intégration. Si vous voulez qu’un agent accède à dix outils d’entreprise différents, vous devez généralement écrire dix wrappers d’API. D’après mon expérience, cela crée une "fatigue des wrappers" et une charge de maintenance énorme. À chaque changement d’API, votre agent casse.

La solution réside dans le partenariat entre le Google Agent Development Kit (ADK) et le Model Context Protocol (MCP). Si l’on considère l’IA comme un collaborateur, l’ADK en est le "cerveau" (orchestration de la logique et de la mémoire), tandis que MCP en constitue les "mains" (une façon standardisée de saisir et d’utiliser n’importe quel outil).

Dans ce tutoriel, nous allons construire un véritable agent de récupération logistique avec ADK. L’agent va :

1. Interroger BigQuery pour identifier les commandes en retard et prioritaires. 
2. Calculer la distance routière réelle entre l’entrepôt et le client via le serveur MCP Google Maps. 
3. Recommander une action de récupération, par exemple passer en expédition aérienne pour les longues distances.

Le tout sans écrire une seule ligne de code d’API personnalisé. L’agent découvre et utilise les outils automatiquement.

Nouveau sur Google Cloud ? Je vous conseille de commencer par le cours gratuit Introduction to GCP pour maîtriser la facturation, les projets et les services de base.

Qu’est-ce que Google ADK ?

Le Google Agent Development Kit (ADK) est le framework open source, orienté code, de Google pour créer, tester et déployer des agents d’IA. Alors que des frameworks comme LangChain se concentrent sur les chaînes, l’ADK est pensé pour l’exécution. Il fournit une structure standardisée sur la façon dont les agents raisonnent, utilisent des ensembles d’outils et tournent en production.

Voici les concepts clés :

• Agents : l’entité principale, définie par son modèle (par ex., Gemini 2.0 Flash) et son jeu d’instructions.
• Ensembles d’outils : un regroupement de capacités. Plutôt que de définir les outils à la main, on pointe l’ADK vers un serveur MCP et il "apprend" automatiquement les outils.
• Runners : le moteur d’exécution qui gère l’état de la conversation et la boucle itérative "pensée‑action‑observation".

Cette approche orientée code nous permet d’utiliser le contrôle de version, les tests et la CI/CD comme pour un logiciel classique. Elle offre aussi une intégration profonde à Google : les serveurs MCP managés nécessitent très peu de déploiement pour BigQuery ou Maps.

Pour comparer les trois grands clouds et leurs services, consultez notre guide AWS vs Azure vs Google Cloud.

Architecture d’intégration Google ADK et flux logique

Notre agent de récupération logistique suit un cheminement clair pour résoudre un problème métier. Comprendre ce flux vous aidera à rédiger les instructions de prompt ensuite.

La boucle de raisonnement se déroule ainsi :

1. L’agent appelle le MCP BigQuery pour trouver les lignes où status='Delayed' et priority='High'. 

2. Pour chaque commande retournée, l’agent extrait les adresses de l’entrepôt et du client. 

3. L’agent appelle le MCP Google Maps pour chaque commande afin de calculer la distance routière. 

4. L’agent applique la logique métier (par ex., au-delà de 500 miles, expédition aérienne) et présente un tableau Markdown de recommandations.

Configuration des serveurs MCP

Avant de coder, nous devons préparer l’infrastructure cloud et prêtre les serveurs MCP. D’après mon expérience, régler correctement les droits IAM est l’étape la plus importante.

Étape 1 : initialiser Google Cloud CLI 

Vérifiez d’abord que le Google Cloud CLI est installé. Ouvrez votre terminal et lancez la commande suivante pour lier votre environnement local à votre compte Google :

gcloud init

Une fenêtre de navigateur s’ouvre automatiquement. Identifiez-vous avec votre compte Google. Après connexion, cliquez sur Allow pour autoriser la CLI à gérer vos ressources. 

De retour dans le terminal, on vous demandera de sélectionner un projet par défaut. S’il existe déjà, choisissez son ID ; sinon, créez-en un nouveau dans le terminal.

Étape 2 : configurer la facturation

Pour utiliser les services d’API, vous devez activer la facturation. Google Cloud offre 300 $ de crédit gratuit pendant 90 jours pour essayer Compute, GKE, Maps, etc. — largement suffisant pour ce tutoriel. Vous ne serez facturé que si vous activez le paiement à l’usage ou la pré-paie. Pour configurer la facturation :

1. Accédez à la page de facturation de la console Google et connectez-vous avec le compte utilisé pour gcloud.

2. Créez un compte de facturation si vous n’en avez pas (ajouter un moyen de paiement est requis, mais le crédit gratuit s’applique d’abord).

3. Liez le compte de facturation à votre projet : Billing → Link a project → sélectionnez votre projet, ou lancez :

gcloud billing projects link YOUR_PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

Étape 3 : activer les API cœur et les services MCP

Nous devons ensuite activer les API produits principales. Elles permettent à l’agent d’accéder aux services de données bruts comme BigQuery et Maps.

gcloud services enable bigquery.googleapis.com
gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com
gcloud services enable mapstools.googleapis.com

Nous devons maintenant activer les points de terminaison MCP managés. Pensez-y comme à des interfaces de traduction au-dessus des API habituelles. 

Commençons par stocker votre ID de projet et votre e-mail de compte dans des variables d’environnement pour ne pas les retaper à chaque commande :

export PROJECT_ID=$(gcloud config get-value project)
export USER_EMAIL=$(gcloud config get-value account)

Avec ces variables, exécutez les commandes suivantes pour activer les fonctionnalités MCP bêta sur votre projet. Elles demandent à Google de préparer les endpoints MCP distants que votre agent appellera :

gcloud beta services mcp enable bigquery.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable mapstools.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable container.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable compute.googleapis.com --project=$PROJECT_ID

Étape 3 : configurer IAM et les clés Maps 

MCP utilise un modèle de sécurité à deux couches. Il faut une autorisation pour parler au serveur MCP lui-même et une autre pour accéder aux données (par ex., les lignes d’une table). Vous pouvez le faire avec gcloud CLI ou via l’interface Google Cloud Console.

Option IAM A : via gcloud CLI 

Pour accorder à votre compte les droits d’utiliser MCP et d’interagir avec BigQuery, exécutez ces trois commandes :

# Permission de dialoguer avec le traducteur MCP
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/mcp.toolUser"

# Droits pour exécuter des jobs BigQuery et voir les données
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/bigquery.jobUser"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/bigquery.dataViewer"

Option IAM B : via Google Cloud Console (UI)

Si vous préférez l’interface, suivez ces étapes dans le navigateur :

1. Allez sur la page IAM & Admin de votre Google Cloud Console.
2. Trouvez votre adresse e-mail dans la liste et cliquez sur l’icône Modifier le membre (crayon).
3. Cliquez sur Ajouter un autre rôle et recherchez MCP Tool User.
4. Répétez pour ajouter BigQuery Data Viewer et BigQuery Job User.
5. Cliquez sur Enregistrer.

Créer une clé d’API Maps

Créez enfin une clé d’API Maps. Contrairement à BigQuery, qui utilise vos identifiants, le serveur MCP Maps utilise cette clé pour la facturation et le suivi des quotas :

gcloud alpha services api-keys create --display-name="Maps-MCP-Key"

Étape 4 : valider les serveurs en local avec MCP Inspector

Avant d’écrire notre code Python, effectuons une vérification rapide avec MCP Inspector. Nous allons utiliser la commande npx, un outil fourni avec Node.js. 

Son objectif est d’exécuter un package (comme l’inspector) immédiatement sans l’installer de façon permanente. Lancez ceci dans votre terminal :

npx @modelcontextprotocol/inspector

Une interface web s’ouvrira (généralement sur http://localhost:3000). J’ai fait des choix précis ci-dessous pour tester la version managée distante des serveurs Google, et non un mock local :

1. Transport type : Streamable HTTP. C’est le protocole standard de production utilisé par Google pour les serveurs cloud managés.

2. URL : Entrez https://mapstools.googleapis.com/mcp. C’est la porte d’entrée directe vers le MCP de Maps de Google.

3. Connection Type : via Proxy. Choix crucial : en sélectionnant "Proxy", l’inspector utilise votre connexion locale gcloud pour gérer automatiquement les échanges de sécurité.

4. Custom Headers : Ajoutez X-Goog-Api-Key et collez votre clé de l’étape 3.

5. Cliquez sur Connect.

Vous devriez voir le statut Connected en vert. Cliquez sur List Tools pour afficher toutes les capacités offertes par le serveur. Si vous voyez compute_routes dans la liste, votre infrastructure est parfaitement configurée.

Pour approfondir l’utilisation de BigQuery, Maps et d’autres services Google avec vos agents, consultez ce tutoriel sur les serveurs MCP Google.

Construire un agent serveur MCP avec Google ADK

L’infrastructure étant prête, passons à l’environnement de développement local. Nous allons démarrer par l’organisation du projet.

Étape 1 : structurer le projet et installer les dépendances

Créez un dossier pour votre projet et mettez en place un environnement virtuel.

mkdir my-agents
cd my-agents
python -m venv .venv
source .venv/bin/activate

La dernière commande est pour macOS ou Linux ; sous Windows, utilisez .venv\Scripts\activate.

Installez ensuite le package google-adk et ses bibliothèques de support.

pip install google-adk google-generativeai python-dotenv httpx  google-auth

Créez aussi un fichier .env à la racine pour stocker votre PROJECT_ID et la MAPS_API_KEY générée à l’étape précédente.

Étape 2 : configurer les ensembles d’outils MCP

Dans un script nommé tools.py, nous n’écrivons pas du code pour "aller chercher la donnée". Nous écrivons du code pour nous connecter à un serveur qui sait le faire. 

Séparer les outils de la logique facilite grandement le débogage. Comme nous parlons à des endpoints Google Cloud distants, nous utilisons StreamableHTTPConnectionParams pour gérer les en-têtes d’authentification.

import os
import google.auth
import google.auth.transport.requests
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams 

# --- BigQuery Toolset ---
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())
        
    return MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://bigquery.googleapis.com/mcp",
            headers={
                "Authorization": f"Bearer {credentials.token}",
                # 'x-goog-user-project' is vital for BigQuery billing
                "x-goog-user-project": project_id,
                "Content-Type": "application/json"
            }
        )
    )

# --- Maps Toolset ---
def get_maps_mcp_toolset():
    maps_api_key = os.getenv('MAPS_API_KEY')
    
    return MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://mapstools.googleapis.com/mcp",
            headers={
                "X-Goog-Api-Key": maps_api_key,
                "Content-Type": "application/json"
            }
        )
    )

Étape 3 : définir la mission de l’agent

Nous construisons maintenant le "cerveau". D’après mon expérience, un modèle Gemini Flash est idéal ici car il est très rapide pour l’appel d’outils. 

Nous fournissons à l’agent une procédure opérationnelle standard via les instructions du fichier agent.py. Remarquez l’usage d’un pipeline clair en quatre étapes pour éviter toute confusion.

from .tools import get_maps_mcp_toolset, get_bigquery_mcp_toolset
from google.adk.agents import LlmAgent

# Nous donnons à l'agent un jeu d'Instructions très structuré.
# Considérez-le comme la SOP (Standard Operating Procedure) de votre agent.
root_agent = LlmAgent(
    model='gemini-2.0-flash',
    name='logistics_recovery_agent',
    instruction="""
      You are an expert Retail Operations Recovery Agent. 
      Your job is to find high-priority problems and solve them using the tools provided.

      Step 1: Use 'execute_sql' to find orders where status is 'Delayed' and priority is 'High'.
      Step 2: For every result, pull the warehouse and customer addresses.
      Step 3: Call the Maps 'compute_routes' tool to find the exact drive distance.
      Step 4: Use this logic: If distance > 500 miles, recommend 'Air Shipping'. 
            Otherwise, recommend 'Regional Express Ground'.
    
      Output the final result as a clean Markdown table.
    """,
    # Nous ajoutons simplement nos ensembles d'outils ici.
    # ADK gère la complexité de savoir quel outil appeler et quand.
    tools=[get_maps_mcp_toolset(), get_bigquery_mcp_toolset()]
)

Étape 4 : exécuter la boucle de l’agent 

Pour exécuter l’agent, nous utilisons le runner. Ce composant garde la trace de l’état de la conversation afin que l’agent sache ce qu’il a déjà fait et ce qu’il doit faire ensuite.

from google.adk.runners import Runner
from google.genai import types

async def main():
    # Le Runner sert d'hôte à notre agent.
    runner = Runner(app_name="logistics_app", agent=root_agent)

    # Encapsuler l'entrée utilisateur au format standard GenAI Content
    user_input = "Identify high-priority delayed orders and suggest recovery shipping methods."
    content = types.Content(role="user", parts=[types.Part(text=user_input)])

    print("--- Starting Smart Logistics Agent ---")
    
    # Nous utilisons run_async pour streamer les événements (pensées et appels d'outils)
    async for event in runner.run_async(user_id="admin_user", new_message=content):
        # Nous n'affichons dans la console que la partie texte de la réponse
        if hasattr(event, 'content') and event.content.parts:
            print(event.content.parts[0].text)

Que se passe-t-il en coulisses ?

Lorsque vous appelez runner.run_async, l’ADK démarre une boucle itérative :

1. Gemini réfléchit : "Je dois d’abord voir les commandes en retard."

2. ADK agit : il appelle l’outil execute_sql de votre ensemble d’outils MCP BigQuery.

3. Observation : l’outil renvoie les données de commande.

4. Gemini réfléchit : "J’ai maintenant besoin des distances pour ces deux commandes."

5. ADK agit : il appelle deux fois l’outil MCP Maps.

6. Réponse finale : Gemini voit toutes les données, applique votre logique des 500 miles et met en forme le tableau.

Tester notre agent Google ADK dans la console web

Le terminal est pratique pour les logs, mais ADK inclut une console web intégrée qui visualise le raisonnement interne de l’agent. C’est l’outil de débogage le plus utile que j’ai trouvé.

Lancez l’interface avec adk web. Une fois le serveur démarré, ouvrez http://127.0.0.1:8000. Vous verrez une interface de type chat où vous pouvez envoyer : "Identify high-priority delayed orders and suggest recovery shipping methods."

Analyser la trace d’exécution

La console ADK fournit une "trace" transparente des interactions de l’agent avec votre infrastructure cloud.

Détaillons-la étape par étape :

1. Handshakes d’outils : repérez les icônes execute_sql et compute_routes. Dans la trace, l’éclair indique une invocation d’outil. L’agent n’a pas deviné : il a effectivement contacté le serveur MCP BigQuery pour exécuter une requête SQL sur votre table des commandes.

2. Logique séquentielle : la trace montre un ordre opérationnel clair. D’abord, récupération via BigQuery (première coche). Une fois les adresses d’entrepôt et de client obtenues, vous voyez plusieurs appels compute_routes. L’agent "boucle" intelligemment sur les commandes en retard pour obtenir les distances réelles depuis le MCP Maps.

3. Synthèse finale : le bas de la trace affiche la réponse finale.

Examinez les données :

• ORD-101 : distance de 380 miles.
• ORD-103 : distance de 352 miles.

Comme nous avons donné la logique suivante : "Si distance > 500 miles, recommander Air Shipping, sinon Regional Express Ground", l’agent a correctement appliqué cette règle métier aux deux commandes et a formaté le tout en un joli tableau Markdown.

Conclusion

Nous venons de construire un agent logistique opérationnel sans écrire la moindre ligne de code API pour BigQuery ou Google Maps. En utilisant ADK et MCP, nous avons conçu une architecture modulaire, sûre et orientée développeur.

L’avenir de l’IA ne se limite pas à des chatbots qui parlent, mais à des agents qui agissent. Avec ces outils, nous nous en rapprochons enfin.

Ce tutoriel constitue un excellent point de départ pour expérimenter Google ADK et les serveurs MCP :

• Remplacez BigQuery par un autre jeu de données (ou même un serveur MCP SQLite local) pour voir la facilité de changer de source.
• Remplacez Maps par un autre serveur MCP (par ex., GKE pour vérifier la santé d’un cluster) pour démontrer le côté plug-and-play.
• Ajoutez plus de logique métier dans le prompt (comparaison de coûts, brouillon d’e-mail) et testez en direct dans l’UI web ADK.

Pour en savoir plus sur l’orchestration d’agents, je vous recommande vivement de vous inscrire à notre parcours de carrière Associate AI Engineer for Developers.