Get Started

Stateful Graph Orchestration, Durable Execution and Checkpoints

Agent is a state machine; nodes are functions; edges are transitions; state is checkpointed after each node. Resume from any failure at the last successful checkpoint. LangGraph is the 2026 reference for this model of low-level stateful orchestration.

75 minutesLearn + BuildPython (stdlib)Free lesson

Learning Objectives

  • Describe LangGraph's core model: state machine with typed state, function nodes, conditional edges, and post-node checkpoints.
  • Name the four capabilities the docs highlight: durable execution, streaming, human-in-the-loop, comprehensive memory.
  • Explain the three orchestration topologies LangGraph supports: supervisor, peer-to-peer (swarm), hierarchical (nested subgraphs).
  • Implement a stdlib state graph with typed state, conditional edges, and a checkpoint/resume cycle.

The Problem

Agents and workflows share a problem: when a 40-step run fails at step 38, you want to resume from step 38, not start over. Second-class state models leave operators hacking retries around a library that assumes fresh runs.

LangGraph's design answer: state is a first-class typed object, mutations are explicit, and checkpoints persist after every node. Resume is a load_state(session_id) call.

The Concept

The graph

A graph is defined by:

  • State type. A typed dict (or Pydantic model) that every node reads and mutates.
  • Nodes. Pure functions (state) -> state_update. Updates are merged into state after return.
  • Edges. Conditional or direct transitions between nodes.
  • Entry and exit. START and END sentinel nodes mark the boundary.

Example: an agent with classifyrefundbugsalesdone nodes, a routing workflow as a graph.

Durable execution

After each node returns, the runtime serializes the state and writes it to a checkpointer (SQLite, Postgres, Redis, custom). On failure at step N, the runtime can resume(session_id) and pick up from step N+1 with exact state.

The LangGraph docs explicitly highlight production users where this matters: Klarna, Uber, J.P. Morgan. The claim isn't the graph shape; it's that the graph shape plus checkpointing makes recovery cheap.

Streaming

Every node can yield partial output. The graph streams per-node-delta events to the caller so UIs update as the graph runs.

Human-in-the-loop

Inspect and modify state between nodes. Implementations: pause before a critical node, surface state to a human, accept modifications, resume. The checkpointer makes this easy because state is already serialized.

Memory

Short-term (within a run, conversation history in state) and long-term (across runs, persistent via the checkpointer plus a separate long-term store). LangGraph integrates with external memory systems (Mem0, custom) via tools.

Three topologies

  1. Supervisor. Central router LLM dispatches to specialist subagents. create_supervisor() in langgraph-supervisor (though the LangChain team in 2026 recommends doing this through tool calls directly for more context control).
  2. Swarm / peer-to-peer. Agents hand off directly via a shared tool surface. No central router.
  3. Hierarchical. Supervisors managing sub-supervisors, implemented as nested subgraphs.

Where this pattern goes wrong

  • Checkpoints too small. Only checkpointing conversation turns leaves tool state and memory writes unrecoverable. Full state must serialize.
  • Non-deterministic nodes. Resume assumes node inputs produce the same state update. Random seeds, wall-clock, external APIs must be captured.
  • Over-use of conditional edges. A graph with every edge conditional is a state machine that cannot be reasoned about. Prefer linear chains with occasional branches.

Build It

code/main.py implements a stdlib stateful graph:

  • Statea typed dict with messagessteprouteoutputhuman_approval.
  • Nodecallable taking state and returning an update dict.
  • StateGraphnodes + edges + conditional edges + run + resume.
  • SQLiteCheckpointer (in-memory fake), serializes state after every node; load(session_id) restores.
  • A demo graph: classify -> branch(refund / bug / sales) -> human gate -> send.

Run it:

Code
python3 code/main.py

The trace shows the first run failing at the human gate, persistence, then resume producing the final output.

Use It

  • LangGraphthe reference, production-ready. Use create_react_agentcreate_supervisoror build your own graph.
  • AutoGen v0.4 (Lesson 14), actor model alternative for high-concurrency scenarios.
  • Claude Agent SDK (Lesson 17), managed harness with built-in session store.
  • Customwhen you need exact control over state shape or checkpointer backend.

Ship It

outputs/skill-state-graph.md generates a LangGraph-shaped state graph in any target runtime with checkpointing and resume wired in.

Exercises

  1. Add a conditional edge from classify to end when classification confidence is below a threshold. Resume the run after a human sets route manually.
  2. Swap the SQLite-like fake for a real SQLite checkpointer. Measure per-step serialization overhead.
  3. Implement parallel edges: two nodes run concurrently, merge by a custom reducer. What does immutable state buy here?
  4. Read langgraph-supervisor reference. Port the toy to create_supervisor. Compare the trace shapes.
  5. Add streaming: each node yields partial state while it runs. Print the deltas as they arrive.

Key Terms

TermWhat people sayWhat it actually means
State graph"Agent as state machine"Typed state + nodes + edges + reducers
Checkpointer"Persistence backend"Serializes state after every node; enables resume
Reducer"State merger"Function that combines current state with a node's update
Conditional edge"Branch"Edge chosen by a function of state
Subgraph"Nested graph"A graph used as a node inside another graph
Durable execution"Resume from failure"Restart at the last successful node with exact state
Supervisor"Router LLM"Central dispatcher for specialist subagents
Swarm"P2P agents"Agents hand off via shared tools; no central router

Further Reading

Check what you learned

7 questions. Answer each one to see why.

Question 1 of 70 correct

What does LangGraph treat as the core unit of the agent?

The full code

Every file for this lesson. Copy it, run it, then change it.

main.py
"""LangGraph-shaped stateful graph in stdlib, with checkpoint and resume.

State is a typed dict. Nodes return update dicts. Runtime serializes state
after every node so resume picks up exactly where it left off.
"""

from __future__ import annotations

import copy
import json
from dataclasses import dataclass, field
from typing import Any, Callable


State = dict[str, Any]
Update = dict[str, Any]
NodeFn = Callable[[State], Update]
Router = Callable[[State], str]


START = "__start__"
END = "__end__"


@dataclass
class Edge:
    src: str
    dst: str
    router: Router | None = None


class StateGraph:
    def __init__(self) -> None:
        self.nodes: dict[str, NodeFn] = {}
        self.edges: dict[str, list[Edge]] = {}
        self.entry: str | None = None

    def add_node(self, name: str, fn: NodeFn) -> None:
        self.nodes[name] = fn

    def set_entry(self, name: str) -> None:
        self.entry = name

    def add_edge(self, src: str, dst: str) -> None:
        self.edges.setdefault(src, []).append(Edge(src=src, dst=dst))

    def add_conditional_edges(self, src: str, router: Router,
                              targets: dict[str, str]) -> None:
        for value, dst in targets.items():
            self.edges.setdefault(src, []).append(
                Edge(src=src, dst=dst, router=_make_router(router, value))
            )

    def _next(self, current: str, state: State) -> str | None:
        for edge in self.edges.get(current, []):
            if edge.router is None or edge.router(state):
                return edge.dst
        return None


def _make_router(router: Router, expected: str) -> Router:
    def fn(state: State) -> bool:
        return router(state) == expected
    return fn


class InMemoryCheckpointer:
    def __init__(self) -> None:
        self._store: dict[str, list[tuple[str, State]]] = {}

    def save(self, session_id: str, step_name: str, state: State) -> None:
        self._store.setdefault(session_id, []).append((step_name, copy.deepcopy(state)))

    def load_latest(self, session_id: str) -> tuple[str, State] | None:
        history = self._store.get(session_id, [])
        if not history:
            return None
        return history[-1]

    def history(self, session_id: str) -> list[tuple[str, State]]:
        return list(self._store.get(session_id, []))


class PausedAtNode(Exception):
    def __init__(self, node: str, state: State) -> None:
        super().__init__(node)
        self.node = node
        self.state = state


class Runner:
    def __init__(self, graph: StateGraph,
                 checkpointer: InMemoryCheckpointer) -> None:
        self.graph = graph
        self.checkpointer = checkpointer

    def run(self, session_id: str, initial_state: State,
            resume_from: str | None = None,
            state_override: State | None = None) -> State:
        if state_override is not None:
            state = copy.deepcopy(state_override)
        else:
            state = copy.deepcopy(initial_state)
        current = resume_from or self.graph.entry
        if current is None:
            raise RuntimeError("no entry node set")
        while current is not None and current != END:
            fn = self.graph.nodes.get(current)
            if fn is None:
                raise RuntimeError(f"unknown node {current!r}")
            update = fn(state)
            if update is None:
                update = {}
            state = {**state, **update}
            self.checkpointer.save(session_id, current, state)
            if state.get("_pause_reason"):
                reason = state.pop("_pause_reason")
                raise PausedAtNode(current, state)
            current = self.graph._next(current, state)
        return state


def _classify(state: State) -> Update:
    text = state["input"].lower()
    if "refund" in text or "money back" in text:
        route = "refund"
    elif "crash" in text or "bug" in text or "error" in text:
        route = "bug"
    elif "pricing" in text or "quote" in text:
        route = "sales"
    else:
        route = "sales"
    return {"route": route, "step": state.get("step", 0) + 1}


def _refund(state: State) -> Update:
    return {"ticket": f"REF-{state.get('input', '')[:12]}",
            "step": state.get("step", 0) + 1}


def _bug(state: State) -> Update:
    return {"ticket": f"BUG-{state.get('input', '')[:12]}",
            "step": state.get("step", 0) + 1}


def _sales(state: State) -> Update:
    return {"ticket": f"SAL-{state.get('input', '')[:12]}",
            "step": state.get("step", 0) + 1}


def _human_gate(state: State) -> Update:
    if not state.get("human_approval"):
        return {"_pause_reason": "awaiting human approval",
                "step": state.get("step", 0) + 1}
    return {"step": state.get("step", 0) + 1}


def _send(state: State) -> Update:
    return {"output": f"sent {state.get('ticket')}",
            "step": state.get("step", 0) + 1}


def build_graph() -> StateGraph:
    graph = StateGraph()
    graph.add_node("classify", _classify)
    graph.add_node("refund", _refund)
    graph.add_node("bug", _bug)
    graph.add_node("sales", _sales)
    graph.add_node("human_gate", _human_gate)
    graph.add_node("send", _send)
    graph.set_entry("classify")

    graph.add_conditional_edges(
        "classify",
        router=lambda s: s["route"],
        targets={"refund": "refund", "bug": "bug", "sales": "sales"},
    )
    graph.add_edge("refund", "human_gate")
    graph.add_edge("bug", "human_gate")
    graph.add_edge("sales", "human_gate")
    graph.add_edge("human_gate", "send")
    graph.add_edge("send", END)
    return graph


def main() -> None:
    print("=" * 70)
    print("LANGGRAPH STATE MACHINE — Phase 14, Lesson 13")
    print("=" * 70)

    graph = build_graph()
    ckpt = InMemoryCheckpointer()
    runner = Runner(graph, ckpt)

    session = "s001"
    initial: State = {"input": "the CLI crashes on ctrl-c, please fix",
                      "step": 0, "human_approval": False}

    print("\nfirst run (will pause at human_gate)")
    try:
        final = runner.run(session, initial)
        print(f"  final: {final}")
    except PausedAtNode as paused:
        print(f"  PAUSED at {paused.node}")
        print(f"  state at pause: {json.dumps(paused.state, default=str)}")

    print("\ncheckpoint history")
    for node, snap in ckpt.history(session):
        print(f"  {node}  route={snap.get('route')}  "
              f"ticket={snap.get('ticket')}  step={snap.get('step')}")

    print("\nhuman approves; resume from next node after human_gate")
    latest = ckpt.load_latest(session)
    assert latest is not None
    last_node, last_state = latest
    approved_state = {**last_state, "human_approval": True}
    approved_state.pop("_pause_reason", None)
    ckpt.save(session, f"{last_node}_reviewed", approved_state)

    final = runner.run(
        session_id=session,
        initial_state=initial,
        resume_from="send",
        state_override=approved_state,
    )
    print(f"  final: {final}")

    print()
    print("property: state serializes after every node; resume is exact.")
    print("no fresh re-runs after step 38 fails; pick up at step 39.")


if __name__ == "__main__":
    main()