Orchestrer des sous-agents à grande échelle avec des workflows dynamiques

Les workflows dynamiques orchestrent de nombreux sous-agents à partir d'un script que Claude écrit et que vous pouvez relancer. Utilisez-les pour les audits de base de code, les migrations importantes et la recherche avec vérification croisée.

{/* plan-availability: feature=workflows plans=pro,max,team,enterprise providers=all */}

Un workflow dynamique est un script JavaScript qui orchestre des sous-agents à grande échelle. Claude écrit le script pour la tâche que vous décrivez, et un runtime l'exécute en arrière-plan tandis que votre session reste réactive.

Utilisez un workflow quand une tâche nécessite plus d'agents qu'une seule conversation ne peut en coordonner, ou quand vous voulez que l'orchestration soit codifiée sous forme de script que vous pouvez lire et relancer. Les exemples incluent un balayage de bugs à l'échelle de la base de code, une migration de 500 fichiers, une question de recherche qui nécessite une vérification croisée des sources les unes par rapport aux autres, et un plan difficile qui vaut la peine d'être rédigé sous plusieurs angles indépendants avant de vous engager sur l'un d'eux.

Cette page couvre comment :

• Décider quand utiliser un workflow au lieu de sous-agents ou de skills
• Exécuter un workflow groupé avec /deep-research
• Faire écrire un workflow par Claude pour votre tâche et l'enregistrer
• Comprendre comment un workflow s'exécute et gérer les exécutions

Quand utiliser un workflow

Les sous-agents, les skills, les équipes d'agents et les workflows peuvent tous exécuter une tâche multi-étapes. La différence réside dans qui détient le plan :

Un workflow déplace le plan dans le code. Avec les sous-agents, les skills et les équipes d'agents, Claude est l'orchestrateur : il décide tour par tour ce qu'il faut générer ou assigner ensuite, et chaque résultat atterrit dans une fenêtre de contexte. Un script de workflow détient la boucle, la ramification et les résultats intermédiaires eux-mêmes, donc le contexte de Claude ne contient que la réponse finale.

Déplacer le plan dans le code permet également à un workflow d'appliquer un modèle de qualité répétable, pas seulement d'exécuter plus d'agents : il peut avoir des agents indépendants qui examinent adversarialement les conclusions les uns des autres avant qu'elles ne soient rapportées, ou rédiger un plan sous plusieurs angles et les peser les uns par rapport aux autres, afin que vous obteniez un résultat plus fiable qu'une seule passe.

Exécuter un workflow groupé

Le moyen le plus rapide de voir un workflow en action est d'exécuter /deep-research, le workflow intégré que Claude Code inclut pour enquêter sur une question à travers de nombreuses sources. Vous verrez les agents travailler à travers un ensemble de phases en arrière-plan tandis que votre session reste libre, et vous obtiendrez un rapport à la fin au lieu d'une transcription tour par tour.

/deep-research What changed in the Node.js permission model between v20 and v22?

/workflows

Pour exécuter un workflow pour votre propre tâche, faites écrire un par Claude, et une fois qu'une exécution fait ce que vous vouliez, vous pouvez l'enregistrer comme commande de votre propre.

Workflows groupés

Claude Code inclut /deep-research comme workflow intégré :

Les workflows que vous enregistrez vous-même deviennent des commandes de la même manière et apparaissent dans l'autocomplétion / aux côtés des workflows intégrés.

Regarder l'exécution

Les workflows s'exécutent en arrière-plan, donc la session reste réactive pendant que les agents travaillent. Exécutez /workflows à tout moment pour lister les workflows en cours d'exécution et terminés, puis sélectionnez-en un pour ouvrir sa vue de progression.

/workflows

La vue de progression affiche chaque phase avec ses nombres d'agents, ses totaux de tokens et son temps écoulé. Le pied de page liste la clé pour chaque action :

Faire écrire un workflow par Claude

Vous pouvez faire écrire un workflow par Claude pour votre tâche de deux façons :

• Demander un workflow dans votre prompt avec vos propres mots ou en incluant le mot clé ultracode, et Claude en écrit un pour la tâche.
• Laisser Claude décider avec ultracode : définissez /effort ultracode et Claude planifie un workflow pour chaque tâche substantielle de la session.

Vous pouvez également exécuter une commande de workflow qui existe déjà : un workflow groupé comme /deep-research, ou un que vous avez enregistré.

Demander un workflow dans votre prompt

Pour exécuter une seule tâche en tant que workflow sans modifier le niveau d'effort de la session, incluez le mot clé ultracode dans votre prompt. Demander avec vos propres mots, par exemple « utiliser un workflow » ou « exécuter un workflow », fonctionne également : Claude traite une demande directe comme le même opt-in. Avant la v2.1.160, le mot clé déclencheur littéral était workflow ; les demandes en langage naturel fonctionnent dans les deux versions.

ultracode: audit every API endpoint under src/routes/ for missing auth checks

Claude Code met en évidence le mot clé dans votre saisie et Claude écrit un script de workflow pour la tâche au lieu de la traiter tour par tour. Si vous ne vouliez pas démarrer un workflow, appuyez sur Option+W sur macOS ou Alt+W sur Windows et Linux pour ignorer la mise en évidence pour ce prompt, ou appuyez sur retour arrière tandis que le curseur se trouve juste après le mot clé en évidence. Pour empêcher le mot clé de déclencher quoi que ce soit, désactivez le déclencheur de mot clé Ultracode dans /config.

Si l'exécution fait ce que vous vouliez, vous pouvez l'enregistrer comme commande après.

Si vous avez déjà un orchestrateur construit d'une autre façon, comme un dossier de prompts de sous-agents ou une compétence qui distribue le travail, vous pouvez pointer Claude vers celui-ci et demander un workflow qui fait la même chose.

Laisser Claude décider avec ultracode

Ultracode est un paramètre Claude Code qui combine l'effort de raisonnement xhigh avec l'orchestration automatique des workflows. Avec lui activé, Claude planifie un workflow pour chaque tâche substantielle au lieu d'attendre que vous le demandiez.

/effort ultracode

Avec ultracode activé, Claude décide quand une tâche justifie un workflow. Une seule demande peut se transformer en plusieurs workflows d'affilée : un pour comprendre le code, un pour faire le changement, et un pour le vérifier. Cela s'applique à chaque tâche de la session, donc chaque demande utilise plus de tokens et prend plus de temps qu'aux niveaux d'effort inférieurs.

Ultracode dure pour la session actuelle et se réinitialise quand vous en commencez une nouvelle. Revenez avec /effort high quand vous retournez au travail de routine. Il est disponible sur les modèles qui supportent l'effort xhigh ; sur les autres modèles, le menu /effort ne l'offre pas.

Approuver le plan avant qu'il s'exécute

Dans le CLI, l'invite par exécution affiche les phases planifiées et ces options :

• Oui, l'exécuter : démarrer l'exécution
• Oui, et ne pas demander à nouveau pour <name> dans <path> : démarrer, et ignorer cette invite pour ce workflow dans ce projet à partir de maintenant
• Afficher le script brut : lire le script avant de décider
• Non : annuler

Ctrl+G ouvre le script dans votre éditeur. Tab vous permet d'ajuster le prompt avant le démarrage de l'exécution.

Que vous voyiez cette invite dépend de votre mode de permission :

Dans l'application Desktop, une carte d'approbation affiche le nom du workflow, la liste des phases et une mise en garde sur l'utilisation des tokens, avec les actions Une fois, Toujours et Refuser. La vue de progression apparaît dans le volet des tâches en arrière-plan.

Votre mode de permission contrôle uniquement l'invite de lancement ci-dessus. Les sous-agents que le workflow génère s'exécutent toujours en mode acceptEdits et héritent de votre liste d'autorisation d'outils, quel que soit le mode de votre session. Les modifications de fichiers sont approuvées automatiquement.

Les commandes shell, les récupérations web et les outils MCP qui ne sont pas dans votre liste d'autorisation peuvent toujours vous inviter pendant l'exécution. Pour éviter cela lors d'une exécution longue, ajoutez les commandes dont les agents ont besoin à votre liste d'autorisation avant de commencer.

Dans claude -p et l'Agent SDK, il n'y a personne pour inviter, donc les appels d'outils suivent vos règles de permission configurées sans confirmation interactive.

Enregistrer le workflow pour réutilisation

Quand Claude écrit un workflow pour une tâche que vous répéterez, vous pouvez enregistrer le script de cette exécution comme commande. Un processus comme une revue que vous exécutez sur chaque branche exécute ensuite la même orchestration à chaque fois.

Exécutez /workflows, sélectionnez l'exécution que vous voulez conserver, et appuyez sur s. Dans la boîte de dialogue d'enregistrement, Tab bascule entre les deux emplacements d'enregistrement :

• .claude/workflows/ dans votre projet : partagé avec tous ceux qui clonent le repo
• ~/.claude/workflows/ dans votre répertoire personnel : disponible dans chaque projet, visible uniquement pour vous

Appuyez sur Entrée pour enregistrer. Le workflow s'exécute comme /<name> dans les futures sessions à partir de l'un ou l'autre emplacement.

{/* min-version: 2.1.178 */}À partir de la v2.1.178, l'enregistrement à l'emplacement du projet écrit dans le répertoire .claude/workflows/ le plus proche qui existe déjà entre votre répertoire de travail et la racine du référentiel, ou à la racine du référentiel s'il n'en existe pas encore. Les workflows de projet se chargent également à partir de chaque .claude/workflows/ le long de ce chemin, et quand plus d'un définit le même nom, Claude Code exécute celui le plus proche du répertoire de travail.

Si un workflow de projet et un workflow personnel partagent un nom, celui du projet s'exécute.

Passer une entrée à un workflow enregistré

Un workflow enregistré peut accepter une entrée via le paramètre args. Le script la lit comme une variable globale nommée args. Utilisez ceci pour fournir une question de recherche, une liste de chemins cibles, ou un objet de configuration au moment de l'invocation au lieu de modifier le script pour chaque exécution.

L'invite suivante exécute un workflow enregistré avec une liste de numéros de problème :

> Run /triage-issues on issues 1024, 1025, and 1030

Claude passe la liste en tant que données structurées, donc le script peut appeler les méthodes de tableau et d'objet sur args directement sans l'analyser d'abord. Si args est omis, la variable globale est undefined à l'intérieur du script.

Comment un workflow s'exécute

Le runtime du workflow exécute le script dans un environnement isolé, séparé de votre conversation. Les résultats intermédiaires restent dans les variables du script au lieu d'atterrir dans le contexte de Claude.

Chaque exécution écrit son script dans un fichier sous le répertoire de votre session dans ~/.claude/projects/. Claude reçoit le chemin au démarrage de l'exécution, vous pouvez donc le demander. Vous pouvez ouvrir ce fichier pour lire l'orchestration que Claude a écrite, la comparer avec le script d'une exécution précédente, ou l'éditer et demander à Claude de relancer à partir de la version éditée.

Le runtime suit le résultat de chaque agent au fur et à mesure que l'exécution progresse, ce qui rend une exécution reprendre possible dans la même session.

Comportement et limites

Le runtime applique les contraintes suivantes :

Gérer les exécutions

Une fois qu'une exécution commence, vous la gérez à partir de la vue /workflows, ou en agrandissant sa ligne de progression dans le panneau des tâches sous la zone de saisie.

Reprendre après une pause

Si vous arrêtez une exécution, vous pouvez la reprendre : les agents qui ont déjà terminé retournent leurs résultats en cache, et le reste s'exécute en direct. Reprenez une exécution en pause à partir de /workflows en la sélectionnant et en appuyant sur p, ou demandez à Claude de relancer le workflow avec le même script.

La reprise fonctionne dans la même session Claude Code. Si vous quittez Claude Code pendant qu'un workflow s'exécute, la session suivante démarre le workflow à nouveau.

Coût

Un workflow génère de nombreux agents, donc une seule exécution peut utiliser significativement plus de tokens que de travailler à travers la même tâche en conversation. Les exécutions comptent vers l'utilisation de votre plan et les limites de débit comme toute autre session.

Pour évaluer les dépenses avant de vous engager dans une tâche importante, exécutez d'abord le workflow sur un petit échantillon : un répertoire au lieu de l'ensemble du dépôt, ou une question étroite au lieu d'une question large. La vue /workflows affiche l'utilisation des tokens de chaque agent au fur et à mesure que l'exécution progresse, et vous pouvez arrêter l'exécution à tout moment sans perdre le travail terminé. Les limites de comportement du runtime limitent le nombre d'agents qu'une seule exécution peut générer, ce qui limite le coût d'un script qui s'échappe.

Chaque agent dans un workflow utilise le modèle de votre session sauf si le script achemine une étape vers un autre. Pour contrôler le coût du modèle :

• Vérifiez /model avant une exécution importante si vous basculez généralement vers un modèle plus petit pour le travail de routine
• Demandez à Claude d'utiliser un modèle plus petit pour les étapes qui n'ont pas besoin du plus fort quand vous décrivez la tâche

Désactiver les workflows

Les workflows sont disponibles dans le CLI, l'application Desktop, les extensions IDE, le mode non-interactif avec claude -p, et l'Agent SDK. Les mêmes paramètres de désactivation s'appliquent sur chaque surface.

Pour désactiver les workflows pour vous-même :

• Basculez Dynamic workflows off dans /config. Persiste entre les sessions.
• Définissez "disableWorkflows": true dans ~/.claude/settings.json. Persiste entre les sessions.
• Définissez CLAUDE_CODE_DISABLE_WORKFLOWS=1. Lire au démarrage, donc cela s'applique partout où vous le définissez.

Pour désactiver les workflows pour toute votre organisation, définissez "disableWorkflows": true dans les paramètres gérés, ou utilisez le bouton bascule sur la page des paramètres d'administration Claude Code.

Quand les workflows sont désactivés, les commandes de workflow groupées ne sont pas disponibles, le mot-clé ultracode ne déclenche plus une exécution, et ultracode est supprimé du menu /effort.

Ressources connexes

• Exécuter les agents en parallèle : comparer les sous-agents, la vue des agents, les équipes d'agents et les workflows
• Créer des sous-agents personnalisés : la primitive worker que les workflows orchestrent
• Gérer les coûts : comment les exécutions multi-agents comptent vers les limites d'utilisation