API Hermes Agent : un endpoint, tout frontend

Tout frontend de chat compatible OpenAI sait déjà parler /v1/chat/completions. Hermes Agent tire tout ce qu'il peut de ce fait : pointez n'importe lequel d'entre eux vers http://localhost:8642/v1, passez une clé API et vous obtenez tout le runtime Hermes - outils, mémoire, skills, cron - derrière une surface HTTP familière, sans changement côté client.

C'est toute l'idée du serveur API Hermes. Ce n'est pas un SDK spécifique Hermes à apprendre. C'est la forme OpenAI, servie localement, qui enveloppe l'agent. Si vous avez déjà Open WebUI, LobeChat, LibreChat, NextChat, ChatBox ou un script qui parle à openai-python, vous savez déjà intégrer.

Cet article détaille ce que le serveur API expose, comment l'activer et les motifs qui tiennent quand on commence à y brancher de vrais frontends.

Ce que le serveur API expose vraiment

Le serveur API est un composant du gateway Hermes. Quand il est activé, il écoute par défaut sur 127.0.0.1:8642 et parle le contrat HTTP d'OpenAI sur quatre familles d'endpoints :

/v1/chat/completions - l'endpoint Chat Completions classique. Sans état, avec ou sans streaming. C'est ce qu'utilisent 90 % des frontends compatibles OpenAI.
/v1/responses - la Responses API plus récente, avec état, avec chaînage par previous_response_id, pour qu'une conversation puisse être reprise par identifiant plutôt qu'en renvoyant tout l'historique.
/v1/runs - une API de tâches longues pour les jobs qui dépassent un simple cycle requête/réponse. Le client soumet un run, interroge le statut, récupère le résultat quand il est prêt.
/api/jobs - une couche REST pour l'ordonnanceur cron intégré, pour qu'une app externe crée, liste et annule des exécutions planifiées de l'agent comme elle gérerait n'importe quelle autre ressource.

Chaque requête que vous envoyez traverse toute la stack Hermes. Le modèle ne répond pas seul. Il a accès au terminal, au système de fichiers, à la recherche web, aux fichiers de mémoire et à tout serveur MCP que vous avez configuré. Pour une vue plus large sur la façon dont ces outils atteignent le modèle, voir Hermes Agent et MCP.

Activer le serveur API

Le serveur API est éteint par défaut. Vous l'activez avec deux réglages dans ~/.hermes/.env :

API_SERVER_ENABLED=true
API_SERVER_KEY=$(openssl rand -hex 32)

Puis redémarrez le gateway (hermes gateway). Les mêmes valeurs peuvent vivre dans ~/.hermes/config.yaml sous gateway.api_server: si vous préférez YAML, mais les variables d'environnement l'emportent quand les deux sont définis.

Quelques choses à savoir avant de basculer :

L'adresse d'écoute par défaut est 127.0.0.1, ce qui veut dire que l'endpoint n'est joignable que depuis le même hôte. Si vous exécutez Hermes dans un conteneur Docker et que vous voulez qu'un autre conteneur ou votre machine hôte l'atteigne, définissez aussi API_SERVER_HOST=0.0.0.0 et assurez-vous que le port est mappé.
API_SERVER_KEY doit faire au moins 8 caractères. Traitez-la comme n'importe quel secret d'API : pas de commit, pas de collage dans un canal partagé. Si elle fuit, n'importe quoi sur le réseau peut exécuter des runs de l'agent sur votre compte avec vos outils et vos identifiants.
Le port 8642 est une convention Hermes, pas un standard. S'il entre en conflit avec quelque chose sur votre machine, changez API_SERVER_PORT. Tout ce qui suit a juste besoin de l'URL de base.

Une fois le serveur en ligne, vérifiez avec n'importe quel SDK OpenAI :

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8642/v1",
    api_key="la-cle-que-vous-avez-definie",
)

resp = client.chat.completions.create(
    model="hermes",
    messages=[{"role": "user", "content": "Quel jour est-on, et lis README.md."}],
)
print(resp.choices[0].message.content)

Rien dans cet extrait n'est spécifique à Hermes, sauf l'URL de base. C'est précisément le but.

Des frontends qui fonctionnent tout de suite

Comme la surface est celle d'OpenAI, la plupart des frontends de chat existants se connectent en changeant un seul réglage. Un petit tour d'horizon de ceux qu'on nous demande le plus :

Open WebUI. Admin Settings → Connections → OpenAI → Add Connection. Mettez l'URL de base à http://localhost:8642/v1 et la clé API à votre API_SERVER_KEY. L'erreur la plus fréquente est d'oublier le suffixe /v1 : ne l'oubliez pas. Open WebUI persiste cela dans sa propre base, donc si vous changez la clé plus tard, mettez à jour depuis l'UI admin, pas en modifiant à nouveau la variable d'environnement.

LobeChat. Dans Settings → Language Model → OpenAI, surchargez l'API proxy URL avec http://localhost:8642/v1 et collez la clé. La liste des modèles peut être une seule entrée nommée hermes ; le serveur mappe tout sur le même agent.

LibreChat. Ajoutez un endpoint personnalisé dans librechat.yaml avec apiKey: votre-cle, baseURL: http://localhost:8642/v1 et le nom de modèle que vous voulez voir dans le sélecteur. LibreChat gère le reste comme si vous aviez configuré un OpenAI auto-hébergé.

NextChat, ChatBox et compagnie. Même motif : URL de base et clé. Si un frontend annonce la compatibilité OpenAI, il fonctionne quasi certainement.

Ce qui est bien avec Hermes derrière ces frontends, c'est que vous récupérez leur soin d'UI - historique de conversation, sessions épinglées, changement de modèle, comparaisons côte à côte - alors que le « modèle » est en réalité votre agent avec vos outils.

Streaming, progrès des outils et la Responses API

Deux choses sur le serveur API surprennent la première fois.

La première, c'est que le streaming transporte le progrès des outils. Quand l'agent décide d'exécuter le shell, d'aller sur le web ou de lire un fichier, le stream le remonte au client. Les frontends qui respectent le format de streaming affichent inline « running tool: web_search » ou similaire, puis continuent avec la vraie réponse du modèle. Vous obtenez une vraie observabilité de ce que fait l'agent sans câbler un log à part.

La seconde, c'est la Responses API. /v1/responses est avec état d'une manière que /v1/chat/completions n'est pas. Au lieu de renvoyer tout l'historique à chaque tour, le client peut passer previous_response_id et le serveur reprend là où la réponse précédente s'est arrêtée. Cela compte pour les longues conversations à plusieurs tours, où renvoyer l'historique coûte cher, et cela colle naturellement à la direction que prennent les SDK plus récents d'OpenAI lui-même. Si votre frontend supporte les deux, préférez Responses pour les sessions longues et Chat Completions pour les appels ponctuels.

Runs et Jobs couvrent les cas qui deviennent gênants dans le modèle requête/réponse : un run qui prend dix minutes ou un job planifié qui se déclenche tous les matins à 8 h et dépose un résumé dans un canal. Voir Hermes Agent scheduled tasks and automation pour le motif côté cron.

Motifs à suivre

Quelques habitudes qui tiennent quand le serveur API fait du vrai travail :

Gardez l'endpoint sur localhost tant que vous n'avez pas de raison. Le bind par défaut est sûr. Si vous avez besoin d'un accès distant, mettez un vrai reverse proxy devant, avec TLS et authentification, plutôt que de simplement basculer l'hôte à 0.0.0.0 sur l'internet public.

Une clé par client, si vous pouvez. Le serveur actuel accepte une seule API_SERVER_KEY. Si vous câblez plusieurs frontends et voulez pouvoir en révoquer un sans casser les autres, faites tourner des instances Hermes séparées derrière des clés séparées, ou terminez sur un proxy qui émet des clés par client et transmet une clé partagée à l'agent.

Le nom du modèle est une étiquette, pas un routeur. Chaque requête passe par le même agent. Pointez chaque frontend sur la même entrée model: "hermes" sauf si vous voulez spécifiquement qu'ils affichent des noms différents dans leur UI.

Surveillez les logs quand vous branchez un nouveau frontend. Le gateway loggue chaque requête entrante et chaque appel d'outil. Parcourez-les sur les premières conversations : vous verrez vite si le frontend envoie les messages attendus ou, par exemple, injecte un system prompt qui se bat contre vos fichiers de mémoire existants.

Préférez Responses pour les longs échanges, Chat Completions pour les scripts. La complexité côté client est la même. Côté serveur, non.

Où Hermify s'insère

Faire tourner le serveur API vous-même est simple, mais cela veut toujours dire garder le processus du gateway en vie, mettre à jour le conteneur et veiller à ce que le port soit joignable. Si vous préférez vous en passer, Hermify fait tourner un Hermes Agent géré pour vous sur Telegram, avec les mêmes outils, la même mémoire et les mêmes skills, en ligne en une minute environ. Aujourd'hui, la surface API managée est Telegram d'abord ; le serveur API auto-hébergé, c'est là où vous allez quand vous voulez pointer des clients sur votre propre agent. Dans un cas comme dans l'autre, le runtime sous-jacent est le même, donc le modèle mental de cet article se transpose.