Streaming & Replay - Hexel Studio

Instead of polling for task completion, you stream events as the task runs — seeing each state change, context assembly, and output delta in real time. When something goes wrong (or you just want to understand what happened), replay lets you reproduce a past run from its recorded trace without re-executing anything. Tasks emit a live stream of Server-Sent Events (SSE) as they plan and execute. Completed or failed tasks can be replayed from their recorded trace for debugging, auditing, and reproduction.

How streaming works

SSE event types

Task lifecycle events

Event	Meaning
`task.submitted`	Task was accepted.
`task.state`	Task changed state (carries new state in payload).
`task.result`	A result payload is available.
`task.error`	An error occurred during execution.
`task.complete`	Task finished successfully (terminal).
`task.failed`	Task failed (terminal).
`task.cancelled`	Task was cancelled (terminal).

Output events

Event	Meaning
`runtime.delta`	Incremental output chunk (render progressively).

Platform events

These events provide additional observability but are implementation details — do not depend on their presence or ordering in your application logic. They may change without notice.

Event	Meaning
`runtime.lease`	Execution resources were allocated.
`runtime.context`	Context was assembled for the run.
`runtime.handoff`	Work was routed between agents.
`runtime.why`	Reasoning detail for a step.

Terminal events (task.complete, task.failed, task.cancelled) signal end-of-stream. Stop reading after receiving one.

Stream a task

for event in client.orchestrator.task.stream("YOUR_TASK_ID"):
    match event["type"]:
        case "runtime.delta":
            print(event["data"], end="", flush=True)
        case "task.complete":
            print("\nDone.")
            break
        case "task.failed":
            print(f"\nFailed: {event.get('data')}")
            break

# Use the SDK: client.orchestrator.task.create(...) with goal as input

Resuming a stream

The stream is resumable. If a connection drops, reconnect and pass the last received event ID to resume without replaying already-delivered events.

Replay a task

Replay re-runs a task from its recorded execution trace.

Python

client.orchestrator.task.replay("YOUR_TASK_ID")

Replay reproduces the recorded run. External systems may have changed since the original execution; side effects are not guaranteed to be identical.

Errors

HTTP	When
`404`	The task ID doesn’t exist or isn’t in your scope.
`400`	Invalid stream resume position or replay request.

A dropped stream connection is not an error — reconnect and resume from the last event ID you received.

Production recommendations

Treat task.complete, task.failed, and task.cancelled as terminal: stop reading once one arrives.
Render runtime.delta events incrementally rather than buffering the whole stream.
Persist the last received event ID so you can resume cleanly after a disconnect.
Use replay to reproduce a failed run before changing the agent or input.

Rate limits

100 requests per organization per minute.

Handling runtime.delta

runtime.delta events carry incremental text chunks. Concatenate and render them progressively for a responsive UI. Do not wait for the full result before displaying output.

Distinguishing terminal events

A stream always ends with exactly one of task.complete, task.failed, or task.cancelled. Use this to determine the final outcome and clean up resources.

Tasks

Submit and manage tasks.

Approvals

Handle plan review events.

Observability

Logs and metrics beyond a single task.

Tasks & Workflows

The lifecycle behind the events.

Next steps

Explore the Tool Gateway to give your agents real-world actions.

​How streaming works

​SSE event types

​Task lifecycle events

​Output events

​Platform events

​Stream a task

​Resuming a stream

​Replay a task

​Errors

​Production recommendations

​Rate limits

​Related pages

Tasks

Approvals

Observability

Tasks & Workflows

​Next steps

How streaming works

SSE event types

Task lifecycle events

Output events

Platform events

Stream a task

Resuming a stream

Replay a task

Errors

Production recommendations

Rate limits

Related pages

Next steps