LangGraph
Graph-Based State Machines · Deep-Dive DD-10 · Course 1
60 minutes · The most architecturally distinct harness · The orchestration baseline · Module 8 reference
The loop as an explicit, editable, testable graph. Nodes are functions. Edges are transitions. State is serialized at every node boundary. interrupt() for HITL. Used INSIDE Claude Code. The framework for when the process is the product.
Deep-Dives · The Harness Roster
The thesis — the loop IS the graph
IMPLICIT LOOP (Pi, DD-01)
The loop is a while(true) hidden inside the harness. The model figures out the process as it goes. Flexible but opaque.
EXPLICIT GRAPH (LangGraph)
The loop is a directed graph you draw before you run it. Every transition is visible in code. Testable, auditable, replayable — but rigid.
For a class of use cases, the process IS the product. Regulated workflows, compliance-governed agents, multi-approval pipelines — these use cases do not want a smart loop that figures it out. They want a declared graph where every transition is visible and every run is replayable from a checkpoint. This is the largest architectural divergence in the roster.
The three primitives — nodes, edges, super-steps
NODE
A function
Takes graph state, does work (call model, run tool, run check), returns a state update. The unit of computation AND the unit of checkpointing.
EDGE
A transition
Connects two nodes. A conditional edge routes based on state — branching in code, not emergent from model behavior.
SUPER-STEP
A checkpoint
Every node boundary serializes state. Crash → resume from the last completed super-step. Module 8 reference: the finest granularity in the roster.
No implicit loop hides the control flow. No emergent behavior you cannot trace. The graph is the program, and the program is auditable by construction.
interrupt() — structural HITL the model cannot route around
BEHAVIORAL HITL (naive)
System-prompt instruction: "ask for approval before writing." The model can forget, defer, or be injected into skipping the ask. The guard is inside the agent's trust boundary.
STRUCTURAL HITL (LangGraph)
The edge from propose to execute goes through an interrupt() node. The model cannot route around it because the model does not control the edges — the graph definition does.
This is the cleanest HITL in the roster. Same principle as NemoClaw (DD-09): enforcement outside the agent's reach. A prompt-injected model cannot skip the approval because the approval is a node in the graph topology, not a request in the prompt.
Super-step checkpoints — Module 8's reference (5/5)
| Granularity | What it means | Who |
|---|
| Session | Resume the session if the process dies | OpenCode (DD-03), most |
| Turn | Resume from the last turn boundary | some harnesses |
| Super-step | Resume from the last completed NODE | LangGraph only |
For long-running, multi-day, multi-human workflows, this is the difference between "resume from where you were" and "resume from approximately where you were." Every checkpoint is serializable, replayable, forkable, inspectable. This is why LangGraph is the Module 8 reference.
When the graph is right vs wrong
RIGHT — process is the product
Regulated workflows (every step auditable). Compliance pipelines (auditor traces the path). Multi-approval flows (different humans, different stages). Declared multi-agent (LangGraph subgraphs).
WRONG — process is emergent
Open-ended coding. Exploratory research. Creative tasks. Emergent multi-agent (CrewAI-style handoffs). Here the rigid graph fights the model — the harness constrains capability.
Decision rule: if you can draw the workflow as a flowchart before you run it, use a graph. If the workflow is "the model figures it out," use a loop (Pi, DD-01) or an implicit-graph harness. The graph-fights-the-model anti-pattern is the future-proof test partially failing — rigid graphs do not co-evolve with model upgrades.
Multi-agent — subgraphs and the C4 E09 connection
LANGGRAPH (declared coordination)
A subgraph is a reusable sub-agent. A multi-agent system is a graph of subgraphs — each subagent is a node, edges between subagents are declared transitions. Auditable for the same reason the single-agent graph is.
CREWAI (emergent coordination)
Agents hand off based on the model's judgment of who should go next. Flexible but opaque — the handoff is emergent, not declared. The contrast is the multi-agent curriculum.
Course 4 Module E09 (Multi-Agent Orchestration) studies the axis between declared coordination (LangGraph) and emergent coordination (CrewAI). LangGraph is the declared-coordination pole. Read this deep-dive alongside DD-12 (CrewAI) — the contrast defines the multi-agent axis the way NemoClaw-vs-Tau defines the governance axis.
The score profile — 37/60, orchestration-substrate shape
| Module | Score | Key decision |
|---|
| 1 Loop | 5/5 | The graph IS the loop, explicitly (reference) |
| 8 State | 5/5 | Super-step checkpoints (finest-grained, reference) |
| 6 Permission | 4/5 | interrupt() as structural HITL |
| 11 Observability | 4/5 | Graph trace = audit trail |
| 2 Tools | 3/5 | Framework — you bring the tools |
| 4 Memory | 3/5 | Checkpointer-based |
| 10 Subagents | 3/5 | Subgraphs (a subgraph is a reusable sub-agent) |
| 5 Sandbox | 2/5 | Framework leaves isolation to the user |
| TOTAL | 37/60 | Orchestration substrate, not a finished harness |
Max on the two orchestration axes (Loop, State). Below median on the substrate axes (Tools, Sandbox) because LangGraph is a framework you build on, not a finished harness. Pair with DD-11 (OpenAI Agents SDK) for sandboxing.
Anti-patterns
Using a graph for work the model could figure out. If the model could determine the workflow as it goes, a rigid graph constrains it. Match the framework to the use case — process-is-product, yes; figure-it-out, no.
Implementing HITL as a system-prompt instruction instead of a graph node. The model can forget, defer, or be injected into skipping the ask. Cure: implement HITL as a graph topology — the edge goes through an interrupt() node. The model cannot route around what it does not control.
Treating the graph as immutable. A common error is to design the graph once and freeze it. As requirements change, the graph must evolve. Cure: treat the graph as a living artifact. Version it. The graph is editable — that is one of its core advantages; do not throw it away by freezing it.
What you can now do
- State LangGraph's thesis — the loop is an explicit, editable, testable graph — and why this is the largest architectural divergence in the roster.
- Distinguish the three primitives (nodes, edges, super-step checkpoints) and why each earns its 5/5 (Module 1 Loop, Module 8 State).
- Explain why
interrupt() is the cleanest HITL primitive — structural, not behavioral — and why a prompt-injected model cannot route around it.
- Apply the "when is the graph right vs wrong" decision rule and name the graph-fights-the-model anti-pattern.
- Connect LangGraph's subgraph pattern to multi-agent orchestration (Module 10) and to Course 4's E09 module.
The lab: build a LangGraph-style state machine in pure Python — nodes as functions, edges as a transition table, super-step checkpoints at every node boundary. Add an interrupt() node and confirm a prompt-injected model cannot route around it. Add a subgraph for multi-agent coordination via explicit edges.
Next: DD-11 — OpenAI Agents SDK (the sandbox-abstraction framework)