Bonnes pratiques pour les Agent Harness : 10 règles pour les agents en production

Le modèle est rarement la partie la plus difficile aujourd'tous les jours. Les modèles de pointe sont suffisamment performants pour que, pour de nombreuses charges de travail d'agents, passer de l'un à l'autre se résume à modifier un champ de configuration. Ce qui sépare un agent qui fonctionne dans une démo d'un agent qui fonctionne toujours de manière fiable trois mois après sa mise en production, c'est tout ce qui entoure le modèle : la boucle (loop), le contexte, les outils, le sandbox, les approbations et les contrôles qui l'empêchent de faire quelque chose d'irréversible.

Cette couche est l'agent harness, et les décisions que vous y prenez peuvent avoir un impact plus important sur la fiabilité et les coûts que le choix du modèle lui-même. Nous l'avons appris en construisant et en exploitant TrueForge, notre agent harness open-source. Voici les 10 meilleures pratiques pour les agent harness que nous recommandons si vous développez des agents pour la production aujourd'hui.

Pourquoi le Harness détermine votre facture

Commençons par un chiffre, car il recadre tout ce qui suit. Nous avons utilisé l'Enterprise-Bench de DevRev : 14 tâches inter-systèmes de difficulté variable qui ressemblent à du véritable travail d'opérations B2B. Pour répondre à l'une d'entre elles, un agent doit planifier, appeler des outils MCP sur trois systèmes (un CRM de type Salesforce, un gestionnaire de projets de type Jira et un espace de stockage de documents et de transcriptions d'appels de type Drive), croiser correctement les résultats et synthétiser la réponse avec le bon niveau de détail.

La précision est quasiment identique. Le modèle fixe le plafond ; le harness ne rend pas le modèle sous-jacent plus intelligent.

Ce que le harness détermine, en revanche, c'est la quantité de travail nécessaire pour atteindre ce plafond.

Dans ce benchmark, TrueForge a résolu à peu près le même nombre de tâches que Claude Managed Agents tout en utilisant environ 62 % de tokens en moins et en coûtant environ 28 % de moins par exécution. Par rapport à deepagents, la différence de tokens était encore plus importante.

C'est l'aspect de l'infrastructure d'agents qui est facile à négliger. Deux agents peuvent utiliser le même modèle, avoir accès aux mêmes outils et tenter la même tâche, mais générer des coûts d'exécution très différents.

La différence provient de ce qui se passe autour du modèle : la quantité de contexte qu'il conserve, les outils qu'il charge, la façon dont il gère les réponses volumineuses, le moment où il compacte l'état et l'efficacité avec laquelle il exécute la boucle.

Lire la méthodologie complète du benchmark →

La quasi-totalité de l'écart de coût dans ce benchmark s'explique par les quatre premières pratiques.

TrueForge : Agent Harness Open-Source

TrueForge est l'agent harness open-source et neutre vis-à-vis des fournisseurs de TrueFoundry, conçu pour les équipes qui souhaitent un meilleur contrôle sur l'exécution de leurs agents en production. Au lieu de lier le runtime à un seul fournisseur de modèles, TrueForge vous permet d'apporter vos propres modèles, serveurs MCP et infrastructures tout en gérant la boucle de l'agent, l'exécution des outils, la gestion du contexte, les approbations et le sandboxing.

Là où un agent auto-hébergé comme Hermes laisse une grande partie de l'infrastructure de production au développeur, TrueForge fournit le plan de contrôle environnant nécessaire pour faire fonctionner des agents à travers plusieurs équipes et environnements. Cela comprend l'accès et les identifiants MCP centralisés, les approbations human-in-the-loop, l'exécution isolée (sandboxed), l'observabilité et la gouvernance.

Vous pouvez l'exécuter localement avec npx @truefoundry/trueforge ou le déployer pour une équipe avec Docker Compose ou Helm.

TrueForge sépare également le runtime de l'agent de la couche modèle. Cela signifie que les équipes peuvent changer de modèle ou router les charges de travail vers différents fournisseurs sans reconstruire l'agent lui-même. Combiné avec l'AI Gateway de TrueFoundry, les équipes peuvent également appliquer le routage de modèles et des contrôles de coûts pour éviter d'utiliser des modèles de pointe coûteux pour des tâches qui ne le nécessitent pas. Le résultat est un juste milieu entre un runtime entièrement géré et le développement de l'intégralité de l'infrastructure d'agent par vous-même : un agent harness open-source doté des contrôles opérationnels nécessaires pour faire fonctionner des agents de production à grande échelle.‍

TrueFoundry fournit également un second levier pour réduire les coûts des modèles grâce à l'Auto Routing de l'AI Gateway. Au lieu d'envoyer chaque requête à un modèle de pointe, l'Auto Routing classifie les requêtes par complexité et les achemine vers différents niveaux de modèles. Dans le benchmark de TrueFoundry portant sur 550 prompts, le routage entre Haiku, Sonnet et Opus a réduit les coûts de 69 % tout en conservant 98 % de la qualité de référence, et la latence moyenne est passée de 7,6 secondes à 4,0 secondes. Sur du trafic représentatif de la production, la réduction globale des coûts a atteint 80 %.

Ces deux couches répondent à différents aspects de l'équation des coûts. TrueForge réduit le surcoût lié à l'exécution de l'agent lui-même, tandis que le routage de modèles vous évite d'utiliser un modèle coûteux lorsque la tâche ne le justifie pas. Pour les équipes qui exploitent des agents à grande échelle, disposer de ces deux contrôles peut importer plus que le seul prix du modèle.

TrueForge est open-source et sous licence MIT, tandis que l'AI Gateway de TrueFoundry ajoute la couche opérationnelle dont les équipes ont besoin lors du passage d'agents individuels à la production : accès centralisé aux modèles, budgets, guardrails, gestion des identifiants et traces unifiées.

Si vous comparez Claude Managed Agents avec une architecture plus configurable, TrueFoundry vaut la peine d'être pris en considération lorsque la flexibilité des modèles, le contrôle de l'infrastructure et l'optimisation des coûts des agents comptent autant que le runtime de l'agent lui-même.

Une alternative open-source à Claude Managed Agents, jusqu'à 75 % moins chère

Exécutez des agents IA prêts pour la production sur votre propre infrastructure avec TrueForge, en utilisant les modèles, outils et fournisseurs de sandbox de votre choix.

Voir sur GitHub

Documentation

Bonnes pratiques d'ingénierie du contexte (Context Engineering)

C'est ici que se jouent les économies. Le context engineering est la discipline qui consiste à décider ce que le modèle voit à chaque tour d'interaction, et sur un agent qui s'exécute longtemps, l'impact s'accumule tour après tour.

1. Traitez la fenêtre de contexte comme un budget, pas comme un tampon (buffer)

Ce qui pose problème : vous connectez cinq serveurs MCP, chaque schéma d'outil se charge au démarrage, et l'agent consomme des dizaines de milliers de tokens pour des définitions d'outils qu'il n'appellera jamais. Chaque tour suivant les transporte.

Ce qu'il faut faire : chargez les schémas d'outils à la demande plutôt qu'au préalable. Une bonne gestion du contexte d'un agent commence avant le premier appel au modèle, et non après que la fenêtre se soit remplie.

Dans TrueForge : le chargement différé des outils (deferred tool loading) donne à l'agent un index léger et ne récupère le schéma complet que lorsqu'il tente d'utiliser cet outil.

2. Compactez, ne tronquez pas

Ce qui pose problème : la fenêtre se remplit, le harness supprime le contenu le plus ancien, et l'agent oublie silencieusement la contrainte que vous lui avez donnée au troisième tour. Il ne génère pas d'erreur. Il devient simplement moins bon, et la défaillance est difficile à repérer car la sortie semble toujours plausible.

Ce qu'il faut faire : résumez l'historique ancien sous forme d'enregistrement structuré et conservez ce résumé. Définissez le seuil sous la limite maximale afin que la compaction se produise selon vos règles et non sous la pression.

Dans TrueForge : la compaction s'enclenche à 80 % de la longueur de contexte du modèle et remplace l'historique ancien par un résumé structuré. La troncation convient pour un agent de support rapide, mais s'avère extrêmement nuisible sur une tâche s'étalant sur plusieurs heures.

Une mise en garde importante : la compaction comporte son propre risque si les politiques et les contraintes ne résident que dans la conversation. Nous avons écrit sur la façon dont la compaction érode la gouvernance et pourquoi l'application des règles doit se faire en dehors de la fenêtre de contexte.

3. Déchargez les réponses volumineuses des outils au lieu de les intégrer en ligne

Ce qui pose problème : un outil renvoie une charge utile JSON de 200 Ko, l'intégralité se retrouve dans la fenêtre de contexte, alors que l'agent n'avait besoin que de trois champs.

Ce qu'il faut faire : écrivez la charge utile dans un endroit accessible par l'agent et donnez-lui une référence plutôt que le contenu brut.

Dans TrueForge : le déchargement des réponses volumineuses d'outils écrit la réponse dans un fichier de sandbox et la remplace par un chemin et un aperçu. Le Mode Code (Code Mode) va plus loin, en permettant à l'agent de chaîner plusieurs appels d'outils dans un seul script de sandbox afin que seul le résultat imprimé entre dans le contexte. Cinq allers-retours deviennent un seul résumé.

4. Donnez aux sous-agents un contexte propre et ne récupérez que le résultat

Ce qui pose problème : un sous-agent hérite du fil d'exécution parent complet, accomplit son travail et renvoie l'intégralité de son historique de raisonnement dans le contexte parent. Vous avez désormais payé deux fois pour le même historique et pollué le fil principal.

Ce qu'il faut faire : la délégation doit réduire le contexte du parent, pas l'augmenter.

Dans TrueForge : les sous-agents s'exécutent avec leur propre contexte propre et ne renvoient que le résultat final.

Essayez-le : npx @truefoundry/trueforge exécute un harness avec ces quatre fonctionnalités activées par défaut, localement, en une minute environ. Ajoutez une étoile sur GitHub.

Exécution et sécurité

5. Faites du sandbox un outil, pas un wrapper

Ce qui pose problème : le harness englobe chaque session dans un conteneur, que l'agent exécute du code ou non. Vous payez du temps de conteneur pour des conversations qui n'étaient que du texte, et un seul serveur peut héberger beaucoup moins d'agents simultanés.

Ce qu'il faut faire : approvisionnez le sandbox uniquement lorsque l'agent a réellement besoin d'exécuter quelque chose. Le sandboxing d'agents concerne le rayon d'impact (blast radius), et vous obtenez le même isolement sans payer pour cela à chaque tour.

Dans TrueForge : le sandbox est un outil, démarré uniquement lorsque l'agent doit exécuter du code, ainsi un seul serveur gère de nombreux agents et les tours qui ne touchent jamais au code restent peu coûteux. Les fournisseurs de sandbox sont configurables à votre guise (bring-your-own).

L'argument plus approfondi en faveur de permettre aux modèles d'exécuter sans les laisser errer mérite d'être lu si vous concevez cela à partir de zéro.

6. Validez les actions irréversibles, et uniquement celles-ci

Ce qui pose problème : les équipes abordent les approbations selon deux extrêmes. Soit rien n'est contrôlé et un agent finit par supprimer quelque chose, soit tout est contrôlé et un humain clique sur approuver quarante fois par heure jusqu'à ce qu'il ne lisent plus les demandes.

Ce qu'il faut faire : conditionnez la validation à l'irréversibilité. Envoyer un e-mail, écrire en production, dépenser de l'argent, supprimer quoi que ce soit. Les lectures et les brouillons s'exécutent librement. Et n'essayez pas de mettre en œuvre une exigence de conformité en la décrivant dans le system prompt en espérant qu'elle soit suivie, car un prompt est une suggestion là où les guardrails qui inspectent chaque appel d'outil sont un contrôle strict.

Dans TrueForge : le serveur central met en pause l'exécution et attend l'approbation pour les actions sensibles avant que l'appel ne soit envoyé, plutôt qu me après.

L'emplacement de ce point de contrôle importe tout autant que son existence, un sujet que nous avons abordé dans la conception des approbations d'outils MCP aux limites du gateway.

7. Rendez les sessions résilientes aux déconnexions

Ce qui pose problème : un ordinateur portable se met en veille, un équilibreur de charge réinitialise une connexion, et quarante minutes de travail de l'agent sont perdues. Sur des tâches qui s'exécutent pendant une heure, cela cesse d'être un cas limite.

Ce qu'il faut faire : persistez l'état de la session afin qu'une connexion interrompue reprenne au lieu de redémarrer.

Dans TrueForge : les sessions persistent malgré les déconnexions et les redémarrages. La reprise de session (resumability) est l'une de ces propriétés que personne ne demande lors de la revue de conception mais dont tout le monde a besoin dès la deuxième semaine.

Opérations et gouvernance

8. Instrumentez la boucle, pas seulement le modèle

Ce qui pose problème : vous disposez du nombre de tokens et de la latence par appel de modèle, mais aucune idée de l'étape qui a déraillé au cours d'une exécution de 60 étapes. Le débogage devient de l'archéologie.

Ce qu'il faut faire : émettez des événements structurés pour chaque étape, de sorte qu'une exécution se lisent comme une chronologie plutôt que comme un mur de journaux (logs). Vérifiez que la boucle elle-même est observable avant de devoir la déboguer dans l'urgence.

Dans TrueForge : chaque étape est transmise en streaming au fur et à mesure, et le contrat de runtime d'événements d'agent est publié afin que vos propres outils puissent le consommer.

La formulation utilisée dans l'ingénierie de boucle (loop engineering) est utile ici : la boucle est le middleware, traitez-la donc comme une infrastructure.

9. Conservez la possibilité de changer de modèle

Ce qui pose problème : l'agent est écrit pour le SDK et les spécificités d'un seul fournisseur. Un modèle moins cher ou plus performant sort et le remplacer nécessite une réécriture, alors vous ne changez pas.

Ce qu me qu'il faut faire : interagissez avec les modèles via des interfaces compatibles OpenAI et gardez les spécificités des fournisseurs hors de la logique de votre agent.

Dans TrueForge : les modèles, les serveurs MCP et les fournisseurs de sandbox sont tous interchangeables via des interfaces ouvertes. Ce n'est pas une valeur purement théorique. Dans le même benchmark, exécuter TrueForge sur GLM-5.2 au lieu d'Opus 4.8 a résolu les mêmes ~11 tâches sur 14 pour 2,90 $ par exécution contre 8,50 $. Cette économie n'est possible que si le changement se résume à une modification de configuration.

10. Centralisez la gouvernance dès que vous dépassez une poignée d'agents

Ce qui pose problème : chaque équipe détient ses propres clés de modèles et identifiants MCP. Personne ne peut plafonner les dépenses, le masquage des PII est incohérent et répondre à un audit implique de regrouper les journaux de neuf services différents.

Ce qu'il faut faire : placez un gateway entre vos agents et tout ce qu'ils appellent.

Dans TrueForge : ce n'est délibérément pas le rôle du harness. En auto-hébergé, vous apportez vos propres clés et les gérez vous-même, ce qui fonctionne jusqu'à ce que vous exécutiez beaucoup d'agents. À ce stade, pointez vers l'AI Gateway de TrueFoundry, qui place plus de 1 000 LLM derrière une API unique compatible OpenAI avec environ 3 à 4 ms de latence ajoutée et plus de 350 RPS sur un seul vCPU, avec RBAC, budgets, guardrails, rotation des identifiants et traces OpenTelemetry vers Grafana, Datadog ou Prometheus.

Vous gérez plus de quelques agents ? Découvrez comment l'AI Gateway les gouverne de manière centralisée, ou réservez une démonstration si vous souhaitez l'adapter à votre configuration.

Comment TrueForge gère ces règles

Neuf des dix règles sont intégrées dans le harness. La dixième ne l'est pas délibérément, car un harness qui cherche aussi à être votre plan de contrôle a tendance à être mauvais dans les deux domaines.

Quatre Anti-Patterns

Reconstruire une boucle qui existe déjà. Si vous écrivez la logique planifier-agir-observer à partir de zéro, vérifiez si un harness ne la fournit pas déjà. La conception d'un agent harness ne vaut votre temps que si votre problème est véritablement inédit.

Compter sur le prompting pour assurer un contrôle. Les étapes de conformité, les plafonds de dépenses et les portes de validation doivent résider dans le code ou au niveau d'un gateway. Un modèle à qui l'on demande gentiment quelque chose peut s'en laisser dissocier par la discussion.

Tout mettre en sandbox. L'isolement à chaque tour coûte réellement cher et n'apporte rien sur les tours qui n'exécutent jamais de code.

Mesurer le modèle au lieu de l'exécution globale. Le nombre de tokens par appel peut sembler correct alors que le coût total par tâche accomplie triple silencieusement. Mesurez l'exécution complète.

FAQ

Q : Quelles sont les meilleures pratiques pour un agent harness ?

R : Celles qui comptent le plus sont les pratiques liées au contexte : charger les schémas d'outils à la demande, compacter l'historique plutôt que de le tronquer, décharger les réponses volumineuses des outils dans des fichiers et séparer le contexte des sous-agents de celui du parent. Ensuite, n'approvisionnez les sandbox que lorsque le code s'exécute, validez les actions irréversibles, persistez les sessions entre les déconnexions et émettez des événements structurés pour chaque étape. Dans notre benchmark, ces décisions ont représenté une différence de plus de 4x sur le nombre de tokens par exécution pour des tâches identiques.

Q : Comment empêcher un agent de manquer de contexte sur une longue tâche ?

R : Par la compaction, pas par la troncation. Résumez l'historique plus ancien dans un enregistrement structuré lorsqu'un seuil est atteint (environ 80 % de la longueur du contexte du modèle), afin que l'agent conserve le fil au lieu de le perdre silencieusement. Associez cela au chargement différé des outils et au déchargement des réponses pour que la fenêtre se remplisse moins vite dès le départ.

Q : Faut-il placer chaque session d'agent dans un sandbox ?

R : Non. Placez l'exécution du code dans un sandbox, pas la session. Maintenir un conteneur ouvert pendant toute une conversation coûte de l'argent à chaque tour qui n'exécute pas de code, et cela limite le nombre d'agents qu'un serveur peut gérer. L'approvisionnement à la demande vous offre la même isolation pour une fraction du coût.

Q : Puis-je exécuter un agent harness dans mon propre VPC ou on-prem ?

R : Oui, avec n'importe quelle option auto-hébergée. TrueForge s'exécute avec une seule commande npx localement, ou via Docker Compose et Helm pour un déploiement d'équipe avec Postgres, Redis, des réplicas et une authentification OIDC. La plateforme gérée de TrueFoundry s'exécute également en auto-hébergé, on-prem, air-gapped ou en environnement hybride, garantissant qu'aucune donnée ne quitte votre domaine.

Q : TrueFoundry prend-il en charge MCP et les agents issus d'autres frameworks ?

R : Oui. La plateforme inclut un MCP Gateway, un Agent Gateway et un registre avec un contrôle d'accès au niveau des outils. Les agents développés sur LangGraph, CrewAI, AutoGen ou un framework personnalisé peuvent être gouvernés via cette même couche, de sorte que ces pratiques ne vous obligent pas à adopter une seule pile technologique.

Lectures connexes

• Agent Harness vs Agent Framework : Quelle est la véritable différence ? : la distinction de catégorie qui sous-tend tout ceci
• Context Engineering : Concevoir ce que votre agent IA voit : la version approfondie des pratiques 1 à 4
• Les Agent Sandboxes expliqués : pourquoi le sandbox est un outil et non un wrapper
• Loop Engineering : La boucle est le nouveau middleware : traiter le runtime comme une infrastructure
• TrueForge vs Claude Managed Agents : la méthodologie et les résultats complets de l'Enterprise-Bench

Conclusion

Les meilleures pratiques pour les agent harness se résument à une habitude : décider délibérément de ce que le modèle voit et de ce qu'il est autorisé à faire, puis mesurer l'ensemble de l'exécution plutôt que l'appel individuel. Les équipes qui appliquent cela obtiennent des agents qui coûtent quatre fois moins cher et dont les défaillances peuvent être facilement diagnostiquées.

Vous n'avez pas à nous croire sur parole pour les chiffres. TrueForge est sous licence MIT et la méthodologie du benchmark est publiée, vous pouvez donc la tester sur vos propres tâches.

npx @truefoundry/trueforge pour l'essayer en une minute environ, lisez la documentation, ou réservez une démonstration si vous préférez le voir appliqué à votre stack.

‍