Hermes Agent : quand Hermes devient une brique d’intégration

Il y a un moment où Hermes change de catégorie.

Au début, c’est un outil que tu lances depuis ton terminal. Tu ouvres une session, tu lui donnes un contexte, tu regardes ce qu’il fait, tu l’arrêtes.

Puis arrive une autre question :

à partir de quand est-ce que ça vaut le coup de brancher Hermes à autre chose ?

C’est là que le sujet devient intéressant. Parce qu’à partir de ce moment, Hermes n’est plus seulement un agent que tu utilises. Il devient une surface que d’autres clients, d’autres outils ou d’autres workflows peuvent appeler.

Et cette bascule change plus que la façon de le lancer.

Elle change la surface d’exposition, le nombre d’entrées possibles, la séparation des contextes, la manière de protéger les accès, et la clarté de ce qui est censé faire quoi.

Ce que tu auras à la fin
Une vision nette de ce que change vraiment le passage à une logique d’intégration, des formes officielles que Hermes propose aujourd’hui pour ça, des cas où ça a du sens, des cas où ça n’en a pas, et des responsabilités supplémentaires que cette bascule ajoute presque toujours.

Ce que change vraiment le mode intégration

Tant qu’Hermes vit seulement dans ton terminal, beaucoup de garde-fous sont presque naturels.

Tu es là. Tu vois le dossier courant. Tu sais quel profile tu utilises. Tu sens vite si tu t’es trompé de contexte, de backend ou de session.

Dès que Hermes devient joignable depuis autre chose, cette protection implicite baisse.

Un client OpenAI-compatible peut lui envoyer des requêtes HTTP. Un éditeur compatible ACP peut l’utiliser comme backend d’agent. Un client MCP peut venir lui parler via stdio. Dans tous les cas, l’idée est la même : Hermes n’est plus seulement un binaire que tu lances pour toi. Il devient un point d’accès réutilisable.

Le gain est réel. Tu peux centraliser un agent déjà bien réglé, le réutiliser derrière une autre interface, et éviter de reconstruire la même logique ailleurs.

Mais le prix l’est aussi. Quand tu ouvres cette porte, tu dois décider plus clairement qui peut entrer, depuis où, avec quels droits, sur quel profile, avec quel backend d’exécution, et avec quel niveau de confiance.

Un Hermes branché à autre chose n’est pas seulement plus pratique. Il demande une gouvernance plus propre.

Pourquoi ce sujet arrive en dernier

Ce tuto arrive logiquement après la suite logique après la série principale.

La raison est simple : ici, on ne parle plus seulement d’ajouter une capacité. On parle de donner à Hermes une place dans un système plus large.

Sans profiles clairs, sans backend compris, sans permissions lisibles et sans cadre de retour arrière, cette bascule devient vite une mauvaise industrialisation d’un setup encore flou.

Usage individuel contre brique réutilisable, en clair

En usage individuel, Hermes est surtout lié à ton moment de travail.

Tu l’ouvres quand tu en as besoin. Tu pilotes le rythme. Le contexte de départ est largement implicite. Même si ton setup est musclé, la frontière reste simple : Hermes est ton agent, sur ta machine, dans ton flux.

En brique réutilisable, Hermes est lié à un contrat d’accès.

Quelqu’un ou quelque chose d’autre le joint. Il faut donc des règles plus explicites : endpoint, authentification, transport, working directory, profile, outils exposés, permissions, isolation éventuelle.

Ce n’est plus seulement une question de confort.

C’est une question de surface, de responsabilité et de lisibilité.

Dit autrement : en CLI, tu pilotes surtout une conversation. En intégration, tu pilotes une interface entre Hermes et le reste.

Les trois formes officielles qui font vraiment sortir Hermes du terminal

La doc officielle actuelle ne décrit pas un unique “serveur Hermes” qui ferait tout.

Elle décrit plusieurs formes d’intégration, avec des usages différents.

1. L’API server

C’est la forme la plus évidente si tu veux brancher Hermes derrière une autre interface.

L’API server expose Hermes comme endpoint HTTP compatible OpenAI. Un frontend qui parle déjà ce format peut donc utiliser Hermes comme backend.

Le point important, ce n’est pas juste le protocole. C’est le fait que le client distant retrouve le vrai agent Hermes, avec son outillage, sa mémoire et ses skills.

C’est utile quand tu veux une autre UI, un autre client, ou un accès programmatique propre, sans reconstruire un agent parallèle.

2. Le mode ACP

Le mode ACP ne sert pas à mettre Hermes sur le réseau au sens large.

Il sert à faire d’Hermes un agent natif pour un éditeur compatible ACP. La doc officielle le présente avec un toolset hermes-acp pensé pour l’éditeur : fichiers, patch, terminal, process, web, mémoire, todo, recherche de session, skills, execute_code, delegate_task et vision, mais sans les couches qui collent mal à cet usage, comme la livraison messagerie ou la gestion des cron jobs.

ACP n’est donc pas le serveur universel. C’est la bonne brique quand tu veux qu’Hermes vive dans l’éditeur comme agent de travail.

3. Le mode MCP server

Avec hermes mcp serve, Hermes ne lance ni un backend d’éditeur, ni simplement “un autre terminal Hermes”.

Il devient un serveur MCP que d’autres clients compatibles peuvent consommer. La doc officielle le présente comme un mode qui expose conversations, sessions et pièces jointes à des clients MCP, avec prise en charge de stdio et de Streamable HTTP.

La bonne lecture, c’est donc celle-ci :

• API server pour brancher un client OpenAI-compatible à Hermes
• ACP pour brancher Hermes proprement dans un éditeur compatible
• MCP server mode pour rendre Hermes consommable comme serveur MCP par un autre client compatible

Ces trois portes ne servent pas au même usage. Les mélanger dans le même sac est la meilleure façon de choisir la mauvaise brique.

Cas 1 — Hermes reste un bon outil individuel, et c’est très bien

La situation de départ

Tu utilises Hermes sur ta machine, pour un projet bien cadré, depuis le terminal. Tu sais où il tourne. Tu sais quel profile tu utilises. Tu n’as pas besoin qu’un autre frontend, un autre éditeur ou un autre agent vienne le consommer.

Pourquoi l’usage individuel suffit

Dans ce cas, passer Hermes en brique d’intégration n’apporte pas grand-chose.

Tu n’as pas de problème d’interface à résoudre.

La CLI reste la forme la plus simple, la plus lisible et souvent la plus propre.

Ce qu’on gagne

Tu gardes un périmètre serré : moins d’exposition, moins d’authentification à gérer, moins de confusion entre le cœur d’Hermes et la façon de l’atteindre.

Ce qu’il faut surveiller

Le piège ici, c’est la curiosité technique. Monter un serveur parce qu’on peut le faire n’est pas une bonne raison.

Pourquoi ça reste une bonne décision

Parce que “Hermes reste un outil individuel” n’est pas une demi-victoire. C’est souvent la décision la plus mature quand le besoin réel n’a pas encore dépassé le terminal.

Cas 2 — Hermes devient une vraie brique derrière un autre client

La situation de départ

Tu as déjà un Hermes propre. Les profiles sont clairs. Le backend d’exécution est compris. Les outils utiles sont choisis. Tu veux maintenant le réutiliser derrière une autre interface au lieu de tout refaire ailleurs.

Exemple public et neutre : brancher une UI compatible OpenAI sur Hermes via l’API server, ou utiliser Hermes comme agent dans un éditeur compatible ACP.

Pourquoi l’usage individuel ne suffit plus

La limite n’est plus la qualité de l’agent. La limite, c’est l’interface.

Tu veux une UI plus confortable, un accès plus naturel depuis un éditeur, ou un backend unique que plusieurs clients compatibles savent déjà appeler.

Ce qu’on gagne

Tu gardes un agent déjà cadré au lieu de multiplier les copies. Même logique, mêmes skills, même discipline d’outils, mais avec une autre porte d’entrée.

C’est là que l’intégration devient propre : tu ne dupliques pas Hermes, tu le rends consommable par autre chose.

Ce qu’il faut surveiller

C’est précisément à ce moment qu’il faut redevenir strict.

Avec l’API server, le client distant parle à un agent qui garde son vrai outillage. Si tu exposes ça trop largement, tu n’exposes pas seulement un chatbot. Tu exposes aussi des capacités d’action.

Avec ACP, la discipline reste nécessaire : working directory, permissions terminales, modèle réellement configuré, et compréhension du fait qu’on parle ici d’un agent de travail intégré à l’éditeur.

Pourquoi ça reste une brique avancée

Parce que le gain ne vient pas d’une fonction magique. Il vient du fait que ton Hermes est désormais assez propre pour servir de backend à autre chose sans devenir opaque.

Cas 3 — C’est une mauvaise idée si la base n’est pas déjà propre

La situation de départ

Tu n’as qu’un profile fourre-tout. Tu ne sais pas toujours si Hermes exécute en local, en Docker ou ailleurs. La mémoire persistante n’est pas claire. Les outils sont trop larges. Bref : ça marche, mais de manière artisanale.

Pourquoi ça casse vite

Exposer Hermes dans cet état ne règle rien. Tu ajoutes une surface d’entrée à un système que tu comprends encore mal.

Le problème n’est pas “le serveur”.

Le problème, c’est d’avoir industrialisé quelque chose qui n’était pas stabilisé.

Ce qu’on perd

On perd la lisibilité. Tu ne sais plus si le problème vient du client, du profile, du backend, du transport, des permissions, ou d’une mémoire qui déborde d’un contexte à l’autre.

Ce qu’il faut retenir

Le vrai prérequis n’est pas “savoir lancer une commande serveur”. C’est avoir déjà un Hermes compréhensible quand il tourne encore seulement pour toi.

Les premières commandes et snippets qui comptent vraiment

Pas de pavé d’API ici. Juste les formes officielles qui servent vraiment.

API server

Dans la doc officielle du moment, l’exemple de base passe par une activation dans ~/.hermes/.env, puis par le gateway.

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev

Puis :

hermes gateway

Selon le setup retenu, le client vient alors parler à l’endpoint local exposé par ce gateway, généralement sur http://127.0.0.1:8642/v1 dans l’exemple de base, avec un bearer token.

Le point important n’est pas d’apprendre toute l’API. Le point important est de comprendre que tu viens d’ouvrir un accès HTTP local à un Hermes réel, avec de vrais outils derrière.

ACP server mode

Si le support ACP n’est pas déjà présent dans ton install :

pip install -e '.[acp]'

Puis, dans la doc actuelle, la porte d’entrée la plus simple reste :

hermes acp

Les entrées hermes-acp et python -m acp_adapter sont aussi documentées selon les cas.

Le plus utile à retenir ici, ce n’est pas une commande figée. C’est que cette porte correspond à une intégration ACP côté éditeur, pas au même rôle que l’API server.

MCP server mode

La commande de base documentée est courte :

hermes mcp serve

Dans la doc actuelle, les exemples les plus directs passent surtout par une déclaration client de ce type :

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp", "serve"]
    }
  }
}

Selon le client MCP utilisé, le transport exact et les détails d’intégration peuvent varier. Le point important n’est pas de retenir toute la syntaxe. C’est de retenir que cette porte relève du monde MCP, pas d’un simple clone de l’API server.

Ce que cette bascule ajoute comme responsabilités

La première responsabilité, c’est l’authentification et l’exposition.

L’API server est documenté avec un bind local par défaut sur 127.0.0.1, un bearer token, et un CORS désactivé par défaut. Ce n’est pas du décor. C’est la doc qui te dit, en creux, que cette surface n’est pas censée être ouverte n’importe comment.

La deuxième responsabilité, c’est la séparation.

Si plusieurs usages, plusieurs personnes ou plusieurs clients doivent cohabiter, les profiles deviennent une vraie frontière utile. La doc officielle montre d’ailleurs explicitement une logique de profiles séparés avec ports et clés distincts côté API server.

La troisième responsabilité, c’est le périmètre d’outils.

En API server, la doc parle bien du full toolset. En ACP, elle documente un toolset plus ciblé pour l’éditeur. En MCP server mode, le périmètre est différent. Il ne faut donc pas raisonner comme si les trois portes exposaient exactement la même chose.

La quatrième responsabilité, c’est le backend d’exécution.

Le client qui parle à Hermes ne change pas la question la plus importante : où Hermes agit-il vraiment ? Si ton backend reste local, le risque local reste local. Si tu l’as déplacé en Docker ou en SSH, la gouvernance change. Mais elle ne disparaît jamais.

Ce qu’il vaut mieux avoir déjà stabilisé avant

Avant de faire d’Hermes une brique d’intégration, il vaut mieux avoir déjà stabilisé quatre choses.

D’abord, les profiles.

Ensuite, le backend d’exécution.

Puis la mémoire, les permissions, et la capacité à revenir proprement en arrière quand quelque chose dévie.

Tu n’as pas besoin d’une usine à gaz.

Tu as besoin d’un socle lisible.

Les erreurs fréquentes

La première, c’est de parler de “serveur Hermes” comme s’il n’existait qu’un seul mode universel.

La deuxième, c’est de croire qu’une autre interface rend l’agent meilleur. Elle le rend plus accessible. C’est déjà beaucoup. Mais ce n’est pas la même chose.

La troisième, c’est d’ouvrir trop large trop tôt.

La quatrième, c’est de confondre intégration et industrialisation. Brancher un client à Hermes ne veut pas dire que tout ton cadre opérationnel est prêt.

Ce que tu ne dois pas faire

• Ne transforme pas Hermes en backend partagé si ton usage principal est encore flou.
• Ne choisis pas un mode d’intégration parce qu’il sonne plus avancé. Choisis-le parce qu’il résout un vrai problème d’interface.
• N’expose pas un agent puissant comme si tu exposais un chatbot sans outils.
• Ne mélange pas ACP, API server et MCP server mode comme s’ils étaient interchangeables.
• Et surtout, n’utilise pas l’intégration pour éviter de clarifier ton setup. Elle ne masque rien. Elle agrandit juste ce qui existait déjà.

La vraie fin du cycle principal

Ce sujet ferme bien ce palier parce qu’il montre la différence de nature entre “Hermes pour toi” et “Hermes branché dans autre chose”.

À partir d’ici, la question n’est plus seulement “qu’est-ce qu’Hermes sait faire ?”

La question devient : “quel rôle exact je lui donne dans mon système, avec quelle porte d’entrée, quel périmètre et quel niveau de confiance ?”

C’est cette bascule qui en fait une vraie brique d’intégration, pas juste une étape plus avancée de la même histoire.