Live token rendering
Display model output incrementally in a chat interface.
AI Agents · Const
Streaming events
streamEvents exposes an asynchronous stream of runnable lifecycle events while a graph executes. Each event identifies its type, source runnable, and execution ID, enabling real-time progress handling and selective filtering.
How it works
streamEvents returns an asynchronous event stream for a runnable or compiled graph. Each event identifies the lifecycle phase, the runnable that emitted it, and its execution ID, allowing applications to observe intermediate progress and filter events such as streamed model output.
Syntax
streamEvents(input, options, streamOptions?): IterableReadableStream<StreamEvent>Parameters
| Name | Type | Description |
|---|---|---|
input | null | InputType | CommandType | Input passed to the runnable or compiled graph. |
options | Partial<PregelOptions<...> & { version: "v1" | "v2" }> | Options including the required stream event version, such as version: "v2". |
streamOptions | Omit<EventStreamCallbackHandlerInput, "autoClose"> | Optional callback-handler streaming configuration, excluding autoClose. |
Returns
IterableReadableStream<StreamEvent>
Key points
- The method exposes events from a runnable's internal execution rather than only its final result.
- Consume the result as an asynchronous iterator to react while execution is still underway.
- Lifecycle names encode the runnable category and whether execution started, streamed, or ended.
- Use the event's
namefield to identify which runnable produced a notification. - Use
run_idto distinguish separate executions of the same runnable.
Common mistakes
- Filter using the documented lifecycle naming pattern, such as
on_chat_model_stream; event names are not arbitrary labels. - Nested runnables emit their own events and IDs, so do not assume one run ID represents the entire execution tree.
Example: Print streamed model output
const stream = await graph.streamEvents(input, { version: "v2" });
for await (const event of stream) {
if (event.event === "on_chat_model_stream") {
process.stdout.write(event.data?.chunk?.content ?? "");
}
}Iterates over runnable events and prints streamed chat-model content as it arrives.
When to use it
Execution progress
Show progress from intermediate nodes and tools during a long graph run.
Tracing and diagnostics
Inspect which runnable emitted each lifecycle notification.
Interview questions
QWhat does streamEvents provide?
streamEvents creates an iterator of StreamEvent objects that reports runnable progress in real time. The event object includes the event name, the emitting runnable's name, and a run ID.
Follow-up: How would you select only generated tokens? Filter for the appropriate model stream lifecycle event, such as on_chat_model_stream, and read its chunk data.
QHow are stream events named?
Event names follow the pattern on_[runnable_type]_(start|stream|end). This lets consumers distinguish invocation start, incremental output, and completion for each runnable type.
Follow-up: How can nested execution be correlated? Use each event's run ID and preserve parent-child relationships when the surrounding event data provides them.
QWhat does streamEvents return and how is it consumed?
The method accepts an input and options containing a stream-events version, and returns an IterableReadableStream<StreamEvent>. In JavaScript, consume it with for await...of.
Follow-up: Why choose version v2 in current code? It is an explicitly supported version in the documented signature and should be passed rather than relying on an implicit default.
Related
streamStreamEventEventStreamCallbackHandleron_chat_model_starton_chat_model_streamon_chat_model_end