Le cas d'usage et l'architecture

Le besoin

La responsable commerciale d'une boutique fictive veut, à partir de l'export de ses ventes 2025 :

les chiffres clés (CA total, par région, par catégorie) ;
les tendances (évolution mensuelle, saisonnalité) ;
un graphique ;
trois recommandations justifiées par des chiffres.

Le fichier ventes.csv contient 144 lignes : mois, region, categorie, unites, prix_unitaire, chiffre_affaires.

mois,region,categorie,unites,prix_unitaire,chiffre_affaires
2025-01,Nord,Casques,38,89,3382
2025-01,Nord,Enceintes,65,35,2275
2025-01,Nord,Accessoires,154,12,1848

Calcul « de tête » contre calcul par code

	Le modèle lit le CSV et répond	Le modèle écrit du Python qui est exécuté
Addition de 144 montants	approximative, erreurs possibles	exacte
Reproductible	non	oui, le code est visible
Graphique	impossible (texte seulement)	oui, matplotlib
Coût	un appel	plusieurs étapes (code, résultat, suite) dans la même réponse

Pourquoi exiger que « tout chiffre vienne d'un code exécuté » dans l'instruction ?

Où s'exécute le code ?

Avec BuiltInCodeExecutor, ADK ajoute à la requête l'outil natif code_execution de Gemini. Le modèle écrit du Python, Google l'exécute dans un bac à sable (un environnement isolé, sans accès à votre machine), le modèle lit le résultat et continue. Tout se passe dans un seul appel à l'API.

sequenceDiagram
  participant R as run.py
  participant A as ADK (analyste_donnees)
  participant G as Gemini
  participant S as Bac à sable Google
  R->>A: question + contenu du CSV
  A->>G: requête avec l'outil code_execution
  G->>S: code Python (pandas)
  S-->>G: sortie texte (totaux)
  G->>S: code matplotlib
  S-->>G: image PNG
  G-->>A: parties executable_code, code_execution_result, image, texte
  A-->>R: événements + image rangée en artefact

Exécuteur ADK 2.10	Où s'exécute le code	Usage
`BuiltInCodeExecutor`	bac à sable de Gemini, côté Google	ce lab : rien à installer
`UnsafeLocalCodeExecutor`	votre processus Python	démos uniquement : le code du modèle a accès à votre machine
`ContainerCodeExecutor`	un conteneur Docker local	isolation locale, extra `google-adk[extensions]`
`VertexAiCodeExecutor`, `AgentEngineSandboxCodeExecutor`	services gérés Google Cloud	production sur GCP

Comment les données arrivent dans le bac à sable

La documentation Gemini indique que l'exécution de code accepte des fichiers en entrée (en ligne ou via la Files API). Dans notre essai du 2026-10-15 avec ADK 2.10 et un CSV joint en ligne, os.listdir('.') renvoyait une liste vide : le modèle a recopié les données dans son code. Nous rendons donc ce comportement explicite : le CSV est placé dans le message, et l'instruction demande de le charger avec io.StringIO en le recopiant en entier, puis de vérifier len(df).

Vous devez analyser 2 millions de lignes de ventes. Quelle approche est raisonnable ?

Exercice : préparer une agrégation

Écrivez en pandas la réduction de ventes.csv à une ligne par mois et par catégorie (somme des unités et du CA). Combien de lignes obtenez-vous ?

Voir la solution

import pandas as pd
d = pd.read_csv("ventes.csv")
agg = d.groupby(["mois", "categorie"], as_index=False)[["unites", "chiffre_affaires"]].sum()
print(len(agg))   # 36 = 12 mois x 3 catégories
agg.to_csv("ventes_par_mois_categorie.csv", index=False)

On divise le volume par 4 (les régions disparaissent). Gardez à l'esprit qu'on perd l'analyse par région : agrégez selon les questions posées.

Résultat obtenu

Premier code exécuté dans le bac à sable lors du run réel (gemini-3.5-flash, 2026-10-15), et sa sortie :

--- résultat (OUTCOME_OK) ---
Nombre de lignes: 144

--- CA TOTAL ---
CA Total: 414,644 €

--- CA PAR REGION ---
region
Sud      123269
Nord     106770
Ouest     99776
Est       84829

Je sais faire

Expliquer pourquoi un agent analyste doit calculer par code
Dire où s'exécute le code avec BuiltInCodeExecutor
Comparer les exécuteurs de code d'ADK et leurs risques
Estimer quand il faut pré-agréger les données