Les dix primitives de l'ingénierie de harness pour agents IA
Un parcours des couches qui entourent le modèle, des instructions à la vérification, et qui transforment un LLM bavard en quelque chose comme Claude Code ou Codex.
Quand un agent comme Claude Code ou Codex fait quelque chose d'impressionnant, on est tenté d'en créditer le modèle. Le modèle compte, évidemment, c'est bien pour cela que la guerre des benchmarks existe. Mais dès que l'on construit de vrais workflows d'agents, le modèle n'est qu'une pièce de la machine. Tout le reste — ce que le modèle voit, ce sur quoi il peut agir, ce dont il se souvient, le travail qui est délégué, la façon dont il vérifie, dont il se rétablit — vit dans le harness. Cet article parcourt les dix primitives qui composent ce harness, en suivant le cadrage de la Harness Engineering Masterclass de The Carbon Layer. Aucune n'est encore formellement normalisée, mais ensemble elles expliquent pourquoi « le modèle a juste fait ça » n'est presque jamais la bonne réponse.
Les instructions
La première primitive est celle que vous écrivez déjà à la main : les instructions. Vous dites au modèle qui il est, quel travail il fait, le ton, les contraintes, le style de code, les règles de la revue, ce qu'il ne doit jamais faire. agents.md, Claude.md, prompts système, instructions personnalisées, règles de curseur : même famille. Leur force est de sortir les consignes répétées de la fenêtre de conversation pour les mettre dans l'environnement, afin de ne pas recoller les mêmes règles à chaque session. Mais les instructions sont passives. Elles peuvent dire « suis la convention du projet » sans pouvoir découvrir la convention. Elles peuvent dire « attention aux migrations » sans pouvoir inspecter une migration. Elles façonnent le comportement ; elles ne tendent pas le monde au modèle.
La livraison de contexte
La primitive suivante est la livraison de contexte, le mécanisme qui tend au modèle la matière dont il a besoin pour travailler réellement. La mention @ qui tire un fichier dans le prompt, le test en échec joint à un rapport de bug, la trace d'appels, la doc, le log. C'est là que la différence entre un modèle nu et un agent dans un harness devient évidente. Demandez à un modèle nu de corriger un bug sans aucun fichier et vous obtenez une correction générique ; donnez-lui le fichier source et le test en échec, et vous obtenez quelque chose qui pourrait vraiment tenir. Mais déverser du contenu n'est pas livrer du contexte, ce qui mène directement à la couche suivante.
La gestion du contexte
La gestion du contexte, c'est le harness qui décide, à chaque tour, ce que le modèle doit regarder maintenant. Les dépôts sont trop gros, les transcriptions de conversation deviennent trop longues, les logs d'incident en production sont énormes. Déversez tout dans la fenêtre et vous n'obtenez pas un agent plus intelligent, vous obtenez un prompt plus bruyant, et souvent une moins bonne réponse, parce qu'un mauvais contexte fait plus de dégâts qu'un contexte manquant. C'est ici que vivent le RAG, le reranking, le résumé, les caches de prompt, les résumés de session et la compaction. Les noms changent ; le travail non : protéger l'attention du modèle. La question n'est plus « peut-on fournir du contexte ? » mais « qui décide du contexte qui compte maintenant ? », et l'essentiel de cette décision revient au harness, pas à l'humain.
L'interface d'outils
La gestion du contexte rend l'agent plus intelligent à l'intérieur de la conversation, mais l'agent reste surtout un causeur. Il peut nommer le fichier, proposer la commande, décrire l'étape suivante. À un moment, il faut que quelque chose se produise vraiment, et c'est l'interface d'outils. Les outils donnent au modèle une manière structurée d'agir — un nom, une description, un schéma d'entrée, parfois un schéma de sortie — et le modèle choisit lequel appeler avec quels arguments. Function calling, tool use, MCP, bash, grep, find : la même primitive à différentes altitudes. MCP est particulièrement intéressant parce qu'il abstrait la façon dont les outils sont exposés, si bien que n'importe quel fournisseur peut brancher ses capacités sur n'importe quel modèle. L'interface d'outils, c'est ce qui transforme un descripteur en acteur.
L'environnement d'exécution
Une fois que le modèle peut appeler des outils, une nouvelle question apparaît : où l'appel s'exécute-t-il réellement ? Sur votre portable ? Dans un conteneur ? Dans un bac à sable cloud avec accès réseau ? Avec quels secrets, et sur quels fichiers ? Les outils échouent, renvoient du texte mal formé, parfois une injection de prompt cachée dans une page web, et le harness doit décider de la confiance à accorder à tout cela. L'environnement d'exécution est la couche qui répond à ces questions opérationnelles : périmètre du système de fichiers, politique réseau, identifiants, bacs à sable, dev containers, worktrees, profils de navigateur. Des entreprises comme Daytona, E2B ou le dev sandbox de Docker existent parce que cette primitive fait un vrai travail. C'est aussi là que la confiance devient pratique : au lieu d'instruire le modèle « ne touche pas aux secrets, s'il te plaît », le harness rend les secrets inatteignables.
L'état durable
Un bac à sable isolé suffit pour une tâche propre, mais le vrai travail se met en pause, reprend, bifurque, échoue et recommence. Si la seule trace de ce qui s'est passé vit dans la fenêtre de contexte du modèle, un plantage fait tout perdre. L'état durable est l'établi qui survit au tour en cours : fichiers de plan, points de contrôle, état des tâches, résumés de session, diffs, logs, mémoires. Pour un agent de code ce sera une branche, un journal de tests, un document de plan ; pour un agent de recherche, une carte des sources ou un tableau de citations extraites. Le format de stockage importe peu. Ce qui compte, c'est que l'avancement devienne inspectable en dehors de l'attention du modèle, pour que l'étape suivante reparte de là où la précédente s'est arrêtée, et non de zéro.
L'orchestration
L'état durable conserve le travail mais ne le fait pas avancer. Un fichier de plan décrit ce qui devrait se produire, il ne décide pas quand réessayer, quand demander une approbation, ni quand passer la main à un humain. Cette coordination, c'est l'orchestration : hooks de cycle de vie, battements de cœur, reprises, portes d'approbation, passages de relais humains, wrappers d'outils, ordonnancement des étapes, routage des tâches. Les hooks de Claude Code en sont un bon exemple : les frameworks d'agents exposent des événements de cycle de vie précisément parce que les systèmes réels ont besoin d'endroits où intercepter le comportement. Le modèle ne fait pas tourner un workflow par force de volonté ; c'est le harness qui porte le workflow, et l'orchestration est ce qui fait que l'ensemble ressemble moins à une conversation qu'à un runtime.
Les sous-agents
Un agent unique qui fait tout en série se heurte à deux problèmes : c'est lent, et son attention est encombrée par du travail sans rapport. Quand le travail se ramifie naturellement — un fil pour explorer le dépôt, un autre pour relire le diff, un autre pour vérifier les sources, un autre pour rédiger le plan — le harness doit se ramifier aussi. C'est la primitive du sous-agent. L'Agent SDK d'OpenAI en capture deux motifs utiles : les agents comme outils, où un gestionnaire appelle des spécialistes et intègre leur production, et les passages de relais, où la conversation active migre vers un spécialiste. Un sous-agent n'est pas simplement plus de modèle ; c'est un modèle avec un travail plus étroit, un contexte plus étroit, et souvent des outils plus étroits. Tout l'intérêt est de réduire la surface sur laquelle chaque exécutant doit raisonner.
Les compétences et procédures
La délégation crée son propre problème : si chaque sous-agent invente son propre processus, vous obtenez de l'incohérence en parallèle, chacun revenant avec sa propre interprétation du travail. Les agents ont besoin de procédures réutilisables, chargeables au bon moment. C'est la couche des compétences : des manuels nommés et structurés qui encodent quand les employer, quelles entrées elles prennent, quelles étapes elles suivent et quels outils elles préfèrent. Commandes slash, runbooks, recettes, workflows : même primitive. Une compétence bien écrite pour relire une PR, préparer un épisode ou lancer des vérifications navigateur fait sortir l'expertise répétée de l'instruction « pense à faire ça » pour en faire une capacité nommée que le harness peut invoquer à la demande. C'est en partie pourquoi le moment où les compétences sont devenues un concept de premier rang a semblé décisif.
La vérification et l'observabilité
Les compétences rendent le travail reproductible mais ne prouvent pas qu'il a réussi. Une compétence peut dire « lance les tests », elle ne confirme pas qu'ils sont passés. Elle peut dire « vérifie le navigateur », elle ne confirme pas que la capture était propre. La vérification, c'est le harness qui réclame des preuves : tests, builds, vérifications de types, linters, captures d'écran, évaluations. Le changement d'état d'esprit, c'est de ne pas faire confiance à la phrase finale parce qu'elle sonne assurée ; vous demandez quels contrôles externes l'étayent. L'observabilité est l'autre moitié, l'enregistreur de l'exécution. Traces, chronologies d'appels d'outils, versions de prompts, versions d'outils, événements d'approbation, coût, latence, toute la chaîne de l'intention à la sortie. Les bugs sont rarement dans le message final ; ils sont trois appels d'outils plus tôt, quand l'agent a cherché le mauvais symbole ou fait confiance à la mauvaise page. La vérification vous dit si l'exécution est passée. L'observabilité vous dit pourquoi elle ne l'est pas, et transforme un échec de « l'agent s'est planté » en un système débogable que vous pouvez réellement améliorer.
Conclusion
Mettez ces dix primitives côte à côte et les schémas d'architecture de Claude Code, Codex ou du CLI Gemini cessent de paraître arbitraires. Chaque couche est là parce que quelque chose en amont laisse un manque : les instructions ne peuvent pas découvrir les fichiers, la livraison de contexte ne peut pas décider de la pertinence, les outils ne peuvent pas décider où s'exécuter, les environnements ne peuvent pas se souvenir, l'état ne peut pas coordonner, l'orchestration ne peut pas se ramifier, les sous-agents ne peuvent pas partager de procédures, les procédures ne peuvent pas prouver la réussite, et la vérification ne peut pas expliquer l'échec. Le test pratique sur lequel la vidéo se termine mérite d'être repris : quand un agent échoue, cessez de demander « le modèle était-il assez bon ? » et demandez quelle couche du harness est arrivée au bout de la route. L'instruction manquait-elle ? Le contexte était-il faux ? Le schéma d'outil a-t-il induit en erreur ? La commande s'est-elle exécutée dans le mauvais environnement ? N'y avait-il ni vérification, ni trace, ni souvenir du correctif de la dernière fois ? C'est le glissement, des agents malins vers les systèmes fiables. Le modèle compte toujours. Mais la fiabilité se construit dans le système autour de lui.
Notes prises à partir de [« Harness Engineering Masterclass: Technical Deep Dive on how to build Agentic Systems »](https://www.youtube.com/watch?v=mQfTdNVCOB0) de The Carbon Layer.