Agent WebSocket Events
Real-time event streaming — connection, reconnection/replay, heartbeats, and the full event type reference.
Connect to receive real-time updates from the runtime:
ws://localhost:4484/ws Global events (all conversations)
ws://localhost:4484/conversations/:id/ws Per-conversation events
Authenticate WebSocket connections with ?api_key=<key>.
Reconnection & replay
Pass lastEventSeq=<n> as a query param when (re)connecting to receive any
missed events:
ws://localhost:4484/conversations/:id/ws?lastEventSeq=42&api_key=secret
The runtime keeps a ring buffer of the last 2000 events. On connect, any
buffered events with seq > lastEventSeq are replayed before live streaming
resumes. For an HTTP-only catch-up (e.g. after a long disconnect), use
GET /events/recent?since=42.
Heartbeat
Every 15 seconds the server sends { "type": "heartbeat" } to all connected
clients. Use it to detect stale connections — close and reconnect if you miss
them.
Event shape
{
"type": "run.started",
"conversationId": "conv_abc123",
"timestamp": 1775845291793,
"seq": 42, // monotonic sequence number (on most events)
"data": {/* ... */},
}
Event types
| Event | When it fires |
|---|---|
run.started | Agent begins processing a message |
run.progress | Mid-run progress (e.g. iteration/tool milestones) |
message.created | New message persisted (user, assistant, or tool) |
message.delta | Streaming text delta (assistant response in progress) |
run.completed | Agent finished processing successfully |
run.failed | Agent run failed |
run.cancelled | Run was cancelled via cancel/interrupt |
queue.updated | Queue changed (item added/removed/completed) |
conversation.updated | Conversation metadata/status/title/model changed |
conversation.deleted | Conversation was deleted |
subagent.started | A delegated subagent run started |
subagent.message.created | A message was created inside a subagent run |
subagent.completed | A subagent run completed |
subagent.failed | A subagent run failed |
heartbeat | Keepalive (no seq; every 15s) |
For a basic chat UI you only need: run.started, message.delta,
message.created, run.completed, and run.failed. The rest power richer
dashboards and observability.
// Examples
{ "type": "run.started", "conversationId": "conv_abc123", "timestamp": 1775845291793, "data": { /* ... */ } }
{ "type": "message.delta", /* ... */ "data": { "delta": "partial text" } }
{ "type": "run.completed", /* ... */ }
{ "type": "run.failed", /* ... */ }
{ "type": "queue.updated", /* ... */ }