Ingénierie de harnais pour agents

Un agent de codage est le modèle plus tout ce qui est construit autour de lui. L'ingénierie du harnais considère cet échafaudage comme un artefact vivant, le resserrant chaque fois que l'agent commet une erreur.

En termes simples : chaque fois qu'un agent échoue, vous concevez une solution permanente pour qu'il ne refasse jamais exactement la même erreur.

Depuis deux ans, l'industrie débat des modèles : lequel est le plus intelligent, lequel écrit le React le plus propre, ou lequel hallucine le moins. Ce débat est important, mais il oublie l'autre moitié du système.

Le modèle n'est qu'un intrant parmi d'autres dans un agent en fonctionnement. Le reste, c'est le harnais : les invites, outils, politiques de contexte, hooks, bacs à sable, sous-agents, boucles de rétroaction et chemins de récupération qui entourent le modèle pour qu'il puisse réellement accomplir des tâches.

Un modèle correct avec un excellent harnais bat systématiquement un excellent modèle avec un mauvais harnais. De plus en plus, le travail d'ingénierie le plus intéressant ne consiste pas à sélectionner le modèle, mais à concevoir l'échafaudage autour de lui.

Cette discipline a désormais un nom. @Vtrivedy10 a inventé le terme harness engineering (ingénierie du harnais), en fournissant une décomposition claire de ce qu'est un harnais et pourquoi chaque pièce existe. D'autres voix de l'industrie, comme @dexhorthy qui suit les schémas émergents, HumanLayer qui qualifie les échecs des agents de « problèmes de compétence » de configuration, l'équipe d'ingénierie d'Anthropic qui publie des guides sur la conception d'applications longue durée, et Birgitta Böckeler qui explore l'expérience utilisateur, convergent toutes vers la même idée.

Ce billet rassemble ces fils.

Qu'est-ce qu'un harnais, vraiment ?

La définition centrale de Trivedy fait l'essentiel du travail :

Agent = Modèle + Harnais. Si vous n'êtes pas le modèle, vous êtes le harnais.

Un harnais englobe tout le code, la configuration et la logique d'exécution qui ne sont pas le modèle lui-même. Un modèle brut n'est pas un agent. Il ne le devient que lorsqu'un harnais lui fournit un état, une exécution d'outils, des boucles de rétroaction et des contraintes applicables.

Concrètement, un harnais comprend :

• Les invites système, CLAUDE.md, AGENTS.md, les fichiers de compétences et les instructions des sous-agents.
• Les outils, compétences, serveurs MCP et leurs descriptions techniques.
• L'infrastructure groupée, comme le système de fichiers, les bacs à sable et les navigateurs sans tête.
• La logique d'orchestration pour générer des sous-agents, gérer les transferts et router les modèles.
• Les hooks et middleware pour une exécution déterministe, comme les vérifications de lint ou la compaction du contexte.
• Les outils d'observabilité pour les logs, traces, coûts et mesures de latence.

Au cœur, un agent est un système qui exécute des outils en boucle pour atteindre un objectif. La véritable compétence réside dans la conception à la fois des outils et de cette boucle.

Bien que cela représente une surface immense, c'est votre surface, pas celle du fournisseur de modèle. Claude Code, Cursor, Codex, Aider et Cline sont tous des harnais. Le modèle sous-jacent peut être identique d'une plateforme à l'autre, mais le comportement que vous ressentez est dominé par le harnais.

Recadrons le « problème de compétence »

Il est courant de voir des ingénieurs blâmer le modèle lorsqu'un agent fait quelque chose d'insensé, en rangeant souvent le problème dans la case « attendre la prochaine version » pour le résoudre.

L'état d'esprit de l'ingénierie du harnais rejette ce réflexe. Les échecs sont généralement lisibles. Si l'agent a ignoré une convention, ajoutez-la dans AGENTS.md. S'il a exécuté une commande destructive, écrivez un hook pour la bloquer. S'il s'est perdu dans une tâche en 40 étapes, scindez l'architecture en un planificateur et un exécuteur. S'il termine systématiquement avec du code cassé, intégrez un signal de contre-pression de vérification de type dans la boucle.

Comme le dit HumanLayer : « Ce n'est pas un problème de modèle. C'est un problème de configuration. » Considérez les benchmarks de performance : un modèle de premier plan fonctionnant dans un framework standard obtient souvent des scores nettement inférieurs au même modèle fonctionnant dans un harnais personnalisé et finement réglé. Déplacer un modèle dans un environnement avec de meilleurs outils de codebase, des invites plus précises et une contre-pression plus forte peut débloquer des capacités que la configuration d'origine avait laissées de côté.

L'écart entre ce que les modèles actuels peuvent théoriquement faire et ce que vous les voyez réellement faire est en grande partie un écart de harnais.

Le cliquet : chaque erreur devient une règle

L'habitude la plus vitale en ingénierie du harnais est de traiter les erreurs des agents comme des signaux permanents – pas des anomalies ponctuelles à réessayer et oublier.

Si un agent livre une PR avec un test commenté qui est fusionné par accident, c'est une entrée. La prochaine itération d'AGENTS.md doit stipuler : « Ne commentez jamais les tests ; supprimez-les ou corrigez-les. » Le prochain hook de pré-commit doit automatiquement signaler .skip( dans le diff. Le sous-agent relecteur doit être mis à jour pour bloquer les tests commentés.

Les contraintes ne doivent être ajoutées que lorsque vous observez un échec réel, et supprimées uniquement lorsqu'un modèle capable les rend redondantes. Chaque ligne dans une bonne invite système doit remonter à un échec historique spécifique.

Pour cette raison, l'ingénierie du harnais est une discipline plutôt qu'un cadre universel. Le harnais approprié pour une base de code donnée est entièrement façonné par son historique d'échecs unique.

Travailler à rebours à partir du comportement

La façon la plus efficace de concevoir un harnais est de partir du comportement souhaité et de construire le composant qui le délivre : Comportement souhaité → Conception du harnais pour l'atteindre.

Chaque pièce du harnais doit avoir un travail distinct. Si vous ne pouvez pas nommer le comportement spécifique qu'un composant existe pour délivrer, il doit être supprimé.

Système de fichiers et Git – état durable

Le système de fichiers est fondamental. Les modèles ne peuvent opérer que sur ce qui tient dans leur fenêtre de contexte. Un système de fichiers fournit un espace de travail pour lire les données, un endroit pour décharger le travail intermédiaire et une surface pour que plusieurs agents se coordonnent.

Ajouter Git fournit un versionnement gratuit, permettant à l'agent de suivre la progression, de bifurquer des expériences et de revenir en arrière sur les erreurs.

Bash et exécution de code : outillage polyvalent

La plupart des agents fonctionnent sur une boucle ReAct : raisonner, agir via un appel d'outil, observer, répéter. Au lieu de pré-construire un outil pour chaque action imaginable, donner à l'agent un accès bash lui permet de construire ce dont il a besoin à la volée.

Les agents excellent généralement dans les commandes shell, faisant du bash et de l'exécution de code la stratégie par défaut pour la résolution de problèmes autonome.

Bacs à sable et outillage par défaut

Bash n'est utile que s'il s'exécute en toute sécurité. Les bacs à sable fournissent aux agents un environnement isolé pour exécuter du code, inspecter des fichiers et vérifier le travail sans risquer la machine hôte.

Un bon bac à sable est livré avec des valeurs par défaut solides : environnements d'exécution de langage préinstallés, CLI de test et navigateurs sans tête, permettant à l'agent d'observer son propre travail et de fermer la boucle d'auto-vérification.

Mémoire et recherche : apprentissage continu

Les modèles n'ont aucune connaissance au-delà de leurs poids d'entraînement et de leur contexte actuel. Les harnais comblent cet écart en utilisant des fichiers mémoire (comme AGENTS.md) qui injectent des connaissances dans chaque session.

Pour les informations en temps réel comme les nouvelles versions de bibliothèques ou les données en direct, la recherche web et les outils MCP sont intégrés directement dans le harnais.

Lutter contre la pourriture du contexte

Les modèles se dégradent dans leur raisonnement à mesure que leurs fenêtres de contexte se remplissent. Les harnais gèrent cette rareté en utilisant trois techniques principales :

• Compaction : Résumer intelligemment et décharger le contexte plus ancien pour éviter les erreurs d'API.
• Déchargement des appels d'outils : Stocker les sorties massives des outils (comme des logs de 2000 lignes) dans le système de fichiers tout en ne gardant que les en-têtes et pieds de page essentiels dans le contexte.
• Divulgation progressive : Révéler les instructions et les outils uniquement lorsqu'une tâche les requiert explicitement, plutôt que de tout charger au démarrage.

Exécution à long horizon

Le travail autonome de longue durée souffre d'arrêts précoces et d'une mauvaise décomposition des problèmes. Les harnais y remédient par une conception structurelle :

• Boucles : Intercepter la tentative de sortie d'un modèle et le forcer à continuer vers un objectif d'achèvement dans une nouvelle fenêtre de contexte.
• Planification : Forcer le modèle à décomposer les objectifs en un fichier de plan étape par étape, en vérifiant son travail via des hooks d'auto-vérification après chaque étape.
• Scissions : Séparer la génération et l'évaluation en agents distincts, empêchant le biais positif inhérent des modèles lorsqu'ils évaluent leur propre travail.

Les hooks sont votre couche d'application

Les hooks comblent le fossé entre la demande d'une action et son application. Ils s'exécutent à des cycles de vie spécifiques : avant un appel d'outil, après une modification de fichier, ou avant un commit. Les hooks bloquent les commandes destructives, appliquent le formatage automatique pour économiser des tokens et exécutent les suites de tests.

Idéalement, le succès est silencieux et les échecs sont verbeux. Si une vérification de type réussit, l'agent n'entend rien ; si elle échoue, l'erreur est injectée directement dans la boucle pour auto-correction.

Voici le livre de règles et le choix des outils

Un fichier Markdown plat à la racine d'un dépôt reste le point de configuration au plus fort effet de levier. Cependant, il doit être traité comme la checklist d'un pilote, pas comme un guide de style. Gardez-le court, et assurez-vous que chaque règle est méritée par un échec passé.

La même discipline s'applique aux outils. Dix outils très ciblés surpasseront toujours cinquante outils qui se chevauchent.

De plus, parce que les descriptions d'outils peuplent l'invite, des intégrations externes malveillantes ou bâclées (comme des serveurs MCP non vérifiés) peuvent injecter de mauvaises invites dans l'agent avant même qu'il ne commence à travailler.

À quoi cela ressemble en production

L'image publique la plus claire que j'aie vue d'un harnais mature est la décomposition (estimée) par Fareed Khan de l'architecture de Claude Code.

Presque tous les concepts de la section précédente apparaissent sur ce diagramme en tant que composants nommés. L'injection de contexte est la couche de connaissance. L'état de la boucle réside dans le magasin de mémoire et l'isolateur d'arbre de travail. Les hooks d'actions destructives se trouvent derrière la porte de permission. Les pare-feu de contexte des sous-agents constituent toute la couche multi-agents. Le registre de répartition des outils est l'endroit où les serveurs MCP et bash se branchent. La trajectoire de Claude Code concerne le harnais au moins autant que le modèle en dessous.

Les harnais ne rétrécissent pas, ils se déplacent

À mesure que les modèles s'améliorent, le besoin d'un harnais ne disparaît pas – il se déplace.

Il est tentant de supposer que de meilleurs modèles rendent l'échafaudage obsolète. Par exemple, les récentes mises à niveau de modèles ont considérablement réduit le besoin d'atténuations de « l'anxiété de contexte ». Mais à mesure que le plancher s'élève, le plafond s'élève aussi. Des tâches auparavant inaccessibles sont désormais à portée, apportant des modes d'échec entièrement nouveaux.

Chaque composant d'un harnais encode une hypothèse sur ce que le modèle ne peut pas faire seul. Lorsque le modèle s'améliore, l'échafaudage obsolète doit être supprimé, et un nouvel échafaudage doit être construit pour atteindre le prochain horizon.

Qu'en est-il de la boucle d'entraînement ?

Il existe une boucle de rétroaction active entre la conception du harnais et l'entraînement du modèle.

Les modèles d'aujourd'hui sont souvent post-entraînés avec des harnais spécifiques dans la boucle, créant un certain degré de surapprentissage. Le modèle devient exceptionnellement bon dans les actions spécifiques que les concepteurs du harnais ont priorisées (par exemple, opérations sur le système de fichiers, bash, répartition des sous-agents).

Cela fait du harnais un système vivant, pas un fichier de configuration statique, et prouve que le « meilleur » harnais est celui optimisé spécifiquement pour vos tâches et flux de travail distincts.

Harnais en tant que service (HaaS)

L'industrie passe de la construction sur des API LLM (qui fournissent des complétions) à la construction sur des API de harnais (qui fournissent un environnement d'exécution). Les SDK offrent désormais la boucle, les outils, la gestion du contexte, les hooks et les bacs à sable directement prêts à l'emploi.

Au lieu de construire l'orchestration à partir de zéro, le défaut moderne est de sélectionner un framework de harnais, de configurer ses piliers centraux et de se concentrer uniquement sur la conception d'invites et d'outils spécifiques au domaine.

C'est ce qui rend le dépannage évolutif : vous ajustez une surface de configuration bien factorisée plutôt que de réinventer toute l'architecture de l'agent.

Où cela mène-t-il ?

Si vous regardez les meilleurs agents de codage aujourd'hui, ils se ressemblent plus que leurs modèles sous-jacents. Les modèles diffèrent, mais les schémas de harnais convergent. L'industrie identifie rapidement l'échafaudage porteur nécessaire pour transformer le texte génératif en logiciel livrable.

Les problèmes ouverts les plus passionnants dépassent les agents uniques : orchestrer plusieurs agents en parallèle, permettre aux agents d'analyser leurs propres traces pour corriger les défaillances au niveau du harnais, et construire des environnements qui assemblent dynamiquement des outils juste-à-temps.

En fin de compte, c'est la phase où les harnais cessent d'être des fichiers de configuration statiques et commencent à agir beaucoup plus comme des compilateurs.

Si vous cherchez un excellent framework de harnais pour agent, @FredKSchott a écrit Flue. C'est solide et apparemment inspiré par une version antérieure de ce billet !