Streaming

Server-Sent Events.

Set "mode": "stream" on interpret to receive tokens as they generate, over text/event-stream.

Event types

Event	Data	Meaning
`status`	`{ stage, label }`	Lifecycle progress (e.g. retrieval).
`token`	`{ text }`	A chunk of the answer.
`outcome`	`{ kind, … }`	The turn ended on something other than prose — `questions`, a `plan`, `changes`, or `unresolved`. Absent when the answer streamed as tokens.
`done`	`{ status, citations, usage }`	Terminal success; the stream closes.
`error`	`{ code, message, details }`	Terminal failure; the stream closes.

Raw wire format

text

event: status
data: {"stage":"rag","label":"Searching the project…"}

event: token
data: {"text":"The main conveyor "}

event: token
data: {"text":"starts when the Start PB is pressed and no E-Stop is active…"}

event: done
data: {"status":"answer","citations":[{"location_kind":"rung","path":"ConveyorControl","rung":12}],"usage":{"input_tokens":1840,"output_tokens":412}}

Citations ride done, not an event of their own. A turn whose answer streams as prose emits no outcome event at all, and that turn has citations like any other — so they arrive on the one event every successful stream ends with, alongside the blocking status and the turn's usage.

Consuming via SDK

python

for event in client.interpret_stream(project_id="prj_…", prompt="…"):
    if event.type == "token":
        print(event.text, end="", flush=True)
    elif event.type == "outcome":
        # questions | plan | changes | unresolved
        print("\nstopped on:", event.outcome.kind)
    elif event.type == "done":
        print("\nread from:", [c.path for c in event.citations])
        print("\nusage:", event.usage)

csharp

await foreach (var ev in client.InterpretStreamAsync("prj_…", "…"))
{
    if (ev.Type == "token") Console.Write(ev.Text);
    else if (ev.Type == "outcome") Console.WriteLine($"\nstopped on: {ev.Outcome?.Kind}");
    else if (ev.Type == "done")
    {
        Console.WriteLine($"\nread from: {ev.Citations.Count} location(s)");
        Console.WriteLine($"usage: {ev.Usage}");
    }
}