Streaming responses example

This walkthrough consumes incremental stream events from the SDK during workflow execution. You iterate run_stream() (Python) or runStream() (TypeScript) and handle token, step start, and step complete events. Server-side SSE remains deferred (streaming deferred); this is in-process SDK streaming only.

Scripts: Streaming responses walkthrough, Streaming responses walkthrough.

What this example demonstrates

Streaming exposes partial output and step lifecycle events before the final WorkflowResult is assembled. Useful for CLI chat UX and local tooling. Both language samples use the stub provider so no API keys are required.

Prerequisites

Step 1: Python streaming run

python examples/streaming/chat_stream.py

Core loop:

async for event in wf.run_stream("Hello from ArcFlow"):
 if event.type == "token":
 print(event.text, end="", flush=True)
 elif event.type == "step_start":
 print(f"\n[step start: {event.step_id}]")
 elif event.type == "step_complete":
 print(f"[step complete: {event.step_id} in {event.duration_ms}ms]")

Step 2: TypeScript streaming run

From repository root after TypeScript SDK build:

npx tsx examples/streaming/chat_stream.ts

Equivalent pattern:

for await (const event of wf.runStream("Hello from ArcFlow")) {
 switch (event.type) {
 case "token":
 process.stdout.write(event.text);
 break;
 case "step_start":
 process.stdout.write(`\n[step start: ${event.step_id}]\n`);
 break;
 case "step_complete":
 process.stdout.write(
 `[step complete: ${event.step_id} in ${event.duration_ms}ms]\n`,
 );
 break;
 }
}

Step 3: Verify event count

Both scripts raise if zero events arrive. Expect at least one step_start and one step_complete on the stub path, plus token events when the provider emits them.

Expected output

Streaming events:

[step start: <step_id>]
<token text may appear here>
[step complete: <step_id> in <ms>ms]

Done.

Exact token text varies. Pass criteria: non-zero event count, no uncaught exceptions, terminal Done. line.

Trace events you should see

Streaming complements but does not replace trace export. After the stream finishes, call workflow.run() synchronously only if you have not already consumed the run, or inspect trace on the same workflow instance if your SDK version attaches trace after stream completion.

Typical post-run trace kinds:

Stream iterators may surface token deltas before StepCompleted appears in trace export.

Troubleshooting

Related