Jesko Anschütz b04acdee09 Dokumentiere ersten HTTP-Statuspfad fuer den Agenten

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

2026-03-22 17:43:08 +01:00

1.9 KiB

Raw Blame History

Info-Board Neu - Erster HTTP-Statuspfad fuer den Player-Agent

Ziel

Dieses Dokument beschreibt den ersten bewusst kleinen Statuspfad zwischen player/agent und server/backend.

Er ist fuer die aktuelle Entwicklungsstufe gedacht und noch kein finales Persistenz-, Authentifizierungs- oder MQTT-Modell.

V1-Dev-Entscheidung

der Agent sendet zunaechst Statusdaten per HTTP an das Backend
das Backend validiert und bestaetigt den Request, speichert ihn in dieser Stufe aber noch nicht dauerhaft
der Pfad dient als erste echte Backend-Agent-Integration vor Registration, Sync und MQTT

Endpoint

POST /api/v1/player/status

Request-Felder

Mindestens enthalten:

screen_id
ts
status

Aktuell zusaetzlich enthalten:

server_url
mqtt_broker
heartbeat_every_seconds
started_at
last_heartbeat_at

Beispiel

{
  "screen_id": "info01-dev",
  "ts": "2026-03-22T16:00:00Z",
  "status": "running",
  "server_url": "http://127.0.0.1:8080",
  "mqtt_broker": "tcp://127.0.0.1:1883",
  "heartbeat_every_seconds": 30,
  "started_at": "2026-03-22T15:59:30Z",
  "last_heartbeat_at": "2026-03-22T16:00:00Z"
}

Antwort

Bei gueltigem Request liefert das Backend aktuell:

{
  "status": "accepted"
}

Bei ungueltigen Requests wird wie bei den anderen API-Endpunkten der gemeinsame Fehlerumschlag verwendet.

Abgrenzung

Noch nicht Teil dieser Stufe:

dauerhafte Speicherung in Datenbank oder State-Store
Screen-Authentifizierung
MQTT-Heartbeat oder MQTT-Status
Admin-UI-Anzeige des letzten Status
Retry-Queue oder lokale Zwischenspeicherung im Agent

Folgeschritte

Auf diesem Pfad bauen spaeter auf:

Screen-Identitaet und Authentifizierung
persistierter letzter Heartbeat und letzter Status auf dem Server
Trennung zwischen HTTP-Snapshot und MQTT-Heartbeat
Admin-Vorschau fuer Online-/Offline- und Degraded-Zustaende

1.9 KiB Raw Blame History