Orchestrer des agents IA en cascade
sur 3 niveaux avec Claude Code
Depuis la version 2.1.219 du 24 juillet 2026, Claude Code autorise les sous-agents imbriqués jusqu’à 3 niveaux par défaut. Je vous explique comment exploiter cette architecture en production sans faire exploser les coûts.
Claude Code version 2.1.219 (24 juillet 2026) réintroduit les sous-agents imbriqués avec une profondeur par défaut de 3 niveaux, contrôlée par la variable CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. Le système dispose de trois variables indépendantes : la profondeur d’imbrication (défaut 3), la concurrence maximale (défaut 20 agents en parallèle) et le total par session (défaut 200 agents). Chaque niveau hérite d’une fenêtre de contexte isolée et peut spawner ses propres sous-agents jusqu’à la limite configurée.
Sans routage des modèles par niveau (Opus au sommet, Sonnet au milieu, Haiku aux feuilles), le coût peut être multiplié par 7 à 12 par rapport à une session équivalente sur un seul fil. Ce guide explique comment configurer l’architecture, choisir le bon niveau de profondeur et éviter les trois pièges récurrents.
Il y a deux semaines, je travaillais sur la migration d’une base de code PHP legacy pour un client toulousain : 47 modules, environ 12 000 lignes de code. J’avais essayé d’orchestrer ça avec un seul agent Claude Code, mais le contexte explosait après une vingtaine de fichiers. J’avais alors construit un système maison avec des scripts Python qui lançaient des sessions Claude Code séparées et collaient les résultats : fragile, impossible à relancer après interruption, et sans visibilité sur l’état global. Chaque fois qu’un sous-module échouait, je devais tout reprendre à la main.
Le 24 juillet 2026, Anthropic a réintroduit les sous-agents imbriqués natifs dans Claude Code avec une profondeur de 3 niveaux par défaut. C’est exactement le modèle d’orchestration que j’attendais : un agent racine qui délègue aux modules, chaque module déléguant à des agents feuilles spécialisés. Dans ce guide, je vous explique comment configurer cette architecture, router les modèles pour maîtriser les coûts et éviter les pièges identifiés en testant cette nouvelle version.
Qu’est-ce qu’un sous-agent imbriqué dans Claude Code ?
Un sous-agent dans Claude Code est une session enfant qu’un agent parent peut spawner pour exécuter une tâche délimitée. Jusqu’ici, vous pouviez déjà utiliser des sous-agents, mais leur imbrication était limitée : un parent pouvait lancer des enfants, mais ces enfants ne pouvaient pas eux-mêmes lancer d’autres agents. C’est la notion d’orchestration à un seul niveau de délégation, dite « flat ».
L’imbrication change la donne : un agent peut spawner un sous-agent, qui lui-même spawne un sous-sous-agent, jusqu’à la profondeur configurée. Chaque niveau dans la hiérarchie dispose de sa propre fenêtre de contexte isolée, de ses propres outils autorisés et de son propre budget de tokens. C’est ce qui permet de construire des architectures d’agents véritablement hiérarchiques, où chaque couche gère un niveau d’abstraction différent.
La version 2.1.217 (21 juillet 2026) avait brusquement désactivé cette imbrication, probablement à la suite d’incidents de récursion non contrôlée. La version 2.1.219 (24 juillet 2026) l’a réintroduite avec un garde-fou explicite : une profondeur maximale de 3 niveaux par défaut, configurable via variable d’environnement. Trois jours de chaos qui ont obligé Anthropic à formaliser publiquement les limites du système.
Les trois variables qui contrôlent l’orchestration de vos agents
Claude Code expose trois variables d’environnement indépendantes pour contrôler comment vos agents se déploient. Chacune régule une dimension différente du fan-out, et les modifier séparément vous permet d’affiner votre architecture selon le type de charge de travail.
La première variable, CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, contrôle la profondeur d’imbrication. Défaut : 3. Si vous la mettez à 1, vous revenez au comportement d’avant la réintroduction : les sous-agents peuvent exister mais ne peuvent pas eux-mêmes spawner d’autres agents. La deuxième variable, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, plafonne le nombre d’agents actifs en parallèle à tout moment. Défaut : 20. C’est la variable la plus importante pour les projets avec des ressources limitées.
La troisième, CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION, fixe le nombre total de sous-agents pouvant être spawnés sur toute la durée d’une session, quelle que soit leur profondeur. Défaut : 200. Cette limite existe pour éviter les dérives runaway, où un agent boucle indirectement en spawnant des agents qui à leur tour en spawnent d’autres. Si vous atteignez cette limite, Claude Code stoppe les nouveaux spawns silencieusement : surveillez les logs pour détecter ce cas.
Configuration et fichiers agents : exemple complet d’une hiérarchie en 3 niveaux
Voici un exemple concret pour orchestrer une migration de codebase PHP en trois niveaux : un agent racine qui pilote le projet, des agents de module qui gèrent chaque sous-répertoire, et des agents feuilles spécialisés pour les réécritures de fonctions.
La règle clé : l’agent feuille (niveau 2) ne doit pas avoir l’outil Agent dans sa liste. C’est ce qui empêche la récursion accidentelle. Si un agent feuille hérite de Agent, il peut spawner un sous-agent supplémentaire même si vous pensez être à la profondeur limite.
Routage des modèles par niveau : la clé pour maîtriser les coûts
Le risque numéro un des sous-agents imbriqués est le coût. Sans routage, chaque niveau tourne par défaut sur le même modèle que la session principale. Si cette session tourne sur Opus, tous vos sous-agents tournent sur Opus. Avec 20 agents en parallèle sur 3 niveaux, vous pouvez rapidement atteindre des coûts de session qui dépassent de loin vos prévisions.
La bonne pratique est de router les modèles selon la complexité cognitive requise à chaque niveau. Le niveau racine (niveau 0) fait la planification et la synthèse : c’est du raisonnement complexe, Opus est justifié. Le niveau intermédiaire (niveau 1) exécute des tâches spécialisées qui requièrent de la compréhension contextuelle : Sonnet est le bon compromis. Le niveau feuille (niveau 2) fait du travail répétitif et bien défini : Haiku est largement suffisant, et il coûte environ 10 fois moins qu’Opus en tokens d’entrée.
Concrètement, la variable CLAUDE_CODE_SUBAGENT_MODEL=haiku définit le modèle par défaut pour tous les sous-agents qui n’ont pas de directive model: explicite dans leur fichier de configuration. Combinez-la avec des directives model: sonnet dans les agents de niveau 1 et model: opus dans l’agent racine. Sur ma migration PHP à 47 modules, ce routage a divisé le coût de la session par 4,3 par rapport à une configuration tout-Opus.
3 architectures d’agents imbriqués adaptées à vos projets
Migration et refactoring de code
Niveau 0 : agent racine analyse le projet et dispatche par module. Niveau 1 : agents module analysent chaque sous-répertoire et délèguent par fichier complexe. Niveau 2 : agents feuilles réécrivent des fonctions ou classes spécifiques et valident avec php -l ou pytest avant de rendre la main.
Audit de sécurité multi-couches
Niveau 0 : orchestrateur définit les catégories de vulnérabilités à scanner. Niveau 1 : agents spécialisés par catégorie (injection SQL, XSS, dépendances obsolètes). Niveau 2 : agents feuilles scannent fichier par fichier et remontent des rapports structurés. Le tout sans jamais saturer le contexte principal.
Génération de documentation
Niveau 0 : agent coordinateur identifie toutes les APIs et interfaces publiques. Niveau 1 : agents par domaine (API REST, classes métier, hooks). Niveau 2 : agents feuilles documentent chaque endpoint ou méthode et génèrent le Markdown. Idéal pour les codebases avec des dizaines de fichiers d’interface.
Quand ne pas utiliser l’imbrication : les cas où un seul agent suffit
L’imbrication n’est pas une solution universelle. Chaque niveau supplémentaire ajoute un overhead : un nouveau contexte isolé, un nouveau système prompt, des coûts de tokenisation qui s’accumulent. La règle empirique est simple : si la tâche fait moins de 500 tokens de contenu utile, ou si le parent pourrait la résoudre directement avec deux appels d’outils, l’imbrication est un anti-pattern.
Les tâches séquentielles sont un autre mauvais candidat pour l’imbrication. Si l’étape B dépend du résultat de l’étape A, et ainsi de suite sur toute la chaîne, vous n’avez rien à gagner à spawner un sous-agent : utilisez un seul agent avec un maxTurns plus élevé. L’imbrication brille uniquement quand les branches de travail sont indépendantes entre elles, c’est-à-dire que chaque sous-agent peut travailler en parallèle sans attendre les résultats d’un autre.
La communication latérale est également une contrainte importante : les sous-agents d’un même niveau ne peuvent pas se parler directement. Si vos agents feuilles doivent échanger des informations entre eux, vous devez faire remonter ces résultats au niveau parent, qui les redistribue. Cette limitation architecturale est souvent sous-estimée, et elle peut rendre la conception d’un workflow imbriqué plus complexe qu’un simple agent avec état centralisé.
Le cap budget : comment –max-budget-usd fonctionne enfin sur les sous-agents
La version 2.1.217 a corrigé un bug critique qui existait depuis longtemps : l’option --max-budget-usd ne s’appliquait pas aux agents de fond. Concrètement, si vous lanciez Claude Code avec un budget maximum de 5 euros, un agent de fond pouvait dépasser cette limite sans être arrêté. Si vous avez lancé des sessions avec des agents de fond avant le 21 juillet, il est recommandé de faire un audit de vos coûts de cette période.
Depuis la 2.1.217, la contrainte budget s’applique à tous les agents de la hiérarchie : si le budget global est dépassé, les nouveaux spawns sont bloqués et les agents en cours sont notifiés. C’est désormais la bonne pratique de toujours spécifier --max-budget-usd quand vous lancez des sessions avec des sous-agents imbriqués, surtout pendant la phase de prototypage où les bugs de récursion peuvent générer des coûts importants très rapidement.
Pour les architectures en production, commencez avec un budget conservateur (5 euros maximum) sur vos premiers tests, puis ajustez progressivement en observant les coûts réels. La combinaison du plafond de profondeur (3), de concurrence (20) et de budget (--max-budget-usd) vous donne trois couches de protection indépendantes. Retrouvez d’autres techniques avancées dans mon hub Claude IA, qui centralise tout ce que j’ai documenté sur l’outil.
Comparatif des architectures d’orchestration Claude Code
Pour choisir la bonne architecture selon votre projet, voici une comparaison honnête des trois approches disponibles sur les critères qui comptent en production.
| Critère | Agent unique | Sous-agents plats | Imbrication 3 niveaux |
|---|---|---|---|
| Taille de projet | Petit (moins de 20 fichiers) | Moyen (20 à 100 fichiers) | Grand (100 fichiers et plus) |
| Coût par session | Le moins cher | Moyen (x2 à x3) | Variable (x4 à x12 sans routage, x2 avec routage) |
| Parallélisme | Aucun | Un seul niveau | Multi-niveaux (jusqu’à 20 agents en parallèle) |
| Complexité de config | Très simple | Simple | Modérée (3 fichiers agents + variables env) |
| Communication latérale | Non applicable | Branches du 1er niveau | Via le parent uniquement (pas de pair à pair) |
Verdict : l’imbrication 3 niveaux est pertinente à partir d’une certaine taille de projet ou d’une complexité d’arborescence suffisante. En dessous, les sous-agents plats ou l’agent unique sont plus efficaces et moins coûteux.
Les 6 règles pour éviter les pièges de l’imbrication
- 1N’ajoutez jamais
Agentdans les outils des feuilles : les agents feuilles (dernier niveau) ne doivent pas avoir l’outilAgentdans leur liste. C’est le seul garde-fou fiable contre la récursion accidentelle. La limite de profondeur est un plafond de sécurité, pas un remplacement de ce principe. - 2Routez les modèles explicitement dans les fichiers agents : n’utilisez pas
CLAUDE_CODE_SUBAGENT_MODELseul. Ajoutez toujours une directivemodel:explicite dans le frontmatter de chaque fichier agent. La variable d’environnement est un défaut de secours, pas une configuration primaire. - 3Toujours spécifier
--max-budget-usd: depuis la version 2.1.217, ce flag s’applique enfin aux agents de fond. Commencez par un budget bas en test (5 euros), ajustez en production une fois que vous avez mesuré le coût réel. - 4Privilégiez 2 niveaux réels plutôt que 3 : la profondeur par défaut est 3, mais la plupart des workflows utiles se contentent de 2 niveaux effectifs. Le troisième niveau augmente significativement la complexité du debugging et la latence globale. N’utilisez le niveau 3 que si les branches de niveau 2 sont elles-mêmes suffisamment complexes pour mériter une délégation supplémentaire.
- 5Utilisez
permissions.denydans.claude/settings.json: la syntaxeAgent(nom_agent)dans le frontmatter ne fonctionne que quand l’agent tourne en thread principal. Dans un contexte imbriqué, cette restriction disparaît. Seulpermissions.denydans les settings globaux offre une restriction fiable dans toutes les configurations. - 6Surveillez les logs avec
--forward-subagent-text: en activant ce flag, l’activité des sous-agents remonte dans le flux de sortie principal, identifiée par le tool_use_id de l’agent parent. Essentiel pour déboguer une hiérarchie d’agents sans perdre la trace de ce que fait chaque niveau.
La commande /fork et le déplacement de /code-review : ce qui change aussi
Deux autres changements importants sont arrivés dans la même fenêtre de mises à jour de juillet 2026. La commande /fork copie maintenant votre conversation dans une nouvelle session de fond, pendant que vous continuez à travailler dans la session principale. L’ancien comportement (lancer un sous-agent in-session) est désormais séparé dans la commande /subtask. Si vous aviez des habitudes avec /fork, il faut mettre à jour vos réflexes.
La commande /code-review tourne désormais comme un sous-agent de fond (version 2.1.218, 22 juillet). Avant, elle saturait la fenêtre de conversation principale avec son output. Maintenant, elle s’exécute en parallèle et remonte son rapport quand elle a terminé. En pratique, vous pouvez demander une revue de code et continuer à travailler pendant que la revue se fait. La contrepartie : /verify et /code-review ne se déclenchent plus automatiquement depuis la version 2.1.215. Vous devez les appeler explicitement.
Ces changements s’inscrivent dans une évolution plus large de Claude Code vers un modèle où les agents de fond sont des citoyens de première classe. L’imbrication à profondeur 3 en est l’expression la plus avancée : vous pouvez maintenant bâtir des hiérarchies d’agents autonomes qui s’exécutent en parallèle, se synchronisent via leurs parents et rendent compte à travers les niveaux.
Questions fréquentes sur les agents imbriqués Claude Code
Quelle version de Claude Code est nécessaire pour les sous-agents imbriqués ?+
Vous avez besoin de la version 2.1.219 ou supérieure, disponible depuis le 24 juillet 2026. Pour vérifier votre version, lancez claude --version dans votre terminal. La mise à jour se fait via npm update -g @anthropic-ai/claude-code si vous avez installé Claude Code via npm. Notez que la version 2.1.217 (21 juillet) avait désactivé l’imbrication : si vous êtes encore sur cette version, mettez à jour en priorité.
La version 2.1.219 réintroduit l’imbrication tout en ajoutant les plafonds de sécurité (profondeur 3 par défaut) et en corrigeant le bug du budget cap sur les agents de fond. Les versions antérieures à 2.1.217 permettaient une imbrication théoriquement illimitée mais sans les garde-fous actuels, ce qui pouvait mener à des dérives de coûts importantes. Il est donc déconseillé de rester sur des versions anciennes même si elles semblaient fonctionner.
Peut-on dépasser la profondeur de 3 niveaux par défaut ?+
Oui, en modifiant la variable CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. Vous pouvez la passer à 4 ou 5 niveaux si votre architecture le nécessite. Des expérimentateurs indépendants ont rapporté avoir atteint 9 niveaux en manipulant les paramètres internes, bien que ce ne soit pas documenté officiellement et que les comportements au-delà de 5 niveaux soient imprévisibles.
En pratique, la très grande majorité des cas d’usage se résolvent en 2 à 3 niveaux effectifs. Au-delà, la complexité du debugging augmente exponentiellement et les coûts deviennent difficiles à prédire. Si vous avez besoin de plus de 3 niveaux, c’est souvent le signe que votre architecture mérite une refonte avec des étapes intermédiaires de synchronisation plutôt qu’une profondeur infinie.
Comment les 20 agents simultanés se répartissent-ils sur les niveaux ?+
Le plafond de 20 agents simultanés (variable CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS) s’applique à l’ensemble de la hiérarchie, tous niveaux confondus. Ce n’est pas 20 agents par niveau, mais 20 actifs en tout en même temps. Concrètement, si votre agent de niveau 1 spawne 10 feuilles en parallèle, il ne reste que 10 slots disponibles pour d’autres agents de n’importe quel niveau.
Cette limitation est intentionnelle : elle évite la saturation des ressources système et des quotas API. Pour les projets à large fan-out (beaucoup d’agents indépendants au même niveau), il peut être nécessaire d’augmenter cette valeur selon votre capacité machine et vos limites de taux API. La limite de 200 agents par session reste le plafond absolu, indépendamment de la concurrence maximale configurée.
Comment les sous-agents communiquent-ils leurs résultats au parent ?+
La communication est unidirectionnelle et hiérarchique : chaque sous-agent retourne son résultat au parent sous forme de texte de synthèse quand il termine. Le parent lit ce résumé, pas le transcript complet de l’exécution de l’enfant. C’est cette compression qui limite la croissance du contexte au niveau parent : tout le détail de l’exécution des feuilles disparaît, seule la conclusion remonte.
Pour les cas où vous avez besoin de plus de transparence, activez --forward-subagent-text. Ce flag fait remonter le texte produit par chaque sous-agent dans le flux de sortie de la session principale, identifié par l’ID de l’outil parent. Cela augmente le volume de sortie mais permet un debugging précis. À noter qu’il n’y a pas de communication latérale possible entre sous-agents d’un même niveau : ils ne peuvent interagir que via leur parent commun.
Peut-on utiliser les connecteurs MCP avec les sous-agents imbriqués ?+
Oui, les sous-agents héritent des connecteurs MCP configurés pour la session principale, sauf si vous les restrictiez explicitement via la configuration de permissions des agents. Un agent feuille peut appeler un connecteur GitHub ou une base de données vectorielle de la même façon qu’un agent principal, à condition que le connecteur soit accessible et que l’agent ait l’outil correspondant dans sa liste d’outils autorisés.
Cette capacité est particulièrement utile pour les architectures de génération de documentation : chaque agent feuille peut interroger directement les APIs de votre codebase (GitHub, Confluence, Jira) pour récupérer du contexte localisé à la portion de code qu’il traite. Vous évitez ainsi de centraliser tout le contexte au niveau parent, ce qui serait un goulot d’étranglement sur les grands projets.
Comment estimer le coût d’une session avec des agents imbriqués ?+
L’estimation est plus complexe qu’avec un agent unique parce que chaque niveau ajoute un overhead de tokens : nouveau système prompt, description de la tâche, historique de contexte au niveau parent. En pratique, une session à 3 niveaux avec routage optimal (Opus au sommet, Sonnet au milieu, Haiku aux feuilles) coûte environ 2 à 3 fois le coût d’une session équivalente sur un seul agent Opus, pas 7 à 12 fois comme sans routage.
La meilleure approche est de faire un test pilote sur un sous-ensemble représentatif de votre projet (5 à 10% du volume total), d’observer le coût réel avec --max-budget-usd configuré généreusement, puis d’extrapoler. Utilisez le tab Running dans Claude Code pour voir le détail par agent, ce qui vous permet d’identifier les agents qui consomment disproportionnellement et d’ajuster leur configuration.
Que se passe-t-il si un sous-agent échoue en cours d’exécution ?+
Par défaut, l’échec d’un sous-agent remonte au parent sous forme d’un message d’erreur dans la synthèse finale de cet agent. Le parent peut alors choisir de réessayer, de passer à un autre sous-agent ou de signaler l’échec au niveau supérieur. Il n’y a pas de mécanisme de retry automatique natif : c’est à l’agent parent de décider quoi faire en cas d’échec d’un enfant.
Pour les architectures robustes, incluez dans les instructions de vos agents parents une logique explicite de gestion des échecs, par exemple : « Si un agent de module rapporte une erreur, note le module concerné et continue avec les autres. Consolide les échecs dans le rapport final. » Cela évite qu’un seul échec partiel bloque l’ensemble de la session et permet une reprise plus granulaire si nécessaire.
L’imbrication fonctionne-t-elle avec Claude Opus 5 et son contexte de 1 million de tokens ?+
Oui, et c’est une combinaison particulièrement puissante. Claude Opus 5, introduit comme modèle par défaut dans la version 2.1.219, dispose d’une fenêtre de contexte de 1 million de tokens. Quand vous l’utilisez comme agent racine (niveau 0), il peut accumuler les synthèses de dizaines de sous-agents de niveau 1 sans saturer son contexte. C’est ce qui rend cette architecture pertinente pour des projets de très grande taille.
En pratique, l’agent racine Opus 5 peut orchestrer un grand nombre de sous-agents de niveau 1 et consolider leurs rapports individuels dans sa fenêtre de contexte de 1 million de tokens, sans jamais perdre d’information. Les agents de niveau 1 (Sonnet) et niveau 2 (Haiku) travaillent sur des portions plus limitées de code, ce qui rend leur fenêtre de contexte standard amplement suffisante pour les tâches déléguées.
Comment structurer le fichier agent pour éviter la récursion circulaire ?+
La récursion circulaire se produit quand un agent spawne un sous-agent qui a lui-même les permissions de spawner le premier agent (ou un agent qui ferme la boucle). Pour l’éviter, la règle simple est : les agents feuilles n’ont jamais l’outil Agent dans leur liste, point. Si votre fichier agent de niveau 2 ne peut pas appeler l’outil Agent, il ne peut pas spawner d’agents, et la récursion est structurellement impossible.
Pour les agents intermédiaires, utilisez permissions.deny dans .claude/settings.json pour blacklister les agents qui ne devraient jamais être spawnés depuis ce niveau. La syntaxe de la liste d’agents autorisés dans le frontmatter (Agent(nom)) est une protection supplémentaire, mais elle ne fonctionne que quand l’agent tourne comme thread principal. Dans un contexte imbriqué, permissions.deny est le seul garde-fou fiable.
Quelles sont les limites de l’imbrication par rapport à une orchestration externe Python ?+
L’imbrication native offre la simplicité de configuration et l’intégration avec le système de permissions et de budget de Claude Code. Vous n’avez pas à maintenir un orchestrateur externe, et la hiérarchie est visible directement dans l’interface Claude Code. La reprise sur erreur et le monitoring sont intégrés dans l’outil.
En revanche, l’orchestration Python externe offre plus de flexibilité : communication latérale entre agents, logique de retry personnalisée, intégration avec des systèmes de monitoring comme Datadog ou Prometheus, et la possibilité de mixer des appels API Claude avec d’autres services. Pour des architectures très complexes avec des besoins de coordination fine entre branches, l’orchestration externe reste une option plus puissante. L’imbrication native est le bon choix pour les cas d’usage standards de décomposition hiérarchique de tâches.
