Heuristic:Langchain ai Langgraph Stream Mode Selection
| Knowledge Sources | |
|---|---|
| Domains | Streaming, User_Experience, Debugging |
| Last Updated | 2026-02-11 14:00 GMT |
Overview
Guidance on selecting the appropriate stream mode for different use cases, from development debugging to production token-by-token streaming.
Description
LangGraph's `stream()` method supports seven distinct stream modes that control what data is emitted during graph execution. Choosing the right mode affects both performance and the information available to the consumer. Multiple modes can be combined in a single stream call.
Usage
Use this heuristic when implementing real-time user interfaces, debugging agent behavior, or monitoring production workflows. The choice of stream mode directly impacts the developer and end-user experience.
The Insight (Rule of Thumb)
- `values`: Emits the full state after each step. Best for simple UIs that display the complete current state. Highest bandwidth usage.
- `updates`: Emits only the node name and its return value after each step. Best for event-driven architectures that react to individual node completions.
- `messages`: Emits LLM tokens one-by-one with metadata. Best for chatbot UIs that need token-by-token streaming for responsiveness.
- `custom`: Emits data written by nodes via `StreamWriter`. Best for custom protocols where nodes need to push arbitrary data to consumers.
- `debug`: Combines `checkpoints` and `tasks` events. Best for development and troubleshooting. Do not use in production due to high verbosity.
- `checkpoints`: Emits events when checkpoints are created. Best for monitoring persistence behavior.
- `tasks`: Emits events when tasks start and finish, including results and errors. Best for progress tracking and error monitoring.
- Trade-off: `values` mode sends the most data per event. `updates` is more efficient for large states. `messages` is optimized for LLM-specific streaming. `debug` is comprehensive but verbose.
Reasoning
Different consumers have different information needs. A chatbot UI needs token-level streaming (`messages`) for perceived responsiveness. A monitoring dashboard needs task-level events (`tasks`). A debugging session needs everything (`debug`). The stream mode system allows consumers to subscribe to exactly the events they need, reducing unnecessary data transfer and processing.
The `StreamWriter` callable is always injected into nodes when requested as a keyword argument, but it operates as a no-op when `stream_mode="custom"` is not active. This means nodes can include custom streaming logic without breaking when the consumer does not request custom events.
Code Evidence
StreamMode type definition from `libs/langgraph/langgraph/types.py:95-109`:
StreamMode = Literal[
"values", "updates", "checkpoints", "tasks", "debug", "messages", "custom"
]
"""How the stream method should emit outputs.
- `"values"`: Emit all values in the state after each step, including interrupts.
- `"updates"`: Emit only the node or task names and updates returned by the nodes.
- `"custom"`: Emit custom data using StreamWriter.
- `"messages"`: Emit LLM messages token-by-token with metadata.
- `"checkpoints"`: Emit an event when a checkpoint is created.
- `"tasks"`: Emit events when tasks start and finish.
- `"debug"`: Emit `"checkpoints"` and `"tasks"` events for debugging purposes.
"""
StreamWriter injection behavior from `libs/langgraph/langgraph/types.py:111-114`:
StreamWriter = Callable[[Any], None]
"""`Callable` that accepts a single argument and writes it to the output stream.
Always injected into nodes if requested as a keyword argument, but it's a no-op
when not using `stream_mode="custom"`."""