« Phase 18 README · Warmup · Deep Dive · Principal Deep Dive · Core Contributor · Staff Notes

Phase 18 — Hitchhiker's Guide (LangGraph)

30-second mental model

LangGraph = a Pregel/BSP stateful graph runtime for agents. State is channels with reducers; it runs in super-steps (active nodes see the same state, writes merge via reducers, then follow edges). A checkpointer + thread_id give memory, durability, and time-travel; interrupt() + Command(resume) give human-in-the-loop. A ReAct agent is just the agent↔tools cycle with a conditional edge.

The facts to tattoo on your arm

FactWhy
super-step (Pregel/BSP)nodes in a step see the same state; writes merge, then edges
reducer = f(current, update)default overwrites; add_messages appends
Annotated[list, add_messages]the most important annotation — accumulates the log
conditional edge = the branch"call a tool or finish?"
recursion_limit (default 25)guards the agent loop cycle
checkpointer + thread_idmemory + durability + time-travel
interrupt() / interrupt_beforedynamic vs static HITL; both need a checkpointer
Command(resume=..., goto=..., update=...)resume/redirect a paused graph

Framework one-liners

  • StateGraph(State) → add_node/add_edge/add_conditional_edges → compile(checkpointer=...).
  • create_react_agent(model, tools) — the prebuilt ReAct graph.
  • MemorySaver (dev) / SqliteSaver / PostgresSaver (prod) — checkpointers.
  • stream_mode: "updates" / "values" / "messages" (token streaming) / "debug".
  • @entrypoint/@task — the Functional API (durability without drawing a graph).
  • langgraph-supervisor / langgraph-swarm — multi-agent prebuilts. LangSmith — tracing.

War stories

  • The clobbered messages. Someone declared messages: list without add_messages; every node overwrote it and the agent lost its history. One annotation fixed it.
  • The infinite loop. A router never returned "end" because a reducer clobbered the channel it read; recursion_limit caught it, get_state_history revealed it.
  • The lost approval. HITL built without a checkpointer couldn't survive a restart mid-pause. HITL needs persistence.

Vocabulary

StateGraph / channel / reducer · super-step (Pregel/BSP) · conditional edge / router · recursion_limit · checkpointer / thread_id / StateSnapshot · time travel / get_state_history / update_state · interrupt / Command / interrupt_before · subgraph · Functional API (@entrypoint/@task) · supervisor / swarm.

Beginner mistakes

  1. A messages channel without the add_messages reducer (it clobbers).
  2. Thinking state is a mutable dict instead of reducer-merged updates.
  3. Compiling without a checkpointer, then wanting memory/HITL.
  4. A router whose exit condition never trips (infinite loop).
  5. Confusing dynamic interrupt() with static interrupt_before.
  6. Treating LangGraph as "LangChain 2.0" instead of a stateful graph runtime.