Un extrait de configuration circule cette semaine : définissez agents.max_concurrent_threads_per_session = 64 dans votre config.toml Codex et regardez une seule session se démultiplier en dizaines de sous-agents. Le post qui a lancé cette histoire affirme que la valeur par défaut est 3 et qu'OpenAI a testé 64. Le paramètre, lui, est bien réel. Les deux chiffres, en revanche, ne figurent dans aucune documentation, et ce qui est intéressant n'est pas du tout le plafond. C'est ce qui arrive au travail quand on le relève.
Cet article explique ce que ce paramètre fait réellement, d'après la référence Codex, et les trois choses qui cassent, dans l'ordre, dès qu'une seule session fait tourner plus d'agents qu'une personne ne peut en lire.
TL;DR
agents.max_concurrent_threads_per_session plafonne le nombre de threads d'agents lancés que Codex garde ouverts simultanément, sans compter le thread principal. La référence ne publie aucune valeur par défaut ; elle indique que Codex en choisit une lorsque la clé n'est pas définie. Les sous-agents renvoient des résumés au thread principal, qui attend qu'ils aient tous terminé puis répond une seule fois, et la documentation les recommande pour les tâches à dominante lecture tout en avertissant que les workflows parallèles à dominante écriture créent des conflits et une surcharge de coordination. Relever le plafond à 64 met exactement ces deux points sous tension : des fichiers partagés et une réponse unique et consolidée que personne ne peut auditer. Sharkly exécute Codex en tant que Runtime et fait monter le parallélisme d'un cran, là où chaque exécution est une Task avec son propre worktree, son propre journal et son propre relecteur.
Ce que fait ce paramètre
Trois clés de la section [agents] de config.toml entrent en jeu ici. Les formulations ci-dessous proviennent de la référence de configuration.
| Clé | Ce que dit la référence |
|---|---|
agents.max_concurrent_threads_per_session |
« Nombre maximum de threads d'agents lancés pouvant être ouverts simultanément, sans compter le thread principal. Lorsque la clé n'est pas définie, Codex choisit la valeur par défaut. » |
agents.max_threads |
« Ancien alias de agents.max_concurrent_threads_per_session. » |
agents.enabled |
« Active ou désactive les outils multi-agents (par défaut : true). » |
Deux clés associées, agents.default_subagent_model et agents.default_subagent_reasoning_effort, déterminent ce sur quoi tournent les agents lancés, sauf indication contraire au moment du lancement.
L'extrait fonctionne donc tel quel :
[agents]
max_concurrent_threads_per_session = 64
Ce que la référence ne dit pas, c'est quelle est la valeur par défaut, ni qu'une quelconque valeur a été testée. Considérez « 3 par défaut » et « OpenAI a testé 64 » comme des affirmations issues d'un post, et non de l'éditeur, tant que la documentation ne dit pas le contraire.
Le guide des sous-agents ajoute les deux phrases qui déterminent si relever le plafond est une bonne idée. Sur les résultats : « Lorsque de nombreux agents tournent, Codex attend que tous les résultats demandés soient disponibles, puis renvoie une réponse consolidée. » Sur la pertinence : les sous-agents conviennent aux « tâches à dominante lecture telles que l'exploration, les tests, le triage et la synthèse », et le guide recommande la prudence avec les « workflows parallèles à dominante écriture, car des agents qui modifient le code en même temps peuvent créer des conflits et augmenter la surcharge de coordination ».
Lisez ces deux passages ensemble et l'ordre des défaillances s'écrit tout seul.
Ce qui casse en premier : le checkout partagé
Au sein d'une même session, les sous-agents partagent le répertoire de travail de la session, sauf si vous en disposez autrement. Cela ne pose aucun problème pour soixante-quatre agents qui lisent. C'est un problème de fusion pour quatre agents qui écrivent.
La défaillance n'a rien de spectaculaire. Deux sous-agents modifient le même fichier, la seconde écriture l'emporte, et le résumé consolidé indique que les deux tâches sont terminées. Vous vous en apercevez en revue, si vous faites une revue, ou en production si vous n'en faites pas. L'avertissement de la documentation sur les conflits et la surcharge de coordination décrit exactement cela.
La solution est celle vers laquelle converge toute configuration d'agents parallèles : une copie de travail par unité de travail. Dans Sharkly, chaque exécution de Task dispose d'un répertoire isolé, et le travail adossé à un dépôt utilise un worktree git distinct par exécution, le mécanisme décrit dans des agents parallèles dans des worktrees isolés. Dix Tasks sur un même dépôt, zéro état partagé. Le Runtime qui effectue les modifications peut toujours être Codex ; l'isolation est assurée autour de lui.
Ce qui casse ensuite : la réponse consolidée
Codex attend chaque sous-agent et renvoie une seule réponse. Avec quatre sous-agents, c'est pratique. Avec soixante-quatre, c'est un message unique qui résume soixante-quatre unités de travail, rédigé par l'agent qui les a lancées, avec les sorties intermédiaires repliées.
Ce n'est pas la bonne forme pour une revue. Un relecteur doit savoir ce que chaque unité de travail a touché, ce qu'elle a exécuté et où elle s'est arrêtée, et doit pouvoir accepter ou rejeter chacune d'elles séparément. Un résumé de résumés ne peut pas être accepté partiellement.
Sharkly stocke la réponse finale de l'Agent sur la Task et conserve, pour chaque exécution, un journal comprenant le déclencheur, le début et la fin, les appels d'outils, les événements du Runtime et les détails de l'échec. Les exécutions se trouvent dans leur propre onglet, séparé de la chronologie des commentaires. Soixante-quatre unités de travail, ce sont soixante-quatre Tasks avec soixante-quatre journaux, chacun pouvant être relu, chacun renvoyant son résultat là où une personne ira regarder.
Ce qui casse en troisième : l'humain dans la boucle
Le plafond ne dit rien de ce qui se passe quand un sous-agent a besoin d'une personne. Au sein d'une session, un sous-agent bloqué n'est qu'un thread devenu silencieux dans une attente consolidée. Le thread principal ne peut pas répondre à votre place, et vous ne pouvez pas voir lequel des soixante-quatre threads s'est arrêté.
Sharkly distingue le statut de la Task de l'état de travail de l'Agent : une Task démarrée peut afficher Working, Waiting for human reply, Waiting for human review ou Error. Les signaux d'attente et d'échec arrivent dans la section Primary de la Inbox de la personne responsable, et une réponse sur la Task lance l'exécution de suivi avec le thread comme contexte. Celui qui est bloqué vous le fait savoir, au lieu de rester suspendu dans une attente que vous ne pouvez pas inspecter.
Sous-agents ou Tasks ? Comment trancher
Utilisez les sous-agents Codex au sein d'une même session lorsque le travail est à dominante lecture et converge vers une seule réponse : explorer une base de code, faire le triage d'une série d'échecs, résumer un ensemble de documents, exécuter une suite de tests. C'est pour cela que le guide les recommande, et un plafond plus élevé ne coûte pas cher quand rien n'écrit.
Utilisez des Tasks distinctes, chacune assignée à un Agent sur un Computer, lorsque les unités de travail écrivent du code, lorsque différentes personnes reliront différentes parties, ou lorsqu'une personne pourrait devoir répondre en cours d'exécution. Sharkly ne remplace pas Codex ; Codex est le Runtime qui exécute chaque Task. La différence tient à l'endroit où vit le parallélisme : à l'intérieur de l'attente consolidée d'une session, ou sur un tableau où contexte, progression, blocages, résultats et revue humaine restent visibles de la demande à la livraison.
Relever le plafond en toute sécurité
Si vous relevez malgré tout max_concurrent_threads_per_session, faites-le comme la documentation de concurrence de Sharkly le décrit pour les Computers : n'augmentez qu'une fois que la configuration actuelle traite la charge existante de manière fiable, car une concurrence plus élevée consomme davantage de CPU, de mémoire, de disque, de capacité du fournisseur et de bande passante du dépôt. Un Computer dans Sharkly possède sa propre limite de concurrence de tâches, et les Agents qui utilisent des répertoires temporaires se limitent par défaut à la moitié de celle-ci. La capacité est bornée par le Computer, la concurrence de l'Agent et la disponibilité des répertoires, et un Agent en ligne peut encore avoir du travail en file d'attente lorsque cette capacité est saturée.
La capacité du fournisseur est ce que tout le monde oublie. Soixante-quatre threads sur une seule clé API, c'est soixante-quatre façons d'atteindre une limite de débit en même temps, et un 429 qui signifie « quota épuisé » ne se règle pas en réessayant. Le journal des exécutions échouées de Sharkly conserve la réponse d'origine du fournisseur à côté d'un intitulé clair, de sorte que la différence est visible avant que quiconque ne relance.
Questions fréquentes
Quelle est la valeur par défaut de agents.max_concurrent_threads_per_session ? La référence de configuration n'en indique aucune. Elle précise que Codex choisit la valeur par défaut lorsque la clé n'est pas définie. Les chiffres qui circulent sur les réseaux sociaux ne viennent pas de la référence.
Relever le plafond rend-il Codex plus rapide ? Pour un fan-out à dominante lecture, plus de threads terminent plus tôt. Pour le travail à dominante écriture, la documentation avertit que des modifications concurrentes créent des conflits et une surcharge de coordination, ce qui coûte plus de temps que le parallélisme n'en fait gagner.
Les sous-agents Codex s'exécutent-ils dans des worktrees git distincts ? Le guide des sous-agents ne l'affirme pas. Partez du principe qu'ils partagent le répertoire de travail, sauf si vous avez mis en place l'isolation vous-même.
Comment Sharkly utilise-t-il Codex ? Comme un Runtime. Un Computer exécutant Codex le signale comme disponible, et les Tasks assignées à un Agent sur ce Computer s'exécutent par son intermédiaire, chaque exécution dans son propre répertoire isolé ou worktree.
Puis-je quand même utiliser des sous-agents dans une Task Sharkly ? Oui. Tout ce que le Runtime peut faire seul fonctionne encore à l'intérieur de l'exécution. Sharkly ajoute autour la Task, l'isolation, le journal et la revue.
En résumé
Le paramètre est bien réel et l'extrait fonctionne. Ce qu'il ne fait pas, c'est rendre soixante-quatre modifications concurrentes sûres, rendre une réponse consolidée relisible, ou vous indiquer quel thread attend une réponse de votre part. Ce sont les trois choses qui cassent, dans cet ordre. Réservez les sous-agents au fan-out à dominante lecture, et placez le travail parallèle à dominante écriture sur un tableau où chaque exécution a son propre worktree et son propre relecteur. Connectez un Computer avec Codex dessus, créez un Agent et confiez-lui une tâche ennuyeuse. La documentation approfondit chaque concept : docs.sharkly.ai.
