14 juillet 2026
Universal Agent Harness : construire une couche d’exécution commune pour les agents IA
Objectifs mesurables, contexte juste-à-temps, ports, machines à états, évaluations, mémoire et preuves : comment je construis un harness portable pour Claude Code, Codex CLI, Hermes et d’autres runtimes.
Dossier d’architecture, d’ingénierie agentique et d’évaluation — état consolidé au 14 juillet 2026
Un agent fondé sur un grand modèle de langage peut écrire du code, analyser une documentation, appeler des outils et proposer des décisions. Cette puissance ne suffit pourtant pas à produire un système de travail fiable. Entre une démonstration réussie et une capacité professionnelle durable se trouvent des problèmes moins spectaculaires : comment définir précisément le résultat attendu, charger seulement le contexte utile, empêcher une action hors périmètre, reprendre après une interruption, vérifier les tests sans croire la déclaration du modèle, conserver les preuves et transformer l’expérience en actifs réutilisables ?
Universal Agent Harness, ou UAH, est ma réponse à cette couche manquante. Le projet fournit un environnement opératoire distribuable dans un dépôt cible. Il rassemble un GOAL harness, un protocole d’exécution, des workflows, des skills, des agents spécialisés, des hooks, des adaptateurs de runtime, un cycle d’ingénierie durable, des évaluations, une mémoire et un système de traces. Son objectif n’est pas de rendre un modèle omniscient. Il cherche à rendre le travail agentique adressable, borné, observable, reprenable et vérifiable.
Ce dossier ne présente pas UAH comme une plateforme autonome achevée. L’état courant est plus nuancé : les distributions principales et une grande partie du noyau déterministe sont validées localement ; les tests racine et ceux du Durable Engineering Cycle passent ; trois scénarios de cycle ont été rejoués hors ligne sans appel réseau ; le retrieval filtré est solide sur son corpus canonique. En revanche, la stabilité indépendante et GraphCAG restent sous gate, l’observabilité provider live est incomplète, un chemin Claude demeure marqué CONTEXT_UNRELIABLE, et la publication publique est bloquée tant que les licences ne sont pas définies.
Un harness utile ne promet pas qu’un agent aura toujours raison. Il organise les conditions permettant de détecter qu’il se trompe, de limiter les conséquences, de reprendre le travail et de conserver une preuve exploitable.
1. Pourquoi un agent puissant reste difficile à exploiter
Un modèle moderne peut résoudre une tâche isolée avec une qualité impressionnante. Lorsqu’il doit intervenir durablement sur un projet réel, plusieurs formes de fragilité apparaissent.
La première concerne l’objectif. Une demande telle que « améliore ce projet », « corrige les problèmes » ou « rends le système SOTA » ne définit ni la portée, ni les critères de réussite, ni les risques acceptables. Un agent peut alors produire beaucoup de changements sans résoudre le problème prioritaire. Il peut aussi optimiser la métrique la plus visible, déplacer une dette vers une autre zone ou considérer qu’un résultat plausible équivaut à un résultat démontré.
La deuxième fragilité concerne le contexte. Charger trop peu d’informations conduit à ignorer une décision architecturale, un fichier de statut ou une contrainte métier. Charger tout le dépôt n’est pas une solution : le signal pertinent se dilue, les informations historiques entrent en conflit avec l’état courant, le coût augmente et les instructions importantes perdent leur poids relatif. Un contexte long peut donner une impression de couverture tout en réduisant la précision opérationnelle.
La troisième fragilité concerne la continuité. Une session peut être interrompue par un quota, une erreur réseau, un redémarrage ou un changement de worker. Sans état partagé, le nouveau processus doit reconstruire le raisonnement depuis des fragments. Il risque de répéter des actions, de perdre une décision ou de modifier une zone déjà stabilisée.
La quatrième concerne l’autorité. Un agent capable d’appeler un shell, une API, un gestionnaire de secrets ou un outil de production possède une capacité d’effet réelle. Une instruction textuelle lui demandant « d’être prudent » ne constitue pas une politique de sécurité. Il faut classer les actions, limiter les permissions, exiger un dry-run ou une approbation et empêcher certaines transitions au niveau logiciel.
Enfin, la réussite elle-même doit être définie indépendamment du modèle. Un LLM peut affirmer que les tests passent sans les avoir lancés, conclure qu’une documentation est alignée alors qu’un statut est obsolète, ou interpréter un benchmark favorable en ignorant son corpus et sa taille d’échantillon. Le système doit donc distinguer le travail proposé par le modèle des faits mesurés par des mécanismes déterministes.
UAH traite ces problèmes comme les responsabilités d’une infrastructure. Le modèle demeure important, mais il devient un worker parmi d’autres dans un environnement qui connaît l’objectif, l’état du cycle, les permissions, les preuves attendues et les conditions de clôture.
2. Ce qu’est UAH — et ce qu’il n’est pas
Universal Agent Harness est un pack opératoire portable destiné à rendre un agent immédiatement plus compétent sur un projet donné. Il ne s’agit pas simplement d’un fichier d’instructions. Le dépôt contient une CLI installable, des sources de vérité universelles, des scaffolds, des workflows, des skills, des hooks, des agents, des registres, des distributions, des évaluations et un moteur de cycle déterministe.
Le flux conceptuel initial peut être résumé ainsi :
GOAL.md + OPERATING_PROTOCOL.md
→ workflows et skills
→ sélection d’assets et contexte minimal
→ adaptateurs Claude / Codex / Hermes / universel
→ distribution vers le projet cible
→ exécution, évaluation, traces et capitalisationLe rôle du harness est de fournir un cadre stable autour de workers remplaçables. Un changement de modèle, de runtime, de client ou de secteur ne devrait pas forcer une réécriture du noyau. Les éléments variables sont portés par des profils, des adaptateurs et des packs de contexte. Les règles fondamentales — objectifs, cycle, permissions, évaluations et preuves — restent aussi indépendantes que possible de la marque du modèle.
UAH n’est pas un remplacement de Strategic Gen OS. Strategic Gen OS définit la gouvernance plus large de l’entreprise augmentée : capacités, organisation, logiciels open source, rôles humains, agents experts et chaînes de responsabilité. UAH intervient plus bas dans la pile pour rendre l’exécution d’une mission technique ou agentique cohérente.
UAH ne remplace pas non plus Agentic Asset Orchestrator. L’orchestrateur inventorie, classe et sélectionne les assets pertinents. Le harness consomme cette sélection pour assembler le contexte opératoire et distribuer les bons fichiers, workflows ou agents dans le runtime cible. Confondre les deux conduirait à mélanger le problème du retrieval avec celui de l’exécution.
Enfin, UAH n’est pas un framework multi-agent monolithique. Il peut se brancher sur plusieurs environnements. Le noyau définit des ports conceptuels et des contrats ; les runtimes, providers et outils concrets restent des adaptateurs. Cette séparation est essentielle pour tester plusieurs solutions, retirer un composant insuffisant et éviter qu’un choix temporaire devienne la structure irréversible du système.
L’ambition est donc précise : fournir une couche commune permettant de passer d’un agent générique à un worker qui connaît son objectif, son périmètre, les assets mobilisables, les gates à franchir et l’état réel du travail.
3. Une vérité éditoriale séparée de la vision cible
Les projets agentiques sont particulièrement exposés à une forme de dérive documentaire : l’architecture cible, les prototypes, les tests locaux et les capacités réellement disponibles finissent par être décrits avec le même vocabulaire. Une roadmap mentionnant une fonction peut être relue quelques semaines plus tard comme la preuve qu’elle existe. Un benchmark favorable peut masquer une autre suite en échec. Une démo hors ligne peut être présentée comme l’équivalent d’une exécution provider réelle.
Pour éviter ce problème, ce dossier utilise cinq statuts explicites.
Opérationnel et vérifié signifie qu’une fonction a été exécutée récemment avec une preuve reproductible. Les distributions principales, les tests et le scénario E2E déterministe entrent dans cette catégorie pour le périmètre local testé.
Validé hors ligne signifie qu’un comportement a été démontré avec des workers simulés ou des commandes déterministes, sans dépendre d’un modèle externe. Ce niveau est utile : il permet de tester les locks, les transitions, les checkpoints, la reprise, les checksums et les règles de clôture. Il ne prouve cependant pas qu’un provider réel suivra toujours le contrat.
Partiellement intégré décrit une chaîne dont les composants existent mais dont la validation bout en bout est incomplète. L’observabilité en est un exemple : la collecte JSONL, les schémas, les métriques locales et les exports existent, mais la couverture de sessions provider réussies reste insuffisante pour une qualification globale.
Bloqué indique qu’une gate empêche une revendication supérieure. Au moment de cette publication, la décision est REMEDIATION_IN_PROGRESS et la classification globale reste BLOCKED parce que quatre gates locales sur vingt et une ne passent pas encore. Dix-sept gates sont validées, mais les quatre restantes changent la conclusion générale et interdisent une qualification de release.
Architecture cible décrit une direction conçue mais non livrée intégralement. Les pipelines de datasets pour fine-tuning local, l’interopérabilité étendue et certaines chaînes A2A appartiennent en partie à ce niveau.
Cette distinction n’est pas une prudence de communication ajoutée après coup. Elle constitue une fonctionnalité du projet. UAH contient des registres de promotion, un truth_doctor, un claim linter, des décisions KEEP, HOLD, REVERT et des packs de preuves. La maturité est conçue comme une donnée à vérifier, pas comme une impression.
Une conséquence importante est que plusieurs résultats peuvent être vrais simultanément. Le retrieval filtré peut être en KEEP, les tests déterministes peuvent être au vert, et le produit global rester en HOLD ou BLOCKED parce que la stabilité indépendante, une intégration provider ou une contrainte de licence n’est pas résolue. Le dossier publie donc les réussites et les limites dans le même tableau de bord.
4. Le GOAL harness : transformer une intention en contrat
Le premier rôle du harness consiste à empêcher qu’une intention vague devienne une exécution incontrôlée. Un objectif exploitable doit préciser le problème, la portée, les résultats attendus, les critères d’acceptation, les contraintes et les preuves nécessaires.
Le GOAL harness donne une structure à cette définition. Il répond à plusieurs questions avant que l’agent commence à modifier quoi que ce soit :
- Quel état concret doit être atteint ?
- Quels fichiers, composants ou systèmes entrent dans le périmètre ?
- Quelles zones sont explicitement hors scope ?
- Quels tests ou mesures permettront de conclure ?
- Quels risques exigent une approbation ?
- Quel résultat doit être capitalisé ?
- Quelles affirmations sont interdites sans preuve ?
Cette formalisation réduit le reward hacking. Sans critères préalables, un agent peut choisir après l’exécution la métrique qui valorise le mieux son travail. Avec une golden task, un rubric et des gates figés, il devient plus difficile de modifier les règles pour faire monter artificiellement le score.
Le GOAL n’est toutefois pas une spécification immuable. Une phase d’inspection peut découvrir que l’objectif initial repose sur une hypothèse fausse. Le harness doit alors produire une décision visible : ajuster la portée avec validation, bloquer l’exécution ou demander une revue humaine. Il ne doit pas silencieusement changer la définition du succès.
Le passage du GOAL à l’action s’effectue par plusieurs niveaux : audit de l’existant, recherche lorsque la fraîcheur compte, plan primaire, plan final, lots testables, tests, documentation et capitalisation. Chacune de ces étapes produit un artefact pouvant être relu par un autre worker.
Cette approche est particulièrement utile dans un projet ancien ou complexe. L’agent ne reçoit pas seulement « le ticket ». Il reçoit aussi les décisions d’architecture, les conventions de contribution, la source de vérité sur le statut, les commandes de validation et les règles de sécurité. L’objectif devient alors un contrat situé dans un système, plutôt qu’une phrase isolée dans une conversation.
5. L’Operating Protocol : une méthode de travail commune
Le GOAL décrit le résultat. L’Operating Protocol décrit la manière de travailler pour l’atteindre. Il fournit une discipline commune à plusieurs runtimes et évite que chaque session réinvente sa propre méthode.
La séquence de base est volontairement simple.
Comprendre le contexte minimal utile. L’agent identifie les sources canoniques, le statut courant, les limites et la zone affectée. Il ne charge pas automatiquement toutes les archives.
Auditer avant de créer. Il vérifie l’existant, les fonctions proches, les scripts, les décisions et les composants adjacents. Cette étape limite les doublons et les nouvelles couches inutiles.
Rechercher lorsque la fraîcheur compte. Les standards, bibliothèques, protocoles et réglementations peuvent changer. Une recherche externe devient obligatoire lorsque la mémoire du modèle n’est pas une source suffisamment fiable.
Planifier en deux temps. Un plan primaire expose la compréhension et les risques. Le plan final incorpore les vérifications et découpe le travail en lots mesurables.
Exécuter par lots testables. Une modification importante n’est pas traitée comme un bloc opaque. Chaque lot possède une hypothèse, une action, une validation et une décision.
Documenter l’état réel. Les fichiers de statut, les décisions, le backlog et les preuves sont mis à jour en fonction de ce qui a réellement passé les gates. La documentation n’est pas une synthèse marketing parallèle au dépôt.
Capitaliser les répétitions. Lorsqu’une solution réapparaît, elle devient un skill, un workflow, un script, un agent, un test, une checklist ou un runbook. Le harness ne cherche pas seulement à terminer une tâche ; il cherche à réduire le coût des tâches futures.
Cette méthode permet aussi de comparer les workers. Claude Code, Codex CLI ou Hermes peuvent avoir des styles de raisonnement et des capacités d’outillage différents. Tant qu’ils respectent le même protocole, leurs résultats peuvent être évalués avec des critères communs. L’agnosticisme ne consiste donc pas à prétendre que tous les runtimes sont identiques. Il consiste à définir un contrat permettant de mesurer leurs différences sans réécrire l’ensemble du système.
Le protocole reste néanmoins soumis à l’enforcement réel. Une instruction dans AGENTS.md peut être ignorée ou mal interprétée. Pour les contraintes critiques, UAH ajoute des hooks, des schémas, des scripts et des gates déterministes. La documentation indique l’intention ; le logiciel bloque les transitions qui ne satisfont pas le contrat.
6. Un noyau agnostique fondé sur des ports
UAH est conçu pour rester utilisable lorsque le fournisseur de modèle, le runtime, le secteur, la source de données ou le client change. Cette ambition impose de distinguer ce qui doit rester stable de ce qui doit varier.
Le noyau stable comprend le GOAL harness, le protocole opératoire, le cycle des workflows, les schémas d’assets, les évaluations, les guardrails et la politique de capitalisation. Ces éléments expriment des intentions durables : sélectionner un asset, exécuter une capacité, mesurer un résultat, stocker une décision ou demander une approbation.
Les éléments variables sont raccordés par des ports conceptuels.
LlmProviderPort permet de changer de fournisseur ou de modèle sans déplacer les règles métier dans l’intégration. AgentRuntimePort raccorde Claude Code, Codex, Hermes ou un worker local. DataSourcePort permet de lire des fichiers, un CRM, un datalake, une API ou une base. AssetSelectionPort délègue la recherche à l’orchestrateur. EvaluationPort fournit les mesures. MemoryPort enregistre les événements et les patterns. PermissionPort applique la politique d’action.
Un port n’est pas uniquement une abstraction de code. Il définit un contrat observable : entrées, sorties, erreurs, idempotence, risques, preuves, délais et stratégie de reprise. Un adaptateur runtime doit traduire ce contrat vers la syntaxe et les capacités concrètes du worker.
Cette architecture permet de retirer un choix insuffisant. GraphCAG, par exemple, possède une voie expérimentale mais reste inactif par défaut parce que les gates de précision et de stabilité ne sont pas franchies. Le reste du harness peut continuer à fonctionner sans forcer cette dépendance dans le noyau.
Elle permet également de comparer les providers. Un modèle peut produire de meilleurs plans mais échouer à respecter un schéma structuré dans un environnement précis. Un autre peut être plus stable sur les commandes d’ingénierie, mais plus coûteux. Ces différences sont traitées dans les profils et les évaluations, pas cachées derrière une promesse d’universalité abstraite.
7. Sélection juste-à-temps : charger moins, mais mieux
L’un des problèmes centraux d’un harness est de déterminer ce que l’agent doit connaître avant d’agir. Une approche naïve consiste à exposer tous les skills, tous les agents, tous les plugins et toute la documentation au démarrage. Elle maximise la couverture apparente, mais elle augmente le bruit, la latence et le risque de choisir une ressource inadaptée.
UAH s’appuie sur une sélection juste-à-temps consommée depuis l’Asset Orchestrator. L’architecture cible combine plusieurs étapes : inventaire des assets, routage par capacité et préconditions, retrieval lexical, retrieval dense, fusion, reranking, expansion graphique optionnelle, contrôle correctif, compression et assemblage d’un pack propre au runtime.
Le résultat n’est pas seulement une liste de fichiers. Il peut inclure pour chaque asset un score, des raisons de sélection, des préconditions et un niveau de confiance. Le context pack précise son mode — rapide, approfondi, exécution, sécurité ou capitalisation — ainsi qu’un budget de tokens et l’éventuel recours à un fallback.
Cette chaîne doit savoir s’abstenir. Si le retrieval ne trouve pas suffisamment de signal, le système doit lancer une recherche ciblée ou demander une clarification plutôt que compléter le contexte avec des éléments faiblement liés.
Les mesures actuelles illustrent à la fois le potentiel et les limites de cette approche. Le benchmark filtered canonique est en KEEP avec un recall@5 de 0,930 et une precision@5 de 0,840 sur 544 assets. Le holdout combiné est également en KEEP, avec un blind à 0,837/0,682 et un adversarial à 0,967/0,620. Ces valeurs ne doivent toutefois pas être extrapolées à toutes les formulations.
La stabilité indépendante reste en HOLD : recall@5 0,583, precision@5 0,337 et Jaccard 0,355. GraphCAG reste également en HOLD et inactif par défaut malgré un signal positif sur certaines mesures. Le projet refuse donc de faire du meilleur benchmark la seule représentation de la qualité.
Une autre expérience importante a conduit à retirer l’injection JIT généraliste du comportement par défaut. Un mécanisme peut améliorer la présence mécanique des assets dans le contexte sans réduire le nombre d’actions ou améliorer la résolution finale. Le verdict a été de conserver la capacité en opt-in, et non de défendre une fonctionnalité parce qu’elle avait déjà demandé du travail.
8. Context rot : gérer la fraîcheur, la provenance et le bruit
Le pourrissement du contexte ne désigne pas seulement une fenêtre de tokens trop longue. Il apparaît lorsque le contexte actif contient des informations anciennes, contradictoires, dupliquées ou détachées de leur provenance. Un agent peut alors suivre une roadmap superseded, appliquer une ancienne commande, confondre un prototype avec le produit courant ou relire un rapport historique comme une décision active.
UAH traite le contexte comme une ressource gouvernée. Plusieurs contrôles sont utilisés : séparation entre données courantes et historiques, marquage de fraîcheur, provenance, déduplication, consolidation non mutante, pruning en dry-run, archivage hashé et récupération fail-closed.
La distinction current/history est déterminante. Les archives restent utiles pour comprendre une décision, mais elles ne doivent pas être chargées comme instructions actives. Le système de vérité privilégie STATUS.md, METRICS.md, les registres de promotion et les preuves explicitement référencées. Un artefact plus récent mais non promu ne change pas automatiquement l’état canonique.
La provenance évite aussi les comparaisons incorrectes. Deux benchmarks peuvent afficher les mêmes métriques tout en utilisant des corpus et des golden sets différents. Les valeurs ne deviennent comparables que si le périmètre, la méthode, les données et les seuils sont alignés.
Un benchmark borné sur les contrôles de mémoire et de contexte a réduit un pack estimé de 12 450 à 249 tokens sans perte des hits vérifiés. Cette mesure démontre qu’une compression radicale est possible sur ce périmètre. Elle ne signifie pas que toutes les tâches peuvent être réduites de 98 % sans conséquence. Le harness conserve la qualification exacte de l’expérience.
La récupération fail-closed complète ce dispositif. Si une archive, un index ou un manifeste ne peut pas être vérifié, le système ne doit pas reconstruire silencieusement une mémoire plausible. Il bloque ou demande une intervention. Dans un environnement agentique, une absence explicite est souvent plus sûre qu’un contexte reconstitué avec une confiance injustifiée.
9. Distribuer un même contrat vers plusieurs runtimes
Les runtimes agentiques ne lisent pas les mêmes fichiers, n’exposent pas les mêmes hooks et ne structurent pas les profils de la même manière. Une approche multi-runtime ne peut donc pas consister à copier un prompt identique dans plusieurs dossiers.
UAH maintient une source canonique universelle, puis génère ou distribue des profils adaptés. Claude Code peut consommer des fichiers CLAUDE.md, des agents et des hooks spécifiques. Codex CLI utilise notamment AGENTS.md, ses profils et ses conventions de worker. Hermes reçoit des overlays correspondant à son rôle dans l’écosystème AAS. D’autres runtimes pourront être ajoutés tant qu’ils implémentent le contrat attendu.
Le Universal Runtime Profile Renderer joue un rôle adjacent : il transforme une définition commune vers les formats attendus, puis vérifie les sorties. La source canonique ne doit pas dépendre de la syntaxe d’un runtime particulier. Le renderer permet également de comparer les distributions et de détecter un drift.
Cette séparation a une conséquence pratique : la parité fonctionnelle n’est pas supposée. Un hook disponible dans Claude Code peut ne pas avoir d’équivalent direct ailleurs. Une capacité doit alors être implémentée dans le moteur de cycle, un wrapper ou un autre mécanisme. L’article et la documentation doivent distinguer la présence d’un fichier de la preuve que l’enforcement fonctionne réellement.
La commande uah doctor rejouée pour ce dossier valide la structure et les distributions dans le checkout courant. La gate d’installation propre du 12 juillet 2026 va plus loin : elle construit séparément les wheels UAH, Agentic Asset Orchestrator et agentic-assets, installe les dépendances verrouillées sans index réseau dans un environnement neuf, puis exécute uah doctor, uah verify, le rendu de profils, un scaffold réel, pip check et la désinstallation. Ce chemin installé passe sans PYTHONPATH ni checkout source.
Cette preuve ferme le défaut de dépendance implicite précédemment observé dans l’environnement éditorial. Elle ne rend pas pour autant tout le catalogue portable : des liens internes historiques doivent encore être normalisés ou externalisés, et la publication publique reste bloquée par les décisions de licence.
10. Durable Engineering Cycle : rendre le travail persistant
Le Durable Engineering Cycle, ou DEC, est la brique qui transforme une succession de sessions en cycle d’ingénierie persistant. Il introduit une machine à états, un état partagé, des locks, des checkpoints, des handoffs, des preuves, des conditions d’arrêt et un archivage vérifiable.
Le problème traité est concret. Un agent de code peut commencer une inspection, produire un plan, modifier des fichiers et atteindre une limite de quota avant les tests. Un second agent reprend alors la mission. Sans protocole, il peut relancer l’analyse, perdre le périmètre, ignorer un échec déjà observé ou entrer en concurrence avec un processus encore actif.
Le DEC matérialise l’état dans un dossier .agentic-cycle/ non versionné du dépôt cible. Il contient notamment un cycle actif, un TODO, l’état du worker, un handoff et un lock. Les événements sont append-only. Les checkpoints enregistrent les informations nécessaires à la reprise. Les archives finales sont hashées.
La machine à états impose des transitions autorisées : initialisation, inspection, planification, conception, implémentation, tests, vérification, revue, documentation, capitalisation, clôture et archivage. Des états de pause, de correction ou d’échec permettent de représenter les incidents au lieu de les masquer.
Le lock évite que deux workers modifient simultanément le même cycle. Il utilise une création exclusive, un TTL et un heartbeat. Le système couvre des scénarios de course multiprocessus, de SIGKILL, de stockage read-only, de worker manquant, de timeout réel et de reprise d’archive interrompue.
Le point le plus important est la clôture. Le LLM ne décide jamais seul que les tests sont réussis, que Git est propre, que l’archive est valide ou que le nombre d’itérations respecte les limites. Ces propriétés sont vérifiées par des scripts, des schémas et un reviewer distinct. Le worker produit une proposition ; le moteur applique le contrat.
Les tests du DEC rejoués pour ce dossier donnent 89 tests et 6 sous-tests passés en 23,99 secondes, sans échec ni skip signalé par cette exécution. Cette preuve porte sur le moteur local et ses scénarios déterministes. Elle ne doit pas être confondue avec la réussite de tous les appels providers réels.
11. Checkpoint, handoff et reprise entre workers
Le changement de worker constitue un test révélateur pour un système agentique. Si toute la continuité réside dans la fenêtre de conversation, le système ne possède pas réellement d’état durable. Le DEC traite le handoff comme un objet structuré.
Lorsqu’un worker doit s’arrêter, il place le cycle dans un état de pause, produit un checkpoint et crée un handoff destiné au worker suivant. Le lock est libéré. Une nouvelle instance du moteur peut ensuite lire l’état canonique, vérifier l’historique des événements, acquérir un nouveau lock et reprendre à partir de la transition autorisée.
La reprise ne doit pas seulement restaurer un statut. Elle doit préserver les preuves déjà enregistrées, les décisions, les critères d’acceptation et les limites. Le nouveau worker ne doit pas pouvoir effacer l’échec précédent en réinitialisant le cycle.
Le scénario hors ligne rejoué le 14 juillet 2026 simule une interruption de quota. Un producteur commence l’inspection et la planification, passe en PAUSED, crée un handoff et un checkpoint, puis une nouvelle instance du moteur reprend le cycle avec un autre worker. Le test vérifie que l’historique des événements n’a pas changé pendant le redémarrage, que les preuves précédentes sont toujours présentes, que les identifiants restent uniques et que le lock est acquis par le nouveau worker.
Le scénario se termine par une revue distincte, une documentation, une capitalisation, une clôture et une archive. Le résultat comporte 23 événements, 11 enregistrements de preuve et 20 fichiers d’archive vérifiés. Aucun appel réseau ou fournisseur payant n’est utilisé.
Cette démonstration ne prouve pas qu’un handoff Claude vers Codex fonctionnera dans toutes les conditions externes. Elle prouve que le contrat local de persistance, de reprise et d’intégrité ne dépend pas du provider. C’est précisément le rôle d’un harness : isoler les invariants que l’on peut tester de façon déterministe, puis tester séparément les adaptateurs externes.
12. Hooks et enforcement : passer de la règle au contrôle
Une politique écrite ne possède pas la même force qu’une contrainte appliquée. Les fichiers d’instructions restent indispensables pour expliquer l’intention et guider le raisonnement. Les hooks et le moteur déterministe interviennent lorsque le système doit empêcher une action ou enregistrer un fait.
Un hook de début de session peut charger un profil compact et vérifier l’état du cycle. Un contrôle préalable à l’outil peut vérifier le lock, le scope et le niveau de permission. Un hook après outil enregistre la commande, le résultat, le chemin affecté et le heartbeat. Un hook d’échec conserve l’erreur. Un hook de fin de session produit un résumé et un handoff. Une gate d’arrêt refuse une clôture si les tests ou les preuves nécessaires sont absents.
L’enforcement est conçu pour être fail-closed sur les actions critiques. Une permission inconnue ne devient pas une permission implicite. Un stockage non accessible ne doit pas être remplacé par une trace imaginaire. Une archive dont le checksum échoue n’est pas acceptée.
Cette discipline réduit un risque courant : demander au même agent de produire le changement, d’évaluer sa qualité et de déclarer le succès. UAH sépare les rôles. Le producteur fournit une implémentation et des preuves. Le moteur exécute les validations. Le reviewer distinct examine le résultat. La clôture rassemble les verdicts.
L’état actuel n’est pas uniforme sur tous les runtimes. Le README du DEC indique que l’enforcement local a été durci et que les scénarios déterministes passent, mais la validation provider réelle reste requise. Le chemin Claude reproduit encore un état CONTEXT_UNRELIABLE après la correction du parseur local, et le reviewer externe n’a pas été exécuté dans la campagne concernée.
Cette limite est structurellement différente d’un échec du moteur local. Elle doit être attribuée à l’adaptateur ou à l’environnement provider, puis traitée avec un test ciblé. L’architecture ports/adaptateurs permet précisément de ne pas dégrader la qualification de tout le noyau lorsqu’un runtime particulier ne respecte pas encore le contrat.
13. Mémoire : transformer les traces en apprentissage organisationnel
La mémoire d’un système agentique ne devrait pas être une accumulation indéfinie de conversations. Elle doit distinguer les événements bruts, les décisions validées, les entités durables, les patterns candidats et les actifs promus.
UAH utilise une chaîne de capitalisation :
trace brute
→ événement MemoryCAG validé
→ entité ou relation
→ pattern candidat
→ skill, workflow ou script
→ benchmark
→ promotion ou rejetUne trace peut montrer qu’un agent a appelé trois outils, rencontré une erreur et appliqué une correction. Cette séquence n’est pas automatiquement un apprentissage. Il faut vérifier que la correction est générale, qu’elle ne dépend pas d’un secret ou d’un contexte client et qu’elle améliore réellement les métriques. Le pattern peut alors devenir un runbook, un hook ou un test.
La mémoire possède aussi une fonction de continuité. Les décisions, les résultats et les erreurs peuvent être retrouvés sans charger toutes les sessions. Les événements sont filtrables par type, entité, statut ou tag. Les liens promus peuvent alimenter le graphe de connaissances, mais la couche GraphCAG reste indépendante et soumise à ses propres gates.
Le pipeline prévoit une séparation stricte entre raw, validated, promoted et dataset. Cette séparation évite qu’une sortie non vérifiée soit utilisée directement pour entraîner un modèle. L’export vers un dataset impose une validation humaine, une anonymisation et un score de qualité.
L’objectif à long terme est une machine d’apprentissage organisationnel : les tâches réussies réduisent le coût des tâches futures, les erreurs deviennent des tests, et les décisions deviennent des composants réutilisables. Cette vision reste partiellement intégrée. MemoryCAG et plusieurs contrôles sont validés localement, tandis que le pipeline complet vers le fine-tuning OSS local appartient encore à la trajectoire cible.
14. Observabilité agentique : voir le raisonnement sans exposer les secrets
Un système d’agents doit pouvoir répondre à des questions opérationnelles simples : quel agent a agi, avec quel objectif, quels outils ont été appelés, combien de temps la tâche a pris, quelles erreurs sont apparues, quelles validations ont été obtenues et quel résultat a été produit ?
L’architecture d’observabilité UAH suit une approche local-first. Les événements et spans sont écrits en JSONL. SQLite et DuckDB peuvent fournir des analyses locales. Langfuse sert de surface de visualisation lorsque le câblage est disponible. Les formats cherchent à rester compatibles avec OpenTelemetry afin d’éviter un verrouillage sur un produit unique.
La chaîne comporte plusieurs couches : agents en exécution, collecte, analytics, capitalisation, datasets R&D et éventuellement fine-tuning local. Chaque promotion ajoute des exigences. Les traces brutes ne deviennent pas automatiquement des données d’entraînement.
La sécurité est une contrainte de premier ordre. Aucun token, cookie, mot de passe ou secret ne doit apparaître dans les traces. Les données client doivent être séparées et anonymisées. Une trace utile pour le debug peut être trop sensible pour un dataset. Les politiques d’accès et de rétention doivent donc être définies par couche.
Les conventions sémantiques GenAI d’OpenTelemetry fournissent désormais des catégories pour les opérations de modèles, les agents et MCP. Elles servent de référence pour nommer les spans et les attributs. Le projet ne prétend pas couvrir l’intégralité de ces conventions. Il cherche à rendre ses formats convertibles et à conserver une provenance explicite.
L’état courant est partiel. Le statut consolidé mentionne quinze métriques mesurées avec provenance, un export OTLP réussi dans un périmètre borné et une architecture locale fonctionnelle. Les métriques de contexte, de tokens et de coût ne couvrent toutefois que deux probes providers ayant échoué, pas une exécution provider réussie représentative. L’observabilité globale reste donc en HOLD.
Cette transparence évite un tableau de bord décoratif. Une métrique n’est utile que si son origine, son périmètre et ses valeurs manquantes sont connus.
15. Évaluer scientifiquement plutôt que confirmer une intuition
UAH applique un protocole d’évaluation simple : question, hypothèse, baseline, intervention, mesure, comparaison, décision et capitalisation. Toute modification importante du retrieval, de la mémoire, de la distribution ou de l’observabilité doit suivre cette séquence.
Les golden tasks contiennent un identifiant, une intention, les assets attendus et interdits, un contrat de sortie, un niveau de risque, des critères de réussite et un rubric. Elles sont gelées avant la mesure. Modifier les réponses attendues pour faire monter un score est explicitement interdit.
Plusieurs dimensions sont suivies. Le retrieval utilise recall@k, precision@k, MRR, nDCG, Jaccard et latence. L’exécution mesure le succès de tâche, les tests, les rollbacks et les violations. La sécurité compte les secrets, actions interdites et contournements d’approbation. Le coût inclut tokens, appels outils, durée et coût par tâche. La capitalisation mesure la réutilisation et la duplication.
Les décisions ne sont pas binaires. KEEP indique que les cibles sont atteintes sans risque critique. REVERT signale une régression ou un danger. HOLD conserve une piste sans la promouvoir. HUMAN_REVIEW s’applique aux ambiguïtés ou aux risques élevés. ITERATE permet une amélioration partielle.
L’histoire du retrieval JIT illustre ce protocole. Une injection pouvait sembler utile parce qu’elle plaçait davantage d’assets attendus dans le contexte. Un test A/B a cependant montré que le taux de résolution avec contexte n’était pas supérieur au bras sans contexte de manière suffisamment fiable. La capacité a été retirée du défaut produit et conservée en opt-in. Le projet a capitalisé la leçon : mesurer la présence d’un contexte ne suffit pas, il faut mesurer son effet sur le résultat.
Le protocole protège également contre les comparaisons trompeuses. Les métriques du filtered, du holdout, de la stabilité et de GraphCAG ne sont pas fusionnées arbitrairement. Chaque suite possède ses données, ses seuils et sa décision.
16. Permissions, sécurité et autonomie graduée
Le modèle de sécurité UAH classe les actions sur cinq niveaux.
Le niveau 0 couvre la lecture publique et l’analyse. Le niveau 1 autorise une écriture locale réversible avec un objectif clair. Le niveau 2 concerne les dépendances, configurations et infrastructures locales ; il demande un plan, un dry-run et une stratégie de retour. Le niveau 3 inclut la production, les secrets, les données sensibles et la suppression ; une approbation humaine explicite est obligatoire. Le niveau 4 couvre les actions illégales, destructives ou abusives et reste interdit.
Cette gradation évite deux extrêmes : un agent incapable d’effectuer la moindre action utile, ou un agent généraliste disposant de tous les accès. Les permissions doivent être proportionnées à la mission et limitées dans le temps.
Le modèle impose le moindre privilège, l’absence de secrets dans les fichiers et prompts, le dry-run avant les actions destructives, la sauvegarde avant une écriture critique et la traçabilité des opérations impactantes. Les actions réseau sont traitées comme une surface spécifique, car l’exposition d’un service peut transformer une modification locale en risque externe.
Les menaces agentiques ne se limitent pas à l’injection de prompt. Un agent peut recevoir une instruction malveillante dans une ressource, appeler un outil avec des paramètres dangereux, déléguer à un autre agent, empoisonner une mémoire ou accumuler des permissions. Les travaux OWASP sur l’Agentic AI recommandent une approche fondée sur le threat modeling, les limites d’autorité, la supervision et la protection des chaînes d’outils.
UAH associe les permissions aux hooks, aux profils et au cycle. Une action de risque 3 ne doit pas seulement être documentée comme sensible : la transition ou l’outil doit demander une approbation vérifiable. Le système conserve également un plan de rollback et un reçu expurgé.
L’état actuel comporte encore une limite de gouvernance du cycle de vie des credentials : une partie de la remédiation locale est vérifiée, mais la preuve externe complète n’est pas disponible. Le projet ne revendique donc ni rotation totale ni clôture de ce contrôle. Cette précision montre le niveau de preuve attendu : une action locale ne suffit pas à démontrer l’état d’un fournisseur distant.
17. MCP et A2A : deux protocoles complémentaires
MCP et A2A sont souvent regroupés sous l’étiquette « protocoles pour agents ». Ils ne répondent pourtant pas au même problème.
Le Model Context Protocol standardise la connexion entre une application LLM et des sources de contexte ou des outils. La spécification distingue les hosts, clients et servers. Les servers peuvent exposer des ressources, des prompts et des tools. Les clients peuvent proposer le sampling, les roots et l’elicitation. La négociation de capacités, les connexions stateful, le suivi de progression et l’annulation font partie du protocole.
MCP ne supprime pas le besoin d’un modèle de permissions. Sa spécification insiste sur le consentement de l’utilisateur, la protection des données et le fait qu’un outil représente une voie potentielle d’exécution arbitraire. Les descriptions des tools ne doivent pas être considérées comme fiables par défaut.
Le protocole A2A structure la communication entre agents. Il définit des Agent Cards pour la découverte, des messages, des tâches, des artefacts, du streaming, des notifications, l’idempotence, plusieurs bindings et des mécanismes d’authentification. Il permet à un agent client de déléguer ou suivre une tâche auprès d’un agent distant sans connaître son implémentation interne.
UAH se situe autour de ces protocoles. Il détermine le contexte, les permissions, le cycle, les évaluations et les preuves. MCP peut fournir les capacités concrètes. A2A peut transporter une mission ou un handoff entre agents. Aucun des deux ne remplace le harness.
Le dépôt contient des cartes A2A et une validation structurée étendue. Le statut indique 74 packs et 148 cartes validées dans les distributions dupliquées. Cela démontre la conformité des artefacts au schéma utilisé. Une découverte cross-domain, une authentification réelle et une chaîne inter-agent complète restent des validations distinctes.
Cette séparation des responsabilités réduit les malentendus architecturaux. Un serveur MCP n’est pas automatiquement un agent autonome. Une Agent Card A2A n’accorde pas automatiquement les outils. Un harness n’est pas un transport. Les trois couches peuvent évoluer indépendamment.
18. Cas d’étude : trois cycles déterministes rejoués
Pour ce dossier, le script run_e2e_validation.py du Durable Engineering Cycle a été rejoué le 14 juillet 2026 dans un nouveau dossier temporaire. Il utilise des commandes Python déterministes et ne réalise aucun appel réseau ou fournisseur payant.
Le premier scénario est nominal. Un worker producteur acquiert le lock, inspecte, planifie, conçoit, implémente, teste et vérifie. Le système tente ensuite de faire acquérir le lock au reviewer alors que le producteur le possède encore ; l’acquisition étrangère doit être rejetée. Le producteur libère le lock, le reviewer l’acquiert, produit la revue, synchronise la documentation et capitalise. Le moteur clôture et archive. Résultat : PASS, état final ARCHIVED, 16 événements, 10 preuves et 17 fichiers d’archive dont les checksums sont vérifiés.
Le deuxième scénario introduit un échec et une correction bornée. Un test initial échoue. Le runner produit un diagnostic, applique une correction sur un fichier simulé et relance la vérification. La boucle doit s’arrêter après une itération lorsque la non-régression passe. Résultat : PASS, 20 événements, 13 preuves et 21 fichiers d’archive vérifiés.
Le troisième scénario teste le handoff et la reprise. Le producteur atteint une interruption simulée de quota après la planification. Le cycle passe en pause, un checkpoint est écrit et le lock est libéré. Une nouvelle instance du moteur recharge l’état, vérifie l’historique, acquiert le lock avec un autre worker et poursuit. Le test contrôle que les événements et preuves n’ont pas disparu. Résultat : PASS, 23 événements, 11 preuves et 20 fichiers d’archive vérifiés.
Ces scénarios démontrent les invariants locaux : état persistant, lock exclusif, transitions, correction bornée, reviewer distinct, reprise et archive hashée. Ils ne démontrent pas la fiabilité d’un modèle à comprendre n’importe quel projet. Leur valeur vient précisément de cette portée bornée : le moteur peut être validé sans dépendre d’une sortie probabiliste.
Les tests racine ont également été rejoués le 14 juillet 2026 : 99 tests et 22 sous-tests passent en 11,99 secondes, sans échec ni skip signalé par cette exécution. L’ensemble fournit un socle de preuve récent pour la publication, tout en laissant visibles les gaps providers et retrieval.
19. Ce que montrent les preuves — et ce qu’elles ne montrent pas
La lecture correcte de l’état UAH demande de ne pas réduire le projet à un seul score.
Les fondations locales sont avancées. Le packaging, les distributions, les schémas, les tests, les contrôles de secrets, le SAST, le SCA, la SBOM et plusieurs gates de reproductibilité passent selon le statut consolidé. Les tests rejoués pour ce dossier confirment le noyau Python et le DEC. Le retrieval filtered et le holdout combiné fournissent des résultats solides sur leurs corpus.
La stabilité reste la principale limite de la couche de retrieval. Une requête reformulée ne retrouve pas encore suffisamment souvent les mêmes assets pertinents dans la suite indépendante. Ce problème est plus important qu’un score filtered élevé, car les utilisateurs et agents formulent rarement deux demandes de manière identique.
GraphCAG reste une piste R&D. Les mesures montrent des gains de recall ou de nDCG dans certains réglages, mais la précision et les intervalles de confiance empêchent sa promotion. Il est donc retiré du scope actif et inactif par défaut.
L’observabilité possède des composants réels mais ne couvre pas encore un échantillon provider réussi suffisamment représentatif. Les tableaux de bord doivent conserver ce manque plutôt que remplacer les valeurs absentes par des estimations.
Le provider live constitue l’autre limite. Deux campagnes reproduisent un producteur Codex et une reprise, mais Claude reste CONTEXT_UNRELIABLE et le reviewer distinct n’a pas terminé le chemin attendu. Le verdict reste BLOCKED_BY_EXTERNAL_CONSTRAINT pour cette chaîne, pas PASS.
Enfin, UAH n’est pas publiable publiquement dans son état actuel. Le candidat reste privé/interne et l’absence de licence sélectionnée déclenche un comportement fail-closed. Le site peut expliquer l’architecture et les résultats sans distribuer les artefacts comme une release open source.
Cette présentation peut sembler moins spectaculaire qu’un label « production-ready ». Elle est pourtant plus utile. Elle permet de savoir quelles briques peuvent servir dès maintenant, lesquelles nécessitent une supervision et quelles expériences doivent encore être menées.
20. Trajectoire de maturation
La prochaine étape n’est pas d’ajouter davantage de composants. Elle consiste à fermer les gaps qui empêchent de transformer un candidat interne avancé en capacité déployable avec une qualification claire.
La première priorité concerne la stabilité du retrieval. Les changements devront améliorer les tâches paraphrasées faibles sans retoucher les answer keys, les aliases ou les seuils. Toute intervention devra être validée sur un second split intact et conserver la non-régression du filtered.
La deuxième concerne le provider live. Le chemin Claude doit résoudre l’échec de sortie structurée ou de contexte, puis exécuter un reviewer distinct. Le test attendu doit conserver le même état partagé, les mêmes gates et les mêmes preuves que le scénario déterministe.
La troisième concerne l’observabilité. Une campagne provider réussie doit alimenter les spans de contexte, tokens, coût, outils, erreurs et outcomes. Le dashboard pourra alors comparer les workers avec des données réelles et non uniquement des probes bornés.
La quatrième concerne la portabilité complète du catalogue. La gate installée et uah verify passent déjà depuis des artefacts construits ; le travail restant porte sur les liens internes historiques, leur normalisation ou leur externalisation explicite, puis sur la conservation de cette preuve lors du prochain carrier propre.
La cinquième concerne la publication et les licences. Les composants, dépendances et assets doivent être cartographiés avant de sélectionner les licences. Tant que ce travail n’est pas terminé, la distribution publique reste bloquée.
Enfin, le projet doit continuer à produire des cas d’étude. Une démonstration réelle sur un composant sandbox — inspection par un worker, implémentation par un autre, revue distincte, tests, clôture et archive — permettra de mesurer la valeur du harness sur une tâche non simulée. La baseline sans harness devra être exécutée sur le même état initial afin de comparer le temps, le contexte, les erreurs et les interventions humaines.
La maturité n’est donc pas une ligne unique allant de prototype à production. Certaines dimensions sont avancées, d’autres expérimentales et d’autres bloquées. La roadmap doit agir sur les gates les plus structurantes plutôt que maximiser le nombre de fonctionnalités.
21. Matérialiser le harness dans un projet réel
Un harness ne crée de valeur que s’il peut être installé dans un projet cible sans transformer ce projet en copie du dépôt UAH. La distribution doit apporter les contrats nécessaires tout en respectant l’architecture, les conventions et le cycle de vie déjà présents.
UAH contient plusieurs niveaux de scaffolds. Un profil minimal apporte les fichiers indispensables à une mission bornée. Un scaffold logiciel ajoute les conventions d’ingénierie, les commandes de validation, les workflows et les règles de documentation. Un projet d’agent expert reçoit en plus ses capacités, permissions, évaluations et contrats de sortie. Les assets_in_box regroupent des templates, scripts, checklists, prompts, exemples et runbooks pouvant être matérialisés à la demande.
La commande d’installation cible ne doit pas déposer indistinctement tous les assets. Elle doit résoudre un profil selon la verticale, le runtime et le niveau de risque. Un projet DevSecOps n’a pas besoin du même pack qu’une mission de veille OSINT ou qu’un workflow de génération de contenu. Le profil peut contenir un AGENTS.md, des skills, des workflows, une permission card, un rubric d’évaluation et les adaptateurs nécessaires.
La matérialisation doit rester idempotente. Une deuxième exécution ne doit pas écraser les choix du client ni dupliquer les sections. Le système doit produire un plan ou un diff, identifier les conflits et demander une validation lorsque le fichier cible possède déjà des conventions incompatibles. La désinstallation doit être définie : les fichiers créés, modifiés et conservés doivent être connus.
Ce niveau produit est encore inégal. Le packaging minimal, les distributions principales et le chemin installé uah verify sont validés dans la gate bornée du 12 juillet 2026, mais plusieurs profils sectoriels et la matérialisation complète des boîtes restent dans le backlog. La preuve actuelle qualifie un candidat privé/interne ; elle ne constitue ni une publication publique ni une validation de toutes les intégrations runtime.
La prochaine preuve packaging attendue est une reproduction de cette gate depuis un carrier aligné et propre après normalisation des liens du catalogue. Elle devra conserver la construction déterministe, l’installation hors checkout, le scaffold, doctor, verify, pip check et la désinstallation, sans secret ni dépendance à un chemin du VPS.
La matérialisation relie finalement l’architecture à un usage professionnel. Elle permet de transformer un ensemble de principes en un environnement de mission reproductible. Le client ou le projet reçoit une couche adaptée, pas le laboratoire complet. La valeur commerciale d’UAH dépendra en grande partie de cette capacité à livrer rapidement un cadre opératoire ciblé, inspectable et réversible.
Conclusion — Construire les conditions d’une confiance vérifiable
Universal Agent Harness part d’un constat : la qualité d’un agent ne dépend pas uniquement du modèle utilisé. Elle dépend du système qui définit son objectif, sélectionne son contexte, limite son autorité, conserve son état, mesure ses résultats et transforme ses expériences en connaissances réutilisables.
Le projet apporte déjà plusieurs briques concrètes : une CLI, des distributions multi-runtime, des sources de vérité, des workflows, des skills, des profils, des évaluations, une mémoire, une observabilité locale et un cycle déterministe. Les tests et scénarios rejoués montrent qu’un cycle peut survivre à un échec, un changement de worker et un redémarrage tout en conservant ses preuves.
La partie la plus importante n’est cependant pas la quantité de composants. C’est la discipline de qualification. UAH accepte qu’un filtered soit en KEEP alors que la stabilité reste en HOLD. Il conserve GraphCAG comme expérience inactive plutôt que de le promouvoir sur un signal partiel. Il ferme le défaut uah verify quand la gate installée le démontre, tout en maintenant les dettes distinctes de portabilité du catalogue. Il distingue une validation offline d’une validation provider live.
Cette discipline est indispensable pour construire des agents capables de participer à une activité professionnelle. Un système agentique utile doit pouvoir agir, mais aussi expliquer son périmètre, montrer ses preuves, demander une approbation, reconnaître une incertitude et reprendre après une interruption.
Dans Strategic Gen OS, UAH devient ainsi la couche d’exécution commune entre les objectifs de l’organisation, les Agents as Services, les runtimes et les logiciels. Il ne remplace ni la gouvernance ni l’expertise. Il leur donne un environnement durable.
Le résultat recherché n’est pas un agent qui paraît autonome pendant une démo. C’est une infrastructure dans laquelle plusieurs workers peuvent coopérer sans que la qualité, la sécurité et la mémoire dépendent entièrement d’une conversation éphémère.