Harness engineering : donner à chaque sous-agent un budget de mémoire, de CPU et de temps
Un agent qui impressionne en démo casse en production quand un sous-agent prend toute la mémoire de l'hôte ou tourne sans fin. Le harness doit donner à chaque sous-agent un contrat d'exécution, détecter le dépassement et décider : relancer ou arrêter. Méthode, options Docker avec leurs limites, et les résultats d'un exemple reproductible en interne, limites comprises.
Note de transparence. Cet article suit la politique éditoriale d'IgnitionAI. Les faits techniques renvoient à leur documentation primaire, consultée le 11/11/2026. Les chiffres viennent d'un exemple construit par IgnitionAI, reproductible en interne, mesuré le 11/11/2026. Les recommandations sont des avis d'IgnitionAI. IgnitionAI construit des agents IA : c'est un conflit d'intérêt. Salim Laimeche est co-auteur de Building Agentic AI Apps with Next.js and TypeScript (Packt), en précommande, sortie prévue le 1er décembre 2026.
Un agent qui réussit en démo peut tomber en production pour une raison banale : un sous-agent prend toute la mémoire de l'hôte, ou tourne sans fin. Le modèle n'y est presque pour rien. Il manque un contrat d'exécution pour chaque sous-agent, et un harness qui applique ce contrat.
Anthropic définit le harness d'agent comme « le système qui permet à un modèle d'agir comme un agent : il traite les entrées, orchestre les appels d'outils et renvoie les résultats » (Demystifying evals for AI agents). Cet article traite une seule de ses responsabilités : borner ce que chaque sous-agent peut consommer.
En bref
- Donnez à chaque sous-agent un contrat : mémoire, CPU, nombre de processus, durée, tokens, tours, format de sortie.
- Un plafond n'est pas une réservation.
--cpusborne le calcul, il ne garantit pas un minimum. - Détectez le dépassement sans vous fier au seul code de sortie, puis décidez : une relance au plus, ou l'arrêt.
- Les limites CPU et mémoire ne couvrent pas les volumes montés. Traitez le disque à part.
- Mesurez la consommation réelle, puis resserrez le contrat. Et mesurez la stabilité de vos résultats, pas seulement leur réussite.
Le problème
Un agent principal (deep agent) délègue à des sous-agents. Chacun exécute du code, appelle des outils et consomme des tokens. Sans limite par sous-agent, un seul défaut, comme une boucle infinie ou un tableau qui grossit sans fin, peut prendre l'hôte entier. La documentation Docker le dit sans détour : sans limite, en cas de manque de mémoire, « n'importe quel processus peut être tué, y compris Docker et d'autres applications importantes » (Resource constraints).
Les 9 briques d'un harness, et qui les fournit
| Brique | Question à poser | Ce qui casse sans elle | Qui la fournit |
|---|---|---|---|
| Boucle | Quand s'arrête l'agent ? | Tours infinis | Votre harness |
| Outils | Quel contrat d'entrée et de sortie ? | Mauvais outil, erreurs opaques | Vous |
| Contexte | Qu'est-ce qui reste dans la fenêtre ? | Dérive | Vous |
| Permissions | Qui autorise quoi, dans l'outil ? | Action non voulue | Votre outil |
| Exécution et quotas | Combien de mémoire, de CPU, de temps par sous-agent ? | Un agent fait tomber l'hôte | Votre infrastructure |
| Coordination | Qui possède quelle ressource ? | Écritures concurrentes | Vous |
| Évals | Comment savoir que ça marche, et que ça marche à chaque fois ? | Régressions silencieuses | Vous |
| Reprise | Que fait l'agent après une coupure ? | Travail refait ou déclaré fini à moitié | Votre harness |
| Coût et journaux | Coût par tâche acceptée ? | Factures inexpliquées | Vous |
Ce tableau est une grille d'IgnitionAI, pas une norme. Cet article détaille la brique exécution et quotas : une démo tourne rarement assez longtemps pour la mettre à l'épreuve.
Un contrat d'exécution par sous-agent
Un sous-agent ne reçoit pas seulement une instruction. Il reçoit un contrat, écrit dans un fichier et validé au démarrage. Voici celui du sous-agent « code » de notre exemple. Les valeurs sont celles de l'exemple, petites exprès pour provoquer les dépassements : ce ne sont pas des recommandations.
# contracts/code.yaml
name: code
allowedTools: [execute]
memoryMb: 64 # --memory
cpus: 0.5 # --cpus : plafond, pas réservation
pidsLimit: 32 # --pids-limit
timeoutMs: 6000 # arrêt côté harness
maxTokens: 2048 # budget de tokens du sous-agent
maxTurns: 4 # plafond de tours de boucle
outputSchema:
type: object
required: [language, code]
incidentPolicy:
memory_overflow: retry
timeout: abort
nonzero_exit: retryUn contrat invalide ne démarre pas, et l'erreur dit quel champ corriger : c'est une des 20 tâches de notre banque d'évals. La politique d'incident est dans le contrat, pas dans le code : le sous-agent « research » de l'exemple, lui, s'arrête au premier dépassement mémoire.
Options Docker : ce qu'elles garantissent, ce qu'elles ne garantissent pas
Sources : Resource constraints et la référence de docker container run.
| Option | Ce qu'elle fait | Ce qu'elle ne garantit pas |
|---|---|---|
--memory | une limite dure : le conteneur ne dépasse pas la valeur fixée | que l'agent survive : en cas de manque de mémoire, le noyau tue des processus du conteneur |
--memory-swap | borne la mémoire plus le swap ; égal à --memory, pas de swap | rien sans --memory, dont elle dépend |
--cpus | un plafond de calcul, équivalent d'un quota CFS | un minimum de calcul : c'est un plafond, pas une réservation |
--cpu-shares | un poids relatif, appliqué seulement quand le CPU manque | un accès CPU précis |
--cpuset-cpus | l'usage limité aux cœurs indiqués | une quantité de calcul : il choisit les cœurs, pas la dose |
--pids-limit | limite le nombre de processus du conteneur | la page ne détaille ni valeur par défaut ni comportement au dépassement |
--storage-opt size=… | la taille du système de fichiers du conteneur, sur certains pilotes ; avec overlay2, seulement sur xfs monté avec pquota | les volumes montés : non documenté, notre inférence (voir plus bas) |
Un plafond n'est pas une réservation. La documentation écrit que --cpus="1.5" garantit « au plus » 1,5 CPU. Si un sous-agent a besoin d'un minimum, organisez-le ailleurs, par exemple en réservant des cœurs.
Les limites CPU et mémoire ne couvrent pas le disque. --storage-opt size vise le système de fichiers du conteneur. Les options --device-write-bps et --device-write-iops limitent le débit d'écriture sur un périphérique (« Limit write rate … to a device », référence docker container run) : elles bornent la vitesse d'écriture, pas le volume total écrit. La documentation ne parle pas des volumes montés ; notre inférence, à prendre comme telle : un agent qui écrit sans fin dans un volume monté peut remplir le disque de l'hôte sans toucher à sa mémoire. Pour un espace de travail temporaire, --tmpfs accepte une taille (size=). Sinon, posez des quotas au niveau du système de fichiers.
Les options Docker n'ont pas de notion de tâche. Elles bornent un conteneur. La décision « relancer ou arrêter » vient de votre harness.
Détecter le dépassement, puis décider
Le harness doit savoir ce qui s'est passé. Notre exemple distingue trois cas, chacun journalisé en JSONL :
- Dépassement mémoire : le harness lit l'état
OOMKilleddansdocker inspect. Dans notre démo, le conteneur sort avec le code 137 etOOMKilled=true. - Dépassement de temps : le harness tue le conteneur à l'échéance
timeoutMs, puis le supprime. - Sortie invalide : la sortie ne respecte pas
outputSchema.
Ne vous fiez pas au seul code 137. Dans la même démo, le conteneur tué par le harness pour dépassement de temps sort aussi en 137, avec OOMKilled=false. Les deux pages Docker citées ici ne documentent pas ce code. Notre harness ne classe donc un incident en dépassement mémoire que si docker inspect le confirme, ou si l'inspection échoue, et il l'écrit alors dans le journal.
La politique est simple : une relance au plus, avec la même limite et un message qui décrit l'incident au modèle. Sans plafond de relance, un sous-agent mal dimensionné consomme le budget de la tâche entière. Si la relance échoue, la tâche s'arrête et le rapport dit pourquoi.
Dans la démo, le dépassement mémoire est suivi d'une relance qui aboutit ; le dépassement de temps arrête la tâche, comme le prévoit le contrat.
Mesurer avant de resserrer
Ne fixez pas les limites au hasard. Mesurez la consommation réelle sur une banque de tâches, puis resserrez le contrat. Sous Docker, docker stats affiche en direct l'usage des conteneurs (référence). Sous Linux avec cgroup v2, memory.max porte la limite dure de mémoire d'un groupe et cpu.max sa limite de bande passante CPU (documentation du noyau Linux). Attention : dans un conteneur, free affiche le swap de l'hôte, pas celui du conteneur (Docker).
Pour la concurrence, additionnez les plafonds des sous-agents actifs. Si la somme dépasse la capacité de l'hôte, mettez en file d'attente : des plafonds dont la somme dépasse l'hôte ne le protègent pas.
Évals : réussir une fois, réussir à chaque fois
Vérifiez le résultat dans l'environnement, pas le déroulé. Anthropic recommande de commencer par « 20 à 50 tâches simples tirées d'échecs réels » (Demystifying evals). Le même article distingue deux mesures :
- pass@k : la probabilité d'obtenir au moins une réussite en k essais ;
- pass^k : la probabilité que les k essais réussissent tous.
La première convient quand une réussite suffit. La seconde, quand la régularité compte, ce qui est le cas d'un agent en production.
Notre exemple tourne sur 20 tâches, dont la plupart provoquent un incident : dépassement mémoire, dépassement de temps, outil refusé, sortie invalide, plafond de tours, budget de tokens, contrat invalide, reprise après coupure. Avec k = 5 essais par tâche :
| Mesure | Résultat |
|---|---|
| pass@k | 1,000 |
| pass^k | 0,850 |
Les 20 tâches réussissent au moins une fois. Trois ne réussissent pas les cinq fois, dont une construite exprès pour échouer au hasard. pass@k seul aurait affiché un score parfait. Deux runs complets, relancés séparément, donnent le même rapport, à la date de génération près.
Pour la reprise, notre exemple tient une note de progression mise à jour après chaque étape enregistrée. Coupé brutalement au milieu de la deuxième étape, il reprend sans refaire la première ; sur trois coupures, le résultat final est identique à celui d'un run sans coupure.
Ce qui n'est pas résolu chez nous
- Le coût par tâche n'est pas stable. Nous voulions publier le coût moyen par tâche acceptée. Deux runs identiques donnent des totaux de tokens qui diffèrent de quelques unités, sur la tâche de dépassement mémoire. Notre hypothèse, non prouvée : selon le tirage, le démon Docker ne signale pas toujours l'état
OOMKilled, et l'incident suit un autre chemin. Nous ne publions donc pas de chiffre de coût. La leçon vaut au-delà de notre exemple : un harness qui dépend de l'état d'un démon partagé doit vérifier que ses mesures sont reproductibles avant de les comparer. - L'ordonnanceur n'est pas automatisé. La répartition des tâches entre sous-agents et les quotas par classe de tâche restent décidés à la main.
- Le modèle est factice. L'exemple tourne hors ligne, sans clé d'API, avec un modèle simulé. Il teste le harness, pas la qualité d'un modèle réel.
Votre situation : par quoi commencer ?
| Votre cas | Premier chantier | Peut attendre |
|---|---|---|
| Démo interne | Contrat par sous-agent, journaux | Concurrence |
| Premier agent sur un outil métier, en lecture seule | Permissions dans l'outil, évals | Reprise avancée |
| Sous-agents qui exécutent du code | Contrat, sandbox, détection des dépassements | Ordonnanceur |
| Agent qui écrit à l'extérieur | Clés d'idempotence, quotas, bac à sable | Optimisation des coûts |
Règle d'ordre : permissions avant autonomie, mesure avant resserrement.
Pour cadrer un projet avant de le lancer, voir les douze questions à trancher avant de financer un projet d'IA en ETI. Pour les permissions d'un agent, voir la validation humaine des outils métier.
Vos sous-agents tournent sans contrat d'exécution ? Décrivez votre contexte à IgnitionAI. Le premier échange sert à repérer ce qui peut faire tomber votre hôte, pas à présenter un produit.
FAQ
Un plafond de mémoire suffit-il à protéger l'hôte ? Non. Il borne la mémoire du conteneur. Le disque, les volumes montés et le calcul partagé demandent des mesures séparées.
Le code de sortie 137 signifie-t-il un manque de mémoire ?
Pas forcément. Dans notre exemple, un conteneur tué pour dépassement de temps sort aussi en 137. Lisez l'état OOMKilled avec docker inspect.
Pourquoi ne pas relancer indéfiniment en cas d'échec ? Parce qu'un sous-agent mal dimensionné consomme le budget de la tâche entière. Une relance au plus, puis un arrêt avec rapport.
Combien de sous-agents peut-on faire tourner en parallèle ? Autant que la somme de leurs plafonds tient dans la capacité de l'hôte. Au-delà, une file d'attente.
Pourquoi mesurer pass^k et pas seulement pass@k ? Parce qu'un agent en production doit réussir à chaque fois. Dans notre exemple, pass@k vaut 1,000 et pass^k 0,850 : le premier chiffre cache trois tâches irrégulières.
Méthodologie et sources
Sources consultées le 11/11/2026 :
- Anthropic, Demystifying evals for AI agents (définition du harness, pass@k, pass^k, 20 à 50 tâches)
- Docker, Resource constraints
- Docker, docker container run
- Docker, docker container stats
- Noyau Linux, Control Group v2
Mesures : test interne du 11/11/2026 sur l'exemple d'IgnitionAI, version du commit 2ab7714, reproductible en interne, en TypeScript, LangGraph JS et Bun, avec un modèle factice hors ligne et des conteneurs Docker node:22-alpine. Banque de 20 tâches, k = 5, graine fixe. Résultats du 11/11/2026 : 46 tests sur 46, deux runs d'évals identiques hors date de génération, démo de reprise relancée trois fois. Le code de l'exemple n'est pas public. Non cité volontairement : tout chiffre de fournisseur sans méthode publique, et notre coût par tâche, instable entre deux runs.