API di Hermes Agent: un endpoint, ogni frontend

Ogni frontend di chat compatibile con OpenAI sa già parlare /v1/chat/completions. Hermes Agent parte da questo fatto e lo porta alle estreme conseguenze: punta uno qualsiasi di loro a http://localhost:8642/v1, passa una chiave API e ottieni tutto il runtime di Hermes - strumenti, memoria, skill, cron - dietro una superficie HTTP familiare, senza cambi lato client.

È tutta qui l'idea del server API di Hermes. Non è un SDK specifico di Hermes da imparare. È la forma di OpenAI, servita in locale, che avvolge l'agente. Se hai già Open WebUI, LobeChat, LibreChat, NextChat, ChatBox o uno script che parla con openai-python, sai già come integrarlo.

Questo post ripercorre cosa espone il server API, come attivarlo e i pattern che tengono quando cominci a collegargli frontend reali.

Cosa espone davvero il server API

Il server API è un componente all'interno del gateway di Hermes. Quando è abilitato, ascolta di default su 127.0.0.1:8642 e parla il contratto HTTP di OpenAI su quattro famiglie di endpoint:

/v1/chat/completions - il classico endpoint Chat Completions. Senza stato, con o senza streaming. È quello che usa il 90% dei frontend compatibili con OpenAI.
/v1/responses - la più recente Responses API, con stato, con concatenazione via previous_response_id, così una conversazione può essere ripresa per ID invece di rispedire tutto lo storico.
/v1/runs - un'API per task lunghi, per lavori che vanno oltre un singolo ciclo di request/response. Il client invia un run, controlla lo stato e recupera il risultato quando è pronto.
/api/jobs - uno strato REST sopra lo scheduler cron integrato, così un'app esterna può creare, elencare e annullare run pianificati dell'agente esattamente come farebbe con qualunque altra risorsa.

Ogni richiesta che invii attraversa l'intero stack di Hermes. Il modello non risponde da solo. Ha accesso al terminale, al filesystem, alla ricerca web, ai file di memoria e a qualsiasi server MCP tu abbia configurato. Per uno sguardo più ampio su come questi strumenti raggiungono il modello, vedi Hermes Agent e MCP.

Accendere il server API

Il server API è spento di default. Ti attivi con due impostazioni in ~/.hermes/.env:

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

Poi riavvia il gateway (hermes gateway). Gli stessi valori possono vivere in ~/.hermes/config.yaml sotto gateway.api_server: se preferisci YAML, ma le variabili d'ambiente vincono quando entrambe sono impostate.

Qualche cosa che vale la pena sapere prima di accenderlo:

L'indirizzo di bind di default è 127.0.0.1, cioè l'endpoint è raggiungibile solo dallo stesso host. Se stai eseguendo Hermes in un container Docker e vuoi che un altro container o la tua macchina host lo raggiunga, imposta anche API_SERVER_HOST=0.0.0.0 e assicurati che la porta sia mappata.
API_SERVER_KEY deve avere almeno 8 caratteri. Trattala come qualsiasi altro segreto API: niente commit, niente incollarla in un canale condiviso. Se trapela, qualsiasi cosa in rete può eseguire run dell'agente sul tuo account con i tuoi strumenti e le tue credenziali.
La porta 8642 è una convenzione di Hermes, non uno standard. Se va in conflitto con qualcosa sulla tua macchina, cambia API_SERVER_PORT. Tutto ciò che sta a valle ha bisogno solo dell'URL base.

Appena il server è su, verificalo con un qualsiasi SDK di OpenAI:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8642/v1",
    api_key="la-chiave-che-hai-impostato",
)

resp = client.chat.completions.create(
    model="hermes",
    messages=[{"role": "user", "content": "Che giorno è, e leggi README.md."}],
)
print(resp.choices[0].message.content)

Non c'è nulla di specifico di Hermes in quel frammento, tranne l'URL base. È esattamente questo il punto.

Frontend che funzionano subito

Poiché la superficie è quella di OpenAI, la maggior parte dei frontend di chat esistenti si connette con una singola modifica alle impostazioni. Un giro veloce su quelli di cui ci si chiede di più:

Open WebUI. Admin Settings → Connections → OpenAI → Add Connection. Imposta l'URL base su http://localhost:8642/v1 e la chiave API sul tuo API_SERVER_KEY. L'errore più comune è dimenticare il suffisso /v1 - non farlo. Open WebUI persiste tutto ciò nel proprio database, quindi se cambi la chiave in seguito, aggiornala dalla UI admin, non modificando di nuovo la variabile d'ambiente.

LobeChat. In Settings → Language Model → OpenAI, sovrascrivi l'API proxy URL con http://localhost:8642/v1 e incolla la chiave. La lista modelli può essere una singola voce chiamata hermes; il server mappa tutto sullo stesso agente.

LibreChat. Aggiungi un endpoint personalizzato in librechat.yaml con apiKey: la-tua-chiave, baseURL: http://localhost:8642/v1 e il nome modello che vuoi mostrare nel selettore. LibreChat gestisce il resto come se avessi configurato un OpenAI self-hosted.

NextChat, ChatBox e affini. Stesso schema: URL base e chiave. Se un frontend dichiara compatibilità OpenAI, quasi sicuramente funziona.

Il bello di eseguire Hermes dietro questi frontend è che ti porti a casa la loro rifinitura di UI - cronologia chat, sessioni fissate, cambio modello, confronti fianco a fianco - mentre il "modello" è in realtà il tuo agente con i tuoi strumenti.

Streaming, progresso degli strumenti e la Responses API

Due cose del server API sorprendono la prima volta.

La prima è che lo streaming trasporta il progresso degli strumenti. Quando l'agente decide di eseguire la shell, colpire il web o leggere un file, lo stream lo fa emergere al client. I frontend che rispettano il formato di streaming mostrano inline "running tool: web_search" o simili, poi proseguono con la vera risposta del modello. Ottieni una vera osservabilità di ciò che l'agente sta facendo senza cablare un log separato.

La seconda è la Responses API. /v1/responses è con stato in un modo in cui /v1/chat/completions non lo è. Invece di rispedire lo storico completo a ogni turno, il client può passare previous_response_id e il server riprende da dove la risposta precedente si è fermata. È importante per conversazioni lunghe a più turni, dove ricaricare lo storico è costoso, e si sposa naturalmente con la direzione in cui vanno anche gli SDK più recenti di OpenAI stessa. Se il tuo frontend supporta entrambi, preferisci Responses per sessioni longeve e Chat Completions per chiamate one-shot.

Runs e Jobs coprono i casi che diventano scomodi nel modello request/response: un run che ci mette dieci minuti o un job schedulato che parte ogni mattina alle 8 e lascia un riepilogo in un canale. Vedi Hermes Agent scheduled tasks and automation per il pattern lato cron.

Pattern che vale la pena seguire

Alcune abitudini che reggono quando il server API sta facendo lavoro vero:

Tieni l'endpoint su localhost finché non hai un motivo per non farlo. Il bind di default è sicuro. Se ti serve accesso remoto, metti davanti un vero reverse proxy con TLS e autenticazione, non limitarti a mettere l'host a 0.0.0.0 su internet pubblica.

Una chiave per client, se puoi. Il server attuale accetta una singola API_SERVER_KEY. Se stai collegando più frontend e vuoi poter revocarne uno senza rompere gli altri, esegui istanze separate di Hermes dietro chiavi separate, oppure termina in un proxy che emette chiavi per client e inoltra una chiave condivisa all'agente.

Il nome del modello è un'etichetta, non un router. Ogni richiesta passa attraverso lo stesso agente. Punta ogni frontend alla stessa voce model: "hermes" a meno che tu non voglia proprio che mostrino nomi diversi nella loro UI.

Guarda i log quando colleghi un frontend nuovo. Il gateway registra ogni richiesta in ingresso e ogni chiamata di strumento. Scorrili nelle prime conversazioni: capirai in fretta se il frontend sta inviando i messaggi che ti aspetti o, per esempio, sta iniettando un system prompt che litiga con i tuoi file di memoria esistenti.

Preferisci Responses per chat lunghe, Chat Completions per gli script. La complessità lato client è la stessa. Quella lato server no.

Dove entra Hermify

Eseguire il server API da soli è lineare, ma significa comunque tenere vivo il processo del gateway, mantenere aggiornato il container e assicurarsi che la porta sia raggiungibile. Se preferisci saltare tutto ciò, Hermify esegue un Hermes Agent gestito per te su Telegram, con gli stessi strumenti, memoria e skill, attivo in circa un minuto. Oggi la superficie API gestita è Telegram-first; il server API self-hosted è dove vai quando vuoi puntare client personalizzati sul tuo agente. In entrambi i casi il runtime sottostante è lo stesso, quindi il modello mentale di questo post si trasferisce.