Streaming

Real-time token streaming for agents and chat. Theazo uses Server-Sent Events (SSE) under the hood and exposes an AsyncIterable interface in the SDK — no callbacks, no event emitters, just for await...of.

Agent streaming

Use agent.stream(task) to receive events as the agent works. Each event has a type field that tells you what happened: text, tool_call, tool_result, progress, or done.

agent-stream.ts

const stream = agent.stream(class="cb-str">'Write a detailed report on market trends')

for await (const event of stream) {
  switch (event.type) {
    case class="cb-str">'text':
      process.stdout.write(event.delta)       class="cb-cmt">// incremental text chunk
      break

    case class="cb-str">'tool_call':
      console.log(class="cb-str">'calling:', event.name, event.input)
      break

    case class="cb-str">'tool_result':
      console.log(class="cb-str">'result:', event.name, event.output)
      break

    case class="cb-str">'progress':
      console.log(event.message)               class="cb-cmt">// 'Searching the web...'
      break

    case class="cb-str">'done':
      console.log(class="cb-str">'output:', event.result.output)
      console.log(class="cb-str">'cost:', event.result.cost)   class="cb-cmt">// { amount: 61, currency: 'usd' }
      break
  }
}

Chat streaming

Chat conversations support the same streaming pattern. Use session.chat.stream() to stream a reply token by token. Each chunk carries a type field so you can distinguish between text output, tool calls, and the final completion signal.

chat-stream.ts

const stream = await session.chat.stream(class="cb-str">'conv_abc', {
  content: class="cb-str">'What were the key findings from the last report?',
})

for await (const chunk of stream) {
  switch (chunk.type) {
    case class="cb-str">'text':
      process.stdout.write(chunk.delta)
      break

    case class="cb-str">'tool_call':
      console.log(class="cb-str">'tool:', chunk.name, chunk.input)
      break

    case class="cb-str">'tool_result':
      console.log(class="cb-str">'result:', chunk.name, chunk.output)
      break

    case class="cb-str">'done':
      console.log(class="cb-str">'messageId:', chunk.messageId)
      console.log(class="cb-str">'cost:', chunk.cost)            class="cb-cmt">// { amount: 12, currency: 'usd' }
      console.log(class="cb-str">'tokens:', chunk.tokenCount)    class="cb-cmt">// { input: 340, output: 128 }
      break
  }
}

SSE Protocol

Under the hood, the SDK connects to the GET /v1/agents/:id/stream endpoint, which returns a standard text/event-stream response. If you are building a client in another language, you can consume the raw SSE format directly.

raw-sse

event: text
data: {class="cb-str">"delta": class="cb-str">"The market for"}

event: text
data: {class="cb-str">"delta": class="cb-str">" cloud infrastructure"}

event: tool_call
data: {class="cb-str">"name": class="cb-str">"web_search", class="cb-str">"input": {class="cb-str">"query": class="cb-str">"cloud infra market size 2025"}}

event: tool_result
data: {class="cb-str">"name": class="cb-str">"web_search", class="cb-str">"output": class="cb-str">"The global cloud infrastructure market..."}

event: progress
data: {class="cb-str">"message": class="cb-str">"Compiling findings into report..."}

event: done
data: {class="cb-str">"output": class="cb-str">"## Market Analysis\n...", class="cb-str">"cost": {class="cb-str">"amount": class="cb-num">61, class="cb-str">"currency": class="cb-str">"usd"}, class="cb-str">"duration": class="cb-num">14320}

Each SSE frame has an event field (the event type) and a data field (JSON payload). The connection closes after the done event is sent.

Stream events reference

All events emitted during a stream, for both agent and chat streaming.

Event typeDescription

textIncremental text output. Contains a delta string with the new token(s). Concatenate all deltas to build the full output.

tool_callThe agent is invoking a tool. Contains name (tool name) and input (the arguments object passed to the tool).

tool_resultA tool has returned. Contains name (tool name) and output (the result from the tool execution).

progressA human-readable status update from the agent. Contains a message string describing what the agent is currently doing.

doneThe stream is complete. For agents: contains the full RunResult (output, artifacts, cost, duration, toolCalls). For chat: contains messageId, cost, and tokenCount. The connection closes after this event.

errorAn error occurred during execution. Contains code, message, and optional details. The connection closes after this event.

Streaming uses AsyncIterable — no callbacks. Use for await...of syntax to consume events. The iterable completes automatically when the done event is received.