HarnessRouter interface unifiée agents IA : installer et observer

HarnessRouter interface unifiée agents IA : installation Docker d’après le README, licence Apache 2.0, tokens, journaux et traces à observer.
HarnessRouter interface unifiée agents IA : installer et observer

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.

Console HarnessRouter interface unifiée agents IA : boîte de dialogue Set up an agent harness avec les choix Agent harness et Model sur Auto et une phrase décrivant un résumé hebdomadaire des retours clients
Source : github.com

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.

Console HarnessRouter : écran Setup saved avec le harnais Hermes, le modèle gpt-6.1-sol, les instructions, puis Sandbox, Orchestration, Sessions, Streaming, Files et artifacts, Cancellation et errors
Source : github.com

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.

Console HarnessRouter : tâche Product images exécutée par Hermes avec gpt-5.4, badge Recorded, trois fichiers PNG produits et durée Done in 105.2 s
Source : github.com

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 harnessrouter montre l’installation des harnais, la ligne ready 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 usage avec input_tokens, output_tokens et total_tokens ; le guide montre aussi reasoning_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 traceparent et tracestate, 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ête baggage n’est jamais lu.
  • Historique d’exécution : GET /v1/sessions/{session_id}/turns donne les tours ; GET /v1/traces/{session_id}/all renvoie 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_usd est refusé. Un tour est borné par max_step et timeout_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.1 et 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 usage pour chaque réponse et fixez vos plafonds de dépense chez le fournisseur.
  • Utilisez une Idempotency-Key pour 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.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Previous Post
ThinkRail IDE vibe coding : installer, observer, limites

ThinkRail IDE vibe coding : installer, observer, limites

Next Post
Skill Recorder skill agent : relire et auditer un skill

Skill Recorder skill agent : relire et auditer un skill

Related Posts