Skip to content
Discutez avec un agent IA
Fondamentaux

Architecture d'un agent harness : les six composantes que votre entreprise doit maîtriser

Orange ITS — Équipe d’ingénierie IA 13 min de lecture

Votre pilote d’agent fonctionne. Puis une mise à jour du modèle sort, un collègue modifie un prompt, et les résultats du rapprochement de factures du mois dernier changent sans bruit. Personne ne sait dire laquelle des pièces autour du modèle en est la cause, parce que personne n’a jamais noté de quelles pièces il s’agit.

C’est la situation d’un responsable technique quand la direction demande : « qu’avons-nous payé exactement, et pouvons-nous le conserver ? » Le modèle est loué. Tout ce qui l’entoure concentre votre investissement, et une bonne part devrait vous appartenir.

Pour les équipes qui veulent cette enveloppe construite autour de leurs propres systèmes, c’est ce que nous réalisons dans notre activité de forward-deployed AI engineering.

Un agent harness se compose de six parties, et l’entreprise devrait maîtriser et documenter chacune d’elles, car ensemble elles déterminent l’auditabilité, la facilité à changer de modèle et la quantité de reprises que vos équipes absorbent. Cet article passe en revue ces six parties, ce qui peut mal tourner dans chacune et l’ordre dans lequel les construire.

Note de périmètre : pour l’angle acheter ou construire, lisez harness IA sur mesure ou copilote SaaS.


Ce qu’est un agent harness

L’équipe d’ingénierie d’Anthropic (Demystifying evals for AI agents) définit l’agent harness (qu’elle appelle aussi scaffold) comme le système qui permet à un modèle d’agir en agent : il traite les entrées, orchestre les appels d’outils et renvoie les résultats. Sa documentation en tire une conséquence : évaluer un agent, c’est évaluer le harness et le modèle qui travaillent ensemble. Changez l’un des deux et le résultat peut changer.

Les éditeurs emploient des vocabulaires différents, mais les pièces se recoupent. Contexte, outils, mémoire, garde-fous, évaluations et orchestration couvrent ce que décrivent les sources, et le tableau ci-dessous est la version que nous utilisons avec nos clients.

ComposanteRôleCe que vous devriez maîtriserDéfaillance typique
ContexteDécide de ce que le modèle voit à chaque étapeFichiers d’instructions et règles de recherche en texte brutInstructions gonflées ou périmées qui augmentent le coût sans améliorer la précision
OutilsPermet à l’agent de lire et de modifier des systèmes réelsDéfinitions des outils, droits d’accès et code d’intégrationDescriptions d’outils floues, d’où le choix de la mauvaise action
MémoireConserve l’état d’une session à l’autreLes fichiers stockés, dans un format exportableNotes périmées prises pour vraies, ou données sensibles écrites dans le stockage
Garde-fousLimite ce que l’agent peut atteindre ou approuverPolitique, sandbox et règles d’approbationRègles écrites sans aucun contrôle technique derrière
ÉvaluationsMesure si le travail était justeCas de test, évaluateurs (graders) et historique des résultatsUn grader défectueux qui annonce le mauvais score avec aplomb
OrchestrationEnchaîne les étapes, les nouvelles tentatives et les passages de relaisLa définition du workflow et ses journauxComplexité ajoutée avant d’avoir montré qu’un agent seul échoue

La suite de l’article les reprend l’une après l’autre.


Contexte : choisir ce que le modèle lit

Les modèles ne lisent pas une quantité illimitée de texte avec la même qualité. Le guide d’Anthropic sur le context engineering parle de « context rot » : le rappel se dégrade à mesure que le nombre de tokens dans la fenêtre augmente, l’objectif étant donc le plus petit ensemble d’informations suffisant pour accomplir la tâche. Parmi ses techniques : récupérer le contenu au moment voulu, condenser les historiques longs, tenir des notes structurées et déléguer des sous-tâches. Le guide en énonce aussi les coûts. L’exploration à l’exécution est plus lente qu’une récupération précalculée, et une condensation trop agressive peut faire perdre un contexte subtil mais décisif. Ce qu’il faut garder, effacer et stocker avant de réduire est traité dans l’article sur l’ingénierie de contexte pour les agents.

Les fichiers d’instructions sont la forme la plus visible du contexte. AGENTS.md en est le format ouvert, et son propre site le présente comme un README pour agents. Des limites pratiques existent : la documentation d’OpenAI Codex indique qu’il cesse d’ajouter des fichiers d’instructions lorsque leur taille cumulée atteint 32 KiB par défaut.

Les données sur la quantité à écrire sont contrastées. Dans une étude de l’ETH Zurich (arXiv 2602.11988), les auteurs ont constaté que les fichiers de contexte n’amélioraient pas en général le taux de réussite des tâches et augmentaient le coût d’inférence de plus de 20 % en moyenne. Les agents suivaient bien les instructions. Ce sont les vues d’ensemble du dépôt, souvent recommandées par les fournisseurs de modèles, qui n’apportaient rien. Les auteurs ont trouvé ces fichiers utiles pour préciser des pratiques non standard, et ceux rédigés par des développeurs ont donné de meilleurs résultats que ceux générés par un modèle.

Ce que cela signifie pour vous : gardez le fichier court, n’y mettez que ce que l’agent ne peut pas déduire de votre code ou de vos documents, et testez-le sur vos propres tâches. L’intérêt pour l’entreprise : moins de tokens dépensés et moins de réponses étranges. Conservez le fichier dans votre propre dépôt, en texte brut, pour qu’il vous suive.


Outils : soigner l’interface comme un produit

Un outil est toute action que l’agent peut effectuer : interroger l’ERP, lire une boîte mail, créer un ticket. Le guide d’Anthropic “Building effective agents” affirme que les définitions d’outils méritent autant d’attention de prompt engineering que le prompt principal, et suggère de rédiger la description d’un outil comme la docstring destinée à un développeur junior. Il recommande aussi de rendre les erreurs plus difficiles dès la conception. Son exemple : exiger des chemins de fichiers absolus a permis à un modèle d’utiliser un outil de façon fiable.

La défaillance est ici discrète. Un outil au nom ambigu ou aux fonctions qui se recouvrent ne plante pas. L’agent en choisit simplement un autre dans une partie des exécutions. Comme le conseille le guide, lancez de nombreux exemples d’entrées, lisez les échecs et ajustez la définition.

Côté propriété, les définitions d’outils et le code d’intégration doivent vous appartenir. S’ils se trouvent dans le constructeur visuel d’un éditeur, demandez un export avant de vous engager. Notre article sur MCP et les outils des agents présente le protocole standard qui rend les outils portables d’un environnement d’exécution d’agents à l’autre.


Mémoire : des fichiers que l’on peut lire et supprimer

La mémoire, c’est tout ce qui survit d’une session à l’autre. La documentation d’Anthropic sur son outil de mémoire précise qu’il fonctionne côté client : le modèle demande des opérations sur les fichiers et votre application les exécute. Le travail de sécurité vous revient donc. La documentation demande aux développeurs de valider chaque chemin pour empêcher le directory traversal, de plafonner la taille des fichiers, de faire expirer ceux qui n’ont pas été consultés depuis longtemps et de retirer les données sensibles avant l’écriture.

Pour une entreprise, c’est plutôt une bonne nouvelle. Une mémoire conservée sous forme de fichiers dans votre stockage est consultable, supprimable et exportable, ce qui compte pour les demandes relatives à la protection des données et pour les audits. Elle échoue aussi de manière prévisible : une vieille note est prise pour un fait actuel. Donnez à chaque fichier de mémoire un responsable et une règle d’expiration.

Dans un article d’avril 2026, Anthropic rapporte que, sur BrowseComp-Plus, un dossier de mémoire a fait passer Sonnet 4.5 de 60,4 % à 67,2 %. Il s’agit d’une seule exécution de l’éditeur, sans réplication indépendante : lisez-la comme un signal encourageant, à confirmer. Notre article sur la mémoire des agents IA détaille les choix de conception.


Garde-fous : une règle exige un contrôle derrière elle

Les garde-fous limitent ce que l’agent peut atteindre et ce qu’il peut faire sans l’approbation d’une personne. La documentation de Claude Code est d’une franchise inhabituelle sur les limites de ses propres modes de permission. Elle indique que le mode le plus permissif n’offre aucune protection contre la prompt injection ou les actions involontaires, et que l’auto mode réduit les demandes d’autorisation sans garantir la sécurité. Elle distingue deux questions : les modes de permission décident si l’agent demande, tandis que les sandbox et l’isolation externe décident de ce qu’une action peut atteindre une fois lancée.

L’article d’Anthropic sur le sandboxing indique qu’il a réduit de 84 % les demandes d’autorisation dans son usage interne, et qu’un sandboxing efficace exige à la fois l’isolation du système de fichiers et celle du réseau. Ce chiffre est une mesure d’Anthropic elle-même, et l’environnement d’exécution était alors publié en research preview bêta.

Une règle écrite n’est pas un contrôle. Un preprint de Ting Yan (arXiv 2608.23550) a examiné 481 fichiers CLAUDE.md publics et estimé que, selon le critère d’appariement le plus strict, seules 4,4 % des règles de sécurité avaient un contrôle intégré correspondant. C’est une étude à auteur unique, portant sur des fichiers publics, et elle ne prouve pas que leurs rédacteurs voulaient voir chaque ligne appliquée. L’enseignement reste valable : si la règle dit « ne jamais toucher à la production », autre chose que le prompt doit le garantir.

Ce que cela signifie pour vous : donnez à l’agent ses propres identifiants avec des droits restreints, journalisez chaque action et exigez une approbation pour tout ce qui est irréversible. L’auditabilité que recherche votre responsable conformité découle de ces journaux et de ces permissions.


Évaluations : l’actif qui survit au modèle

Les évaluations sont les tests qui disent si l’agent a bien fait son travail. L’article d’Anthropic sur les évaluations définit une tâche, un essai (trial), un grader et un résultat, et insiste sur le fait que le résultat est l’état final de l’environnement (la réservation existe-t-elle dans la base de données ?), quoi que l’agent affirme avoir fait. Son conseil pour démarrer est concret : 20 à 50 tâches simples tirées d’échecs réels constituent un excellent début, et les évaluations deviennent plus difficiles à construire à mesure qu’on attend.

Deux détails de cet article comptent pour les dirigeants. D’abord, la constance. Un taux de réussite de 75 % par essai donne environ 42 % si les trois tentatives sur trois doivent réussir. Un agent qui traite correctement une facture trois fois sur quatre n’est pas prêt à travailler sans supervision. Ensuite, les graders peuvent se tromper. L’article indique que les scores peuvent induire en erreur si les graders sont défectueux ou les tâches ambiguës, et décrit un benchmark où des problèmes de notation avaient fait baisser le score initial d’un modèle.

Les évaluations sont aussi la partie la plus portable du harness. Un jeu de cas réels assorti de seuils de réussite convenus fonctionne avec n’importe quel modèle et n’importe quel environnement d’exécution. Quand un éditeur publie un nouveau modèle, vous relancez le jeu et tranchez en un après-midi. Sans lui, changer de modèle relève de l’opinion. Notre guide sur les tests et évaluations des agents IA montre comment construire le premier jeu.


Orchestration : n’ajouter de la structure que lorsqu’un agent seul échoue

L’orchestration décide de la façon dont les étapes sont enchaînées, rejouées et transmises. Anthropic distingue les workflows, où des chemins de code prédéfinis dirigent le modèle, des agents, où le modèle dirige son propre processus. Elle recense cinq schémas courants : prompt chaining, routage, parallélisation, orchestrator-workers et evaluator-optimizer. Son conseil est de chercher la solution la plus simple possible, car les agents entraînent des coûts plus élevés et un risque d’erreurs qui se cumulent.

Les conceptions multi-agents appellent un scepticisme supplémentaire. Dans son article sur les agents de longue durée, Anthropic dit qu’on ne sait pas encore si un seul agent de codage généraliste fonctionne le mieux ou si une architecture multi-agents fait mieux. Son article d’avril 2026 rapporte qu’avec Opus 4.6, le lancement de sous-agents a amélioré les résultats BrowseComp de 2,8 % par rapport aux meilleures exécutions à agent unique, soit un résultat d’éditeur sur une tâche étroite. La position honnête est que les gains de nombreux agents coopérants ne sont pas démontrés, et que les rôles supplémentaires ajoutent des coûts, des journaux à lire et davantage d’endroits où quelque chose peut casser.


Les fichiers qui gardent le cap des agents de longue durée

Une tâche de plusieurs heures s’étend sur de nombreuses sessions, et chaque nouvelle session démarre sans souvenir de la précédente. L’article d’Anthropic sur les harness de longue durée décrit une réponse simple, bâtie avec des fichiers ordinaires. Nous en ajoutons un cinquième, qui est notre propre recommandation et ne fait pas partie de cet article :

  • Un fichier cartographique (notre ajout) tel qu’AGENTS.md ou CLAUDE.md, qui indique à chaque nouvelle session où se trouvent les choses et quelles sont les règles.
  • Un script d’initialisation, que l’article décrit comme un init.sh qui démarre le serveur de développement et lance un contrôle de bout en bout de base.
  • Une liste de fonctionnalités en JSON où chaque fonctionnalité démarre à l’état d’échec. L’article rapporte que le modèle est moins enclin à modifier le JSON de façon inappropriée, que les agents ne peuvent éditer que le champ passes, et que supprimer ou modifier des tests est déclaré inacceptable. Dans la démonstration, elle comptait plus de 200 fonctionnalités.
  • Un journal d’avancement, un fichier texte qui consigne ce qu’a fait chaque session, afin que la suivante puisse reprendre.
  • L’historique Git avec des messages de commit descriptifs, pour pouvoir annuler les mauvaises modifications.

Le travail avance une fonctionnalité à la fois. Les auteurs précisent que la démonstration était réglée pour le développement web full-stack, et ils se contentent de supposer que les enseignements valent pour d’autres domaines.

Ces artefacts valent plus pour l’entreprise qu’il n’y paraît. Ils forment la piste d’audit : ce qui a été tenté, ce qui a réussi, qui a modifié quoi et quand. Ils constituent aussi votre porte de sortie. Un nouveau modèle, ou un nouveau prestataire, peut lire les mêmes fichiers et poursuivre.


Ordre de construction et dates de revue

Ce qu’il faut construire d’abord, et ce qu’on peut écarter

L’ordre compte davantage que l’exhaustivité. Une séquence qui fonctionne pour un premier workflow :

  1. Choisissez un workflow bien délimité et écrivez à quoi ressemble un résultat correct.
  2. Construisez le jeu d’évaluations, en partant de 20 cas issus d’échecs ou de corrections réels du passé.
  3. Définissez les outils dont le workflow a besoin, avec des permissions restreintes et une journalisation.
  4. Rédigez le fichier d’instructions utile le plus court, puis vérifiez si chaque section améliore votre score d’évaluation.
  5. Ajoutez garde-fous et approbations pour tout ce qui est irréversible, appuyés sur des contrôles techniques.
  6. Ajoutez la mémoire lorsque les sessions doivent poursuivre le travail les unes des autres.
  7. Ajoutez l’orchestration seulement si l’agent seul a échoué de façon démontrable.

Écartez tout ce qui fait doublon avec ce que votre plateforme fournit déjà. Écartez les équipes multi-agents jusqu’à ce que l’étape 7 pose la question.

Les composantes vieillissent : prévoyez une revue

Le meilleur argument contre un investissement lourd vient des éditeurs eux-mêmes. Lance Martin, d’Anthropic, écrit dans un article de 2026 que les harness encodent des hypothèses sur ce que le modèle ne sait pas faire seul, et que ces hypothèses vieillissent à mesure que les modèles progressent. Il cite des réinitialisations de contexte conçues pour une génération de modèles qui sont devenues un poids mort avec la suivante. LangChain, dans le même esprit, écrit qu’à mesure que les modèles progressent, ses garde-fous deviendront probablement inutiles. Pour savoir ce que peut valoir un gain obtenu par le seul harness et comment tester quelles règles supprimer, voyez harness engineering.

Le résultat propre de LangChain est en tension avec cela. Dans son article sur l’harness engineering, les seules modifications du harness ont fait passer un agent de codage de 52,8 % à 66,5 % sur Terminal-Bench 2.0, le modèle restant fixe. C’est un seul éditeur, un seul benchmark, réglé sur ce benchmark, et LangChain ne distingue pas l’apport de chaque modification. Ses auteurs préviennent aussi que des changements qui collent trop à une tâche peuvent provoquer des régressions sur d’autres.

Les deux constats peuvent coexister. Le travail sur le harness est rentable aujourd’hui, et une partie sera obsolète après le prochain modèle. D’où le conseil du début : maîtrisez les composantes liées à votre activité (cas de test, accès aux outils, journaux, standards écrits) et traitez le scaffolding générique comme jetable. Posez une date de revue sur chaque composante et relancez le jeu d’évaluations à chaque changement de modèle.

Si vous ne pouvez pas dire aujourd’hui qui maîtrise chacune des six parties, c’est le premier constat de toute revue de harness. L’étape suivante la moins coûteuse est un inventaire d’une page : pour chaque partie, où elle se trouve, qui la maintient et si vous pourriez l’exporter dès demain.

Questions fréquentes

Qu'est-ce qu'un agent harness ?

Un agent harness est le code et la configuration qui entourent un modèle de langage et en font un agent. Anthropic le décrit comme le système qui permet à un modèle d'agir en agent en traitant les entrées, en orchestrant les appels d'outils et en renvoyant les résultats. Dans notre approche, il couvre le contexte, les outils, la mémoire, les garde-fous, les évaluations et l'orchestration, tandis que le modèle fournit le raisonnement.

Qu'est-ce qu'AGENTS.md et en avons-nous besoin ?

AGENTS.md est un format ouvert, en Markdown simple, pour donner des instructions de projet aux agents de codage, souvent présenté comme un README pour agents. Il ne vous faut que si vous faites tourner des agents de codage sur vos propres dépôts. Gardez-le court, car OpenAI Codex cesse de lire les fichiers d'instructions à 32 KiB cumulés par défaut, et vérifiez que chaque ligne sert vraiment.

Quelle composante du harness faut-il construire en premier ?

Commencez par un petit jeu d'évaluations, puis par les outils et le contexte d'un seul workflow bien délimité. Anthropic propose comme bon départ 20 à 50 tâches simples tirées d'échecs réels. Sans ce jeu, vous ne pouvez pas savoir si un changement ultérieur du contexte, de la mémoire ou de l'orchestration a aidé, et tout le reste se construit à l'aveugle.

Faut-il plusieurs agents ?

En général non, au début. Anthropic conseille de chercher la solution la plus simple possible et prévient que les agents entraînent des coûts plus élevés et un risque d'erreurs qui se cumulent. Dans son article sur les agents de longue durée, elle admet qu'on ne sait pas encore si un agent généraliste ou une architecture multi-agents fonctionne le mieux. N'ajoutez des rôles que lorsqu'un agent seul échoue de façon démontrable.

Des modèles plus performants rendront-ils le harness inutile ?

En partie, oui. LangChain indique que ses garde-fous deviendront probablement inutiles à mesure que les modèles progressent, et Anthropic affirme que les hypothèses d'un harness vieillissent. Les composantes qui restent utiles sont celles liées à votre activité : cas de test, accès aux outils, journaux d'audit et définition écrite d'un résultat correct. Revoyez chaque composante à chaque changement de modèle.

Insights

Passez de l’idée à l’action

Un appel de 30 minutes suffit pour savoir si un agent IA s’intègre à votre flux de travail — et ce qu’il rapporterait.