Node-RED ──POST /ask──▶ Quart relay ──serialized call──▶ warme Hermes-agent
                           │
                           ├── JSON direct terug naar Node-RED
                           └── Telegram-bezorging op de achtergrond via `hermes send`

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: Telegram ligt niet meer in het HTTP-pad. Een succesvolle /ask reageert zodra het model antwoordt.
Background delivery: Telegram wordt betrouwbaar gelogd. Bij 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": true
}

elapsed_seconds blijft aanwezig voor compatibiliteit en is de LLM-duur. request_elapsed_seconds is de feitelijke HTTP-duur. telegram_queued betekent dat bezorging geaccepteerd is voor de achtergrondtaak; raadpleeg 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_DELIVERY_WORKERS`	`2`	Begrensde workers voor Telegram-bezorging
`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;