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

Les workflows dynamiques sont disponibles sur tous les plans payants, avec accès à l’API Anthropic, et sur Amazon Bedrock, Google Cloud’s Agent Platform et Microsoft Foundry. Sur Pro, activez-les à partir de la ligne Dynamic workflows dans /config.

Un workflow dynamique est un script JavaScript qui orchestre de nombreux sous-agents à la fois. 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.

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 :

	Sous-agents	Skills	Équipes d’agents	Workflows
Ce que c’est	Un worker Claude génère	Des instructions que Claude suit	Un agent principal supervisant des sessions entre pairs	Un script que le runtime exécute
Qui décide ce qui s’exécute ensuite	Claude, tour par tour	Claude, en suivant le prompt	L’agent principal, tour par tour	Le script
Où vivent les résultats intermédiaires	La fenêtre de contexte de Claude	La fenêtre de contexte de Claude	Une liste de tâches partagée	Les variables du script
Ce qui est répétable	La définition du worker	Les instructions	La définition de l’équipe	L’orchestration elle-même
Échelle	Quelques tâches déléguées par tour	Identique aux sous-agents	Une poignée de pairs s’exécutant longtemps	Des dizaines à des centaines d’agents par exécution
Interruption	Redémarre le tour	Redémarre le tour	Les coéquipiers continuent de s’exécuter	Reprendre dans la même session

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 intégré

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 étudier une question à travers de nombreuses sources. Vous verrez des agents progresser à travers une série de phases en arrière-plan pendant que votre session reste disponible, et vous obtiendrez un rapport unique à la fin au lieu d’une transcription tour par tour.

Exécuter le workflow

Exécutez /deep-research avec une question que vous souhaitez étudier. Il lance des recherches web en parallèle sous plusieurs angles, récupère et recoupe les sources qu’il trouve, puis synthétise un rapport avec citations.

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

Autoriser les workflows

Claude Code vous demande s’il faut autoriser le workflow. Sélectionnez Yes pour continuer. La demande exacte dépend de votre mode de permission. Consultez Approuver le plan avant son exécution pour les options propres à chaque mode.

Suivre la progression

L’exécution démarre en arrière-plan. Exécutez /workflows pour ouvrir sa vue de progression :

/workflows

Si /workflows affiche plutôt une liste d’exécutions, sélectionnez celle que vous venez de lancer et appuyez sur Enter. La vue affiche chaque phase avec son nombre d’agents. Explorez n’importe quelle phase pour voir ses agents et ce que chacun a trouvé. Consultez Suivre l’exécution pour l’ensemble des commandes.Vous pouvez également suivre l’exécution depuis le panneau des tâches situé sous la zone de saisie : un résumé de progression d’une ligne y apparaît pendant l’exécution. Appuyez sur la flèche vers le bas pour lui donner le focus, puis sur Enter pour le développer.

Lire le rapport

Une fois l’exécution terminée, le rapport apparaît dans votre session. Il cite les sources dont provient chaque affirmation, les affirmations qui n’ont pas résisté au recoupement étant déjà filtrées.Lorsque les agents vérificateurs ne peuvent pas vérifier une affirmation, par exemple après une limite de débit ou une erreur de l’API, le rapport indique cette affirmation comme non vérifiée au lieu de la compter comme réfutée.

Pour exécuter un workflow pour votre propre tâche, demandez à Claude d’en écrire un, et une fois qu’une exécution fait ce que vous vouliez, vous pouvez l’enregistrer comme votre propre commande.

Workflows intégrés

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

Commande	Ce qu’elle fait
`/deep-research <question>`	Lance des recherches web en parallèle sur une question sous plusieurs angles, récupère et recoupe les sources trouvées, vote sur chaque affirmation et renvoie un rapport avec citations, les affirmations qui n’ont pas résisté au recoupement étant filtrées. Nécessite que l’outil WebSearch soit disponible

/deep-research ne s’exécute que lorsque vous l’invoquez. 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.

Suivre l’exécution

Les workflows s’exécutent en arrière-plan, de sorte que la session reste réactive pendant que les agents travaillent. Exécutez /workflows à tout moment pour lister les workflows en cours et terminés, puis sélectionnez-en un pour ouvrir sa vue de progression. Lorsque la session ne comporte qu’une seule exécution, /workflows ignore la liste et ouvre directement cette exécution. Pour arrêter un workflow en cours depuis la liste sans l’ouvrir, sélectionnez-le et appuyez sur x. La vue de progression affiche chaque phase avec son nombre d’agents. Le pied de page indique la touche associée à chaque action :

Touche	Action
`↑` / `↓`	Sélectionner une phase ou un agent
`Enter` ou `→`	Explorer la phase sélectionnée, puis le détail d’un agent. Dans le détail, `Enter` le développe ou le réduit
`Esc` ou `←`	Remonter d’un niveau
`j` / `k`	Faire défiler le détail de l’agent lorsqu’il déborde
`f`	Filtrer la liste des agents de la phase sélectionnée par statut. Appuyez à nouveau pour passer d’un filtre à l’autre
`p`	Mettre en pause ou reprendre l’exécution
`x`	Arrêter l’agent sélectionné, ou arrêter tout le workflow lorsque le focus est sur l’exécution
`r`	Redémarrer l’agent en cours sélectionné
`s`	Enregistrer le script de l’exécution comme commande

Le détail de l’agent présente le prompt de l’agent, ses appels d’outils récents et son résultat. Chaque appel indique son état, par exemple toujours en cours ou en échec. Lorsque l’agent tient sa propre liste de tâches, le détail l’affiche également, avec le statut de chaque tâche. Appuyez sur Enter pour développer le détail. Le prompt et le résultat s’affichent alors en entier, et chaque appel listé affiche son entrée et le début de son résultat.

Demander à Claude d’écrire un workflow

Vous pouvez demander à Claude d’écrire un workflow pour votre tâche de deux façons :

Demander un workflow dans votre prompt, soit avec vos propres mots, soit 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 intégré comme /deep-research, ou un workflow que vous avez enregistré.

Demander un workflow dans votre prompt

Pour exécuter une seule tâche sous forme de workflow sans modifier le niveau d’effort de la session, incluez le mot-clé ultracode dans votre prompt. Le demander avec vos propres mots, par exemple « use a workflow » ou « run a workflow », fonctionne également : Claude traite une demande directe comme le même consentement explicite.

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

Claude Code met en surbrillance 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. Le mot-clé détermine uniquement la façon dont Claude structure le travail : les appels d’outils des agents sont soumis aux mêmes vérifications de permission et au même sandboxing que tout autre appel d’outil de la session. Si l’exécution fait ce que vous souhaitiez, vous pouvez ensuite l’enregistrer en tant que commande. Si vous disposez déjà d’un orchestrateur construit autrement, comme un dossier de prompts de sous-agents ou un skill qui répartit le travail, vous pouvez le montrer à Claude et lui demander un workflow qui fait la même chose.

Ignorer ou désactiver le mot-clé

Si vous n’aviez pas l’intention de lancer un workflow, appuyez sur Option+W sous macOS ou Alt+W sous Windows et Linux pour ignorer la surbrillance pour ce prompt, ou appuyez sur retour arrière lorsque le curseur se trouve juste après le mot-clé en surbrillance. Pour empêcher complètement le mot-clé de se déclencher, désactivez Ultracode keyword trigger dans /config.

Où le mot-clé fonctionne

Le mot-clé ne vaut consentement explicite que dans un prompt que vous saisissez vous-même : dans le prompt interactif, dans le panneau d’une extension IDE, dans un client Remote Control, ou dans une application Agent SDK qui marque l’origin de votre saisie clavier comme { kind: "human" }. Il ne lance pas de workflow lorsqu’il parvient à la session d’une autre manière :

un prompt transmis avec -p
un prompt qu’une application Agent SDK envoie sans le marquer comme saisie humaine
le prompt d’une tâche planifiée
un payload de webhook ou un commentaire de pull request relayé dans la conversation

Laisser Claude décider avec ultracode

Ultracode est un paramètre de Claude Code qui active l’orchestration automatique de workflows pour la session, quel que soit le niveau d’effort de la session. Lorsqu’il est activé, Claude planifie un workflow pour chaque tâche substantielle au lieu d’attendre que vous le demandiez. Activez-le dans le prompt de Claude Code :

/effort ultracode

Pour démarrer une session avec ultracode déjà activé, lancez claude --effort ultracode, ce qui définit également le niveau d’effort sur xhigh. Pour l’activer depuis le curseur /effort, appuyez sur Tab pour basculer l’option Ultracode, puis sur Enter pour l’appliquer. Ajuster le niveau d’effort répertorie les moyens d’activer ultracode. Lorsqu’ultracode est activé, Claude décide quand une tâche justifie un workflow. Une seule demande peut se transformer en plusieurs workflows successifs : un pour comprendre le code, un pour effectuer la modification et un pour la vérifier. Cela s’applique à chaque tâche de la session, de sorte que chaque demande consomme plus de tokens et prend plus de temps que la même demande sans workflow. Avec un abonnement, ces tokens sont décomptés de vos limites d’utilisation, de sorte qu’une session avec ultracode activé atteint une limite de session ou hebdomadaire plus tôt que le même travail sans ultracode. Activer ultracode revient déjà à accepter des exécutions volumineuses, c’est pourquoi ces vérifications ne s’appliquent pas tant qu’il est activé :

L’avertissement Large workflow n’apparaît pas lors de l’exécution d’un workflow
La limite de sous-agents simultanés de la session n’est pas appliquée aux sous-agents que Claude lance avec l’outil Agent
En mode de permission auto, il ne vous est pas demandé d’approuver le premier lancement de workflow

/effort ultracode dure le temps de la session en cours ; pour que chaque session démarre avec, définissez le paramètre ultracode. Désactivez-le avec /effort ultracode off lorsque vous revenez à un travail courant. Le curseur /effort ne propose l’option que lorsqu’ultracode est disponible. Avant la v2.1.284, /effort ultracode définissait la session sur xhigh, et /effort ultracode off échouait avec Invalid argument.

Approuver le plan avant son exécution

Dans la CLI, la demande affichée pour chaque exécution présente les phases planifiées et les options suivantes :

Yes, run it : démarrer l’exécution
Yes, and don’t ask again for <name> in <path> : démarrer, et ne plus afficher cette demande pour ce workflow dans ce projet à l’avenir. Claude Code propose cette option lorsque vous exécutez par son nom un workflow intégré, enregistré ou issu d’un plugin, mais pas pour un script que Claude a écrit pour la tâche en cours.
View raw script : lire le script avant de décider
No : annuler

Ctrl+G ouvre le script dans votre éditeur. Lorsque Yes, run it ou No est sélectionné, appuyez sur Tab pour ajouter un commentaire à votre réponse. L’affichage de cette demande dépend de votre mode de permission :

Mode de permission	Quand la demande s’affiche
Auto	Premier lancement uniquement. Tout Yes enregistre votre consentement dans vos paramètres utilisateur, et les lancements suivants démarrent sans demande. Entièrement ignorée lorsqu’ultracode est activé
Manuel, acceptation des modifications	À chaque exécution, sauf si vous avez sélectionné Yes, and don’t ask again pour ce workflow dans ce projet
Contournement des permissions	Claude Code ne vous demande rien. L’exécution démarre immédiatement
`claude -p`, Agent SDK	Claude Code ne vous demande rien

Dans claude -p et l’Agent SDK, Claude Code n’affiche jamais cette demande. Il soumet l’appel de l’outil Workflow à la même évaluation des permissions que le reste de la session, de sorte que les règles de refus, les règles de demande et le mode dontAsk s’appliquent au lancement comme à tout appel d’outil. Pour permettre au workflow de démarrer dans ces exécutions, utilisez l’une des options suivantes :

Règle de permission : ajoutez Workflow à vos règles d’autorisation pour approuver tous les workflows, ou Workflow(<name>) pour approuver un workflow enregistré par son nom.
Mode de permission auto : exécutez en mode auto, où le classifieur examine l’appel et peut l’approuver.
Mode de contournement des permissions : exécutez en mode de contournement des permissions.
Un hook : renvoyez "allow" pour l’appel depuis un hook PreToolUse. En mode plan, le workflow ne démarre pas sur la seule approbation du hook ; utilisez plutôt une règle de permission ou l’approbation de votre hôte dans ce cas.
Votre hôte : un --permission-prompt-tool ou, avec l’Agent SDK, un callback canUseTool l’approuve.

Dans l’application Desktop, une carte d’approbation affiche le nom du workflow, la liste des phases et un avertissement sur la consommation de tokens, avec les actions Once, Always et Deny. La vue de progression apparaît dans le panneau latéral des tâches en arrière-plan. Les sous-agents lancés par le workflow utilisent vos règles de permission, et Claude Code choisit leur mode de permission selon les règles décrites dans quel mode de permission utilise un sous-agent. Pour éviter les demandes lors d’une longue exécution, ajoutez les outils dont les agents ont besoin à vos règles d’autorisation avant de démarrer.

Enregistrer le workflow pour le réutiliser

Lorsque Claude écrit un workflow pour une tâche que vous allez répéter, vous pouvez enregistrer le script de cette exécution en tant que commande. Un processus comme une revue que vous effectuez sur chaque branche exécute alors la même orchestration à chaque fois. Exécutez /workflows, sélectionnez l’exécution que vous souhaitez 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 toutes les personnes qui clonent le dépôt
~/.claude/workflows/ dans votre répertoire personnel : disponible dans tous les projets, visible uniquement par vous. Si vous définissez CLAUDE_CONFIG_DIR, cet emplacement est le répertoire workflows/ sous ce chemin.

La boîte de dialogue d’enregistrement affiche le chemin résolu pour l’emplacement personnel. Appuyez sur Enter pour enregistrer. Le workflow s’exécute en tant que /<name> dans les sessions futures, quel que soit l’emplacement. Claude Code vérifie la présence de liens symboliques dans l’emplacement d’enregistrement avant d’écrire, et affiche une erreur au lieu d’écrire à travers l’un d’eux :

Emplacement du projet : Claude Code refuse si .claude, .claude/workflows ou le fichier cible est un lien symbolique.
Emplacement personnel : Claude Code refuse uniquement si le fichier cible lui-même est un lien symbolique, de sorte qu’un répertoire ~/.claude géré par un outil de dotfiles fonctionne toujours.

Dans un monorepo comportant plusieurs répertoires .claude/, vous pouvez conserver les workflows à côté du package auquel ils s’appliquent. L’enregistrement dans l’emplacement du projet écrit dans le répertoire .claude/workflows/ existant le plus proche entre votre répertoire de travail et la racine du dépôt, ou à la racine du dépôt s’il n’en existe encore aucun. Les workflows de projet sont également chargés depuis chaque .claude/workflows/ situé sur ce chemin, et lorsque plusieurs définissent le même nom, Claude Code exécute celui qui est le plus proche du répertoire de travail. Si un workflow de projet et un workflow personnel portent le même nom, c’est celui du projet qui s’exécute.

Distribuer un workflow dans un plugin

Pour partager un workflow entre plusieurs équipes ou dépôts, incluez-le dans un plugin. Placez le script dans un répertoire workflows/ à la racine du plugin, ou indiquez un autre emplacement avec le champ de manifeste workflows. Les workflows de plugin sont préfixés par le nom du plugin. Un plugin nommé acme-tools contenant un script dont le meta.name est release-audit s’exécute en tant que /acme-tools:release-audit.

Transmettre des données d’entrée à un workflow enregistré

Un workflow enregistré peut accepter des données d’entrée via le paramètre args. Le script les lit sous forme d’une variable globale nommée args. Utilisez-le 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 à chaque exécution. Le prompt suivant exécute un workflow enregistré avec une liste de numéros d’issues :

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

Claude transmet la liste sous forme de données structurées, de sorte que le script peut appeler directement des méthodes de tableau et d’objet sur args sans avoir à l’analyser au préalable. Si args est omis, la variable globale vaut undefined dans le script.

Exemples de prompts de workflow

Un workflow convient mieux quand la tâche est plus grande qu’un agent ne peut la tenir en contexte, ou quand la même étape doit s’exécuter sur de nombreux éléments. Les prompts ci-dessous montrent des formes courantes. Chacun demande à Claude d’écrire et d’exécuter un workflow pour cette tâche ; vous n’écrivez pas le script vous-même.

Auditer de nombreux fichiers pour le même problème

Distribuez un agent par fichier, puis collectez et vérifiez les conclusions.

use a workflow to audit every route handler under src/routes/ for missing authentication checks, and adversarially verify each finding before reporting it

Continuer à corriger jusqu’à ce qu’une vérification réussisse

Exécutez un vérificateur, corrigez ce qui a échoué, et répétez jusqu’à ce qu’il réussisse ou cesse de faire des progrès.

use a workflow to run npx tsc --noEmit and keep fixing the reported errors until the type check passes or two rounds in a row make no progress

Migrer de nombreux fichiers en parallèle

Découvrez les fichiers à migrer, transformez chacun dans une copie isolée afin que les modifications ne se chevauchent pas, et vérifiez chaque résultat.

use a workflow to migrate every component under src/components/ from JavaScript to TypeScript, working on each file in its own isolated copy

Examiner chaque fichier modifié et écrire un résumé

Exécutez un examinateur par fichier, puis remettez toutes les conclusions à un agent qui les classe et les déduplique.

use a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summary

Rechercher un sujet à travers de nombreuses sources

Distribuez les lecteurs sur les journaux des modifications, les problèmes et la documentation, puis synthétisez. Le workflow groupé /deep-research fait cela ; vous pouvez également décrire une version plus étroite.

use a workflow to research how our three competitors handle rate limiting: read their public docs and recent changelog entries in parallel, then compare the approaches

Trouver des problèmes jusqu’à ce que la liste cesse de croître

Continuez à chercher par rounds et arrêtez-vous quand les nouveaux rounds ne trouvent rien de nouveau.

use a workflow to find flaky tests in this repo: run the suite repeatedly, record which tests fail intermittently, and stop once two rounds in a row find nothing new

À quoi ressemble le script enregistré

Quand vous enregistrez un workflow, le fichier dans .claude/workflows/ contient un bloc meta suivi d’un corps de script qui orchestre les sous-agents. Vous n’avez généralement pas besoin de l’éditer, mais voici la forme d’un petit pour que vous puissiez reconnaître ce que Claude a généré :

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

Le corps est du JavaScript simple avec await au niveau supérieur. agent() génère un sous-agent, pipeline() en exécute un par élément dans une liste, et parallel() exécute un ensemble de tâches d’agent en même temps et attend que toutes se terminent. Un appel agent() se résout en null si vous l’arrêtez en cours d’exécution ou s’il rencontre une erreur API irrécupérable. pipeline() conserve chaque null dans le tableau des résultats, c’est pourquoi l’exemple se termine par .filter(Boolean) pour supprimer ces entrées, y compris l’emplacement d’un agent qui s’est bloqué à chaque tentative. En mode auto, le prompt que votre script transmet à agent() ne compte pas comme une demande de votre part quand le classificateur examine les actions de ce sous-agent, car Claude Code le marque comme du texte que le script a calculé. Si vous passez un schema sur un appel agent(), ce sous-agent retourne du JSON correspondant à la forme au lieu de prose. Claude Code vérifie le schéma avant de démarrer le sous-agent : quand il peut prouver que le schéma se contredit lui-même, l’appel échoue avec une erreur nommant la contradiction, et le sous-agent ne démarre jamais. Une contradiction qu’il peut prouver est une clé required que additionalProperties: false exclut. Si la sortie du sous-agent échoue toujours la validation après cinq tentatives, l’appel échoue avec une erreur qui inclut l’échec de validation le plus récent. Pour modifier le nombre de tentatives, définissez MAX_STRUCTURED_OUTPUT_RETRIES.

Éditer un script enregistré

Pour modifier un workflow que vous avez enregistré, éditez son fichier .js ou demandez à Claude de faire le changement. Avant d’éditer ou de demander, exécutez la compétence groupée /workflow-authoring pour charger la référence de rédaction de script sur laquelle Claude travaille. La compétence nécessite Claude Code v2.1.248 ou ultérieur. Pour exécuter la version éditée dans la session actuelle, exécutez /reload-skills pour relire les répertoires de workflow, puis exécutez /<name> à nouveau. Claude Code applique ces règles à chaque partie du fichier quand il charge et exécute le script :

Bloc meta : gardez export const meta comme première instruction, et gardez-le un objet littéral simple avec un name et une description. S’il contient autre chose que des valeurs littérales, comme une variable, un appel de fonction ou une propagation, Claude Code supprime /<name> de l’autocomplétion /.
Corps : en plus de agent(), pipeline() et parallel(), vous pouvez appeler phase() pour regrouper les agents qui suivent sous un titre dans la vue de progression, appeler log() pour afficher un message au-dessus des phases, et lire le global args. Si le corps a une erreur de syntaxe, Claude Code la signale quand vous exécutez le workflow.
phases : si vous les listez dans meta, donnez à chaque entrée exactement le titre que vous passez à phase(). Un titre phase() sans entrée obtient son propre groupe de progression.
Horodatages et aléatoire : Claude Code fait en sorte que Date.now(), Math.random() et un new Date() sans argument lèvent une exception à l’intérieur du script, afin qu’une exécution relancée répète les mêmes appels agent(). Passez plutôt un horodatage via args.

Vous pouvez également éditer le script d’une seule exécution plutôt que la copie enregistrée. Reprendre après une pause couvre les agents qui s’exécutent à nouveau quand vous relancez un script édité. Pour les entrées de l’outil Workflow, consultez son entrée dans la référence Agent SDK.

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. Sauf si Claude démarre une exécution à partir du chemin d’un fichier de script, Claude Code écrit le script de l’exécution dans un fichier sous le répertoire de votre session dans ~/.claude/projects/. Claude reçoit le chemin du script 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, en faire un diff avec le script d’une exécution précédente, ou l’éditer et demander à Claude de relancer à partir de la version éditée. Claude ne peut démarrer un workflow que à partir d’un fichier de script que la session est déjà autorisée à lire. Pour exécuter un script conservé en dehors de votre répertoire de travail, ajoutez d’abord son répertoire avec /add-dir ou une règle d’autorisation Read. 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.

Prompt caching dans un fan-out

Les agents dans la même exécution peuvent lire le prompt cache les uns des autres. Deux agents qui s’exécutent avec le même modèle, le même niveau d’effort, le même type d’agent, les mêmes outils, le même schéma de sortie et le même répertoire de travail construisent le même préfixe d’outils et de système-prompt, donc un agent qui démarre après que la réponse d’un frère correspondant a commencé lit le cache de ce frère à sa première requête. Les requêtes d’un agent de workflow se situent en dehors du bucket TTL du cache de la conversation principale, donc son cache se maintient pendant cinq minutes par défaut, y compris sur un abonnement Claude. Pour le conserver pendant une heure, définissez subagentPromptCacheTtl sur 1h. L’API facture les écritures de cache d’une heure à un taux plus élevé. Lorsqu’un fan-out démarre plusieurs agents correspondants à la fois, Claude Code maintient tous les agents sauf le premier jusqu’à ce que la réponse du premier agent commence, puis libère les agents maintenus ensemble afin que leurs premières requêtes lisent le préfixe partagé au lieu que chacun le traite sans cache. Claude Code plafonne la retenue à CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS millisecondes, 5000 par défaut. Définissez-le sur 0 pour désactiver la retenue.

Comportement et limites

Le runtime applique les contraintes suivantes :

Contrainte	Pourquoi
Pas d’entrée utilisateur en cours d’exécution	Une exécution se met en pause uniquement pour les invites de permission d’agent et une attente de limite d’utilisation. Pour l’approbation entre les étapes, exécutez chaque étape comme son propre workflow
Pas d’accès direct au système de fichiers ou au shell à partir du workflow lui-même	Les agents lisent, écrivent et exécutent des commandes. Le script coordonne les agents
Pas de chargement de module : un script qui contient `import()` échoue avant le démarrage de l’exécution	Le corps du script est du JavaScript pur. Mettez le travail qui nécessite une bibliothèque dans la tâche d’un agent
Jusqu’à 16 agents concurrents par défaut, moins lorsque Claude Code dispose de moins de CPU disponibles, y compris à l’intérieur d’un conteneur limité en CPU. Pour modifier la limite, définissez `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` sur une valeur de 1 à 256, ce qui nécessite Claude Code v2.1.269 ou version ultérieure	Limite l’utilisation des ressources locales
Dans un fan-out, les agents qui partagent le préfixe du prompt-cache du premier agent démarrent jusqu’à 5 secondes après par défaut	Tous sauf le premier lisent le préfixe que le premier agent a mis en cache au lieu que chacun le traite sans cache
Jusqu’à 4 096 éléments dans un seul appel `parallel()` ou `pipeline()` : le runtime rejette une liste plus longue avec une erreur	Un plafond silencieux supprimerait une partie de la charge de travail sans le dire au script
1 000 agents au total par exécution	Empêche les boucles incontrôlées

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. Quand vous arrêtez une exécution, elle reste dans le panneau des tâches tant que l’un des processus de ses agents est toujours en cours d’exécution. Si vous l’arrêtez à nouveau, Claude Code renvoie à nouveau un signal à ces processus.

Reprendre après une pause

Reprenez une exécution en pause à partir de /workflows en la sélectionnant et en appuyant sur p. Pour une exécution que vous avez arrêtée, demandez à Claude de relancer le workflow avec le même script. Si les agents de l’exécution arrêtée n’ont pas encore quitté, Claude Code refuse le relancement jusqu’à ce qu’ils le fassent, afin qu’une deuxième copie de ces agents ne puisse pas s’exécuter à côté d’eux.

Quels agents s’exécutent à nouveau

Claude Code rejoue l’exécution dans l’ordre où les agents ont commencé, et chaque agent retourne soit son résultat sauvegardé, soit s’exécute à nouveau :

Terminé : retourne son résultat sauvegardé. Le premier agent dont l’invite diffère de l’exécution précédente, parce que vous avez modifié le script ou qu’un agent antérieur a retourné quelque chose de différent, s’exécute à nouveau, tout comme tous les agents après lui, même ceux qui ont terminé. Avant la v2.1.305, les agents terminés pouvaient également s’exécuter à nouveau quand vous relanciez un script non modifié dont les éléments pipeline() ou les tâches parallel() exécutaient chacun plus d’un agent. Pour éviter ces réexécutions lors des nouvelles exécutions, mettez à jour Claude Code.
Toujours en cours d’exécution quand vous avez arrêté : recommence. L’arrêt de l’ensemble de l’exécution ne compte aucun agent comme ayant échoué.
Échoué : s’exécute à nouveau, tout comme tous les agents que le script démarre après lui, même ceux qui ont terminé. L’arrêt d’un seul agent, en le sélectionnant dans /workflows et en appuyant sur x, compte comme un échec.

Ce dernier cas signifie qu’un échec au milieu d’une distribution réexécute le travail qui a déjà terminé. Si un script démarre A, B, C et D dans cet ordre et que B échoue, relancer retourne A du cache et exécute B, C et D à nouveau. Si vous modifiez un script qui démarrait A, B, C et D pour qu’il démarre A, C, B et D, le deuxième agent à démarrer est désormais C, là où l’exécution précédente démarrait B. Relancer retourne A du cache et exécute C, B et D à nouveau.

Reprendre après avoir quitté la session

Si vous mettez votre session en arrière-plan ou quittez Claude Code pendant qu’une exécution de workflow est en cours, l’exécution ne continue pas d’elle-même. L’exécution ne continue que lorsque Claude la relance avec un appel Workflow, qui rejoue l’exécution à partir de ses résultats sauvegardés.

Vous avez mis la session en arrière-plan ou choisi Move to background and exit : si l’exécution n’a pas continué lorsque vous consultez la session en arrière-plan, demandez à Claude, dans cette session, de relancer le workflow. Selon votre mode de permission, Claude Code vous demande d’abord d’approuver le relancement. Si la session apparaît sous Needs input dans la vue agent, attachez-vous à elle pour répondre à la demande d’approbation.
Le relancement dans la session en arrière-plan a échoué avec nothing to resume : demandez à Claude de démarrer le workflow à nouveau en tant que nouvelle exécution. Si Claude a démarré l’exécution à partir du chemin d’un fichier de script situé en dehors de ~/.claude/projects/, par exemple un fichier dans votre répertoire de travail, Claude ne peut pas le relancer dans la session en arrière-plan.
Vous avez choisi Exit and stop tasks, ou Move to background and exit ne vous a pas été proposé : l’exécution s’est arrêtée avec la session, et Claude Code conserve les résultats sauvegardés de l’exécution dans le répertoire de cette session dans ~/.claude/projects/. Reprenez la session avec claude --resume dans votre shell, puis demandez à Claude de relancer le workflow. Dans une nouvelle session, Claude n’a aucune exécution antérieure à relancer et démarre le workflow à nouveau.

Dans une session cloud, Claude Code sauvegarde également les résultats de l’exécution avec l’historique de conversation de la session, qui persiste quand la VM de la session est récupérée. Quand vous rouvrez une telle session et demandez à Claude de relancer le workflow, les agents terminés retournent toujours leurs résultats sauvegardés. Dans les sessions locales et cloud, quand Claude relance une exécution antérieure et que Claude Code ne peut pas trouver du tout les résultats sauvegardés de cette exécution, le relancement échoue avec une erreur nothing to resume au lieu de démarrer l’exécution à nouveau de son propre chef. Demandez à Claude de démarrer le workflow à nouveau en tant que nouvelle exécution.

Quand une exécution atteint votre limite d’utilisation

Quand un agent atteint votre limite d’utilisation claude.ai, l’exécution se met en pause plutôt que de faire échouer cet agent : les agents qui ont atteint la limite attendent la réinitialisation, et aucun nouvel agent ne démarre. Peu de temps après la réinitialisation de la limite, les agents en attente s’exécutent à nouveau et l’exécution continue d’elle-même. Nécessite Claude Code v2.1.271 ou ultérieur ; sur les versions antérieures, les agents affectés échouent. Pendant que l’exécution attend, sa ligne de progression dans le panneau des tâches et l’en-tête /workflows affichent quand la limite se réinitialise. L’exécution se met en pause uniquement quand tous ces éléments sont vrais ; quand l’un d’eux ne l’est pas, l’agent affecté échoue à la place :

La session est interactive et connectée avec un abonnement claude.ai. Une exécution ne se met pas en pause en mode non-interactif avec claude -p ou l’Agent SDK, dans une session en arrière-plan, ou dans une session coéquipier Remote Control ou équipe d’agents.
autoContinueAtUsageLimit est activé, le même paramètre qui permet à la session elle-même d’attendre la réinitialisation d’une limite d’utilisation. Si vous le désactivez pendant une attente, l’attente se termine et les agents en attente échouent.
La limite se réinitialise dans les 24 heures. Une limite hebdomadaire peut se réinitialiser plus loin.
L’exécution n’a pas déjà attendu deux fois. Quand elle atteint la limite une troisième fois, l’agent échoue.

Quand un agent se bloque et redémarre

Un agent dont la sortie cesse d’arriver suffisamment longtemps recommence à partir du même prompt. Dans /workflows, son nom reçoit un suffixe (retry 1) et son détail affiche attempt 2 (stalled). Le redémarrage est automatique, vous n’avez donc rien à faire. La nouvelle tentative démarre sans la transcription de la tentative bloquée. Les fichiers que la tentative bloquée a déjà modifiés restent modifiés, et les tokens qu’elle a consommés restent dans le total de l’exécution. La fenêtre de blocage est la durée pendant laquelle Claude Code attend une sortie d’un agent avant de mettre fin à la tentative. Le temps que l’agent passe à attendre ses propres appels d’outils ou une réinitialisation de la limite d’utilisation n’est pas compté dans la fenêtre de blocage. Un agent redémarre au maximum cinq fois, en comptant tout redémarrage que vous demandez avec r. Si la sixième tentative se bloque également, l’appel agent() échoue, et le début de l’erreur en indique la raison :

agent stalled on all 6 attempts : chaque tentative a passé toute la fenêtre sans sortie. Si le travail de l’agent le maintient silencieux aussi longtemps, allongez la fenêtre
agent lost its reply on all 6 attempts : le flux de réponse de chaque tentative est devenu silencieux et Claude Code a cessé de l’attendre. Allonger la fenêtre de blocage n’aide pas, car un watchdog d’inactivité du streaming a mis fin à la réponse en premier et CLAUDE_STREAM_IDLE_TIMEOUT_MS définit le délai d’expiration de ce watchdog
agent abandoned after 6 attempts : les tentatives se sont terminées de différentes manières, que l’erreur liste dans l’ordre

Pour donner à un agent plus de temps pour produire une sortie avant la fin de la fenêtre :

Un seul agent : passez stallMs en millisecondes dans son appel agent(), par exemple agent(prompt, { stallMs: 1800000 }) pour 30 minutes
Tous les agents : définissez CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS, qui s’applique également aux sous-agents en dehors des workflows

La poursuite de l’exécution après l’échec dépend de la façon dont votre script a appelé l’agent :

À l’intérieur de parallel() ou pipeline() : l’exécution continue avec null à la place du résultat de l’agent
Attendu directement : l’exécution se termine avec l’erreur

Pour réessayer, demandez à Claude de relancer le workflow. Reprendre après une pause explique ce qui s’exécute à 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. 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, généralement sans perdre le travail terminé. Reprendre après une pause couvre ce qu’une exécution arrêtée conserve. Les limites d’agents 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. Pour garder les exécutions à moins d’agents, choisissez la directive de taille small. Claude Code signale également une exécution qui devient anormalement grande. Quand un workflow planifie plus de 25 agents, ou que son total de tokens projeté dépasse 1,5 million, sa ligne de progression dans le panneau des tâches sous la zone de saisie affiche un avertissement Large workflow. L’avertissement vous dirige vers /workflows, où vous pouvez arrêter l’exécution. L’avertissement est consultatif : il ne met pas en pause ou ne limite pas l’exécution. Deux paramètres changent quand vous le voyez :

Si vous choisissez une directive de taille vous-même, le nombre d’agents de la directive remplace le seuil de 25 agents. La directive par défaut intégrée laisse le seuil à 25.
Les sessions avec ultracode activé n’affichent pas l’avertissement, car l’activation d’ultracode vous inscrit déjà aux exécutions importantes.

Claude Code choisit le modèle de chaque agent de workflow dans le même ordre qu’il utilise pour les sous-agents. Un modèle que le script nomme pour une étape compte comme le modèle par invocation dans cet ordre. Quand rien d’autre n’en assigne un, l’agent s’exécute sur le modèle de votre session. 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

Quand la liste d’autorisation availableModels de votre organisation bloque un modèle que le script demande pour un agent, cet agent s’exécute sur un modèle substitué à la place, en suivant les mêmes règles de substitution que les sous-agents.

Définir une directive de taille

Une directive de taille indique à Claude combien d’agents viser quand il écrit un workflow dynamique. Claude Code envoie la directive à Claude comme conseil, pas comme une limite, donc un prompt qui appelle une échelle différente la remplace toujours. Chaque valeur correspond à un nombre d’agents :

Valeur	Nombre d’agents que Claude vise
`unrestricted`	Aucune directive : Claude dimensionne le workflow à la tâche
`small`	Moins de 5 agents
`medium`	Moins de 10 agents
`large`	Moins de 50 agents

La valeur par défaut est medium, ou small quand vous êtes connecté sur un plan Pro avec Claude Code v2.1.271 ou ultérieur. Jusqu’à ce que vous choisissiez une valeur, la ligne /config affiche la valeur comme par défaut, et la ligne Running in background du workflow affiche la taille en vigueur. Pour modifier la directive, choisissez une valeur pour le paramètre Dynamic workflow size dans /config, ou exécutez /config workflowSizeGuideline=small. Vous pouvez également définir la clé workflowSizeGuideline dans n’importe quel fichier de paramètres ; cette valeur a la priorité sur /config, et Claude Code masque la ligne /config tandis qu’un fichier de paramètres en fournit une. Les modifications prennent effet à l’invite suivante. Les limites d’agents du runtime s’appliquent toujours indépendamment du paramètre.

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 :

/workflows, les commandes de workflow et le skill /workflow-authoring ne sont pas disponibles
Le mot-clé ultracode ne déclenche plus d’exécution, et le bouton bascule Ultracode est supprimé de /effort

Une exécution qui était déjà en cours continue. Désactiver les workflows rend également ultracode indisponible. Aucun paramètre géré n’exclut ultracode seul : partout où il est disponible, les utilisateurs peuvent l’activer avec /effort ultracode. Une limite d’effort abaisse le niveau d’effort qu’une session avec ultracode activé exécute, mais ne désactive pas ultracode.

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

​Quand utiliser un workflow

​Exécuter un workflow intégré

​Workflows intégrés

​Suivre l’exécution

​Demander à Claude d’écrire un workflow

​Demander un workflow dans votre prompt

​Ignorer ou désactiver le mot-clé

​Où le mot-clé fonctionne

​Laisser Claude décider avec ultracode

​Approuver le plan avant son exécution

​Enregistrer le workflow pour le réutiliser

​Distribuer un workflow dans un plugin

​Transmettre des données d’entrée à un workflow enregistré

​Exemples de prompts de workflow

​Auditer de nombreux fichiers pour le même problème

​Continuer à corriger jusqu’à ce qu’une vérification réussisse

​Migrer de nombreux fichiers en parallèle

​Examiner chaque fichier modifié et écrire un résumé

​Rechercher un sujet à travers de nombreuses sources

​Trouver des problèmes jusqu’à ce que la liste cesse de croître

​À quoi ressemble le script enregistré

​Éditer un script enregistré

​Comment un workflow s’exécute

​Prompt caching dans un fan-out

​Comportement et limites

​Gérer les exécutions

​Reprendre après une pause

​Quels agents s’exécutent à nouveau

​Reprendre après avoir quitté la session

​Quand une exécution atteint votre limite d’utilisation

​Quand un agent se bloque et redémarre

​Coût

​Définir une directive de taille

​Désactiver les workflows

​Ressources connexes

Quand utiliser un workflow

Exécuter un workflow intégré

Workflows intégrés

Suivre l’exécution

Demander à Claude d’écrire un workflow

Demander un workflow dans votre prompt

Ignorer ou désactiver le mot-clé

Où le mot-clé fonctionne

Laisser Claude décider avec ultracode

Approuver le plan avant son exécution

Enregistrer le workflow pour le réutiliser

Distribuer un workflow dans un plugin

Transmettre des données d’entrée à un workflow enregistré

Exemples de prompts de workflow

Auditer de nombreux fichiers pour le même problème

Continuer à corriger jusqu’à ce qu’une vérification réussisse

Migrer de nombreux fichiers en parallèle

Examiner chaque fichier modifié et écrire un résumé

Rechercher un sujet à travers de nombreuses sources

Trouver des problèmes jusqu’à ce que la liste cesse de croître

À quoi ressemble le script enregistré

Éditer un script enregistré

Comment un workflow s’exécute

Prompt caching dans un fan-out

Comportement et limites

Gérer les exécutions

Reprendre après une pause

Quels agents s’exécutent à nouveau

Reprendre après avoir quitté la session

Quand une exécution atteint votre limite d’utilisation

Quand un agent se bloque et redémarre

Coût

Définir une directive de taille

Désactiver les workflows

Ressources connexes