When would you use astream_events on a LangGraph graph instead of stream_mode?

## Two different lenses `stream_mode` is LangGraph's own vocabulary: supersteps, node deltas, state snapshots, model tokens, custom payloads. `astream_events` is langchain-core's vocabulary: a tree of runs, where every runnable that executes — the graph, each node, each chat model, each tool, each parser nested inside a node — announces its start, its streaming output, and its end. That difference decides when each is right. If your question is "what should the user see?", the answer is `stream_mode`. If your question is "why did this run take that path, and what arguments did it pass to the search tool?", the answer is `astream_events`. ## The event shape Each yielded event is a dict with a stable set of keys: - `event` — the type, such as `on_chain_start`, `on_chain_end`, `on_chat_model_start`, `on_chat_model_stream`, `on_chat_model_end`, `on_tool_start`, `on_tool_end`, `on_retriever_start`, `on_retriever_end`. - `name` — the runnable's name; for a node it is the node name. - `run_id` and `parent_ids` — identity and lineage, which is what lets you rebuild the call tree offline. - `tags` and `metadata` — anything bound via config, plus LangGraph's own additions (`langgraph_node`, `langgraph_step`, the checkpoint namespace). - `data` — payload: `input` on start events, `output` on end events, `chunk` on stream events. Token text lives at `event["data"]["chunk"].content` on `on_chat_model_stream`. Tool results live at `event["data"]["output"]` on `on_tool_end`. Those two, plus the node name in metadata, cover most debugging. ## What it shows that stream_mode cannot The step-level modes describe boundaries. They tell you node `agent` ran and returned a message with two tool calls; they do not tell you what happened inside the node before it returned. The event stream exposes the interior: - The exact prompt sent to the model (`on_chat_model_start` input) — invaluable when a prompt template silently rendered wrong. - Each tool invocation with its arguments and its result, in order, even when several tools run inside one node. - Timing, because start and end events are separate — you can attribute latency to a specific model call rather than to "the agent node". - Nested structure via `parent_ids`, so a node containing a sub-chain is legible as a tree. ## The costs **Volume.** Every nested runnable emits at least two events, and every token emits one. A single agent turn with two tool calls easily crosses several hundred events. Pushing that to a browser is wasteful; parsing it in a hot loop costs real CPU. **Async only.** There is no synchronous equivalent, so a sync codebase must adapt. **Coupling to internals.** Event names track the runnable composition of your graph. Refactor a node from one chain into three and the event stream changes shape. Consumers that pattern-match on `name` are brittle; filtering on tags you set deliberately is far more stable. **Callback propagation.** As with token streaming, an async node on Python 3.10 that fails to thread its `RunnableConfig` into inner calls produces a stream missing those inner events entirely — with no error. If the events for one node's interior are mysteriously absent, suspect config propagation before suspecting the framework. ## Filtering The method accepts `include_names`, `include_types`, `include_tags` and the matching `exclude_*` arguments. In practice: tag the runnables you care about at construction time, then filter on that tag. It keeps the consumer decoupled from internal naming and cuts the volume by an order of magnitude. ## How this relates to tracing Events are the live, in-process view; a tracing backend is the durable, after-the-fact view of the same underlying run tree. When you are inside a debugging session with a reproducible input, events are faster — no upload, no UI, and you can assert on them in a test. For an incident on a run that already happened in production, tracing wins, because nobody was holding an iterator at the time. Mature teams use both, and it is a good answer to say so explicitly. ## Interview-worthy summary Use `stream_mode` for the product. Use `astream_events` when you need to see inside a node — prompts, tool arguments, per-call latency — or when you are building instrumentation that must react to specific inner events. Never make it the default transport of a user-facing endpoint without filtering, and never let consumers pattern-match on runnable names you expect to refactor.