HarnessRouter interface unifiée agents IA : le dépôt HarnessRouter/harnessrouter propose une couche auto-hébergeable qui pilote plusieurs harnais d’agents (Codex, Claude Code, Hermes et une trentaine d’autres) derrière une seule API. Il compte environ 3 700 étoiles et 395 forks à la fin d’octobre 2026, sous licence Apache 2.0. C’est un dépôt jeune : la page de releases affiche une dizaine de versions 0.36 et 0.37 publiées entre le 23 et le 27 octobre 2026, dont la v0.37.6 du 27 octobre.
Pour un SRE, l’intérêt est simple : un point d’entrée unique pour lancer, suivre et annuler des tâches d’agents, au lieu d’une intégration par outil. La question suivante vient tout de suite : que peut-on observer de ce point d’entrée ? Cet article suit le README, le guide d’auto-hébergement et le fichier LICENSE, lus le 27 octobre 2026.
Précision d’honnêteté : span.observer n’a pas installé HarnessRouter. Les commandes viennent du README, et les trois captures ci-dessous sont des images publiées dans le dossier docs/images du dépôt, sous sa licence Apache 2.0.
HarnessRouter interface unifiée agents IA : ce que dit le dépôt
- Rôle : le README décrit « l’interface unifiée pour les harnais d’agents ». Un harnais est ici un agent en ligne de commande comme Codex ou Claude Code. HarnessRouter les expose via une API compatible avec l’OpenAI Responses API, avec sessions persistantes, flux de progression, fichiers, annulation et erreurs structurées.
- Protocole : il implémente le Unified Harness Protocol (UHP). Le dépôt contient l’implémentation de référence, les schémas et une suite de conformité.
- Licence : Apache 2.0 (fichier LICENSE lu, avec un NOTICE de dépendances). Les CLI d’agents installés au premier lancement restent soumis à leurs propres licences : le guide cite par exemple les conditions d’Anthropic pour Claude Code et invite à vérifier la licence de Hermes.
- Chiffres : environ 3 700 étoiles, 395 forks, 789 commits sur la branche principale, relus sur la page du dépôt. La page ne montre pas de répartition des langages : nous n’en citons aucun.
- Périmètre : environ 30 bases d’agents listées (Codex, Claude Code, Hermes, Pi, OpenCode, Gemini CLI, Cline, goose, Aider, OpenHands, etc.). Une matrice de support indique lesquelles tournent avec quel fournisseur.
Visite de l’interface
La console web écoute sur le port 3000. Le README décrit un parcours en trois temps : connecter une clé de fournisseur de modèle (« Bring your own key »), décrire en une phrase ce que l’agent doit faire, puis envoyer une première tâche.

Selon le README, HarnessRouter écrit alors les instructions de l’agent, choisit le harnais, le modèle, les compétences et les outils, puis laisse une requête d’exemple. Le harnais est figé une fois la configuration enregistrée : pour en changer, on crée une autre configuration.

Le README propose aussi trois exemples dont la requête rejoue une exécution enregistrée, pour voir une tâche terminée sans dépenser de tokens. La capture suivante en montre une : un fichier produit, le badge « Recorded » et la durée de 105,2 secondes.

Installation pas à pas
Prérequis selon le README : Docker, environ 4 Go de disque et une clé API d’un fournisseur de modèle. Aucun compte HarnessRouter, aucun modèle ni clé d’essai n’est fourni. Le README ne détaille pas de procédure par système : tout passe par Docker.
Étape 1 — Lancer le conteneur
docker run -d --name harnessrouter \
-p 127.0.0.1:3000:3000 \
-v harnessrouter:/data \
harnessrouter/harnessrouter
Le volume nommé conserve la base, les fichiers, les CLI d’agents installés et les espaces de travail. N’ajoutez pas --user : le point d’entrée a besoin de root pour gérer un utilisateur par session. Gardez la liaison sur 127.0.0.1 tant que le mot de passe initial n’est pas changé.
Étape 2 — Attendre la fin du premier démarrage
docker logs -f harnessrouter
Le premier lancement installe les CLI d’agents. Continuez quand le journal affiche [harnessrouter] ready on :3000. La ligne backends available: liste ce qui s’est réellement installé.
Étape 3 — Ouvrir la console et changer le mot de passe
Ouvrez http://localhost:3000. Les identifiants initiaux du README sont harnessrouter pour l’utilisateur et le mot de passe. Changez-les dans Profile avant toute exposition ; le journal répète un avertissement tant que le mot de passe par défaut est en place.
Étape 4 — Appeler l’API depuis votre produit
Créez une clé dans API Keys et gardez-la côté serveur dans HARNESSROUTER_API_KEY. Le harnais se choisit par metadata.harness_id :
export HARNESSROUTER_BASE_URL=http://localhost:3000/api/harness
curl --fail-with-body -sS "$HARNESSROUTER_BASE_URL/v1/responses" \
-H "Authorization: Bearer ${HARNESSROUTER_API_KEY:?}" \
-H 'content-type: application/json' \
-d '{
"input":"Reply with exactly: it works.",
"metadata":{"harness_id":"codex"},
"model":"gpt-5.4-mini",
"stream":false
}'
Changer d’agent revient à changer harness_id (et le modèle). C’est le routage : le même appel, un autre harnais. La tâche et sa transcription apparaissent dans la console. Pour rejouer une requête sans la relancer, envoyez le même en-tête Idempotency-Key ; une clé réutilisée avec un corps différent renvoie une erreur 409.
Observer HarnessRouter : journaux, tokens et traces
Voici ce que la documentation du dépôt décrit, et rien de plus.
- Journaux du conteneur :
docker logs -f harnessroutermontre l’installation des harnais, la ligneready on :3000, les harnais disponibles et les installations en échec. Le guide précise que le journal nomme l’installation qui a échoué. - Tokens par tâche : la réponse de l’API contient un objet
usageavecinput_tokens,output_tokensettotal_tokens; le guide montre aussireasoning_tokens, le compte du fournisseur, absent quand celui-ci n’en donne pas. Ce sont ces champs qu’il faut collecter côté appelant pour suivre les coûts. - Contexte de trace W3C : si la requête porte les en-têtes
traceparentettracestate, les appels au modèle de la tâche reçoivent un enfant de cette trace : même identifiant de trace, nouvel identifiant de span, drapeau d’échantillonnage conservé. Une valeur invalide est ignorée sans faire échouer la tâche. L’en-têtebaggagen’est jamais lu. - Historique d’exécution :
GET /v1/sessions/{session_id}/turnsdonne les tours ;GET /v1/traces/{session_id}/allrenvoie le flux d’événements du harnais en JSON délimité par des sauts de ligne, un événement par ligne. - Données de produit : l’édition communautaire désactive l’analytique de la console.
Deux limites à connaître. D’abord, le guide indique que les spans d’appels au fournisseur (les requêtes au modèle derrière un tour) relèvent de l’observabilité du service hébergé et non de cette édition. Ensuite, dans le README et le guide lus, nous n’avons trouvé aucun export OTLP ni métriques Prometheus : on corrèle donc les traces côté appelant, en injectant traceparent, et on collecte usage soi-même. Pour cette collecte, voir le coût d’un agent IA en tokens avec OpenTelemetry et observer les agents MCP avec OpenTelemetry.
Limites et points ouverts
- Ancrage à signaler : dépôt très récent, avec des versions publiées presque chaque jour. Les formules du README (« la première interface unifiée au monde », 99,8 % de coût en moins et 3,2 fois plus rapide sur huit configurations) sont des affirmations du projet. La méthodologie est sur harnessrouter.ai/benchmarks, que nous n’avons pas vérifiée ; le README précise que le moins cher et le plus rapide varient selon la tâche.
- Pas de plafond de coût : le guide écrit qu’aucun plafond de coût ne limite un tour ; un harnais avec
max_cost_usdest refusé. Un tour est borné parmax_stepettimeout_seconds; les limites de dépense se règlent chez le fournisseur. - Sécurité : mot de passe par défaut, conteneur qui exige root, sessions séparées par utilisateur système et non par conteneur. Le README rappelle qu’un secret lisible par l’agent peut être envoyé ailleurs si une consigne le lui demande : donnez des jetons courts et à droits minimaux.
- Édition communautaire : facturation, multi-utilisateurs et plusieurs réplicas relèvent du service hébergé payant. Les kits de démarrage (Slides, Sheets, Dashboards, Videos, My Workplace) sont sous d’autres conditions que l’édition communautaire.
- Licences amont : chaque CLI d’agent garde sa licence ; Apache 2.0 ne les remplace pas.
Pour situer le projet, voir OpenClaw (un agent et ses canaux), Paperclip (l’orchestration d’une flotte), Orca (le pilotage d’agents de code), Ruflo (les essaims), ECC (l’optimisation des harnais) et wshobson/agents (une place de marché de plugins). Dans la série, OpenBot traite le même besoin côté poste de bureau. HarnessRouter se place côté serveur, comme passerelle d’API.
Bonnes pratiques
- Gardez
127.0.0.1et changez le mot de passe avant de publier le port ; placez le reste derrière TLS, comme le guide le décrit. - Limitez les harnais installés avec
HR_BACKENDS: un harnais non installé échoue à sa première tâche. - Envoyez
traceparentà chaque appel pour retrouver la tâche dans vos traces. - Enregistrez
usagepour chaque réponse et fixez vos plafonds de dépense chez le fournisseur. - Utilisez une
Idempotency-Keypour toute nouvelle tentative. - Fournissez aux agents des jetons à durée courte et à droits minimaux.
Questions fréquentes
HarnessRouter est-il open source ?
L’édition communautaire est sous licence Apache 2.0, d’après le fichier LICENSE. Les kits de démarrage ont des conditions différentes et les CLI d’agents gardent leurs licences d’origine.
HarnessRouter exporte-t-il des traces OpenTelemetry ?
Le README décrit la propagation du contexte W3C (traceparent, tracestate) vers les appels au modèle. Le guide précise que les spans d’appels au fournisseur sont réservés au service hébergé. Aucun export OTLP n’est documenté dans les pages lues.
Comment suivre le coût en tokens ?
Lisez l’objet usage de chaque réponse. Aucun plafond de coût n’existe dans cette édition : réglez-le chez votre fournisseur de modèle.
Conclusion
HarnessRouter donne un point d’entrée unique pour plusieurs agents de code, avec un routage par harness_id et une API déjà familière. L’observabilité reste à construire autour : journaux du conteneur, usage et contexte de trace injecté par l’appelant. Essayez-le d’abord en local, sans exposer le port. Sources : dépôt HarnessRouter/harnessrouter et son guide d’auto-hébergement.
span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC ni aux projets cités. Les marques citées appartiennent à leurs propriétaires. Les outils évoluent vite : vérifiez les commandes et options dans leur documentation officielle.