Guide · IA & agents
Évaluer un orchestrateur d’agents par les preuves
Construisez un harnais local en Python qui transforme une demande en contrat, simule le routage, contrôle des preuves structurées et bloque une livraison incomplète.

Un orchestrateur d’agents ne devient pas fiable parce qu’il produit un résumé convaincant. Il faut pouvoir retrouver la demande reçue, la politique appliquée, les outils sélectionnés et les preuves qui autorisent ou bloquent la livraison. Le petit noyau Python étudié ici met ces éléments dans des fichiers structurés avant de laisser un agent produire quoi que ce soit.
En bref. Le manifeste décrit les étapes, les limites et les critères. La simulation compile une demande sans appeler de fournisseur. L’évaluateur reçoit des mesures déjà extraites et renvoie
PASSouBLOQUÉ. Ce guide s’appuie sur une exécution locale réelle du noyau le 4 novembre 2026 : 9 tests réussis, une simulation créée, un cas passant et un cas bloqué vérifiés.
Le problème que le harnais résout
Une boucle agentique classique reçoit une consigne, choisit des outils, agit puis annonce que le travail est terminé. Ce parcours devient difficile à auditer quand plusieurs décisions restent dans la conversation. Après une compaction ou un redémarrage, il manque parfois le détail qui expliquait un choix. Un nouvel agent peut aussi interpréter différemment la même demande.
Le harnais sépare cinq responsabilités :
| Élément | Question traitée | Sortie vérifiable |
|---|---|---|
| Demande normalisée | Quel résultat a été demandé ? | Objet JSON stable |
| Manifeste de domaine | Quelles étapes et limites s’appliquent ? | Fichier versionné |
| Routeur | Quelles procédures sont nécessaires ? | Liste motivée de skills |
| État du run | Où en est l’exécution ? | Statut, décisions et échecs |
| Évaluateur | Les preuves satisfont-elles les règles ? | Verdict et constats détaillés |
Cette architecture ne rend pas le modèle plus intelligent. Elle rend ses décisions observables et permet de refuser une livraison sans demander au même modèle de juger sa propre réponse.
Le principe rejoint les travaux sur les agents qui surestiment leur avancement. Le dossier OverclaimBench : quand un agent surestime le travail effectué explique pourquoi un message final ne suffit pas comme preuve.
Commencer par un manifeste versionné
Un manifeste est un fichier de configuration lu par le moteur. Il porte un identifiant et une version, puis les étapes, profils, évaluateurs, règles de routage et politiques applicables au domaine.
Pour un workflow vidéo, un manifeste peut déclarer :
{
"version": "1.0",
"id": "video",
"stages": ["preflight", "brief", "assets", "compose", "evaluate", "deliver"],
"policy": {
"local_output_only": true,
"allow_external_publish": false,
"require_verified_sources": true
},
"limits": {
"max_renders": 5,
"max_wall_minutes": 45
}
}
Cet exemple est volontairement réduit. Le manifeste réellement exécuté ajoute cinq profils de plateforme, des safe zones, un budget de disque, une liste d’évaluateurs et des règles de sélection de skills. Il bloque aussi la publication externe et la modification des skills pendant un run.
Versionnez le manifeste avec le code. Un changement de seuil ou de politique modifie le sens d’un verdict. Sans historique, deux runs portant le même nom peuvent avoir suivi des règles différentes.
La validation minimale vérifie la présence des champs obligatoires. Un projet destiné à plusieurs équipes gagnera à ajouter un schéma JSON complet, des contraintes de type et des migrations de version. La documentation Python de json explique la lecture et l’écriture ; elle ne remplace pas une validation de schéma.

Compiler la demande en contrat
Le moteur commence par normaliser la demande. Il retire les espaces superflus, fixe le domaine, la plateforme, la durée, la langue et les sources fournies. Il applique ensuite les valeurs par défaut du manifeste.
Une demande comme celle-ci :
Crée une vidéo sur une application mobile
Plateforme : TikTok
produit un contrat qui associe l’objectif à un profil vertical, une durée, une langue, une politique et des critères d’acceptation. La demande d’origine reste conservée. Cette conservation évite qu’une reformulation ultérieure efface une contrainte.
Le noyau calcule une empreinte SHA-256 à partir de la demande normalisée et de la version du manifeste. Cette empreinte sert de clé de run. Deux demandes identiques sous le même manifeste réutilisent le même dossier de simulation au lieu de créer deux états concurrents.
Ce cache reste strictement local. Il ne signifie pas que deux générations réelles seront identiques, surtout si elles sollicitent des modèles externes. Il garantit seulement que la compilation déterministe réutilise le même état préparatoire.
Router des skills sans laisser le modèle improviser
Le routeur part d’un socle obligatoire. Dans le pack vidéo étudié, ce socle couvre les droits des médias, le motion design, le contrôle de livraison et la boucle d’orchestration. Une seule règle thématique complète ensuite ce socle à partir de mots-clés. Les formats verticaux ajoutent une procédure dédiée aux vidéos courtes.
La sortie ne contient pas uniquement des noms. Chaque choix possède une raison : provenance et droits, contrôle du master, profil vertical ou mot-clé détecté. Cette justification permet de repérer une sélection absurde avant l’exécution.
Un routeur lexical reste limité. Le mot « carte » peut désigner une carte géographique, une carte de profil ou une carte bancaire. Quand l’erreur de routage coûte cher, ajoutez une étape de clarification ou des règles plus précises. Ne remplacez pas une ambiguïté par une décision silencieuse du modèle.
Pour comprendre les limites de permissions autour des outils, consultez Sécuriser les outils d’un agent : commencer par les permissions.
Simuler avant d’appeler un fournisseur
La commande de simulation exécutée pour ce guide était :
PYTHONPATH=src python3 -m agentic_workflow.cli simulate \
--prompt "Crée une vidéo sur une application mobile" \
--platform tiktok \
--runs-dir /chemin/vers/agentic-runs
Elle n’a généré aucune image, voix ou vidéo. Elle a créé six artefacts :
run-request.json, le contrat compilé ;routing.json, les skills et leurs raisons ;production-plan.json, le storyboard et le plan d’évaluation ;resources.json, l’espace disponible et les limites ;run-state.json, le statut et les preuves ;delivery-report.md, le résumé lisible.
Le run a reçu le statut simulated. Sa première preuve dit qu’aucun fournisseur, secret ou rendu n’a été appelé. Le runtime est resté unresolved, car la détection des outils appartient au préflight d’une future exécution réelle.
Cette nuance compte. Un plan de production réussi n’est pas une vidéo réussie. La simulation prouve seulement que la demande peut être compilée, routée et enregistrée avec la politique choisie.
Fournir des preuves, pas des impressions
L’évaluateur ne lit pas directement une vidéo. Il attend un objet de preuves produit par des outils adaptés : présence des sous-titres, contraste minimal, validité des safe zones, fréquence maximale des flashs, vérification des faits et résultats de similarité.
Un cas passant peut prendre cette forme :
{
"captions_present": true,
"minimum_contrast_ratio": 7.0,
"safe_zone_valid": true,
"max_flash_hz": 2,
"facts_verified": true,
"similarity_matches": [
{"label": "original", "score": 0.2}
]
}
Le 4 novembre 2026, cette fixture a produit PASS pour le profil TikTok, avec une sortie 1080 × 1920 à 30 images par seconde et aucun constat.
Un second cas a volontairement fourni des sous-titres absents, un contraste de 2,1:1, une safe zone invalide, des flashs à 5 Hz, des faits non vérifiés et une similarité de 0,91 avec une référence protégée. L’évaluateur a renvoyé BLOQUÉ, six constats et un code de sortie 1.
Les mesures doivent provenir de contrôles média séparés et documentés avant de construire ce type d’objet.
Corriger une contradiction entre le README et le code
Le README du noyau indique que l’évaluateur « bloque une livraison à la première règle non satisfaite ». L’implémentation et les tests montrent un autre comportement : toutes les règles sont évaluées, chaque échec est ajouté à findings, puis le verdict global devient BLOQUÉ.
Le test du cas invalide exige d’ailleurs les six gates : sous-titres, contraste, safe zone, photosensibilité, sources et similarité. L’exécution réelle a confirmé cette accumulation.
La formulation correcte est donc : une seule règle non satisfaite suffit à bloquer le verdict, mais l’évaluateur continue et rapporte tous les constats détectés. Le README doit être corrigé lors d’une évolution du projet. L’article suit ici le code testé, tout en conservant la contradiction dans le registre de provenance.
Cet exemple montre pourquoi une documentation seule ne suffit pas. Quand une phrase contredit un test déterministe, exécutez le test et expliquez l’écart au lieu de choisir la version la plus commode.
Organiser les statuts et les classes d’échec
Le noyau distingue PASS, PARTIEL et BLOQUÉ dans son vocabulaire général. L’évaluateur vidéo actuel ne renvoie toutefois que PASS ou BLOQUÉ. N’affichez pas PARTIEL dans une interface tant qu’une règle explicite ne le produit pas.
Les échecs appartiennent à une taxonomie fermée : source, droit, asset, runtime, audio, qualité, budget ou factualité. Une classe inconnue lève une erreur au lieu de créer une nouvelle catégorie à la volée.
Cette fermeture facilite les tableaux de bord et les tests. Elle oblige aussi à faire évoluer la taxonomie avec soin. Un incident qui ne rentre dans aucune classe mérite une modification versionnée du modèle, pas une étiquette improvisée dans un rapport.
Tester le harnais lui-même
La commande suivante a été exécutée dans le projet local :
PYTHONPATH=src python3 -m unittest discover -s tests -v
Résultat : 9 tests réussis en 0,010 seconde. Ils contrôlent notamment :
- le profil YouTube par défaut et le routage d’une carte d’itinéraire ;
- l’idempotence de la simulation ;
- le rejet d’une plateforme inconnue ;
- le rejet d’une classe d’échec inconnue ;
- le verdict bloqué avec six constats ;
- le verdict passant avec des preuves complètes ;
- les politiques du manifeste vidéo ;
- les dix cas uniques du catalogue d’évaluation ;
- le statut encore planifié du manifeste de développement.
Un test rapide n’est pas une validation de production. Le noyau actuel ne prouve pas qu’un outil média a calculé correctement le contraste ou la similarité. Il vérifie seulement la décision prise à partir des valeurs reçues. Il faut tester séparément les extracteurs, leur provenance et leurs erreurs.
Adapter ce modèle à un autre domaine
Pour un agent de développement, le manifeste pourrait exiger un diff limité, des tests ciblés, un lint, un typecheck et un rapport de sécurité. Les preuves contiendraient les commandes exécutées, leurs codes de sortie et les fichiers touchés. Le verdict refuserait une livraison si un contrôle obligatoire manque.
Pour une recherche fondée sur des sources, remplacez les gates vidéo par la résolution des URL, la date des sources, la couverture des affirmations et l’absence de citation inventée. Pour une migration de données, ajoutez sauvegarde, simulation, comptage avant/après et procédure de retour arrière.
Gardez la même séparation : le manifeste énonce la politique, les outils produisent les preuves, l’évaluateur décide, et l’agent explique le résultat. Un outil ne doit pas fabriquer la preuve qu’il consomme lui-même sans contrôle indépendant.
Limites et licence
Le dossier local étudié ne contient pas de fichier LICENSE à sa racine. Son code peut servir de source interne et de base à une réécriture originale, mais il ne doit pas être distribué comme modèle téléchargeable tant que le propriétaire n’a pas choisi de licence.
Le noyau ne publie rien et n’appelle aucun fournisseur pendant simulate. Une future commande d’exécution devra encore protéger les secrets, isoler les sorties, borner les coûts et confirmer les actions externes. Le manifeste contient ces intentions, mais une règle JSON ne constitue pas à elle seule une barrière système.
Enfin, les seuils sont propres au domaine. Un contraste de 4,5:1 et une limite de 3 Hz sont des décisions encodées dans cet évaluateur. Leur présence ne certifie pas automatiquement la conformité de toutes les scènes, tailles de texte ou conditions de visionnage.
Questions fréquentes
Un verdict PASS prouve-t-il que le livrable est bon ?
Il prouve que les preuves fournies satisfont les règles codées. Il ne couvre pas une règle absente, un extracteur erroné ou un critère métier non déclaré.
Pourquoi stocker les runs sur disque ?
Les fichiers permettent de reprendre une enquête, comparer les décisions et relire les preuves sans dépendre de la conversation de l’agent. Ils doivent rester hors des secrets et des données personnelles inutiles.
Peut-on laisser le modèle choisir les seuils ?
Non pour un contrôle reproductible. Les seuils appartiennent au manifeste ou au code versionné. Le modèle peut signaler une ambiguïté, mais il ne doit pas déplacer la règle pendant l’évaluation.
Faut-il arrêter au premier échec ?
Pas nécessairement. L’implémentation étudiée accumule tous les constats, ce qui évite plusieurs cycles de correction. Une seule règle échouée suffit néanmoins au verdict bloqué.
Ce harnais remplace-t-il une CI ?
Non. Il prépare et évalue un run agentique. La CI reste utile pour exécuter les contrôles du dépôt dans un environnement indépendant et conserver leur historique.
Sources
- Code, manifestes, tests et documentation du noyau Agentic Workflow, source interne Vibarche revue et exécutée le 4 novembre 2026.
- Python, bibliothèque
unittest, consultée le 4 novembre 2026. - Python, bibliothèque
hashlib, consultée le 4 novembre 2026. - Python, bibliothèque
json, consultée le 4 novembre 2026.