Wire protocol

Protocol version: v1.

Transport

• WebSocket, TLS in production (wss://), plaintext in dev (ws://).
• Message framing: one JSON object per WebSocket frame. UTF-8. No batching at the WS layer (see “Event batching” below for the application-layer batch frame).
• Authentication: Authorization: Bearer <token> header on the WS handshake.
• Fallback: HTTPS long-poll at /ws/longpoll for networks that block WebSockets.

Frames (agent → brain)

hello

Sent once, immediately after handshake.

{
  "type": "hello",
  "protocol": "v1",
  "agent_name": "web-01",
  "framework": "django",
  "framework_version": "5.0.2",
  "engines": ["celery"],
  "schedulers": ["celery-beat"],
  "capabilities": {
    "celery": {
      "native_retry": true,
      "native_cancel": true,
      "bulk_retry": true,
      "purge": true,
      "chord_aware": true
    },
    "celery-beat": {
      "schedule_crud": true,
      "writable_backend": "django-celery-beat"
    }
  },
  "metadata": { "hostname": "web-01", "pid": 12345 }
}

event_batch

The hot path. Batched to reduce WS framing overhead.

{
  "type": "event_batch",
  "seq": 4281,
  "events": [
    {
      "event_type": "task_sent",
      "task_id": "1f9c5…",
      "engine": "celery",
      "ts": "2026-04-16T12:34:56.789012Z",
      "name": "email.send_welcome",
      "args_redacted": ["<str len=24>"],
      "kwargs_redacted": { "to": "<email>" },
      "queue": "default",
      "routing_key": "email"
    }
  ]
}

See API § events for full event type list.

heartbeat

Every 30s.

{"type": "heartbeat", "ts": "2026-04-16T12:34:56.789Z"}

command_result

Reply to brain-initiated commands.

{
  "type": "command_result",
  "cmd_id": "cmd-4821",
  "ok": true,
  "result": { "new_task_id": "…" }
}

schedule_snapshot / schedule_update

Scheduler state sync.

Frames (brain → agent)

command

{
  "type": "command",
  "cmd_id": "cmd-4821",
  "cmd": "retry_task",
  "args": { "task_id": "1f9c5…", "engine": "celery" }
}

Commands: retry_task, cancel_task, bulk_retry, purge_queue, restart_agent, schedule_create, schedule_update, schedule_delete, schedule_pause.

ack

{"type": "ack", "seq": 4281}

Acks the last persisted event batch. Enables at-least-once delivery - the agent retains unacked batches.

Sequence numbers & delivery

• Agent → Brain: agent assigns monotonic seq per batch. Brain persists, then emits ack.
• On reconnect, the agent replays unacked batches. Brain dedupes by (agent_id, seq).
• Brain → Agent: cmd_id is a UUID. Agent replies with same cmd_id in command_result. No retries on commands - timeouts surface as user-visible errors.

Version negotiation

hello.protocol says “v1”. The brain accepts matching major versions. A mismatch closes the WS with code 4001. The agent logs and does not reconnect until upgraded.

Forward-compat: agents MAY send unknown fields; brains MUST ignore them. New command types added in minor versions are rejected with ok: false, error: "unsupported_command" by older agents.

See API § WebSocket protocol for the reference schema.