Node-RED ──POST /ask──▶ Quart relay ──serialized call──▶ warme Hermes-agent
                           │
                           └── JSON direct terug naar Node-RED

Optioneel: Telegram-bezorging via `hermes send` (standaard uit)

Gedrag en grenzen

Warme agent: Hermes wordt tijdens startup geladen/geïnitialiseerd.
Veilige concurrency: de gedeelde, mutable agent verwerkt precies één LLM-call tegelijk. Overige HTTP-verzoeken wachten in de queue; ze kunnen niet elkaars messages resetten.
Timeout: HERMES_RELAY_TIMEOUT (standaard 120 s) omvat wachttijd plus LLM-call. Een timeout retourneert HTTP 504.
Snelle response: Een succesvolle /ask reageert zodra het model antwoordt.
Geen chatbezorging standaard: relay-antwoorden blijven in de HTTP-response en verschijnen dus niet in Telegram.
Optionele Telegram-bezorging: alleen met HERMES_RELAY_TELEGRAM_DELIVERY_ENABLED=true wordt het antwoord asynchroon via hermes send bezorgd. Bij een gecontroleerde shutdown wacht de service op lopende bezorgingen.

Endpoints

`POST /ask`

JSON body:

{ "payload": "Wat is het weer in Best?" }

Succesresponse:

{
  "status": "ok",
  "answer": "...",
  "elapsed_seconds": 6.213,
  "llm_elapsed_seconds": 6.213,
  "request_elapsed_seconds": 6.214,
  "telegram_queued": false
}

elapsed_seconds blijft aanwezig voor compatibiliteit en is de LLM-duur. request_elapsed_seconds is de feitelijke HTTP-duur. telegram_queued is standaard false; bij expliciet ingeschakelde Telegram-bezorging betekent true dat de achtergrondtaak is ingepland. Raadpleeg dan journald voor het uiteindelijke bezorgresultaat.

Fouten: 400 lege payload, 413 payload groter dan limiet, 504 timeout, 502 onverwachte agentfout.

`GET /health`

Geeft service-status, versie en het aantal lopende Telegram-bezorgingen terug.

/health?detail=true voegt de lokale agent-state toe; dit doet bewust geen dure LLM/provider-call.

Configuratie

Variabele	Standaard	Betekenis
`HERMES_RELAY_TIMEOUT`	`120`	Max. wachttijd + modelcall per HTTP-request
`HERMES_RELAY_TELEGRAM_DELIVERY_ENABLED`	`false`	Zet alleen op `true` voor asynchrone Telegram-bezorging
`HERMES_RELAY_DELIVERY_WORKERS`	`2`	Begrensde workers voor Telegram-bezorging als die is ingeschakeld
`HERMES_RELAY_MAX_PAYLOAD_CHARS`	`12000`	Maximale lengte van `payload`
`HERMES_RELAY_MAX_TURNS`	`10`	Agent turn-budget
`HERMES_RELAY_MODEL`	profieldefault	Optionele modelovertuiging
`HERMES_RELAY_TOOLSETS`	leeg	Alleen invullen met geldige benodigde toolsets

De relay leest zijn Hermes-config via profiel voice-assistant. Pas model/provider/config aan en herstart daarna de service:

systemctl restart hermes-relay

Testen

curl -s http://127.0.0.1:8650/health
curl -s -X POST http://127.0.0.1:8650/ask \
  -H 'Content-Type: application/json' \
  -d '{"payload":"Zeg alleen hoi"}'

journalctl -u hermes-relay -f

Node-RED

Gebruik een HTTP Request-node:

Method: POST
URL: http://192.168.1.74:8650/ask
Return: parsed JSON
Timeout: 120000 ms

Voorafgaande Function-node:

msg.payload = { payload: msg.payload };
return msg;