Streaming

Read tokens, tool calls, and artifacts as they arrive — AsyncIterator of SDKMessage.

Canonical contract: packages/sdk/docs.md — SDKMessage discriminated union, run.stream(), Vercel AI Data Stream v1 wire format.

agent.send(prompt) returns a Run. You can await run.wait() for the full result, OR iterate run.stream() to consume events as they happen.

Iterate the stream

const run = await agent.send("Tell me a story about robots.");

for await (const msg of run.stream()) {
  switch (msg.type) {
    case "text_delta":
      process.stdout.write(msg.text);
      break;
    case "tool_call":
      console.log("[calling tool]", msg.name);
      break;
    case "tool_result":
      console.log("[tool returned]", msg.content);
      break;
    case "finished":
      console.log("\n[done]", msg.stopReason);
      break;
  }
}

SDKMessage is a discriminated union. The full variant list:

`type`	Meaning
`text_delta`	Incremental text token from the model
`tool_call`	Model emitted a tool call (name + args)
`tool_result`	Tool execution finished (success or error)
`partial_object`	When using `streamObject`, partial typed payload
`complete_object`	When using `streamObject`, final typed payload
`finished`	Run is over (with `stopReason: end_turn
`error`	A non-recoverable error was emitted

Structured streaming (`streamObject`)

For typed payloads, use Agent.streamObject<T>:

import { z } from "zod";
const schema = z.object({ title: z.string(), bullets: z.array(z.string()) });

const stream = await Agent.streamObject({
  apiKey, model, schema,
  prompt: "Outline a blog post about Rust ownership.",
});

for await (const msg of stream) {
  if (msg.type === "partial_object") console.log("partial:", msg.value);
  if (msg.type === "complete_object") console.log("final:", msg.value);
}

The SDK uses a synthetic forced tool (ADR D33) — the model calls a single tool whose schema is your Zod schema, the SDK validates each partial, and you get progressively-typed updates.

React hooks

For browser apps, @theokit/react exposes hooks that consume the same wire format (Vercel AI Data Stream v1, ADR D38):

useTheoChat — multi-turn chat
useTheoCompletion — single-shot text
useTheoAssistant<T> — object streaming

See the react-nextjs example.

API reference

Agent.streamObject

Typed structured streaming.

SDKMessage variants

Full union of stream events.