API Server — Hermes as a Service | Easy Understand Hermes Agent

Serveur API — Hermes en tant que service

Imaginez ceci : vous avez construit un agent IA incroyable avec Hermes. Il peut exécuter des commandes terminal, rechercher sur le web, gérer des fichiers et mémoriser des choses. Mais il vit dans votre terminal. Et si vous pouviez le brancher sur une belle interface de chat comme Open WebUI ou LobeChat ? C’est exactement ce que fait le Serveur API.

Considérez-le comme un traducteur universel. Le Serveur API expose Hermes comme un point de terminaison HTTP compatible OpenAI. Cela signifie que n’importe quelle interface frontale qui parle le « langage OpenAI » — et il y en a des centaines — peut se connecter à Hermes et l’utiliser comme un backend puissant. Votre agent conserve tout son arsenal d’outils, et l’interface frontale ne devient qu’un joli habillage pour lui.

Le meilleur dans tout ça ? Lorsque vous diffusez les réponses en streaming, les indicateurs de progression des outils apparaissent en ligne. Ainsi, vos utilisateurs peuvent réellement voir l’agent exécuter une commande ou rechercher sur le web, au lieu de fixer un curseur clignotant.

Un Seul Backend, Pleine Puissance

Avant de plonger, un petit conseil. Hermes a besoin d’un fournisseur configuré et de backends d’outils pour être utile. Un abonnement Nous Portal gère les deux — vous obtenez l’accès à plus de 300 modèles ainsi qu’aux outils web, image, TTS et navigateur via la Tool Gateway.

Exécutez hermes setup --portal une fois, et vous êtes prêt à offrir à n’importe quelle interface frontale un backend entièrement équipé d’outils. C’est le moyen le plus simple de démarrer.

Démarrage Rapide : Trois Étapes

1. Activer le Serveur API

Ouvrez votre fichier ~/.hermes/.env et ajoutez ces lignes :

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Optionnel : uniquement si un navigateur doit appeler Hermes directement
# API_SERVER_CORS_ORIGINS=http://localhost:3000

Le API_SERVER_KEY est votre mot de passe. Changez-le pour quelque chose de sécurisé !

2. Démarrer la Passerelle

Exécutez cette commande :

hermes gateway

Vous verrez un message comme :

[API Server] API server listening on http://127.0.0.1:8642

Et voilà. Votre agent est maintenant un service.

3. Connecter une Interface Frontale

Pointez n’importe quel client compatible OpenAI vers http://localhost:8642/v1. Testons avec curl :

curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer change-me-local-dev" \
  -H "Content-Type: application/json" \
  -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'

Ou connectez Open WebUI, LobeChat, ou toute autre interface frontale. Consultez le guide d’intégration Open WebUI pour des instructions étape par étape.

Les Points de Terminaison : Deux Façons de Dialoguer

Le Serveur API offre deux points de terminaison principaux.

POST /v1/chat/completions

C’est le format standard des Chat Completions d’OpenAI. Il est sans état — vous envoyez l’historique complet de la conversation dans chaque requête via le tableau messages.

Voici une requête simple :

{
  "model": "hermes-agent",
  "messages": [
    {"role": "system", "content": "You are a Python expert."},
    {"role": "user", "content": "Write a fibonacci function"}
  ],
  "stream": false
}

Et la réponse :

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "hermes-agent",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Here's a fibonacci function..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250}
}

Les images en ligne sont prises en charge. Vous pouvez envoyer des images dans le contenu du message :

{
  "model": "hermes-agent",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/cat.png", "detail": "high"}}
      ]
    }
  ]
}

Les URL distantes et les URL data:image/... fonctionnent toutes les deux. Notez que les fichiers téléversés et les URL de données non-image renverront une erreur 400 unsupported_content_type.

Le streaming, c’est là que la magie opère. Définissez "stream": true et vous obtiendrez des Server-Sent Events (SSE) avec des réponses token par token. Pour les Chat Completions, vous verrez des événements standard chat.completion.chunk plus un événement personnalisé hermes.tool.progress. Cela permet aux interfaces frontales d’afficher l’activité des outils sans polluer le texte final de l’assistant.

POST /v1/responses

C’est le format plus récent de l’API Responses d’OpenAI. La grande différence ? Il prend en charge l’état de conversation côté serveur via previous_response_id. Le serveur stocke l’historique complet de la conversation, y compris les appels d’outils et leurs résultats, de sorte que le contexte multi-tours est préservé sans que le client ait à le gérer.

Voici une requête :

{
  "model": "hermes-agent",
  "input": "What files are in my project?",
  "instructions": "You are a helpful coding assistant.",
  "store": true
}

La réponse montre les appels d’outils qui ont déjà été exécutés :

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "hermes-agent",
  "output": [
    {"type": "function_call", "status": "completed", "name": "terminal", "arguments": "{\"command\": \"ls\"}", "call_id": "call_1"},
    {"type": "function_call_output", "status": "completed", "call_id": "call_1", "output": "README.md src/ tests/"},
    {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "Your project has..."}]}
  ],
  "usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}

Remarquez comment les appels d’outils ont "status": "completed". Hermes les a déjà exécutés côté serveur. Le client n’a plus qu’à rendre l’interface utilisateur structurée des outils.

Le multi-tours est un jeu d’enfant. Il suffit d’enchaîner les réponses :

{
  "input": "Now show me the README",
  "previous_response_id": "resp_abc123"
}

Le serveur reconstruit la conversation complète, y compris tous ces appels d’outils, et reprend là où vous vous étiez arrêté.

Prêt à Servir ?

Le Serveur API transforme Hermes d’un outil local en un service à part entière. Que vous préfériez la simplicité des Chat Completions ou la puissance avec état des Responses, vous disposez désormais d’un backend universel pour toute interface frontale compatible OpenAI. Essayez-le — votre agent est prêt à servir.