Hermes Agent API-Integration: ein Endpunkt, jedes Frontend

Jedes OpenAI-kompatible Chat-Frontend spricht bereits /v1/chat/completions. Hermes Agent zieht daraus die Konsequenz: Richten Sie eines dieser Frontends auf http://localhost:8642/v1, übergeben Sie einen API-Schlüssel und Sie erhalten die gesamte Hermes-Laufzeit - Werkzeuge, Speicher, Skills, Cron - hinter einer vertrauten HTTP-Oberfläche, ohne dass am Client etwas geändert werden muss.

Das ist die ganze Idee des Hermes-API-Servers. Es ist kein Hermes-spezifisches SDK, das Sie erlernen müssten. Es ist die OpenAI-Form, lokal bereitgestellt, um den Agenten herum. Wenn Sie bereits Open WebUI, LobeChat, LibreChat, NextChat, ChatBox oder ein Skript nutzen, das mit openai-python spricht, wissen Sie bereits, wie die Integration geht.

Dieser Beitrag geht durch, was der API-Server bereitstellt, wie Sie ihn einschalten und welche Muster tragen, sobald echte Frontends daran hängen.

Was der API-Server wirklich bereitstellt

Der API-Server ist eine Komponente im Hermes-Gateway. Wenn er aktiviert ist, lauscht er standardmäßig auf 127.0.0.1:8642 und spricht den HTTP-Vertrag von OpenAI über vier Endpunkt-Familien:

/v1/chat/completions - der klassische Chat-Completions-Endpunkt. Zustandslos, mit oder ohne Streaming. Das nutzen rund 90 % der OpenAI-kompatiblen Frontends.
/v1/responses - die neuere Responses-API, mit Zustand und Verkettung über previous_response_id, sodass eine Konversation per ID fortgesetzt werden kann, statt den gesamten Nachrichtenverlauf erneut zu senden.
/v1/runs - eine API für lang laufende Aufgaben, die einen einzelnen Request-Zyklus überschreiten. Der Client reicht einen Run ein, fragt den Status ab und holt das Ergebnis, wenn es bereit ist.
/api/jobs - eine REST-Schicht über dem eingebauten Cron-Planer, sodass eine externe App geplante Agent-Ausführungen genauso anlegen, listen und abbrechen kann wie jede andere Ressource.

Jede Anfrage, die Sie senden, durchläuft den vollständigen Hermes-Stack. Das Modell antwortet nicht allein. Es hat Zugriff auf das Terminal, das Dateisystem, die Websuche, die Speicherdateien und jeden MCP-Server, den Sie konfiguriert haben. Für einen breiteren Blick darauf, wie diese Werkzeuge überhaupt zum Modell gelangen, siehe Hermes Agent und MCP.

Den API-Server einschalten

Der API-Server ist standardmäßig aus. Sie schalten ihn mit zwei Einstellungen in ~/.hermes/.env ein:

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

Danach starten Sie das Gateway neu (hermes gateway). Dieselben Werte können auch in ~/.hermes/config.yaml unter gateway.api_server: stehen, wenn Sie YAML bevorzugen, aber Umgebungsvariablen gewinnen, wenn beides gesetzt ist.

Ein paar Dinge, die Sie vor dem Umlegen wissen sollten:

Die Standard-Bind-Adresse ist 127.0.0.1, das heißt der Endpunkt ist nur vom selben Host aus erreichbar. Wenn Sie Hermes in einem Docker-Container betreiben und ein anderer Container oder Ihr Host-Rechner darauf zugreifen soll, setzen Sie zusätzlich API_SERVER_HOST=0.0.0.0 und stellen Sie sicher, dass der Port gemappt ist.
API_SERVER_KEY muss mindestens 8 Zeichen lang sein. Behandeln Sie ihn wie jedes andere API-Geheimnis: nicht committen, nicht in geteilte Kanäle einfügen. Wenn er durchsickert, kann alles im Netzwerk Agent-Runs auf Ihrem Konto mit Ihren Werkzeugen und Ihren Zugangsdaten ausführen.
Der Port 8642 ist eine Hermes-Konvention, kein Standard. Wenn er mit etwas auf Ihrem Rechner kollidiert, ändern Sie API_SERVER_PORT. Alles nachgelagert braucht nur die Basis-URL.

Sobald der Server läuft, prüfen Sie ihn kurz mit einem beliebigen OpenAI-SDK:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8642/v1",
    api_key="der-schluessel-den-sie-gesetzt-haben",
)

resp = client.chat.completions.create(
    model="hermes",
    messages=[{"role": "user", "content": "Welcher Tag ist heute, und lies README.md."}],
)
print(resp.choices[0].message.content)

An diesem Snippet ist außer der Basis-URL nichts Hermes-spezifisch. Genau das ist der Punkt.

Frontends, die einfach funktionieren

Weil die Oberfläche die von OpenAI ist, verbinden sich die meisten bestehenden Chat-Frontends mit einer einzigen Einstellungsänderung. Ein kurzer Rundgang durch die am häufigsten nachgefragten:

Open WebUI. Admin Settings → Connections → OpenAI → Add Connection. Setzen Sie die Basis-URL auf http://localhost:8642/v1 und den API-Schlüssel auf Ihren API_SERVER_KEY. Der häufigste Fehler ist, das Suffix /v1 wegzulassen - lassen Sie es nicht weg. Open WebUI speichert das in einer eigenen Datenbank; wenn Sie den Schlüssel später ändern, aktualisieren Sie ihn über die Admin-UI, nicht durch erneutes Bearbeiten einer Umgebungsvariable.

LobeChat. In Settings → Language Model → OpenAI überschreiben Sie die API-Proxy-URL mit http://localhost:8642/v1 und fügen den Schlüssel ein. Die Modellliste kann ein einziger Eintrag namens hermes sein; der Server bildet alles auf denselben Agenten ab.

LibreChat. Fügen Sie in librechat.yaml einen benutzerdefinierten Endpunkt hinzu mit apiKey: ihr-schluessel, baseURL: http://localhost:8642/v1 und dem Modellnamen, den Sie im Auswahlfeld anzeigen möchten. LibreChat regelt den Rest, als hätten Sie ein selbst gehostetes OpenAI konfiguriert.

NextChat, ChatBox und weitere. Gleiches Muster: Basis-URL und Schlüssel. Wenn ein Frontend OpenAI-Kompatibilität behauptet, funktioniert es fast sicher.

Der Vorteil, Hermes hinter diesen Frontends zu betreiben, ist, dass Sie deren UI-Feinschliff mitnehmen - Chat-Verlauf, angeheftete Sitzungen, Modellwechsel, Seite-an-Seite-Vergleiche - während das „Modell" in Wirklichkeit Ihr Agent mit Ihren Werkzeugen ist.

Streaming, Werkzeug-Fortschritt und die Responses-API

Zwei Dinge am API-Server überraschen beim ersten Mal.

Das erste: Streaming transportiert den Werkzeug-Fortschritt. Wenn der Agent entscheidet, die Shell zu starten, ins Web zu greifen oder eine Datei zu lesen, meldet der Stream diesen Schritt an den Client. Frontends, die das Streaming-Format respektieren, zeigen inline „running tool: web_search" oder Ähnliches und fahren dann mit der eigentlichen Antwort des Modells fort. Sie bekommen echte Beobachtbarkeit dessen, was der Agent tut, ohne einen separaten Log-Kanal zu verdrahten.

Das zweite ist die Responses-API. /v1/responses ist auf eine Weise zustandsbehaftet, die /v1/chat/completions nicht ist. Anstatt bei jeder Runde den vollständigen Nachrichtenverlauf erneut zu senden, kann der Client previous_response_id mitgeben, und der Server macht dort weiter, wo die vorige Antwort endete. Das zählt bei langen, vielrundigen Konversationen, in denen das erneute Hochladen des Verlaufs teuer ist, und es passt natürlich zu der Richtung, in die sich auch OpenAIs eigene neuere SDKs bewegen. Wenn Ihr Frontend beides unterstützt, bevorzugen Sie Responses für langlebige Sitzungen und Chat Completions für Einmal-Aufrufe.

Runs und Jobs decken die Fälle ab, die im Request/Response-Modell umständlich sind: ein Run, der zehn Minuten braucht, oder ein geplanter Job, der jeden Morgen um 8 Uhr feuert und eine Zusammenfassung in einen Kanal legt. Siehe Hermes Agent scheduled tasks and automation für das Muster auf der Cron-Seite.

Muster, die es sich zu befolgen lohnt

Ein paar Gewohnheiten, die tragen, wenn der API-Server echte Arbeit leistet:

Halten Sie den Endpunkt auf localhost, solange Sie keinen Grund für etwas anderes haben. Der Standard-Bind ist sicher. Wenn Sie Fernzugriff brauchen, stellen Sie einen echten Reverse-Proxy mit TLS und Authentifizierung davor; drehen Sie den Host nicht einfach auf 0.0.0.0 im öffentlichen Internet.

Ein Schlüssel pro Client, wenn möglich. Der aktuelle Server nimmt einen einzigen API_SERVER_KEY. Wenn Sie mehrere Frontends anschließen und einen davon widerrufen können möchten, ohne den Rest zu brechen, betreiben Sie separate Hermes-Instanzen hinter separaten Schlüsseln oder terminieren Sie an einem Proxy, der Schlüssel pro Client vergibt und einen geteilten Schlüssel an den Agenten weiterreicht.

Der Modellname ist ein Label, kein Router. Jede Anfrage geht durch denselben Agenten. Zeigen Sie mit jedem Frontend auf denselben Eintrag model: "hermes", es sei denn, Sie wollen ausdrücklich unterschiedliche Namen in deren UI anzeigen.

Beobachten Sie die Logs, wenn Sie ein neues Frontend anschließen. Das Gateway loggt jede eingehende Anfrage und jeden Werkzeugaufruf. Überfliegen Sie sie in den ersten Konversationen: Sie sehen schnell, ob das Frontend die erwarteten Nachrichten sendet oder etwa einen Systemprompt einspeist, der mit Ihren vorhandenen Speicherdateien kollidiert.

Bevorzugen Sie Responses für lange Chats, Chat Completions für Skripte. Die Client-Komplexität ist dieselbe. Die Server-Kosten nicht.

Wo Hermify hineinpasst

Den API-Server selbst zu betreiben, ist geradlinig, bedeutet aber weiterhin, den Gateway-Prozess am Leben zu halten, den Container aktuell zu halten und dafür zu sorgen, dass der Port erreichbar bleibt. Wenn Sie sich das lieber sparen, betreibt Hermify einen verwalteten Hermes Agent für Sie auf Telegram, mit denselben Werkzeugen, demselben Speicher und denselben Skills, in etwa einer Minute live. Heute ist die verwaltete API-Oberfläche Telegram-first; der selbst betriebene API-Server ist der Weg, wenn Sie eigene Clients auf Ihren eigenen Agenten richten wollen. So oder so ist die zugrunde liegende Laufzeit dieselbe, weshalb sich das mentale Modell aus diesem Beitrag überträgt.