agent.stream() runs an agent exactly like agent.send() and reports the run
as a stream of typed events: model text as it arrives, every tool call,
step boundaries, approval requests, and a final run.done. Every event is a
plain JSON object, so you can forward it to a browser over Server-Sent Events
or a WebSocket without converting it. The vendor/ model prefix chooses the
provider; with OpenRouter use openrouter/<vendor>/<model> (e.g.
openrouter/openai/gpt-4o-mini).
Snippets on this page leave some names to you:provideris anyLLMProvider(offline:createMockProvider());agentis acreateAgent()result;inputis the user’s text, astring;approvalStoreis anApprovalStore;toolRegistryis aToolRegistry.
AgentExecutor.stream(options) takes the
same options as AgentExecutor.execute() (approval store, checkpoints, hooks,
tracing, toolConcurrency, …).
These events, the AgentEvent union, are the SDK’s one event system: the
stream, the listener options, session.on(),
the UI hooks, the server routes, ACP and channels all carry them.
The AgentRun handle
stream() returns an AgentRun:
- The run starts immediately. You do not have to iterate:
await run.resulton its own drives the run to completion. resultresolves with the sameExecutionResultthatsend()returns, and rejects with the same errorsend()would reject with. An aborted run resolves withfinishReason: 'aborted'; a run paused for approval resolves withfinishReason: 'awaiting-approval'andapprovalId. Leavingresultunawaited never causes an unhandled rejection.- A failed run throws from the loop. When the run fails,
for awaityields theerrorandrun.done { finishReason: 'error' }events, then rethrows the errorrun.resultrejects with (the onesend()would throw), so atryaround the loop catches it. Pass{ throwOnError: false }tostream()to end the loop normally and read the failure from the events orrun.result. An abort, an earlybreakand a pause for approval never throw. Session andapprovals.streamResolve()streams keep ending normally. - Breaking out of the
for awaitloop early aborts the run (through the same path assignal, see Cancellation).resultthen resolves withfinishReason: 'aborted'. - No backpressure; nothing is dropped. The run never waits for the consumer. Events are buffered until you read them, so a slow consumer sees every event, in order. Iterating after the run finished still yields all of its events.
enqueue(input)adds user input to the run while it runs: it joins the transcript before the next model call. See Queued input.steer(input)redirects the run: a model call that has not produced anything yet is aborted and made again with the input. See Steering.- One consumer. An
AgentRuncan be iterated once; a secondfor awaitthrows. To fan out, collect the events yourself. - Invalid options (no
provider,agentorinput, a badtoolConcurrency) throw synchronously fromstream().
Listening without iterating
A listener that throws does not fail the run (its tools may already have had side effects): the error is logged once per run withconsole.warn and the run continues.
To observe every run without iterating one, give the agent a listener:
createAgent({ onEvent }), or onAgentEvent in the AgentExecutor.execute()
/ stream() / resumeAfterApproval() options. It is called synchronously
with each AgentEvent as it happens, on send() as on stream(), for
session turns and for runs resumed after an approval. It gets the same events,
in the same order, as iterating the stream would: with a listener, send() /
execute() stream each model call too, so a step’s text arrives as several
text.delta events (one text.delta per step when the provider cannot
stream). Concatenate them, or use text.done for each step’s whole text;
AgentExecutor.execute({ streamModelCalls: false }) generates whole steps.
Output guardrails still check only the final reply of a send(), as without
a listener. Sub-agents’ events arrive tagged with subagent.
Migrating from onEvent / ExecutionEvent
ExecuteOptions.onEvent and its ExecutionEvent type were removed in this
release (they were deprecated earlier). Pass onAgentEvent to
AgentExecutor.execute() / stream() / resumeAfterApproval() instead -
createAgent({ onEvent }) already takes AgentEvents and is unchanged.
The table below maps the old event names to the AgentEvents a listener
gets now:
AgentEvent also reports what ExecutionEvent never did: step boundaries,
approval requests, permission decisions, budgets, guardrails, queued and
steered input, compaction, reasoning, provider retries, agent drift and handoffs (see the
schema).
Streaming a session turn
session.stream(input, { signal }) streams one turn of a multi-turn
session and returns the same AgentRun. The run sees the
conversation so far, and when it ends its turn is saved to the session’s
store, just as session.send() saves it. run.done is delivered after the
save, so the transcript is complete when the loop ends. An aborted or failed
run, or one you stop reading early, is not saved.
Streaming after an approval
A run that paused for an approval can continue as a stream too.agent.approvals.streamResolve() (or streamAnswer()) returns an
AgentRun whose result is what agent.approvals.resolve() returns. Its events are run.start, the decided
call’s tool.resume and tool.done (tool.error for a rejection - tool.resume,
not a second tool.start, because the paused run already reported that call’s
start), then the
continuation’s events exactly as in a fresh run, up to run.done; a further
pause ends it with approval.requested (kind: 'sign-in' with a signIn
link when a tool waits for an OAuth sign-in). Cancellation, enqueue() and
steer() work as on any run, and the approval can come from another
process, since everything is read from the approval store. A model chosen per
run (model as a function) is the one the paused run used.
Advanced: the executor API
With the executor directly,streamResumeAfterApproval() takes the arguments
of resumeAfterApproval() (see the executor API) and
returns the same AgentRun.
type, runId, seq, timestamp and v. The full list of event types, the ordering guarantees, the TypeScript helpers and the versioning rules are on Stream events.
Sub-agents
When the agent delegates with thetask tool
(see Sub-agents), the sub-agent’s run is streamed
inside the same stream: its steps, text.deltas, text.dones, tool events
and errors appear between the lead’s tool.start and tool.done (or
tool.error) for that call, each with a subagent field:
toolCallId is the lead’s tool call that started the sub-agent; a sub-agent
of a sub-agent has depth: 2 and the enclosing one as parent. Events
without subagent are the top-level run’s: the ordering guarantees above hold
for them, and separately for each sub-agent’s steps (several sub-agents
running in parallel interleave). run.start and run.done belong to the
top-level run only, so they still come exactly once. A sub-agent that pauses
for approval is reported once, by the top-level approval.requested (which
carries the sub-agent’s call).
Token streaming and providers
When the provider implementsstream() (all built-in providers and
mockModel do), each model step is streamed and text.delta events arrive
as the model produces text. Tool calls are assembled from the stream. When a
provider has no stream(), or its supportsStreaming(model) returns
false, the step falls back to generate() and its text arrives as a single
text.delta followed by text.done.
Streaming changes only how one model step is obtained. Hooks, argument
validation, approvals, parallel tool calls, checkpoints, cancellation,
tracing spans and the other execute() callbacks behave exactly as in
send(). send() and execute() stream the same way when they have a
listener (onEvent / onAgentEvent); without one they use generate().
A custom provider’s stream() should yield text-delta chunks and a final
finish chunk with finishReason and usage. Tool calls can be yielded as
tool-call chunks, or resolved on the toolCalls promise of the
StreamResult. An error chunk fails the step.
Cancellation
Passsignal to stop a run from outside, or break out of the loop. Both end
the run the same way as an aborted send(): the signal is checked between
stream chunks, before every model call and every tool call, and reaches the
provider and the tools. The stream ends with step.done ('aborted', when a
step was running) and run.done ('aborted'), and result resolves with
finishReason: 'aborted'.
run.enqueue(input) waits for the next safe point, run.steer(input) interrupts the current model call.
Example: terminal
Example: Server-Sent Events
Events are JSON-serializable, so an SSE endpoint is oneres.write per
event. Abort the run when the client disconnects. For session turns,
createRouteHandler() does the opposite by default: the turn finishes and is
saved even when the client leaves (see Next.js).
useLoushoAgent() POSTs the input and reads the same data: lines.
lousho dev serves this format for a session per browser tab: POST /chat
with { sessionId, input } streams agent.session({ id }).stream(input) as
data: lines ending with event: done, and approvals are decided through
POST /chat/:sessionId/approvals/:id (see CLI).
Advanced: the executor API
AgentExecutor.stream() accepts every execute() option (see
the executor API). Here a tool that
needs approval ends the stream with approval.requested: