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

API-Server — Hermes als Dienst

Stell dir das vor: Du hast mit Hermes einen erstaunlichen KI-Agenten gebaut. Er kann Terminalbefehle ausführen, im Web suchen, Dateien verwalten und sich Dinge merken. Aber er lebt in deinem Terminal. Was, wenn du ihn an eine schöne Chat-Oberfläche wie Open WebUI oder LobeChat anschließen könntest? Genau das macht der API-Server.

Denk daran wie an einen universellen Übersetzer. Der API-Server stellt Hermes als OpenAI-kompatiblen HTTP-Endpunkt bereit. Das bedeutet, jedes Frontend, das die „OpenAI-Sprache“ spricht – und davon gibt es hunderte – kann sich mit Hermes verbinden und es als leistungsstarkes Backend nutzen. Dein Agent behält sein komplettes Werkzeug-Set, und das Frontend wird einfach zu einem hübschen Gesicht dafür.

Das Beste daran? Wenn du Antworten streamst, erscheinen Fortschrittsanzeigen für Werkzeuge direkt inline. Deine Nutzer können also tatsächlich sehen, wie der Agent einen Befehl ausführt oder im Web sucht, statt nur auf einen blinkenden Cursor zu starren.

Ein Backend, volle Kraft

Bevor wir loslegen, ein kurzer Tipp. Hermes benötigt einen konfigurierten Provider und Tool-Backends, um nützlich zu sein. Ein Nous Portal-Abonnement deckt beides ab – du erhältst Zugang zu über 300 Modellen plus Web-, Bild-, TTS- und Browser-Tools über das Tool-Gateway.

Führe einmal hermes setup --portal aus, und schon bist du bereit, jedem Frontend ein voll ausgestattetes Backend zu geben. Das ist der einfachste Weg, um loszulegen.

Schnellstart: Drei Schritte

1. API-Server aktivieren

Öffne deine ~/.hermes/.env-Datei und füge diese Zeilen hinzu:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Optional: nur, wenn ein Browser Hermes direkt aufrufen muss
# API_SERVER_CORS_ORIGINS=http://localhost:3000

Der API_SERVER_KEY ist dein Passwort. Ändere es in etwas Sicheres!

2. Gateway starten

Führe diesen Befehl aus:

hermes gateway

Du siehst eine Meldung wie:

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

Das war’s. Dein Agent ist jetzt ein Dienst.

3. Frontend verbinden

Richte einen beliebigen OpenAI-kompatiblen Client auf http://localhost:8642/v1 aus. Testen wir es mit 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!"}]}'

Oder verbinde Open WebUI, LobeChat oder ein anderes Frontend. Schau dir den Open WebUI-Integrationsleitfaden für Schritt-für-Schritt-Anweisungen an.

Die Endpunkte: Zwei Wege zu kommunizieren

Der API-Server bietet zwei Haupt-Endpunkte.

POST /v1/chat/completions

Dies ist das Standard-OpenAI-Chat-Completions-Format. Es ist zustandslos – du sendest den gesamten Gesprächsverlauf in jeder Anfrage über das messages-Array.

Hier ist eine einfache Anfrage:

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

Und die Antwort:

{
  "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}
}

Inline-Bilder werden unterstützt. Du kannst Bilder als Teil des Nachrichteninhalts senden:

{
  "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"}}
      ]
    }
  ]
}

Sowohl Remote-URLs als auch data:image/...-URLs funktionieren. Beachte, dass hochgeladene Dateien und Nicht-Bild-Daten-URLs einen 400 unsupported_content_type-Fehler zurückgeben.

Beim Streamen passiert die Magie. Setze "stream": true und du erhältst Server-Sent Events (SSE) mit Token-für-Token-Antworten. Für Chat Completions siehst du standardmäßige chat.completion.chunk-Events plus ein benutzerdefiniertes hermes.tool.progress-Event. Das ermöglicht Frontends, Tool-Aktivitäten anzuzeigen, ohne den endgültigen Assistententext zu verschmutzen.

POST /v1/responses

Dies ist das neuere OpenAI-Responses-API-Format. Der große Unterschied? Es unterstützt serverseitigen Gesprächszustand über previous_response_id. Der Server speichert den gesamten Gesprächsverlauf, einschließlich Tool-Aufrufen und -Ergebnissen, sodass der Kontext über mehrere Runden erhalten bleibt, ohne dass der Client ihn verwalten muss.

Hier ist eine Anfrage:

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

Die Antwort zeigt Tool-Aufrufe, die bereits ausgeführt wurden:

{
  "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}
}

Beachte, wie die Tool-Aufrufe "status": "completed" haben. Hermes hat sie bereits serverseitig ausgeführt. Der Client rendert nur die strukturierte Tool-Oberfläche.

Mehrere Runden sind einfach. Verkette einfach Antworten:

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

Der Server rekonstruiert das gesamte Gespräch, einschließlich all dieser Tool-Aufrufe, und macht dort weiter, wo du aufgehört hast.

Bereit zu dienen?

Der API-Server verwandelt Hermes von einem lokalen Werkzeug in einen vollwertigen Dienst. Egal, ob du die Einfachheit von Chat Completions oder die zustandsbehaftete Leistungsfähigkeit von Responses bevorzugst – du hast jetzt ein universelles Backend für jedes OpenAI-kompatible Frontend. Probier es aus – dein Agent ist bereit zu dienen.