Streaming

All Octavus responses stream in real-time using Server-Sent Events (SSE). This enables responsive UX with incremental updates.

Stream Response

When you execute a request, you get an async generator of parsed events:

Event Types

The stream emits various event types for lifecycle, text, reasoning, and tool interactions.

Lifecycle Events

Block Events

Track execution progress:

Text Events

Streaming text content:

Reasoning Events

Extended reasoning (for supported models like Claude):

Tool Events

Tool call lifecycle:

Resource Events

Resource updates:

Display Modes

Each block/tool specifies how it should appear to users:

Note: Hidden events are filtered before reaching the client SDK. Your frontend only sees user-facing events.

Stream Event Type

Client Tool Request

When a tool has no server handler registered, the SDK emits a client-tool-request event:

After the client handles the tools, send a continue request with all results:

See Client Tools for full client-side implementation.

Error Events

Errors are emitted as structured events with type classification:

Error Types

Tool Errors

Tool errors are captured per-tool and don't stop the stream:

The stream always ends with either finish or error.

For client-side error handling patterns, see Error Handling.