Orchestration multi-agents

Fan-out parallèle vs pipeline

Orchestrer plusieurs agents, c'est choisir une topologie. Les deux primitives :

• Parallèle (fan-out) : lancer N agents en même temps sur des tâches indépendantes, attendre tout le monde (une barrière), puis agréger. A utiliser quand vous avez besoin de tous les résultats ensemble (déduplication globale, compte total).
• Pipeline : chaque élément traverse toutes les étapes de façon indépendante, sans barrière entre les étapes. L'élément A peut être à l'étape 3 pendant que B est encore à l'étape 1. Le choix par défaut pour un travail multi-étapes : le temps total est celui de la chaîne la plus lente, pas la somme des plus lents par étape.

Le piège classique : poser une barrière (parallèle) là où un pipeline suffirait, juste parce que le code semble plus propre. Une barrière n'est justifiée que si l'étape N a besoin du résultat complet de l'étape N-1 (fusion, déduplication, arrêt précoce si zéro). Sinon, pipeline.

Application concrète chez Pierre : ses audits SEO multi-langues (Eskimoz en 4 langues) sont des fan-outs ; un agent par langue, agrégation à la fin. Sa règle de modèle s'applique : Haiku/Sonnet pour les agents de masse, Opus pour la synthèse.

Vérification adversariale et panels de juges

Un agent qui détecte des bugs ou des résultats produit des sorties plausibles mais fausses (hallucination, encore). Le correctif d'orchestration : faire vérifier chaque résultat par d'autres agents avant de le conserver.

Patterns de qualité :

• Vérification adversariale : pour chaque résultat, lancer N agents sceptiques dont la consigne est de le réfuter. Ne conserver le résultat que si la majorité échoue à le réfuter. Élimine les faux positifs plausibles.
• Vérification multi-perspectives : si un résultat peut échouer de plusieurs façons, donner à chaque vérificateur un angle différent (exactitude, sécurité, performance, reproductibilité) plutôt que N copies identiques.
• Panel de juges : générer N solutions indépendantes sous des angles différents, les noter avec des juges en parallèle, synthétiser à partir du gagnant en greffant les meilleures idées des autres.
• Boucle jusqu'au tarissement : pour une recherche de taille inconnue (bugs, cas limites), relancer les détecteurs jusqu'à ce que K tours consécutifs ne renvoient rien de nouveau.

Principe directeur : la confiance naît de perspectives indépendantes qui se contredisent, non d'un agent seul et sûr de lui. C'est exactement l'esprit du réflexe de Pierre "reproduire via Playwright avant de corriger" : vérifier avant de croire, appliqué à l'échelle des agents.

Workflows : orchestration déterministe

Quand l'orchestration devient complexe (boucles, conditions, fan-out, budgets), on passe d'un agent improvisant à un workflow : un script qui orchestre les sous-agents de façon déterministe. Le flux de contrôle (qui s'exécute, quand, en parallèle ou en série) est codé, pas décidé par le modèle.

Blocs de construction typiques d'un moteur de workflow :

• agent(prompt, schema) : lancer un sous-agent et obtenir une sortie structurée validée.
• pipeline(items, ...stages) : faire passer chaque élément par les étapes sans barrière.
• parallel(thunks) : une barrière, tout en même temps.
• Boucles : loop-until-count (accumuler jusqu'à N), loop-until-dry (jusqu'à épuisement), loop-until-budget (jusqu'à un quota de tokens).

L'avantage par rapport à un seul grand agent : la structure (décomposer et couvrir en parallèle), la confiance (vérifier avant de conclure) et l'échelle (migrations ou audits qu'un contexte unique ne pourrait pas contenir). Vous restez dans la boucle : vous lisez chaque résultat avant de décider l'étape suivante. C'est le niveau le plus avancé, à réserver aux tâches qui le justifient vraiment, car il consomme beaucoup de tokens.

Barriere ou sans barriere

Dans un pipeline multi-agents (une chaîne d'agents IA où chaque agent effectue une tâche précise), vous devez décider à chaque transfert : l'étape suivante doit-elle attendre tous les résultats précédents, ou peut-elle démarrer dès qu'un seul résultat est disponible ? Cette décision s'appelle placer une barrière (ou non).

Une barrière est un point de synchronisation. Aucun agent en aval de la barrière ne démarre tant que tous les agents en amont n'ont pas terminé. C'est le bon choix quand l'étape suivante a réellement besoin d'une vue complète avant de pouvoir agir. Un fonctionnement sans barrière (également appelé streaming ou fan-in sans attente) laisse les résultats s'écouler un par un au fur et à mesure de leur arrivée, de sorte que le travail en aval commence immédiatement.

Posez-vous une seule question : "L'étape suivante peut-elle produire un résultat correct avec seulement des données partielles ?" Si oui, supprimez la barrière. Si non, ajoutez-en une. Une erreur dans un sens comme dans l'autre a un coût : une barrière inutile sérialise ce qui pourrait s'exécuter en parallèle, gaspillant du temps ; une barrière manquante corrompt les résultats car les agents en aval agissent sur des informations incomplètes.

• Utilisez une barrière quand vous agrégez des scores, fusionnez des jeux de données, rédigez un résumé final, ou pour toute opération qui n'est pas définie sur un sous-ensemble.
• Pas de barrière nécessaire quand chaque résultat est utilisable indépendamment : traduction de documents, redimensionnement d'images, envoi de notifications individuelles, ou diffusion de réponses partielles à un utilisateur.
• Les barrières partielles sont également valides : attendez les N premiers résultats (un quorum), puis continuez en ignorant les retardataires.

Boucler jusqu'à épuisement

Certaines tâches ont une frontière inconnue : vous ne savez pas combien d'éléments existent avant d'avoir fini de les collecter. La pagination, les analyses récursives de répertoires et le parcours itératif du web partagent cette structure. Le bon patron est une boucle à sec : répéter un cycle de recherche ou de récupération, collecter les nouveaux résultats, et s'arrêter uniquement lorsqu'un cycle ne renvoie rien de nouveau.

Dans un contexte multi-agents (où plusieurs instances de Claude se transmettent du travail), l'agent orchestrateur exécute la boucle et confie chaque lot aux agents travailleurs. L'orchestrateur gère un ensemble déjà vu, une collection dédupliquée de tout ce qui a déjà été traité, et compare chaque nouveau cycle à cet ensemble. Lorsque l'ensemble cesse de croître, la boucle se termine.

Claude Code prend en charge ce patron grâce aux commandes shell enchaînées et aux appels de sous-agents. Une boucle minimale dans une tâche Claude Code ressemble à ceci :

1. Exécuter une recherche ou un appel API et capturer la sortie.
2. Comparer la sortie à l'ensemble déjà vu.
3. Si la différence est non vide, ajouter les nouveaux éléments à l'ensemble déjà vu, envoyer le travail, puis revenir à l'étape 1.
4. Si la différence est vide, s'arrêter et faire un compte rendu.

Deux protections sont obligatoires : un plafond de cycles (par exemple, 50 itérations) pour éviter les boucles infinies causées par des bugs ou des comportements imprévus de l'API, et des travailleurs idempotents (des travailleurs qui produisent le même résultat s'ils traitent accidentellement deux fois le même élément). Sans ces protections, une boucle à sec peut tourner indéfiniment ou corrompre les résultats.

Worktrees pour les agents parallèles

Lorsque vous exécutez plusieurs agents Claude Code simultanément, ils opèrent tous par défaut sur les mêmes fichiers du dépôt. Si deux agents modifient le même fichier en même temps, l'un écrasera le travail de l'autre. Les Git worktrees résolvent ce problème : un worktree est un répertoire de travail supplémentaire lié au même dépôt, extrait sur sa propre branche, de sorte que chaque agent dispose de fichiers isolés sans aucun chevauchement.

Vous créez un worktree avec git worktree add. Chaque worktree possède sa propre branche et sa propre copie des fichiers de travail sur le disque. Les agents s'exécutent dans des répertoires séparés et ne touchent jamais aux fichiers des autres. Une fois leur travail terminé, vous fusionnez les branches normalement.

Claude Code prend en charge ce schéma directement. La commande /worktrees (ainsi que le flag --worktree lors du lancement d'un sous-agent) indique à un agent dans quel chemin de worktree il doit opérer. L'agent orchestrateur crée les worktrees, en attribue un à chaque sous-agent, puis attend que tous aient terminé avant de fusionner.

• Aucune collision de fichiers : chaque agent n'écrit que dans son propre répertoire.
• Aucun conflit de branches : chaque worktree est sur sa propre branche.
• Point de fusion propre : l'orchestrateur fusionne toutes les branches après que les agents ont signalé leur complétion.
• Nettoyage facile : git worktree remove supprime le répertoire et le désenregistre.

Dispatcher des agents en parallèle

Quand une tâche peut être découpée en morceaux indépendants, les exécuter l'un après l'autre fait perdre du temps. Le fan-out consiste à lancer plusieurs agents (ou sous-processus) au même moment, chacun traitant une portion distincte du travail, puis à rassembler tous les résultats une fois qu'ils ont terminé. Claude Code supporte ce schéma grâce à l'outil Agent, qui permet à un agent orchestrateur de créer des agents enfants.

La règle essentielle est l'indépendance : les tâches que l'on distribue en fan-out ne doivent pas dépendre du résultat des autres. Si la tâche B a besoin que la tâche A soit terminée en premier, ces deux tâches doivent rester séquentielles. Les bons candidats au fan-out incluent : l'audit de fichiers distincts, la traduction d'un même contenu dans plusieurs langues, l'exécution d'un même prompt sur des jeux de données différents, ou la récupération de plusieurs URLs en parallèle.

Un workflow fan-out typique comporte trois étapes :

1. Décomposer : l'orchestrateur divise l'objectif en N sous-tâches indépendantes.
2. Dispatcher : il appelle l'outil Agent N fois, un appel par sous-tâche, sans attendre entre les appels.
3. Collecter : une fois que tous les agents ont répondu, l'orchestrateur fusionne ou résume les résultats.

Dans Claude Code, il est aussi possible de faire un fan-out au niveau du shell en utilisant --print (mode non interactif) et des processus en arrière-plan, puis de réunir les sorties. Cela fonctionne bien pour les tâches simples où vous contrôlez directement l'environnement shell.

Maîtriser le coût d'un fan-out à grande échelle

Un fan-out se produit quand un orchestrateur (l'agent coordinateur) lance plusieurs sous-agents en parallèle pour traiter différentes parties d'un problème simultanément. Chaque sous-agent consomme des tokens, donc le coût total d'un fan-out correspond à la somme des tokens en entrée et en sortie de chaque agent. Sans anticipation, les coûts s'envolent rapidement.

Le premier levier est la sélection du modèle par tâche. Chaque sous-agent n'a pas besoin du modèle le plus puissant. Réservez claude-opus-4-8 aux tâches qui exigent un raisonnement approfondi, comme les décisions d'architecture ou les analyses ambiguës. Utilisez claude-sonnet-4-6 pour les travaux de complexité moyenne, tels que la génération de code, et claude-haiku-4-5 pour les tâches simples et volumineuses comme la classification, la mise en forme ou l'extraction. Ce seul ajustement peut réduire le coût d'une exécution de 80 % ou plus.

Le deuxième levier est le réduction du contexte. L'entrée de chaque agent est facturée en totalité. Ne transmettez que la portion de contexte dont cet agent a réellement besoin : un fichier pertinent, un court résumé ou un objet structuré plutôt que l'intégralité de l'historique de conversation. Le prompt caching (réutilisation d'un préfixe commun entre agents) réduit davantage les frais liés au contexte répété lorsque plusieurs agents partagent un grand prompt système ou un document de référence.

Contrôles budgétaires pratiques à appliquer avant de lancer une flotte d'agents :

• Définissez max_tokens par agent au minimum nécessaire pour ce type de tâche.
• Limitez le nombre d'agents en parallèle : davantage de concurrence augmente le coût sans toujours améliorer la qualité.
• Ajoutez une étape d'estimation à blanc : comptez les tokens des entrées prévues avant de lancer une exécution complète.
• Utilisez la terminaison anticipée : si un résultat intermédiaire satisfait déjà le critère de succès, annulez les agents restants.
• Journalisez l'usage des tokens par appel d'agent et fixez un plafond absolu dans la boucle de l'orchestrateur.

Schémas pour des données d'agent propres

Dans un pipeline multi-agent (une chaîne de modèles IA qui se transmettent des résultats), la sortie d'un agent devient l'entrée du suivant. Si cette sortie est du texte libre, l'agent récepteur doit deviner la structure, ce qui provoque des erreurs silencieuses. La solution est la sortie structurée : forcer le modèle à retourner les données dans un format strict et lisible par les machines, comme JSON.

Claude prend en charge la sortie structurée via l'utilisation d'outils. Vous définissez un JSON Schema (une description formelle des champs, des types et des propriétés requises attendus) et vous le passez comme définition d'outil. Claude remplit alors ce schéma au lieu d'écrire du texte. Le résultat est un objet JSON que votre code peut analyser et valider sans aucune manipulation de chaîne de caractères.

Principales raisons d'imposer des schémas dans les chaînes d'agents :

• Fiabilité : les agents en aval reçoivent des clés et des types prévisibles, pas du texte ambigu.
• Validation : vous pouvez rejeter ou relancer une réponse dès qu'un champ requis est absent, avant que de mauvaises données ne se propagent.
• Observabilité : les journaux structurés sont plus faciles à rechercher, à comparer et à surveiller en production.
• Composabilité : tout agent qui parle le même schéma peut être échangé sans réécrire le code de liaison du pipeline.

Dans Claude Code, l'API Claude (l'interface HTTP que votre agent appelle par programmation) vous permet de passer un tableau tools avec un outil dont l'input_schema définit exactement ce que vous voulez recevoir. Définir tool_choice à {"type":"tool","name":"votre_outil"} force Claude à appeler cet outil à chaque fois, garantissant une sortie structurée pour chaque requête.

Reprendre et mettre en cache un workflow

Un workflow multi-agents (un pipeline où plusieurs sous-agents IA traitent différentes tâches en séquence) peut être coûteux à relancer entièrement à chaque modification d'une étape. La solution est la reprise partielle : relancer uniquement les étapes dont les entrées ont changé, et réutiliser les sorties de tout le reste.

Claude Code prend en charge cela via deux mécanismes complémentaires. La mise en cache des prompts (une fonctionnalité de l'API Anthropic) stocke le calcul au niveau des tokens pour un prompt système long et stable, ou pour un bloc de contexte, afin que le modèle évite de le retraiter lors de l'appel suivant. Cela réduit à la fois la latence et le coût. Les accès au cache sont facturés à environ 10 % du tarif normal des tokens d'entrée. Le cache est indexé par le texte exact du préfixe : même un seul caractère modifié dans le bloc mis en cache l'invalide.

Au niveau du workflow, vous contrôlez la reprise via des points de contrôle (checkpoints) : les sorties de chaque étape d'agent sont sauvegardées sur disque ou dans un store. Quand vous relancez le pipeline, chaque étape vérifie si son checkpoint est toujours valide (entrées inchangées) avant d'appeler le modèle. Les schémas courants incluent :

• Vérification par hachage de contenu : calculer le hash des entrées de l'étape et le comparer au hash stocké avec le checkpoint. Une correspondance signifie que l'étape est ignorée.
• Vérification par horodatage : ignorer l'étape si le fichier checkpoint est plus récent que tous les fichiers sources qu'elle lit.
• Invalidation explicite : passer un indicateur --from step-name à votre orchestrateur pour forcer la réexécution à partir d'une étape nommée.
• Graphe de dépendances : modéliser quelles étapes dépendent de quelles sorties ; invalider uniquement les étapes en aval quand une sortie en amont change.

Dans Claude Code, vous pouvez écrire cette logique dans un orchestrateur shell ou Node qui appelle claude avec l'indicateur --print (non interactif, affiche la réponse et quitte) et écrit chaque sortie dans un fichier. Au lancement suivant, lisez d'abord le fichier et ignorez complètement l'appel claude si le checkpoint est frais.

Le critique de complétude

Dans un pipeline multi-agents (une chaîne d'agents IA dont chacun réalise une tâche précise), le dernier goulot d'étranglement est rarement du contenu erroné. C'est du contenu manquant. Un critique de complétude est un agent final dont l'unique rôle est de se demander : "Qu'est-ce qui devrait être ici et qui ne l'est pas ?" Il passe en revue la sortie de tous les agents précédents par rapport au cahier des charges initial et signale les lacunes avant que le résultat n'atteigne l'utilisateur.

Cet agent est délibérément ciblé. Il ne réécrit pas, n'améliore pas le ton et ne vérifie pas les faits. Il compare uniquement la portée du cahier des charges à la portée de la sortie et renvoie une liste structurée d'omissions. Ce rôle restreint le rend rapide, économique (un modèle Haiku suffit généralement), et facile à tester.

Exemples courants de ce qu'un critique de complétude détecte :

• Une section mentionnée dans le cahier des charges qui n'apparaît jamais dans la sortie
• Un exemple promis dans l'introduction mais jamais rédigé
• Une contrainte (nombre de mots, audience, langue) abandonnée sans signalement
• Un point d'action d'un compte rendu de réunion reformulé jusqu'à disparaître

Le critique renvoie ses conclusions dans le pipeline sous forme de diff structuré (une liste de différences lisible par une machine). Un agent de second passage, ou l'orchestrateur lui-même (l'agent qui coordonne tous les autres agents), décide ensuite quelles lacunes combler, lesquelles accepter et lesquelles remonter à l'humain.