Ingénierie du Harnais : Comment construire des agents IA qui fonctionnent réellement

La plupart des gens essaient de corriger les agents IA à la mauvaise couche.

Quand un agent échoue, ils réécrivent le prompt. Quand il échoue à nouveau, ils ajoutent des instructions, changent de modèle, augmentent la fenêtre de contexte ou connectent un autre outil.

Puis les mêmes problèmes reviennent.

L'agent oublie une décision importante. Il utilise le mauvais outil. Il perd le fil de ce qui s'est passé trois étapes plus tôt. Il affirme que la tâche est terminée sans vérifier le résultat. Il retente la même action en échec jusqu'à épuiser le budget.

Le problème ne vient pas toujours du modèle.

Le problème vient de l'environnement qui l'entoure.

Cet environnement, c'est le harness.

Le Harness Engineering consiste à construire le système autour d'un modèle : un système qui décide de ce qu'il peut voir, de ce qu'il peut faire, de ce dont il se souvient, de ce qui compte comme un succès et de ce qui se passe quand quelque chose échoue.

Un meilleur prompt peut améliorer une seule réponse.

Un meilleur harness améliore chaque exécution.

Suivez mon Substack pour plus d'analyses pratiques sur les agents IA, l'automatisation et les systèmes en production :

substack.com/@lunarresearcher

1. Le modèle n'est pas l'agent

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

Cela n'en fait pas un agent fiable pour autant.

Un véritable agent doit aussi trouver le bon contexte, utiliser des outils, préserver son état, respecter les permissions, vérifier son propre travail et récupérer quand l'environnement se comporte différemment de ce qui était prévu.

Le modèle n'est que le moteur de raisonnement.

Le harness est tout ce qui transforme ce raisonnement en exécution réelle.

1DEMANDE UTILISATEUR
2      |
3      v
4+-----------------------------+
5|           HARNESS           |
6|                             |
7| contrat       contexte      |
8| outils        état          |
9| politique     vérification  |
10| traces        récupération  |
11+-----------------------------+
12      |
13      v
14    MODÈLE
15      |
16      v
17ENVIRONNEMENT RÉEL

Placez le même modèle dans une boîte de chat et il répondra à des questions.

Placez-le dans un dépôt avec accès au terminal, tests, outils navigateur, mémoire de projet, permissions contrôlées et boucle de révision, et il pourra accomplir un vrai travail.

Le modèle n'a pas changé.

Le harness, si.

2. Transformez chaque demande en contrat

Le langage naturel est flexible.

L'exécution autonome ne devrait pas l'être.

Une demande comme :

Améliore le parcours d'onboarding.

convient très bien quand un humain est assis à côté du modèle.

Elle est catastrophique comme instruction de production.

Avant que l'agent n'agisse, transformez la demande en un contrat de tâche délimité.

1objectif: réduire l'abandon lors de l'onboarding
2
3entrées:
4  - brief produit
5  - données analytiques
6  - dépôt
7
8contraintes:
9  - préserver l'authentification
10  - ne pas modifier le schéma de base de données
11  - conserver le comportement mobile actuel
12
13livrable:
14  - pull request révisable
15
16terminé_quand:
17  - les tests passent
18  - l'événement analytique se déclenche correctement
19  - le parcours desktop passe la révision
20  - le parcours mobile passe la révision
21
22approbation_requise:
23  - déploiement en production

L'élément crucial est terminé_quand.

Sans lui, l'agent peut résoudre une version légèrement plus simple du problème et affirmer en toute confiance que la tâche est terminée.

Avec lui, l'achèvement devient mesurable.

L'agent ne devrait pas demander :

Que dois-je faire ensuite ?

Il devrait demander :

Quelle action rapproche l'environnement actuel du résultat convenu dans le contrat ?

C'est une boucle bien plus robuste.

3. Donnez à l'agent une carte, pas une fenêtre de contexte géante

Le réflexe courant face aux erreurs d'un agent est de donner plus de contexte au modèle.

Plus de documentation.

Plus d'historique de conversation.

Plus de fichiers.

Plus de sorties d'outils.

À la fin, l'agent reçoit tout et comprend moins.

Le contexte n'est pas du stockage.

C'est un budget d'attention.

Au lieu de déverser tout le projet dans chaque exécution, donnez à l'agent une petite carte indiquant où se trouvent les informations utiles.

1CARTE DU PROJET
2
3règles produit    -> docs/product/
4architecture      -> docs/architecture.md
5frontend          -> apps/web/
6backend           -> services/api/
7tests             -> tests/
8commandes         -> docs/commands.md
9sécurité          -> docs/security.md

Puis n'étendez cette vue qu'en cas de besoin.

1TÂCHE
2  |
3  v
4CARTE DU PROJET
5  |
6  v
7SYSTÈME PERTINENT
8  |
9  v
10FICHIERS EXACTS
11  |
12  v
13INSTRUCTIONS LOCALES

Le document source décrit cela comme une divulgation progressive : le harness doit charger plus d'informations parce que la tâche en a besoin, et non simplement parce que ces informations existent.

L'objectif n'est pas d'avoir un contexte maximal.

L'objectif est d'avoir un signal utile maximal.

4. Placez une passerelle entre le modèle et ses outils

Un modèle doté de vingt outils n'est pas automatiquement vingt fois plus performant.

Il a peut-être simplement vingt façons supplémentaires d'échouer.

Chaque outil devrait avoir un contrat.

1OUTIL : edit_file
2
3ENTRÉES
4chemin
5patch
6
7PRÉCONDITIONS
8le chemin existe
9le chemin est dans l'espace de travail
10
11SUCCÈS
12patch appliqué
13diff renvoyé
14
15ÉCHEC
16erreur structurée
17aucun écrasement partiel
18
19RISQUE
20réversible

Le chemin d'exécution devient alors :

1LE MODÈLE PROPOSE
2      |
3      v
4LA PASSERELLE VALIDE
5      |
6      v
7LA POLITIQUE AUTORISE
8      |
9      v
10L'OUTIL EXÉCUTE
11      |
12      v
13LE HARNESS ENREGISTRE LE RÉSULTAT

Le modèle décide de l'action qu'il souhaite effectuer.

Le harness décide si cette action est valide, autorisée et sûre.

Cette distinction devient critique lorsque les outils peuvent envoyer des messages, modifier la production, dépenser de l'argent ou supprimer des données.

Une bonne passerelle d'outils peut également ajouter des timeouts, valider les arguments, restreindre les chemins de fichiers, normaliser les erreurs et rendre les tentatives sécurisées.

De bons outils réduisent le nombre de choses que le modèle doit deviner.

5. Sortez la mémoire de la conversation

La conversation ne devrait pas être le système de référence.

Les agents de longue durée finissent par atteindre les limites de contexte, planter, redémarrer ou transmettre le travail à une autre session.

Si chaque décision importante n'existe que dans le transcript, le workflow est fragile.

Stockez l'état durable séparément.

1{
2  "task_id": "feature_042",
3  "status": "vérification",
4  "current_step": "vérification_mobile",
5
6  "completed": [
7    "implémentation",
8    "tests_unitaires",
9    "vérification_desktop"
10  ],
11
12  "decisions": [
13    "réutiliser le endpoint d'export existant",
14    "conserver le format de date actuel"
15  ],
16
17  "artifacts": [
18    "export.csv",
19    "desktop-after.png"
20  ],
21
22  "open_risks": [
23    "la barre d'outils mobile pourrait déborder"
24  ],
25
26  "next_action": "rendre la vue mobile"
27}

Un système efficace sépare la mémoire en quatre catégories :

1FAITS
2connaissances stables
3
4DÉCISIONS
5ce qui a été choisi et pourquoi
6
7ÉTAT
8où en est l'exécution actuelle
9
10LEÇONS
11échecs qui devraient influencer les exécutions futures

La prochaine session de l'agent devrait hériter de l'état du travail, et non d'une histoire compressée de la conversation précédente.

6. Faites de la preuve la condition d'achèvement

Un agent qui dit « terminé » ne prouve pas que le travail est fait.

Ce n'est qu'une sortie de modèle de plus.

Le harness a besoin de preuves observables.

1AFFIRMATION               PREUVE
2
3"le bug est corrigé"      le test qui échouait passe désormais
4
5"la page fonctionne"      le parcours navigateur est terminé
6
7"les données sont justes" les valeurs correspondent à la source
8
9"la migration est sûre"   simulation + rollback réussis
10
11"la tâche est terminée"   tous les critères d'acceptation sont validés

Privilégiez d'abord les vérifications déterministes.

1syntaxe
2  |
3  v
4types
5  |
6  v
7tests ciblés
8  |
9  v
10tests d'intégration
11  |
12  v
13révision visuelle / sémantique
14  |
15  v
16approbation humaine

Ne demandez pas à un autre modèle de répondre à quelque chose qu'un compilateur, un test, un schéma ou une requête de base de données peut prouver.

Utilisez les modèles pour le jugement.

Utilisez les systèmes déterministes pour les faits.

Le modèle crée l'artefact.

L'environnement crée des preuves concernant cet artefact.

Le harness décide si ces preuves sont suffisantes.

7. Séparez le constructeur du vérificateur

L'auto-révision pose un autre problème.

L'agent qui a commis l'erreur transporte souvent les mêmes hypothèses dans sa phase de révision.

Une architecture plus solide sépare l'exécutant du vérificateur.

1CONSTRUCTEUR
2   |
3   v
4crée un candidat
5   |
6   v
7VÉRIFICATEUR
8   |
9   +-- vérifie le contrat
10   +-- cherche les cas manquants
11   +-- teste les affirmations non étayées
12   +-- tente de casser le résultat
13   |
14   +------ SUCCÈS ------> ACCEPTER
15   |
16   +------ ÉCHEC ------> RENVOYER LES PREUVES

Le vérificateur ne devrait pas demander :

Est-ce que ça a l'air correct ?

Il devrait demander :

Qu'est-ce qui rendrait ceci inacceptable ?

Cela transforme la révision : on passe de la confirmation à la tentative de réfutation.

Le document source recommande explicitement de donner à la vérification ses propres critères de rejet et suffisamment d'indépendance pour remettre en question les hypothèses qui ont produit le premier résultat.

8. Sortez les permissions du modèle

Certaines règles ne devraient jamais dépendre de la capacité du modèle à s'en souvenir.

1ne jamais publier sans approbation
2ne jamais exposer de secrets
3ne jamais dépasser la limite de dépenses
4ne jamais écrire en dehors de l'espace de travail
5ne jamais affirmer que les tests ont réussi s'ils n'ont pas été exécutés

Ce ne sont pas des suggestions de prompt.

Ce sont des politiques.

Une échelle de permissions simple :

1FAIBLE RISQUE
2
3lire
4chercher
5inspecter
6
7-> automatique
8
9RÉVERSIBLE
10
11modifier l'espace de travail
12exécuter des tests
13créer un brouillon
14
15-> automatique + trace
16
17EFFET EXTERNE
18
19envoyer
20déployer
21acheter
22
23-> approbation requise
24
25IRRÉVERSIBLE / SENSIBLE
26
27supprimer des données
28faire tourner les identifiants
29publier globalement
30
31-> blocage strict ou interdit

Plus la conséquence est forte, plus le contrôle doit l'être.

Le modèle peut recommander l'action.

Le harness l'autorise.

L'outil l'exécute.

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

C'est la liberté à l'intérieur d'une limite imposée.

9. Arrêtez de retenter à l'aveugle

L'une des pires politiques de récupération est :

Quelque chose a échoué. Réessaie.

Si rien ne change, le système paie simplement pour reproduire le même échec.

Les échecs doivent d'abord être classifiés.

1TIMEOUT D'OUTIL
2-> retenter avec backoff
3
4ARGUMENTS INVALIDES
5-> réparer l'appel d'outil
6
7CONTEXTE MANQUANT
8-> récupérer la source manquante
9
10TEST ÉCHOUÉ
11-> inspecter le comportement défaillant
12
13PERMISSION REFUSÉE
14-> demander une approbation
15
16EXIGENCES CONTRADICTOIRES
17-> escalader
18
19ÉCHEC RÉPÉTÉ SANS CHANGEMENT
20-> arrêter

Une boucle d'agent efficace ressemble à ceci :

1OBSERVER
2   |
3   v
4DÉCIDER
5   |
6   v
7AGIR
8   |
9   v
10MESURER
11   |
12   +---- ACCEPTER
13   |
14   +---- RÉPARER
15   |
16   +---- ESCALADER
17   |
18   +---- ARRÊTER

Chaque boucle devrait avoir des limites en nombre de tentatives, en temps, en dépenses et en portée destructrice.

Un agent fiable doit savoir comment continuer.

Il doit aussi savoir quand une nouvelle tentative n'en vaut plus la peine.

10. Transformez les instructions répétées en infrastructure

Supposons que le prompt contienne :

Exécute toujours le formateur.

Cette règle est plus forte si le formateur s'exécute automatiquement.

Supposons que les instructions disent :

Le code UI ne doit pas accéder directement à la base de données.

C'est plus fort sous forme de test d'architecture qui échoue lorsque la règle est enfreinte.

La progression ressemble à ceci :

1EXPLICATION
2      |
3      v
4CHECKLIST
5      |
6      v
7MODÈLE
8      |
9      v
10VÉRIFICATION AUTOMATISÉE
11      |
12      v
13POLITIQUE IMPOSÉE

Le prompt devrait expliquer le jugement.

Le harness devrait imposer les invariants.

Chaque erreur récurrente devrait descendre un peu plus bas sur cette échelle.

À terme, le modèle n'a plus besoin de retenir la leçon.

L'environnement s'en souvient pour lui.

11. Enregistrez l'exécution

Un artefact final parfait peut masquer un chemin d'exécution désastreux.

Peut-être que l'agent a accédé à la mauvaise source.

Peut-être qu'il a ignoré une commande en échec.

Peut-être qu'il a répété deux fois une action externe.

Peut-être qu'il a dépensé dix fois le budget prévu.

Peut-être qu'il a trouvé la bonne réponse pour la mauvaise raison.

Enregistrez suffisamment d'informations pour reconstituer ce qui s'est passé.

109:14  contrat de tâche créé
209:15  architecture.md chargé
309:17  checkout.ts modifié
409:18  échec du test ciblé
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 bloqué : approbation requise

Les traces utiles incluent les sources de contexte, les appels d'outils, les changements d'état, les résultats de vérification, les raisons des nouvelles tentatives, les décisions d'approbation, le coût et la latence.

L'idée n'est pas de collecter des logs pour le plaisir.

L'idée est de localiser l'échec.

Si l'étape 18 casse, vous devriez pouvoir réparer l'étape 18.

Vous ne devriez pas avoir à rejouer toute l'exécution.

12. Fournissez un reçu pour chaque exécution

Ne forcez pas un humain à relire un transcript de quarante messages.

Compilez le résultat dans un petit reçu.

1OBJECTIF
2
3Corriger l'application en double des coupons.
4
5MODIFIÉ
6
7validation du checkout
8test de non-régression
9
10VÉRIFIÉ
11
12lint réussi
13tests unitaires réussis
14test d'intégration réussi
15
16NON VÉRIFIÉ
17
18fournisseur de paiement en production
19
20RISQUES
21
22client mobile legacy indisponible
23
24APPROBATION NÉCESSAIRE
25
26déploiement en staging

Ce n'est pas un résumé de ce que le modèle prétend s'être passé.

C'est un résumé de ce que le harness peut prouver s'être passé.

Cette distinction rend le reçu utile pour les révisions, les passations et les futures sessions d'agent.

13. Faites en sorte que chaque échec améliore le harness

La plupart des équipes corrigent le résultat défaillant.

La meilleure approche consiste à corriger le système qui a permis l'échec.

1CONTEXTE MANQUANT
2-> améliorer la carte du projet
3
4MAUVAIS OUTIL
5-> améliorer le routage ou le contrat de l'outil
6
7MAUVAIS RÉSULTAT
8-> ajouter un validateur
9
10BOUCLE RÉPÉTÉE
11-> ajouter une limite de tentatives
12
13ACTION NON SÛRE
14-> ajouter une barrière de permission
15
16DÉCISION PERDUE
17-> persister l'état
18
19ÉCHEC INCONNU
20-> améliorer le traçage

C'est là que le Harness Engineering commence à produire des effets cumulatifs.

Un résultat réparé aide une seule exécution.

Un harness réparé améliore toutes les exécutions suivantes.

Les meilleurs systèmes d'agents deviennent plus fiables parce que les erreurs laissent derrière elles de l'infrastructure.

14. Commencez par le plus petit harness utile

Vous n'avez pas besoin d'une énorme plateforme d'orchestration pour démarrer.

Construisez par couches.

1NIVEAU 0
2
3prompt
4modèle
5
6NIVEAU 1
7
8contrat de tâche
9carte du projet
10outils
11
12NIVEAU 2
13
14état structuré
15vérification
16boucle délimitée
17
18NIVEAU 3
19
20permissions
21traces
22récupération
23barrières humaines

Une courte tâche de recherche peut n'avoir besoin que d'un prompt et d'une révision.

Une tâche de codage de six heures avec accès aux fichiers, au réseau et capacité de déploiement en nécessite beaucoup plus.

Ajoutez de la complexité uniquement lorsque la surface d'échec le justifie.

Pas parce que l'architecture d'agents a l'air cool.

La checklist du Harness Engineering

Avant d'accorder une autonomie significative à un agent, demandez-vous :

1[ ] Le succès est-il défini avant l'exécution ?
2
3[ ] L'agent peut-il trouver le bon contexte
4    sans tout charger ?
5
6[ ] Chaque outil a-t-il un objectif clair,
7    un schéma et un état d'échec ?
8
9[ ] Les décisions importantes sont-elles stockées
10    en dehors de la conversation ?
11
12[ ] L'achèvement exige-t-il des preuves ?
13
14[ ] Les actions risquées sont-elles protégées par une politique ?
15
16[ ] Chaque boucle a-t-elle une limite de tentatives ?
17
18[ ] L'exécution peut-elle reprendre après une interruption ?
19
20[ ] Pouvez-vous reconstituer chaque action importante ?
21
22[ ] Un échec améliore-t-il une règle, un outil,
23    un test, une carte ou une permission ?
24
25[ ] La modification finale peut-elle être annulée ?

Si plusieurs réponses sont négatives, un modèle plus puissant ne rendra pas automatiquement l'agent fiable.

Il pourrait simplement rendre l'échec plus rapide et plus coûteux.

Le véritable changement de paradigme

Le Prompt Engineering demande :

Que dois-je dire au modèle ?

Le Context Engineering demande :

Que devrait savoir le modèle à cet instant précis ?

Le Harness Engineering demande :

Quel système permet au modèle d'agir, de vérifier son travail, de récupérer après un échec et d'opérer en toute sécurité ?

1PROMPT
2-> instruction
3
4CONTEXTE
5-> vue de travail
6
7HARNESS
8-> environnement d'exploitation
9
10BOUCLE
11-> correction locale
12
13GRAPHE
14-> coordination

Les modèles continueront de changer.

L'avantage durable se construit autour d'eux.

Vos contrats s'améliorent.

Vos outils s'améliorent.

Vos tests s'améliorent.

Votre état devient plus propre.

Vos permissions deviennent plus sûres.

Votre logique de récupération devient plus intelligente.

Vos échecs se transforment en infrastructure.

C'est ainsi que des modèles performants deviennent des agents fiables.

C'est ça, le Harness Engineering.

Si vous êtes arrivé jusqu'ici

Mettez ce guide en favoris.

Suivez-moi sur X : x.com/0xjmori

Abonnez-vous à mon Substack : substack.com/@lunarresearcher

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