Essence du pattern
Code-Execution Agent est un pattern où l'agent ne se limite pas au raisonnement textuel: il exécute du code généré dans un environnement contrôlé, obtient un résultat factuel, puis s'appuie dessus.
Quand l'utiliser : quand la réponse doit être calculée ou vérifiée via exécution de code, et pas seulement générée en texte.
L'agent :
Generate: génère un code court pour la tâcheRun: l'exécute dans une sandboxObserve: récupère le résultat réelExplain: renvoie le résultat avec explication
Problème
Imaginez que vous demandiez :
"Calcule la conversion moyenne depuis ce CSV."
L'agent écrit un script et répond : "La conversion moyenne est 3,84%."
Mais sans environnement contrôlé, vous ne voyez pas :
- ce qui a réellement été exécuté
- quels fichiers ont été lus
- s'il y a eu des tentatives d'appels réseau
- quelles ressources le code a consommées
Dans l'exécution de code, la logique du code ne suffit pas: les limites de l'environnement d'exécution comptent aussi.
C'est le problème central: le résultat dépend du code et du runtime, donc "juste exécuter" est risqué et opaque.
Solution
Code-Execution Agent exécute le code uniquement via une couche d'exécution contrôlée.
Analogie : c'est comme un laboratoire avec règles de sécurité. L'expérience n'est autorisée que dans une salle isolée et selon des contraintes. Cela réduit le risque d'endommager l'environnement ou d'exfiltrer des données.
Principe clé : le modèle peut écrire du code, mais l'exécution n'est autorisée qu'en sandbox et après contrôle de policy.
Contraintes de base :
- sandbox runtime
- accès fichiers restreint
- pas de réseau
- limites CPU/RAM/temps
Boucle contrôlée :
- Planification : définir le script minimal pour la tâche
- Génération : produire le code
- Contrôle policy : vérifier sécurité et opérations autorisées
- Exécution isolée : lancer le code en sandbox
- Validation du résultat : vérifier correction et risque
Si le contrôle policy ou la validation échoue, exécution stoppée ou escaladée.
Cela protège contre les cas où l'agent pourrait :
- lire des fichiers sensibles
- envoyer des données vers l'extérieur
- se bloquer dans des boucles longues
- exécuter des opérations dangereuses
Une exécution fiable du code n'est pas "juste exécuter", c'est exécuter d'une façon que la runtime-policy ne peut pas être contournée techniquement.
Comment ça fonctionne
Élément clé : la sandbox.
Elle limite en général :
système de fichiers: accès limité au répertoire de travailréseau: souvent totalement désactivéressources:CPU/RAM/time quotasenvironnement runtime: bibliothèques et syscalls autorisés
Description complète du flow : Plan → Generate Code → Policy Check → Execution Layer → Sandbox Run → Validate → Return
Planification
L'agent détermine ce qui doit être calculé et le format de résultat attendu.
Génération de code
Le modèle génère le code minimal pour l'étape visée, sans volume inutile.
Contrôle policy
Le code généré passe par policy-engine : bibliothèques autorisées, type de calcul et niveau de ressources acceptable.
Couche d'exécution
Le système prépare l'exécution contrôlée : environnement, limites, règles d'accès.
Exécution sandbox
Le code est exécuté en isolation avec limites strictes.
Validation
Le système vérifie le format du résultat, les erreurs, les policies de sécurité et la conformité au schéma attendu.
Retour
L'utilisateur reçoit une réponse valide ou un stop/escalade contrôlé.
En code, ça ressemble à ceci
code = agent.generate_code(goal, constraints={
"language": "python",
"no_network": True,
"max_seconds": 5,
})
exec_result = execution_layer.run_code(
code=code,
policy="sandboxed_python",
)
if not exec_result.success:
return fallback_or_stop(exec_result.error)
validated = validate_output(exec_result.stdout, schema=expected_schema)
if not validated.ok:
return stop_with_reason(validated.reason)
return format_answer(validated.data)
Règle principale : ne jamais exécuter du code généré hors contrôle sandbox et policy.
Ce que ça donne pendant l'exécution
Goal: calculer la conversion sur un rapport CSV
Generate Code:
- lecture de sales.csv
- calcul conversion_rate = paid / leads
- sortie d'un tableau par jour
Sandbox Run:
- timeout: 5s
- memory: 256MB
- network: disabled
Output:
- tableau de 7 lignes
- conversion moyenne: 3,84%
Exemple complet d'agent Code-Execution
Quand c'est adapté - et quand non
Adapté
| Situation | Pourquoi Code-Execution est adapté | |
|---|---|---|
| ✅ | Calculs réels requis, pas des suppositions textuelles | L'exécution de code donne un résultat factuel au lieu de devinettes du modèle. |
| ✅ | Travail avec tableaux, fichiers, formules | Ici il faut exécuter réellement les étapes, pas seulement les décrire. |
| ✅ | La reproductibilité du résultat est importante | L'exécution dans un environnement contrôlé facilite la vérification. |
| ✅ | Sandbox + application forcée des policies | Une infrastructure sûre permet d'exécuter du code sans risque critique. |
Non adapté
| Situation | Pourquoi Code-Execution n'est pas adapté | |
|---|---|---|
| ❌ | Tâche purement textuelle | L'exécution de code ajoute de la complexité sans bénéfice. |
| ❌ | Pas d'environnement d'exécution isolé | Sans sandbox, impossible d'exécuter du code généré en sécurité. |
| ❌ | Risque supérieur à la valeur | Le dommage potentiel ne justifie pas cette approche dans ce cas. |
Car l'exécution de code ajoute des exigences opérationnelles: sandbox, limites de ressources, monitoring, audit des runs.
Différence avec Guarded-Policy
| Guarded-Policy | Code-Execution | |
|---|---|---|
| Focus principal | Ce qui est autorisé à être exécuté | Comment exécuter du code généré en sécurité |
| Mécanisme clé | Policy gate | Sandbox runtime + validation de sortie |
| Quand ça s'active | Avant l'action | Pendant et après l'exécution du code |
| Risque sans pattern | Action dangereuse envoyée en exécution | Résultats d'exécution non fiables ou dangereux |
Guarded-Policy décide s'il faut agir. Code-Execution décide comment exécuter une action de code de façon sûre et reproductible.
Quand utiliser Code-Execution (vs autres patterns)
Utilisez Code-Execution quand l'agent doit exécuter du code, vérifier les résultats et itérer en sécurité.
Test rapide:
- si vous devez "exécuter du code et travailler sur un output factuel" -> Code-Execution
- si vous devez "d'abord seulement décomposer une grande tâche" -> Task Decomposition Agent
Comparaison avec d'autres patterns et exemples
Aide-mémoire rapide:
| Si la tâche ressemble à ça... | Utilisez |
|---|---|
| Après chaque étape, il faut décider quoi faire ensuite | ReAct Agent |
| Il faut d'abord découper un grand objectif en tâches exécutables | Task Decomposition Agent |
| Exécuter du code, vérifier les résultats et itérer en sécurité | Code Execution Agent |
| Analyser des données et produire des conclusions | Data Analysis Agent |
| Recherche multi-sources avec preuves structurées | Research Agent |
Exemples:
ReAct: "Trouve la cause d'une panne API: vérifier les logs -> regarder les erreurs -> lancer le contrôle suivant selon le résultat."
Task Decomposition: "Prépare le lancement d'un nouveau plan: découpe en sous-tâches content, technique, QA et support."
Code Execution: "Calcule la rétention sur 12 mois en Python et vérifie la validité des formules sur des données réelles."
Data Analysis: "Analyse un CSV de ventes: trouve tendances, anomalies et donne des conclusions courtes."
Research: "Collecte des données sur 5 concurrents depuis plusieurs sources et produis un résumé comparatif."
Comment combiner avec d'autres patterns
- Code-Execution + Guarded-Policy: avant run, l'agent vérifie le code selon les règles de sécurité et bloque les actions dangereuses.
- Code-Execution + Fallback-Recovery: si l'exécution bloque ou échoue, l'agent passe à un scénario fallback sûr.
- Code-Execution + Supervisor: les runs risqués ne sont pas auto-exécutés, ils partent en approbation humaine.
En bref
Code-Execution Agent:
- Génère du code pour une tâche précise
- L'exécute en sandbox isolée
- Valide le résultat avant réponse
- Augmente la précision pour les tâches de calcul
Avantages et Inconvénients
Avantages
donne des résultats plus précis pour les calculs
résultat facile à vérifier et reproduire
visibilité sur le code réellement exécuté
pratique pour manipuler fichiers et données
Inconvénients
environnement isolé obligatoire
réponse potentiellement plus lente à cause de l'exécution
erreurs possibles pendant l'exécution du code
FAQ
Q: Peut-on exécuter le code directement sur le serveur sans isolation ?
A: En production: non. Il faut isolation, limites de ressources et contrôle des opérations autorisées.
Q: L'exécution de code garantit-elle la justesse du résultat ?
A: Pas complètement. Il faut validation de sortie, tests d'invariants et contrôle de policy.
Q: Que faire si le code échoue pendant l'exécution ?
A: Appliquer une reprise bornée: retry, environnement d'exécution de secours ou stop contrôlé avec stop reason.
Et ensuite
L'approche Code-Execution permet à l'agent d'exécuter des calculs de façon fiable.
Mais comment appliquer cela à une analytique complète: nettoyage des données, agrégats, graphiques et conclusions ?