Stream modes and event types
A LangGraph run streams in eight modes, in two chunk versions, and through one beta event protocol, and each one has a fixed shape at langgraph 1.2.22.
Every row of this page comes from the code of langgraph 1.2.22 or from a capture of the same agent run. That run makes two model calls and one tool call. Section 5.1 explains when to use each mode.
The modes of stream
The type StreamMode lists seven modes. The loop also accepts tools, which the type leaves out. The register of the sources page records that gap as D4.
| Mode | One chunk in v1 | Chunks in our run | Capture |
|---|---|---|---|
values | the whole state after each step | 4 | 21-stream-updates-values.txt |
updates | a dict from the node name to the update that the node returned | 3 | 21-stream-updates-values.txt |
messages | a tuple of a message chunk and a metadata dict | 13 | 22-stream-messages.txt |
custom | the value that a node or tool passed to stream_writer | 0, because no tool wrote one | 23-stream-tasks-custom-debug.txt |
tasks | a task start with id, name, input, and triggers, or a task result with error and result | 6 | 23-stream-tasks-custom-debug.txt |
debug | a dict with step, timestamp, a type of checkpoint, task, or task_result, and a payload | 6, with no checkpointer | 23-stream-tasks-custom-debug.txt |
checkpoints | a checkpoint in the shape of get_state | not in the kit | none |
tools | a tool event, as the table below shows | 4, on the slow_sum agent | 26-stream-tools-mode.txt |
A create_agent graph streams updates when you pass no mode. A plain Pregel object streams values. Inside another graph, a graph with no mode streams values too.
The metadata of a messages chunk holds langgraph_node, langgraph_step, langgraph_triggers, ls_provider, and ls_model_type, among other keys. Read langgraph_node to tell the model of an agent from a model inside a tool.
The shape of a chunk in v1
| Call | What stream yields |
|---|---|
| one mode | the chunk |
| a list of modes | a tuple (mode, chunk) |
one mode with subgraphs=True | a tuple (namespace, chunk) |
a list of modes with subgraphs=True | a tuple (namespace, mode, chunk) |
StreamPart in v2
With version="v2", every chunk is a TypedDict with the keys type, ns, and data, whatever modes you ask for. The v2 value came in langgraph 1.1.0.
| Type | type value | Line in types.py |
|---|---|---|
ValuesStreamPart | values | 274 |
UpdatesStreamPart | updates | 286 |
MessagesStreamPart | messages | 298 |
CustomStreamPart | custom | 311 |
CheckpointStreamPart | checkpoints | 322 |
TasksStreamPart | tasks | 330 |
DebugStreamPart | debug | 345 |
invoke(..., version="v2") returns a GraphOutput with value and interrupts. Access to it as a dict still works, and it warns LangGraphDeprecatedSinceV11, as capture 24-stream-v2.txt shows.
Tool events
The tools mode yields one dict for each tool event. Its event key names the kind:
event | Other keys | In our run |
|---|---|---|
tool-started | tool_call_id, tool_name, input | 1 |
tool-output-delta | tool_call_id, delta | 2, from runtime.emit_output_delta |
tool-finished | tool_call_id, output, the ToolMessage | 1 |
tool-error | defined by the protocol | 0 |
stream_events v3
stream_events defaults to version="v2", and you must name v3. Version v3 is beta, and it warns LangChainBetaWarning: The v3 streaming protocol on Pregel is experimental.. It returns a GraphRunStream, whose public members in capture 25-stream-events-v3.txt are abort, extensions, interleave, interrupted, interrupts, lifecycle, messages, output, subagents, subgraphs, tool_calls, and values.
| Rule | Where |
|---|---|
stream_mode and subgraphs raise TypeError under v3. | |
A sync stream_events with v1 or v2 raises NotImplementedError. Use astream_events for those versions. | |
The kit pins the event shapes with langchain-protocol 0.0.21. | capture/requirements.txt |
Each raw event is a frame with type event, a method, params with namespace, timestamp, and data, and a seq number. Our run gave 23 frames: 4 values, 17 messages, and 2 tools.
method | What data holds | Line in protocol.py |
|---|---|---|
lifecycle | the status of a graph or a subagent: started, running, completed, failed, or interrupted | 269, 462 |
messages | a message event and its metadata | 273 |
tools | a tool event | 277 |
input.requested, input.answered | an interrupt and its answer | 281, 285 |
values, updates, checkpoints, custom, tasks | the data of the v1 mode of the same name | 289 to 305 |
A messages frame carries one of these events for one model message:
| Event | Keys | In our run |
|---|---|---|
message-start | role, id | 2 |
content-block-start | index, content | 2 |
content-block-delta | index, delta, such as {"type": "text-delta", "text": "The"} | 9, of which 8 are text-delta and 1 is tool-call-delta |
content-block-finish | index, content, the whole block | 2 |
message-finish | none in our run | 2 |
error | defined by the protocol | 0 |
A provider that streams the arguments of a tool call sends tool-call-delta deltas. ChatOllama sends each call whole on one chunk before the last. So the v3 run of the kit has one tool-call-delta, which carries the whole call.
LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11