LangGraph, the basics

LangGraph is a state machine runner with a save button. You write plain functions. You wire them into a graph. The library runs the graph, passes one shared state dict between the functions, and saves a copy of that state after every step. That is the whole product.

It does not call a model for you, it has no prompts, and it does not make an agent smarter. A node that calls an LLM is your code inside a function; LangGraph only decides which function runs next and remembers where the run is. It is an MIT-licensed Python library from LangChain Inc., with a JavaScript port (LangGraph.js). It reached 1.0 in October 2025; everything below was run on langgraph 1.2.17 in a python:3.12-slim container.

Why anyone needs that: an agent is a loop — call the model, maybe call a tool, look at the result, decide whether to go round again. Writing that loop yourself is ten lines. Making it survive a crash, stop for a human approval and continue tomorrow, show progress while it runs, and not spin forever is where the ten lines become a framework. LangGraph is that framework.

The four parts

PartWhat it isIn code
StateOne dict shared by every node. Its schema is a TypedDict or Pydantic model.class State(TypedDict): ...
NodeA function that reads the state and returns the keys it wants to change.def write(state) -> dict
EdgeWhich node runs next. Fixed, or chosen by a function at run time (conditional edge).add_edge, add_conditional_edges
CheckpointerStores a snapshot of the state after every step, keyed by a thread_id.compile(checkpointer=...)

Two more words: a reducer says how a node’s return value merges into a key — overwrite (the default) or, say, append to a list. A thread is one conversation or job: every run with the same thread_id continues from the last saved snapshot.

A complete example

A writer node produces a draft. A conditional edge sends it back to try again until it has three drafts, then hands over to a review node that stops and waits for a human.

import operator
from typing import Annotated, TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import interrupt, Command

class State(TypedDict):
    question: str
    drafts: Annotated[list[str], operator.add]   # reducer: append, don't overwrite
    tries: int

def write(state: State) -> dict:
    n = state["tries"] + 1
    return {"drafts": [f"draft {n}"], "tries": n}   # an LLM call would go here

def check(state: State) -> str:
    return "review" if state["tries"] >= 3 else "write"

def review(state: State) -> dict:
    ok = interrupt({"show": state["drafts"][-1]})   # pause, wait for a human
    return {"drafts": [f"approved={ok}"]}

g = StateGraph(State)
g.add_node("write", write)
g.add_node("review", review)
g.add_edge(START, "write")
g.add_conditional_edges("write", check, ["write", "review"])
g.add_edge("review", END)
app = g.compile(checkpointer=InMemorySaver())

cfg = {"configurable": {"thread_id": "t1"}}
for ev in app.stream({"question": "q", "drafts": [], "tries": 0}, cfg, stream_mode="updates"):
    print(ev)
print("next:", app.get_state(cfg).next)
for ev in app.stream(Command(resume=True), cfg, stream_mode="updates"):
    print(ev)
print("final:", app.get_state(cfg).values)

Output:

{'write': {'drafts': ['draft 1'], 'tries': 1}}
{'write': {'drafts': ['draft 2'], 'tries': 2}}
{'write': {'drafts': ['draft 3'], 'tries': 3}}
{'__interrupt__': (Interrupt(value={'show': 'draft 3'}, id='4d81…', response_schema=None),)}
next: ('review',)
{'review': {'drafts': ['approved=True']}}
final: {'question': 'q', 'drafts': ['draft 1', 'draft 2', 'draft 3', 'approved=True'], 'tries': 3}

The first stream call returns at the interrupt. Nothing is waiting in memory: the run is a saved snapshot whose next node is review. The second call, possibly from another process, loads that snapshot and continues. drafts grew to four entries because of the operator.add reducer; tries was overwritten each time because it has none.

The example graph: START leads to the write node, a conditional edge loops back to write while tries is below 3 and moves to review at 3, review calls interrupt and waits for a human to resume it, then the run ends. Below, the six checkpoints the run saved, at steps -1 to 4, each recording the node due to run next. The example as a graph, and the checkpoints it leaves boxes = nodes (your functions) · arrows = edges · strip = one saved snapshot per step, thread t1 START write +1 draft, tries += 1 check(): tries < 3 check(): tries ≥ 3 review interrupt(): run stops END human: Command(resume=True) seconds or days later, any process Checkpoints step · next node -1 input → START 0 → write 1 → write 2 → write 3 paused → review 4 → done each box is a full copy of the state; any of them can be loaded, edited and run from again
The example graph and the six checkpoints the run saved (read back with get_state_history). The run paused at step 3 with review due next.

How a run actually executes

LangGraph runs in steps (the docs call them super-steps; the model is Google’s Pregel). In each step:

  1. Every node that is due runs. Nodes due in the same step run in parallel.
  2. Their returned dicts are merged into the state, key by key, through the reducers.
  3. A checkpoint is saved.
  4. Edges are evaluated to find the nodes due in the next step. None due → the run ends.

Rules that follow from this, each checked on 1.2.17:

What the checkpoints buy you

FeatureHow
Memory across turnsInvoke again with the same thread_id; the state is already there.
Human in the loopinterrupt(value) inside a node stops the run; Command(resume=x) continues it, and interrupt returns x.
Crash recoveryA failed run restarts from the last checkpoint, not from the beginning.
Time travel / debuggingget_state_history lists every snapshot; update_state edits one; run again from it.
Streamingstream_mode="updates" yields each node’s changes as above; "messages" yields LLM tokens as they arrive; "values" the full state per step.

Storage backends are separate packages: InMemorySaver (built in, gone on restart), langgraph-checkpoint-sqlite, langgraph-checkpoint-postgres. The state must be serializable, because it is written to that store on every step.

Where the LLM goes

Inside a node, like any other code. The usual agent is two nodes and one conditional edge:

That loop is shipped ready-made: ToolNode and tools_condition in langgraph.prebuilt, and LangChain 1.0’s create_agent builds exactly this graph. The model client can be anything — LangChain’s chat models, the raw Anthropic or OpenAI SDK, or an HTTP call to a local vLLM or Ollama server. Installing langgraph does pull in langchain-core (1.7.0 here) for its message types, but nothing forces you to use LangChain’s model wrappers.

When to use it, and when not

Your appUse
One prompt, one answerPlain code. A graph adds nothing.
A fixed chain: retrieve, then generatePlain code. Two function calls do not need a scheduler. (RAG basics)
A loop: model ↔ tools until doneA plain while loop works; LangGraph once you need the next rows.
Must pause for approval and resume laterLangGraph. Saved state + interrupt is the core feature.
Long jobs that must survive restartsLangGraph with the Postgres checkpointer.
Several agents handing work to each otherLangGraph: each agent is a node or a subgraph, the shared state is the hand-off.

Things that go wrong

Questions? Let's Chat :)

ai llm engineering