Reading the wire — what the runtime actually streams

When you call POST /v1/orchestrate, you don't get a response — you get a stream. Every turn the agent takes, every sub-agent it delegates to, every tool it invokes, every advisor verdict, arrives as a discrete Server-Sent Event. The web app you're reading this on is just one consumer of that stream. Your client would see exactly the same frames.

The shape of a turn

A single orchestration opens with a request_received frame and ends with exactly one done. In between, each agent turn brackets its work with stream_start / stream_end, and emits text, tool_call, token_usage, and — when an advisor is configured — advisor events as it goes:

event: request_received
data: {"agent":"index","request_id":"a1b2c3"}

event: stream_start
data: {"agent":"index","stream_id":1,"depth":0}

event: text
data: {"stream_id":1,"delta":"Checking the deploy status…"}

event: tool_call
data: {"stream_id":1,"tool":"fetch","ok":true}

event: advisor
data: {"stream_id":1,"kind":"gate_continue"}

event: done
data: {"ok":true,"duration_ms":4120}

Why a stream, not a response

Two reasons, and they're both about honesty.

The first is latency. A multi-agent turn can take minutes. Holding the connection open with nothing to show isn't an option — you want the first token on screen the moment the model produces it, and you want the tool calls visible as they happen, not reconstructed after the fact.

The second is observability. A buffered response only tells you the outcome. The stream tells you the path: which sub-agent ran, which tool failed and got retried, where the advisor stepped in to redirect. When something goes wrong, the difference between "the agent failed" and "the agent's third /fetch 404'd, the advisor redirected, and the retry succeeded" is the difference between guessing and knowing.

The durable-execution layer makes that path replayable, too — if your connection drops mid-turn, you reconnect to GET /v1/requests/:id/events?since_seq=N and pick up exactly where you left off. No tokens lost, nothing re-billed.

The full event catalog — every event: name and its data: schema — is in the SSE events concept doc. If you're writing a client, that page is the contract.