Harness Engineering : Le guide complet pour créer des agents IA robustes

La plupart des gens tentent d'améliorer les agents IA au mauvais niveau.

Quand un agent échoue, ils réécrivent le prompt.

Quand il échoue à nouveau, ils ajoutent plus d'instructions.

Avant de commencer :

Suivez mon Substack pour des infos exclusives sur l'IA, des workflows d'agents et des guides pas à pas avant leur publication sur X : [https://substack.com/@lunarresearcher

Ensuite, ils changent de modèle, ajoutent plus d'outils, augmentent la fenêtre de contexte, et espèrent que la prochaine exécution se comportera différemment.

Mais de nombreux échecs d'agents ne sont pas des échecs de raisonnement.

Ce sont des échecs d'environnement.

L'agent ne savait pas quels fichiers étaient importants.

Il a utilisé le bon outil au mauvais endroit.

Il a perdu les décisions prises lors de la session précédente.

Il a prétendu avoir réussi sans exécuter les vérifications.

Il a répété une action après un échec partiel.

Il avait la permission de faire quelque chose qui aurait dû nécessiter une approbation.

Le modèle n'était pas nécessairement le problème. Le système autour du modèle était incomplet.

Ce système, c'est le harnais.

Et sa conception devient une discipline d'ingénierie à part entière.

L'ingénierie du harnais est la pratique qui consiste à construire l'environnement qui transforme l'intelligence du modèle en travail fiable.

Un prompt modifie une tentative.

Un harnais modifie chaque tentative.

Ce guide explique comment en construire un.

1. Le Modèle N'est Pas l'Agent

Un modèle peut raisonner, générer, comparer et choisir.

Mais un agent doit aussi interagir avec un environnement réel.

Il doit :

• comprendre la tâche
• trouver le contexte pertinent
• sélectionner et utiliser des outils
• préserver l'état
• respecter les permissions
• inspecter le résultat
• se remettre d'un échec
• prouver que le travail est terminé

Le modèle est le moteur de raisonnement à l'intérieur de ce système.

Le harnais est tout ce qui rend le raisonnement opérationnel.

1requête utilisateur
2     |
3     v
4+-----------------------------+
5|          HARNAIS            |
6| contrat | contexte | règles |
7| outils  | état     | contrôles |
8| traces  | reprise            |
9+-----------------------------+
10     |
11     v
12    modèle
13     |
14     v
15environnement réel

Un modèle puissant dans un harnais faible reste un agent faible.

Il peut produire des réponses individuelles impressionnantes, mais il se comportera de manière incohérente sur des tâches longues, des environnements changeants et des échecs partiels.

L'objectif de l'ingénierie du harnais n'est pas de supprimer l'incertitude du modèle.

C'est de contenir cette incertitude à l'intérieur d'un système capable d'observer, de vérifier et de récupérer.

2. Commencez par un Contrat de Tâche

La plupart des tâches d'agent commencent par une intention vague :

Améliorer le flux d'onboarding.

Cette phrase peut suffire pour une conversation.

Elle ne suffit pas pour une exécution autonome.

Avant que l'agent n'agisse, le harnais doit convertir la demande en un contrat de tâche.

Un contrat utile répond à cinq questions :

1. Quel résultat doit exister ?
2. Qu'est-ce qui est dans le périmètre ?
3. Qu'est-ce qui ne doit pas changer ?
4. Quelles preuves attestent de l'achèvement ?
5. Quelles actions nécessitent une approbation humaine ?

1objectif : réduire l'abandon lors de l'onboarding
2
3périmètre :
4  - flux d'inscription
5  - analytics de l'onboarding
6
7contraintes :
8  - ne pas modifier l'authentification
9  - préserver le comportement mobile existant
10
11acceptation :
12  - les tests passent
13  - l'événement analytics est émis
14  - les captures d'écran couvrent desktop et mobile
15
16approbation_requise :
17  - déploiement en production
18  - migration de base de données

Cela transforme la question de l'agent de :

Que dois-je faire ensuite ?

à :

Quelle action rapproche l'environnement du résultat contracté ?

Sans contrat, l'agent optimise pour une activité plausible.

Avec un contrat, il peut optimiser pour un achèvement vérifié.

3. Donnez une Carte à l'Agent, Pas un Manuel

Déverser l'intégralité du dépôt, de la documentation et de l'historique des conversations dans le contexte n'est pas une bonne ingénierie du contexte.

C'est une inondation de contexte.

Le harnais doit d'abord fournir une petite carte, puis laisser l'agent récupérer les détails lorsqu'ils deviennent pertinents.

1CARTE DU PROJET
2
3règles produit      -> docs/produit/
4architecture        -> docs/architecture.md
5frontend            -> apps/web/
6backend             -> services/api/
7tests               -> tests/
8commandes           -> docs/commandes.md
9règles de version   -> docs/version.md

C'est la divulgation progressive :

1tâche
2  -> carte du projet
3      -> sous-système pertinent
4          -> fichiers exacts
5              -> instructions locales

Le contexte doit s'étendre parce que la tâche l'exige, pas parce que l'information existe.

Un bon compilateur de contexte décide :

• ce qui est toujours nécessaire
• ce qui peut être récupéré plus tard
• ce qui est devenu obsolète
• ce qui peut être résumé
• ce qui doit rester textuel

L'objectif n'est pas le contexte maximum.

C'est le maximum de signal par token.

4. Construisez une Passerelle d'Outils, Pas un Tas d'Outils

Donner vingt outils à un agent ne le rend pas compétent.

Cela donne à l'agent vingt façons de faire une erreur.

Chaque outil doit avoir un contrat clair :

1OUTIL : edit_file
2
3entrées :
4  chemin
5  correctif
6
7conditions préalables :
8  le chemin existe
9  le chemin est dans l'espace de travail autorisé
10
11preuve de succès :
12  correctif appliqué
13  diff résultant retourné
14
15comportement en cas d'échec :
16  pas de réécriture partielle
17  erreur structurée retournée
18
19classe de risque :
20  réversible

Le harnais doit contrôler comment les outils sont exposés et utilisés.

Il peut :

• masquer les outils non pertinents
• valider les arguments
• restreindre les chemins et domaines
• attacher des délais d'attente
• rendre les tentatives idempotentes
• normaliser les sorties
• exiger une confirmation pour les actions risquées
• retourner des preuves, pas seulement un "succès"

Cela crée une séparation importante :

1le modèle décide de l'intention
2la passerelle valide l'action
3l'outil modifie l'environnement
4le capteur observe le résultat

Le modèle peut proposer une action.

La passerelle d'outils décide si cette action est suffisamment valide pour être exécutée.

5. Séparez le Cerveau, les Mains et l'Historique

De nombreux agents fragiles mélangent tout dans un seul transcript qui grossit.

Le raisonnement, les appels d'outils, les fichiers, les décisions, les erreurs et les anciennes observations se disputent la même fenêtre de contexte.

Un système plus solide sépare trois responsabilités :

1CERVEAU
2planifie, raisonne, choisit
3
4MAINS
5exécute les outils dans un environnement contrôlé
6
7HISTORIQUE
8stocke les faits durables, les décisions et l'état de l'exécution

Le modèle n'a pas besoin de chaque événement brut dans le contexte actif.

Il a besoin du bon état courant.

Le bac à sable n'a pas besoin de comprendre l'objectif entier.

Il doit exécuter en toute sécurité une action limitée.

Le journal de session n'a pas besoin de raisonner.

Il doit préserver ce qui s'est passé après la disparition du contexte actuel.

Cette séparation rend les agents à longue durée de vie plus faciles à reprendre, inspecter et réparer.

Elle vous permet également de remplacer une partie sans reconstruire l'ensemble du système.

6. La Mémoire Doit Devenir un État Durable

L'historique des conversations n'est pas une mémoire fiable.

C'est un flux d'événements.

La mémoire utile doit être convertie en état explicite.

Au minimum, préservez quatre catégories :

1FAITS
2informations stables découvertes sur l'environnement
3
4DÉCISIONS
5choix effectués et la raison derrière eux
6
7PROGRÈS
8travail terminé, actif, bloqué et restant
9
10LEÇONS
11échecs qui devraient modifier le comportement futur

Par exemple :

1faits :
2  - la validation du panier se trouve dans services/commandes
3
4décisions :
5  - réutiliser le pipeline de validation existant
6  - raison : évite une deuxième source de vérité
7
8progrès :
9  terminé :
10    - ajout d'une règle côté serveur
11  restant :
12    - mettre à jour le test d'intégration
13
14leçons :
15  - la commande de test locale nécessite TEST_DB_URL

C'est bien plus utile que de rejouer cinquante pages de transcript en espérant que le modèle remarque la ligne importante.

Stockez l'historique brut pour l'auditabilité.

Compilez l'état durable pour l'exécution.

7. L'Achèvement Nécessite des Preuves

Un agent qui dit "fini" n'est pas une preuve que la tâche est terminée.

Ce n'est qu'une autre sortie du modèle.

L'achèvement doit être déterminé par des changements observables dans l'environnement.

1affirmation                    preuve
2--------------------------------------------------
3"le bug est corrigé"           le test qui échouait passe maintenant
4"la page fonctionne"           le flux navigateur est terminé
5"la migration est sûre"        le dry run et le rollback réussissent
6"le rapport est correct"       les valeurs correspondent aux données source
7"la tâche est terminée"        toutes les vérifications d'acceptation passent

Le harnais doit d'abord exécuter les vérifications déterministes les moins coûteuses.

1syntaxe
2  -> types
3      -> tests ciblés
4          -> tests d'intégration
5              -> revue visuelle ou sémantique
6                  -> approbation humaine

N'utilisez pas un autre modèle là où un compilateur, un schéma, une somme de contrôle, une requête ou un test peut répondre à la question.

Utilisez les modèles pour l'ambiguïté.

Utilisez le code pour la plomberie.

Un modèle peut proposer que la tâche est terminée.

Seul l'environnement peut le prouver.

8. La Vérification Doit Attaquer le Résultat

Les travailleurs et les évaluateurs ne doivent pas partager le même objectif.

Le travailleur essaie de créer la solution la plus solide.

L'évaluateur essaie de trouver la raison pour laquelle elle devrait être rejetée.

1travailleur
2  -> produit un candidat
3
4vérificateur
5  -> vérifie le contrat
6  -> cherche les cas manquants
7  -> teste les affirmations non étayées
8  -> tente de casser le résultat
9
10survit
11  -> accepter
12
13échoue
14  -> retourner des preuves ciblées

Cette asymétrie est importante.

Si vous demandez au même agent, dans le même contexte, de "vérifier son travail", il préserve souvent les hypothèses qui ont créé l'erreur.

Une étape de vérification utile doit avoir :

• une grille de rejet explicite
• un accès à l'artefact produit
• un accès au contrat d'acceptation
• des outils indépendants ou un contexte frais si nécessaire
• la permission de rejeter sans réparer

La vérification n'est pas un second avis.

C'est une tentative de réfutation.

9. Le Modèle Propose, la Politique Autorise

Certaines règles ne doivent jamais dépendre du fait que le modèle s'en souvienne.

1ne jamais publier sans approbation
2ne jamais exposer un secret
3ne jamais écrire en dehors de l'espace de travail
4ne jamais dépasser le plafond de dépenses
5ne jamais marquer les tests comme réussis s'ils n'ont pas été exécutés

Ce ne sont pas des suggestions de prompt.

Ce sont des politiques.

La conception la plus sûre maintient la politique en dehors de la boucle de raisonnement.

1RISQUE FAIBLE
2lire des fichiers, rechercher, inspecter
3-> automatique
4
5CHANGEMENT RÉVERSIBLE
6modifier l'espace de travail, exécuter des tests
7-> automatique avec trace
8
9EFFET EXTERNE
10envoyer un message, déployer, acheter
11-> approbation explicite
12
13IRRÉVERSIBLE OU SENSIBLE
14supprimer des données, faire pivoter des identifiants, publier globalement
15-> barrière stricte ou interdit

Plus la conséquence est forte, plus la barrière est dure.

L'autonomie n'est pas l'absence de contrôle.

C'est la capacité d'opérer librement à l'intérieur d'une frontière clairement appliquée.

10. La Reprise Doit Cibler la Classe d'Échec

La stratégie de reprise la plus courante est :

Quelque chose a échoué. Réessayez.

Ce n'est pas une reprise.

C'est une répétition.

Le harnais doit classer l'échec avant de sélectionner l'action suivante.

1délai d'attente de l'outil
2-> réessayer avec backoff
3
4arguments invalides
5-> réparer l'appel d'outil
6
7contexte manquant
8-> récupérer la source spécifique
9
10test échoué
11-> inspecter le comportement défaillant
12
13permission refusée
14-> demander l'approbation ou choisir une voie sûre
15
16exigences contradictoires
17-> escalader vers un humain
18
19échec répété inchangé
20-> arrêter la boucle

Une tentative de reprise doit modifier au moins une condition pertinente.

Sinon, le système paie pour reproduire le même échec.

Une boucle d'agent bornée ressemble à ceci :

1observer
2  -> décider
3      -> agir
4          -> mesurer
5              -> accepter
6              -> réparer
7              -> escalader
8              -> arrêter

Chaque boucle a besoin d'un budget :

• nombre maximum de tentatives
• temps maximum
• dépense maximum
• portée destructive maximum
• condition d'escalade

Les agents fiables savent comment continuer.

Ils savent aussi quand continuer n'est plus rationnel.

11. Les Instructions Doivent Devenir une Infrastructure

Les instructions de l'agent sont utiles lorsqu'elles expliquent la réalité locale.

Mais les instructions seules sont une application faible.

Si une règle compte de manière répétée, descendez-la dans la pile.

1"utilisez le formateur"
2-> exécuter le formateur automatiquement
3
4"n'importez pas entre les couches"
5-> ajouter un test d'architecture
6
7"incluez un rollback de migration"
8-> exiger un fichier de rollback dans le CI
9
10"ne modifiez pas les fichiers générés"
11-> bloquer les écritures vers les chemins générés
12
13"citez chaque affirmation externe"
14-> valider la couverture des citations

Cela crée une échelle d'instructions :

1explication
2  -> liste de contrôle
3      -> modèle
4          -> vérification automatisée
5              -> politique appliquée

Descendez les connaissances importantes aussi bas que possible sur cette échelle.

Le prompt doit expliquer le jugement.

Le harnais doit appliquer les invariants.

12. Observez l'Exécution, Pas Seulement la Réponse Finale

Un artefact final propre peut cacher un processus terrible.

L'agent a peut-être :

• accédé aux mauvaises données
• ignoré une commande qui a échoué
• réessayé une action externe deux fois
• consommé dix fois le budget attendu
• atteint la bonne réponse pour la mauvaise raison

Vous avez besoin de traces qui rendent l'exécution reconstructible.

109:14  contrat créé
209:15  source de contexte chargée : architecture.md
309:17  fichier modifié : checkout.ts
409:18  test ciblé échoué : coupon en double
509:21  implémentation réparée
609:22  test ciblé réussi
709:24  test d'intégration réussi
809:25  déploiement externe bloqué : approbation requise

Une trace utile enregistre :

• les transitions d'état
• les sources de contexte
• les entrées et sorties des outils
• les modifications de l'environnement
• les résultats de vérification
• les raisons des tentatives
• les décisions d'approbation
• le coût et la latence

L'objectif n'est pas la surveillance.

L'objectif est la réparation locale.

Lorsqu'une exécution échoue à l'étape 18, vous devez pouvoir redémarrer à partir d'un point de contrôle fiable au lieu de rejouer toute la tâche.

13. Chaque Exécution a Besoin d'un Reçu de Modifications

Les longs transcripts d'agent sont difficiles à examiner.

À la fin d'une exécution, le harnais doit compiler un petit reçu de modifications.

1OBJECTIF
2Corriger l'application de coupon en double lors du paiement.
3
4MODIFIÉ
5- logique de validation du paiement
6- test de régression ciblé
7
8VÉRIFIÉ
9- lint réussi
10- tests unitaires réussis
11- test d'intégration du paiement réussi
12
13NON VÉRIFIÉ
14- fournisseur de paiement en production
15
16DÉCISIONS
17- ordre de priorité des coupons existant préservé
18
19RISQUES
20- client mobile héritage non disponible localement
21
22APPROBATION NÉCESSAIRE
23- déployer en staging

Le reçu n'est pas un résumé de ce que le modèle a dit.

C'est un résumé de ce que le système peut prouver.

Cela donne aux humains une surface de révision compacte et donne à la prochaine session d'agent un point de départ fiable.

La meilleure transition n'est pas "voici la conversation".

C'est "voici l'état, les preuves et le risque non résolu".

14. Chaque Échec Doit Améliorer le Harnais

Les équipes les plus faibles corrigent le résultat qui a échoué.

Les équipes les plus fortes corrigent également le système qui l'a permis.

Après un échec, demandez :

1Le contrat de tâche était-il ambigu ?
2Un contexte important était-il invisible ?
3Le mauvais outil était-il exposé ?
4Une condition préalable manquait-elle ?
5Le résultat était-il invérifiable ?
6La politique était-elle laissée dans le prompt ?
7La reprise était-elle trop large ?
8La trace était-elle insuffisante ?

Convertissez ensuite la leçon en une amélioration réutilisable.

1échec
2  -> diagnostic
3      -> nouveau capteur, règle, carte, test ou contrat d'outil
4          -> les exécutions futures s'améliorent automatiquement

C'est le volant d'inertie du harnais.

Le système devient plus fiable parce que les échecs laissent une infrastructure derrière eux.

Une réponse corrigée aide une exécution.

Un harnais corrigé aide chaque exécution future.

15. Les Harnais se Détériorent Aussi

Plus de harnais n'est pas toujours meilleur.

Les modèles s'améliorent. Les outils s'améliorent. Les tâches changent. Les anciennes sauvegardes peuvent devenir des frictions inutiles.

Un contournement créé pour le modèle d'hier peut empêcher le modèle d'aujourd'hui d'utiliser une meilleure stratégie.

Cela crée une détérioration du harnais :

1limitation de l'ancien modèle
2  -> contournement du harnais
3      -> le modèle s'améliore
4          -> le contournement reste
5              -> le système devient plus lent ou moins performant

Traitez les composants du harnais comme du code de production.

Mesurez s'ils apportent toujours une valeur ajoutée.

Pour chaque routeur, évaluateur, couche de mémoire et règle de tentative, demandez :

• Quel échec cela empêche-t-il ?
• À quelle fréquence cet échec se produit-il encore ?
• Quelle latence et complexité cela ajoute-t-il ?
• Le même résultat peut-il maintenant être obtenu plus simplement ?
• Que se passe-t-il si nous le supprimons ?

Le meilleur harnais n'est pas le plus grand.

C'est le plus petit système qui comble de manière fiable l'écart entre l'intention et la preuve.

Construisez pour supprimer.

16. Le Harnais Minimum Viable

Vous n'avez pas besoin d'une plateforme d'orchestration pour commencer.

Construisez le harnais en couches.

Niveau 1 : Une tâche délimitée

• objectif
• périmètre
• contraintes
• vérifications d'acceptation

Niveau 2 : Un environnement lisible

• carte du projet
• commandes
• instructions locales
• dépendances connues

Niveau 3 : Actions contrôlées

• outils typés
• validation des arguments
• limites de chemin et de permission
• résultats structurés

Niveau 4 : Exécution durable

• état d'exécution explicite
• points de contrôle
• décisions
• leçons

Niveau 5 : Preuves

• vérifications déterministes
• vérification contradictoire
• reçu de modifications

Niveau 6 : Reprise et apprentissage

• classification des échecs
• tentatives limitées
• escalade
• mises à jour du harnais à partir des échecs récurrents

Construisez la plus petite couche qui élimine l'échec que vous avez réellement.

Ne commencez pas par une architecture multi-agents parce qu'un seul prompt a parfois besoin de clarification.

La complexité doit être gagnée par l'observation de l'échec.

17. Une Spécification de Harnais Réutilisable

Avant de donner une autonomie significative à un agent, définissez ceci :

1SPÉCIFICATION DU HARNAIS D'AGENT
2
31. CONTRAT
4   objectif :
5   périmètre :
6   contraintes :
7   preuve d'acceptation :
8
92. CONTEXTE
10   carte toujours chargée :
11   sources de récupération :
12   instructions locales :
13   règles de fraîcheur :
14
153. OUTILS
16   outils autorisés :
17   conditions préalables :
18   effets secondaires :
19   preuve de succès :
20   politique de délai d'attente et de tentative :
21
224. ÉTAT
23   faits :
24   décisions :
25   progrès :
26   leçons :
27   format du point de contrôle :
28
295. POLITIQUE
30   actions automatiques :
31   actions nécessitant une approbation :
32   actions interdites :
33   limites budgétaires :
34
356. VÉRIFICATION
36   vérifications déterministes :
37   vérifications contradictoires :
38   règle d'acceptation :
39
407. REPRISE
41   classes d'échec :
42   limites de tentative :
43   conditions d'escalade :
44   rollback sécurisé :
45
468. OBSERVABILITÉ
47   événements de trace :
48   métriques :
49   reçu final de modifications :

Si ces champs ne sont pas définis, l'agent n'est pas autonome.

Il improvise.

18. Mesurez le Système au Bon Niveau

Le nombre de tokens n'est pas la métrique finale.

Pas plus que le nombre de tâches tentées.

L'unité utile est le travail accepté.

Une métrique pratique est :

1sorties acceptées
2------------------------------
3minutes de revue humaine + coût d'exécution

Suivez également :

• taux d'acceptation au premier passage
• taux de reprise après un échec d'outil
• taux d'échec répété
• interventions humaines par tâche
• affirmations d'achèvement non étayées
• temps entre la demande et le résultat vérifié
• surcharge du harnais par composant

Cela évite une illusion courante :

Un agent peut sembler très productif tout en créant un travail de révision coûteux.

L'objectif n'est pas plus d'activité de l'agent.

C'est plus de résultats fiables par unité d'attention humaine.

19. Quand Vous N'avez Pas Besoin d'un Harnais Lourd

Tous les appels de modèle n'ont pas besoin d'un système d'exploitation.

Utilisez un prompt simple lorsque :

• la tâche est courte
• la sortie est facile à inspecter
• l'échec est peu coûteux
• aucun effet secondaire externe ne se produit
• l'utilisateur reste dans la boucle

Ajoutez un harnais lorsque :

• le travail s'étend sur plusieurs outils ou sessions
• l'environnement peut changer
• les actions ont des conséquences réelles
• l'achèvement est difficile à juger manuellement
• le même échec apparaît de manière répétée
• la revue humaine devient le goulot d'étranglement

Le but d'un harnais n'est pas de rendre une démo sophistiquée.

C'est de rendre le travail réel fiable.

Le Vrai Changement

La première génération de produits IA a été construite autour des prompts.

La prochaine génération est construite autour des environnements.

La question n'est plus seulement :

Comment améliorer la réponse du modèle ?

Elle est :

Comment construire un système où les bonnes actions sont faciles, les actions dangereuses sont contrôlées, les échecs sont visibles et l'achèvement est prouvable ?

C'est le passage de l'ingénierie du prompt à l'ingénierie du harnais.

Le modèle fournit l'intelligence.

Le harnais fournit la structure.

Ensemble, ils produisent une exécution fiable.

Si votre agent continue de s'effondrer, arrêtez d'ajouter des adjectifs au prompt.

Construisez l'environnement dont il a besoin pour réussir.

Si Vous Êtes Allé Jusqu'au Bout

Ajoutez ce guide à vos favoris.

Suivez @LunarResearcher sur X

Abonnez-vous à mon Substack

Envoyez cet article à quelqu'un qui essaie encore de corriger chaque échec d'agent avec un prompt plus long.