API Server — Hermes come servizio | Easy Understand Hermes Agent

API Server — Hermes come servizio

Immagina questa scena: hai costruito un agente AI straordinario con Hermes. Sa eseguire comandi nel terminale, cercare sul web, gestire file e ricordare le cose. Ma vive nel tuo terminale. E se potessi collegarlo a una bellissima interfaccia chat come Open WebUI o LobeChat? È esattamente ciò che fa l’API Server.

Pensalo come a un traduttore universale. L’API Server espone Hermes come un endpoint HTTP compatibile con OpenAI. Questo significa che qualsiasi frontend che parla il “linguaggio OpenAI” — e ce ne sono centinaia — può connettersi a Hermes e usarlo come un potente backend. Il tuo agente mantiene il suo set completo di strumenti, e il frontend diventa semplicemente una bella facciata.

La parte migliore? Quando trasmetti le risposte in streaming, gli indicatori di avanzamento degli strumenti appaiono in linea. Così i tuoi utenti possono davvero vedere l’agente eseguire un comando o cercare sul web, invece di fissare un cursore lampeggiante.

Un Solo Backend, Tutta la Potenza

Prima di addentrarci, un piccolo consiglio. Hermes ha bisogno di un provider configurato e di backend per gli strumenti per essere utile. Un abbonamento a Nous Portal copre entrambe le cose — hai accesso a oltre 300 modelli più strumenti web, immagini, TTS e browser tramite il Tool Gateway.

Esegui hermes setup --portal una volta sola, e sei pronto a dare a qualsiasi frontend un backend completamente equipaggiato con strumenti. È il modo più semplice per iniziare.

Avvio Rapido: Tre Passaggi

1. Attiva l’API Server

Apri il tuo file ~/.hermes/.env e aggiungi queste righe:

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Opzionale: solo se un browser deve chiamare Hermes direttamente
# API_SERVER_CORS_ORIGINS=http://localhost:3000

La API_SERVER_KEY è la tua password. Cambiala con qualcosa di sicuro!

2. Avvia il Gateway

Esegui questo comando:

hermes gateway

Vedrai un messaggio come questo:

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

Tutto qui. Il tuo agente ora è un servizio.

3. Connetti un Frontend

Punta qualsiasi client compatibile OpenAI su http://localhost:8642/v1. Testiamolo con 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!"}]}'

Oppure collega Open WebUI, LobeChat o qualsiasi altro frontend. Dai un’occhiata alla guida all’integrazione con Open WebUI per istruzioni passo passo.

Gli Endpoint: Due Modi per Parlare

L’API Server offre due endpoint principali.

POST /v1/chat/completions

Questo è il formato standard di Chat Completions di OpenAI. È senza stato — invii l’intera cronologia della conversazione in ogni richiesta tramite l’array messages.

Ecco una richiesta semplice:

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

E la risposta:

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

Le immagini inline sono supportate. Puoi inviare immagini come parte del contenuto del messaggio:

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

Funzionano sia gli URL remoti che gli URL data:image/.... Nota che i file caricati e i data URL che non sono immagini restituiranno un errore 400 unsupported_content_type.

Lo streaming è dove avviene la magia. Imposta "stream": true e riceverai Server-Sent Events (SSE) con risposte token per token. Per Chat Completions, vedrai eventi standard chat.completion.chunk più un evento personalizzato hermes.tool.progress. Questo permette ai frontend di mostrare l’attività degli strumenti senza inquinare il testo finale dell’assistente.

POST /v1/responses

Questo è il formato più recente dell’API Responses di OpenAI. La grande differenza? Supporta lo stato della conversazione lato server tramite previous_response_id. Il server memorizza l’intera cronologia della conversazione, incluse le chiamate agli strumenti e i risultati, così il contesto multi-turno viene preservato senza che il client debba gestirlo.

Ecco una richiesta:

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

La risposta mostra le chiamate agli strumenti già eseguite:

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

Nota come le chiamate agli strumenti hanno "status": "completed". Hermes le ha già eseguite lato server. Il client si limita a renderizzare l’interfaccia strutturata degli strumenti.

Il multi-turno è facile. Basta concatenare le risposte:

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

Il server ricostruisce l’intera conversazione, incluse tutte quelle chiamate agli strumenti, e continua da dove ti eri fermato.

Pronto a Servire?

L’API Server trasforma Hermes da uno strumento locale in un servizio a tutti gli effetti. Che tu preferisca la semplicità di Chat Completions o la potenza stateful di Responses, ora hai un backend universale per qualsiasi frontend compatibile OpenAI. Provalo — il tuo agente è pronto a servire.