What a run emits while it runs

The flight recommender waits and then answers. That is defensible for a product where the answer arrives in four seconds. Run the same design against a document-extraction graph that takes forty and you have built a screen whose only content, for the entire time anyone is looking at it, is a claim that something is happening.

The interesting part is that the graph is not silent during those forty seconds. It is emitting continuously, in several different shapes at once, and the design question is not “can I show progress” but “which of these several truths am I subscribing to.” Picking wrong in one direction gives you the spinner back. Picking wrong in the other floods a broker with the agent’s internal monologue.

The modes, and what each one is actually good for

The JavaScript streaming documentation lists six modes. Verbatim descriptions, with the surface each one is for:

Source: LangChain, Streaming (JavaScript) — vendor documenting its own product, fetched 2026-09-02.

One caution that matters more than the table does: this list is language-specific and it moves. tools is present in the JavaScript documentation and the Python side has modes the JavaScript side does not. Worse, LangGraph’s older generated reference site still publishes a different mode union — one that includes modes the current documentation does not list, and omits tools. Both pages are live. Only one is current. Check the version you have installed rather than the first search result, and treat this as the standing condition of the field rather than an annoyance: on the Vista job you will be reading docs for framework versions nobody has written a blog post about yet.

The chunk shapes, which is where the work is

updates yields an object keyed by node name, whose value is that node’s state update:

for await (const chunk of await graph.stream(inputs, { streamMode: "updates" })) {
  for (const [nodeName, state] of Object.entries(chunk)) {
    console.log(`Node ${nodeName} updated:`, state);
  }
}

Two things to notice. The node name arrives with the data, which is what lets you drive a per-node activity list without inventing a parallel step registry. And the docs are explicit that multiple updates in the same step stream separately — a fanned-out superstep does not arrive pre-merged, so if your UI wants one row per node, this shape already gives it to you, and if it wants one row per superstep, you are doing the grouping.

Also: these are updates, in the sense the state lesson drew a line under. On an accumulating channel the chunk carries the increment, not the accumulated value. Assign it into local state and the transcript collapses to one entry.

messages yields a two-tuple, destructured directly:

for await (const [messageChunk, metadata] of await graph.stream(
  { topic: "ice cream" },
  { streamMode: "messages" }
)) {
  if (messageChunk.content) {
    console.log(messageChunk.content + "|");
  }
}

The metadata half is the useful one and the half people drop. It carries langgraph_node and tags, which is how you show tokens from the drafting node and not from the classifier that happens to use the same model. A graph with three model calls streaming into one undifferentiated text area is a real bug that looks like a design choice.

And to take more than one at a time, pass an array — each yielded value becomes a [mode, chunk] tuple:

for await (const [mode, chunk] of await graph.stream(inputs, {
  streamMode: ["updates", "custom"],
})) {
  console.log(mode, chunk);
}

Nothing tells you “page 3 of 14” unless a node says so

This is the finding worth taking to a backend engineer. None of the built-in modes know anything about your domain. updates knows a node called extractFields ran. It does not know that node is on its third page of fourteen, because that fact exists only inside the node’s loop and nothing exports it.

The mechanism for exporting it is the writer on the config passed as a node’s second argument — typed as (chunk: unknown) => void, described in the reference as the callback for sending custom data chunks via the custom stream mode:

const node: GraphNode<typeof State> = async (state, config) => {
  config.writer({ custom_key: "Generating custom data inside node" });
  return { answer: "some data" };
};

So “show the broker which page we are on” is not a UI ticket you can complete alone. It is a request for a config.writer call inside a node, plus an agreed payload shape, plus a client subscribed to custom. Recognizing that early — and arriving with the payload shape already drafted rather than with a Figma frame implying it — is most of what makes a UI architect useful on an agent team rather than downstream of one.

Interrupts arrive in the same stream

A pause is not a separate transport. When a graph hits an interrupt, the payload comes back to the caller under an __interrupt__ key, as an array — the docs’ printed shape is entries of { id, value }, where value is exactly what the node passed to interrupt():

{
  vals: [],
  __interrupt__: [
    { id: '...', value: 'question_a' },
    { id: '...', value: 'question_b' }
  ]
}

Note the plural. Parallel branches can each be waiting on their own question at the same time, which means “the run is paused” is not necessarily one decision to render. Hold that thought; it is the interrupt module’s problem, and it is a harder design problem than it first looks.

One more thing to know exists rather than to learn now: alongside the mode-based API there is a newer event-streaming interface, streamEvents at version: "v3", which the LangChain streaming documentation currently recommends for new applications. Instead of parsing mode tuples it hands back typed projections you iterate independently — stream.messages, stream.values, stream.toolCalls, and for our purposes stream.interrupted and stream.interrupts. Same underlying events, a shape closer to how a client actually wants to consume them. The modes are still documented and still work; know that both exist so you can tell which one a codebase is using.

What this does not cover

Everything here has assumed the run finishes on its own. The __interrupt__ shape appeared only as a chunk in a stream, which badly undersells it — a pause is a durable state the run sits in, addressable by anyone who has the thread, not an event that flew past. That is the whole interrupt module, starting with the interrupt-and-resume lesson, and it is where your review gate finally becomes an agent primitive.

Nothing here covers reading a run that is not currently streaming to you either: a second reviewer opening a link, a page refreshed after a crash, a run started yesterday. That reads from checkpoints rather than from a stream, and it is the checkpointers-and-threads lesson. This is also the end of module one, which means you now have the four things the reading pass produces — execution model, routing, state contract, emission — and the primitives map in the reference section is the one-page version to keep open while you use them.