Accueil / Plusieurs agents et vérification adverse

Faire tenir un fan-out à grande échelle

Un livrable volumineux confié à un seul agent se fait couper par une limite de taille sans que rien ne soit écrit : fractionner par axe, faire écrire chaque agent sur son propre fichier, respecter le plafond documenté de seize agents actifs à la fois et de mille agents au total sur un même run, un seul appel acceptant jusqu'à 4 096 éléments que le runtime ordonnance lui même sous ce plafond, puis vérifier en comparant les fichiers attendus à ce qui existe réellement sur le disque plutôt que de croire les agents sur parole.

Un agent unique chargé d'écrire un livrable trop long se fait interrompre par une limite de taille de sortie, et rien n'est écrit sur le disque : la tâche paraît impossible alors que le problème tient au découpage. La parade tient en une phrase, un agent par axe, chacun écrivant son propre fichier, pour que la limite ne porte plus jamais que sur un seul fichier à la fois plutôt que sur l'ensemble du livrable.

Le plafond documenté

Claude Code plafonne le nombre d'agents actifs en même temps à seize, un chiffre qui redescend si la machine dispose de moins de processeurs, y compris dans un conteneur dont le nombre de cœurs est limité. Un second plafond, distinct du premier, limite à mille le nombre total d'agents lancés sur l'ensemble d'un même run, justement pour empêcher une boucle qui s'emballerait et relancerait des agents sans fin. Ces deux compteurs ne se confondent pas : le premier borne ce qui tourne au même instant, le second borne le cumul sur toute la durée du travail. Un troisième chiffre change la donne pratique : un seul appel parallel() ou pipeline() accepte jusqu'à quatre mille quatre-vingt-seize éléments, et c'est le runtime lui même qui les ordonnance sous le plafond de seize, sans intervention manuelle, un envoi plus long étant simplement rejeté avec une erreur plutôt que silencieusement tronqué. Le découpage manuel en vagues successives, chaque vague vérifiée avant que la suivante ne démarre, garde son utilité, mais comme un choix pour vérifier le travail par lots plutôt que comme la seule façon de rester sous le plafond de concurrence.

Vérifier le disque, pas le rapport

Un agent qui affirme avoir écrit son fichier peut se tromper, sur son propre chemin de sortie ou sur le contenu réellement produit. La discipline qui referme la boucle consiste à écrire, avant de lancer le fan-out, la liste exacte des fichiers attendus, puis à la comparer après coup à ce qui existe vraiment sur le disque, jamais aux comptes rendus renvoyés par les agents eux mêmes.

# liste attendue, écrite avant le lancement
cat > attendus.txt < obtenus.txt
diff attendus.txt obtenus.txt

Un dernier réflexe économise du budget sur un grand volume d'appels similaires qui n'ont pas besoin d'une réponse immédiate. La Batch API traite ce genre de travail de façon asynchrone avec une remise de cinquante pour cent sur le coût en jetons, sur un quota de débit séparé de celui des appels en direct. Elle convient à un fan-out déjà écrit et prêt à tourner en une seule fois, pas à un travail dont chaque étape dépend du résultat de la précédente.

Ces trois disciplines se combinent dans l'ordre inverse de leur découverte. On isole d'abord chaque agent dans son worktree, on respecte ensuite le plafond de concurrence par des vagues, et on vérifie enfin sur le disque ce que le fan-out a réellement produit, jamais ce que les agents en ont dit.