GyaanStack. Blog

Articles / agentslanggraphpython

LangGraph explained from scratch: state, edges, cycles, checkpoints and interrupts

Learn LangGraph 1.2 by building one small graph: state and reducers, nodes, conditional edges, a retry loop, checkpoints, threads, interrupts and streaming.

By Raghunath · · 17 min read

A LangChain chain runs in one direction: prompt, model, parser, done. Agents need to go back. A model drafts an answer, something checks it, and on failure control returns to the drafting step with feedback. LangGraph is a library for exactly that shape of program. You describe a graph of Python functions that share a state dictionary, and the graph may contain cycles.

This post builds one small graph and uses it to explain every core idea in the order you meet them: state and reducers, nodes, edges, conditional edges, a cycle with a cap, checkpointers and threads, interrupts for a human in the loop, and streaming. All code below ran against langgraph 1.2.24, the release on PyPI as of 20 November 2026. The model is a stub so you can run everything with no API key; one comment shows where a real model goes.

If you already know the basics and want bigger builds, two other posts pick up from here: multi-agent workflow automation in Python covers parallel branches, retries and cost per run, and the local multi-agent research assistant runs a planner, researchers and a reviewer on Ollama. For choosing between supervisor, handoff and critic designs, see multi-agent architecture patterns.

The mental model#

Three pieces make up every LangGraph program.

  • State is a typed dictionary that every step can read. It is the only way steps talk to each other.
  • Nodes are plain functions. Each takes the current state and returns a dict with the keys it wants to change. A node never returns the whole state.
  • Edges decide which node runs next. A normal edge always goes to the same place. A conditional edge calls a function that looks at the state and returns a node name.

Execution happens in super-steps. In each super-step LangGraph runs every node that is scheduled, collects their returned updates, merges them into the state, then follows edges to pick the next set of nodes. A run ends when nothing is scheduled, which happens when every active path has reached END.

What we will build#

A tiny math tutor. It classifies the question, and for arithmetic it drafts an answer, checks it with real Python arithmetic, and loops back with feedback if the draft is wrong. After two failed drafts it stops looping and pauses for a human to supply the answer. Anything that is not arithmetic goes to a chat node.

            START
              |
          [classify]
           /      \
     math /        \ general
         v          v
  +-> [solve]     [chat] ---> END
  |      |
  |   [check]
  |   /   |   \
  +--+    |    \ wrong, attempts >= 2
 wrong,   |     v
 attempts |  [ask_human]   (interrupt: pause the run)
 < 2      |     |
          v     v
          [reply] ---> END

The stub model gets every first draft wrong by one on purpose, so the loop actually runs.

Setup#

LangGraph 1.2 needs Python 3.10 or newer. Install it in a virtual environment:

python3 -m venv .venv
.venv/bin/pip install langgraph pytest

That pulls in langchain-core for the message classes and langgraph-checkpoint for the in-memory checkpointer. You do not need the full langchain package for this post.

Step 1: the model behind an interface#

Nodes should not know which model they call. A one-method protocol keeps the stub and a real model interchangeable:

import operator
import re
from typing import Annotated, Literal, Protocol, TypedDict

from langchain_core.messages import AIMessage, AnyMessage
from langgraph.config import get_stream_writer
from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import add_messages
from langgraph.types import interrupt

MAX_ATTEMPTS = 2

OPS = {"*": operator.mul, "x": operator.mul, "+": operator.add, "-": operator.sub}


def compute(text: str) -> int:
    a, op, b = re.search(r"(\d+)\s*([*x+-])\s*(\d+)", text).groups()
    return OPS[op](int(a), int(b))


class TextModel(Protocol):
    def complete(self, prompt: str) -> str: ...


class StubModel:
    """Deterministic fake. Gets the first math answer wrong on purpose."""

    def __init__(self, always_wrong: bool = False):
        self.calls = 0
        self.always_wrong = always_wrong

    def complete(self, prompt: str) -> str:
        self.calls += 1
        if prompt.startswith("CLASSIFY"):
            return "math" if re.search(r"\d", prompt) else "general"
        if prompt.startswith("SOLVE"):
            right = compute(prompt)
            wrong_try = "FEEDBACK" not in prompt or self.always_wrong
            return str(right + 1 if wrong_try else right)
        return "Happy to chat. Ask me a sum and I will check my own answer."


# A real model goes here instead, for example:
#   from langchain.chat_models import init_chat_model
#   llm = init_chat_model("<provider>:<model-name>")
#   class RealModel:
#       def complete(self, prompt): return llm.invoke(prompt).content
model: TextModel = StubModel()

To use a real model, install langchain plus the provider package and swap in the RealModel class from the comment. init_chat_model takes a provider:model string, so the graph code does not change.

Step 2: state and reducers#

class TutorState(TypedDict, total=False):
    messages: Annotated[list[AnyMessage], add_messages]  # reducer: append
    category: str                                       # no reducer: overwrite
    draft: str
    feedback: str
    attempts: int

Every key has a rule for how updates merge. A key with no annotation uses the default: the new value replaces the old one. When check returns {"feedback": ""}, the old feedback is gone.

messages carries a reducer, the second argument to Annotated. A reducer is a function (old, new) -> merged. add_messages appends new messages to the list, and if a new message has the same ID as an existing one, it replaces that message instead of duplicating it. That is why the reply node can return {"messages": [AIMessage(...)]} with only the one new message.

The reducer matters most when two nodes write the same key in the same super-step. Here is a small graph where nodes a and b both start from START, so they run in parallel, once with a reducer and once without:

import operator
from typing import Annotated, TypedDict
from langgraph.graph import StateGraph, START, END

class Plain(TypedDict):
    notes: list[str]

class Summed(TypedDict):
    notes: Annotated[list[str], operator.add]

def build(schema):
    g = StateGraph(schema)
    g.add_node("a", lambda s: {"notes": ["from a"]})
    g.add_node("b", lambda s: {"notes": ["from b"]})
    g.add_edge(START, "a")
    g.add_edge(START, "b")   # a and b run in the same step
    g.add_edge("a", END)
    g.add_edge("b", END)
    return g.compile()

print(build(Summed).invoke({"notes": ["start"]}))
try:
    build(Plain).invoke({"notes": ["start"]})
except Exception as e:
    print(type(e).__name__, "-", str(e).splitlines()[0])
{'notes': ['start', 'from a', 'from b']}
InvalidUpdateError - At key 'notes': Can receive only one value per step. Use an Annotated key to handle multiple values.

Without a reducer, LangGraph refuses to guess which write wins. If you ever need to bypass a reducer and replace a list outright, langgraph.types.Overwrite exists for that.

Step 3: nodes#

Each node reads what it needs and returns only the keys it changes.

def classify(state: TutorState) -> dict:
    question = state["messages"][-1].content
    return {"category": model.complete(f"CLASSIFY {question}"), "attempts": 0,
            "feedback": ""}


def solve(state: TutorState) -> dict:
    question = state["messages"][-1].content
    prompt = f"SOLVE {question}"
    if state.get("feedback"):
        prompt += f"\nFEEDBACK {state['feedback']}"
    draft = model.complete(prompt)
    get_stream_writer()({"progress": f"attempt {state['attempts'] + 1}: {draft}"})
    return {"draft": draft, "attempts": state["attempts"] + 1}


def check(state: TutorState) -> dict:
    """Verify with code, not with the model."""
    expected = compute(state["messages"][-1].content)
    if state["draft"].strip() == str(expected):
        return {"feedback": ""}
    return {"feedback": f"{state['draft']} is wrong, recompute it"}


def ask_human(state: TutorState) -> dict:
    answer = interrupt({"question": state["messages"][-1].content,
                        "last_draft": state["draft"]})
    return {"draft": str(answer), "feedback": ""}


def reply(state: TutorState) -> dict:
    return {"messages": [AIMessage(state["draft"])]}


def chat(state: TutorState) -> dict:
    text = model.complete(f"CHAT {state['messages'][-1].content}")
    return {"messages": [AIMessage(text)]}

Two details. classify resets attempts and feedback, because with a checkpointer the state from the previous turn on the same thread is still there. Forget that reset and the second question in a conversation starts with stale counters. And check uses arithmetic, not a second model call. When a cheap deterministic check exists, use it; a model judging a model is the fallback for things code cannot verify.

Step 4: edges, conditional edges and the cycle#

Routing functions read state and return the name of the next node. LangGraph reads the Literal return type to learn the possible targets, which is how it draws the graph and validates names. If you skip the type hint, pass a mapping dict as the third argument to add_conditional_edges instead.

def route_category(state: TutorState) -> Literal["solve", "chat"]:
    return "solve" if state["category"] == "math" else "chat"


def route_check(state: TutorState) -> Literal["reply", "solve", "ask_human"]:
    if not state["feedback"]:
        return "reply"
    if state["attempts"] < MAX_ATTEMPTS:
        return "solve"          # the cycle
    return "ask_human"


def build(checkpointer=None):
    g = StateGraph(TutorState)
    for name, fn in [("classify", classify), ("solve", solve), ("check", check),
                     ("ask_human", ask_human), ("reply", reply), ("chat", chat)]:
        g.add_node(name, fn)
    g.add_edge(START, "classify")
    g.add_conditional_edges("classify", route_category)
    g.add_edge("solve", "check")
    g.add_conditional_edges("check", route_check)
    g.add_edge("ask_human", "reply")
    g.add_edge("reply", END)
    g.add_edge("chat", END)
    return g.compile(checkpointer=checkpointer)

The cycle is the "solve" return in route_check: an edge that points back to an earlier node. In a plain script you would write a while loop with a counter and a break. Here the loop is part of the graph, so each pass is checkpointed, streamed and visible in a trace.

Older tutorials use workflow.set_entry_point("categorizer"). It still works, but add_edge(START, ...) is what the current Graph API docs use, and it reads the same as every other edge.

compile() checks the structure (an edge to an unknown node raises ValueError) and returns a runnable object with invoke, stream and the state methods used below.

Step 5: run it with a checkpointer and threads#

The script below (run in the same folder, with the code above saved as tutor.py) makes three calls on one compiled graph.

from langchain_core.messages import HumanMessage
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import Command
import tutor

app = tutor.build(checkpointer=InMemorySaver())

print("== run 1: updates + custom stream, thread t1")
cfg = {"configurable": {"thread_id": "t1"}}
for part in app.stream({"messages": [HumanMessage("What is 55 x 10?")]},
                       cfg, stream_mode=["updates", "custom"], version="v2"):
    data = part["data"]
    if part["type"] == "updates" and "reply" in data:
        data = {"reply": [m.content for m in data["reply"]["messages"]]}
    print(part["type"], data)

print("== run 2: same thread, chat turn")
out = app.invoke({"messages": [HumanMessage("hi there")]}, cfg)
print([f"{m.type}: {m.content}" for m in out["messages"]])

print("== run 3: model always wrong, thread t2")
tutor.model = tutor.StubModel(always_wrong=True)
cfg2 = {"configurable": {"thread_id": "t2"}}
out = app.invoke({"messages": [HumanMessage("What is 12 + 30?")]}, cfg2)
print("interrupt:", out["__interrupt__"])
snap = app.get_state(cfg2)
print("paused before:", snap.next, "| attempts:", snap.values["attempts"])
out = app.invoke(Command(resume=42), cfg2)
print("final:", out["messages"][-1].content)
print("t1 still has", len(app.get_state(cfg).values["messages"]), "messages")
print("t2 checkpoints:", len(list(app.get_state_history(cfg2))))

Real output:

== run 1: updates + custom stream, thread t1
updates {'classify': {'category': 'math', 'attempts': 0, 'feedback': ''}}
custom {'progress': 'attempt 1: 551'}
updates {'solve': {'draft': '551', 'attempts': 1}}
updates {'check': {'feedback': '551 is wrong, recompute it'}}
custom {'progress': 'attempt 2: 550'}
updates {'solve': {'draft': '550', 'attempts': 2}}
updates {'check': {'feedback': ''}}
updates {'reply': ['550']}
== run 2: same thread, chat turn
['human: What is 55 x 10?', 'ai: 550', 'human: hi there', 'ai: Happy to chat. Ask me a sum and I will check my own answer.']
== run 3: model always wrong, thread t2
interrupt: [Interrupt(value={'question': 'What is 12 + 30?', 'last_draft': '43'}, id='2169dd6226d5ddd377d64249ee2b1598', response_schema=None)]
paused before: ('ask_human',) | attempts: 2
final: 42
t1 still has 4 messages
t2 checkpoints: 9

Run 1 shows the cycle. The first draft is 551, check writes feedback, route_check sends control back to solve, the second draft is 550, and the loop exits to reply.

Run 2 shows what a checkpointer buys you. The input was one new message, but the output has four: the graph loaded thread t1's saved state, and add_messages appended to it. A checkpointer saves a snapshot of the state after every super-step, keyed by thread_id. Same thread ID, same conversation. A new thread ID starts empty, and the last line confirms that thread t2's run left t1 untouched at four messages.

InMemorySaver keeps snapshots in RAM, so they vanish when the process exits. The persistence docs point to SqliteSaver (langgraph-checkpoint-sqlite) for local development and PostgresSaver (langgraph-checkpoint-postgres) for production. Thread t2 produced nine checkpoints for one short question, one per super-step plus the input. Long conversations pile these up, and the same docs recommend pruning old checkpoints.

Step 6: interrupts and resuming#

Run 3 forces both drafts to be wrong. After the second failed check, route_check sends control to ask_human, which calls interrupt(...). The run stops, the checkpointer saves the state, and invoke returns with the payload under __interrupt__. get_state shows the graph waiting at ask_human.

To continue, call the graph again on the same thread with Command(resume=42). That value becomes the return value of interrupt() inside the node, the node finishes, and the run carries on to reply.

Per the interrupts docs, on resume the node restarts from its first line, not from the interrupt call. Any code above the interrupt runs twice. If that code sends an email or charges a card, it does so twice. Keep a node that interrupts free of side effects before the pause, or split the side effect into its own node after it.

Interrupts need a checkpointer. Without one there is nowhere to save the paused state, and you must resume with the same thread_id that paused.

The docs now recommend driving interruptible graphs through graph.stream_events(..., version="v3"), which exposes stream.interrupted and stream.interrupts. The invoke form above still works and is easier to read in a first example.

Step 7: streaming modes#

invoke waits for the end. stream yields as the graph runs, and stream_mode picks what you get. The streaming docs list these modes:

Mode What each chunk holds Typical use
values The full state after each step Debugging, simple UIs
updates Only the node name and what it returned Progress logs, cheaper than values
messages Model tokens plus metadata Token-by-token chat output
custom Anything you send with get_stream_writer() Progress bars, tool status
checkpoints An event each time a checkpoint is saved Audit trails
tasks Task start and finish events, with errors Monitoring
debug Everything above, verbose Last resort

Pass a list to get several at once, as run 1 does with ["updates", "custom"]. The custom lines come from get_stream_writer() inside solve. Passing version="v2" (LangGraph 1.1 and later) gives every chunk the same shape, a dict with type and data, whatever modes you pick; without it, a multi-mode stream yields (mode, chunk) tuples. All examples in the current docs use v2.

messages mode emits tokens only from LangChain chat models called inside nodes, so the string stub here produces nothing in that mode. With a real model wired in through init_chat_model, it works with no graph changes.

Step 8: test the graph#

The stub makes the graph deterministic, so plain pytest works. These three tests cover routing, the retry loop and the human handover:

from langchain_core.messages import HumanMessage
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import Command
import tutor


def fresh(always_wrong=False):
    tutor.model = tutor.StubModel(always_wrong=always_wrong)
    return tutor.build(checkpointer=InMemorySaver())


def test_routes_general_to_chat_without_solving():
    app = fresh()
    cfg = {"configurable": {"thread_id": "a"}}
    nodes = [list(u)[0] for u in app.stream(
        {"messages": [HumanMessage("hello")]}, cfg, stream_mode="updates")]
    assert nodes == ["classify", "chat"]


def test_wrong_first_draft_is_retried_and_fixed():
    app = fresh()
    cfg = {"configurable": {"thread_id": "b"}}
    out = app.invoke({"messages": [HumanMessage("7 x 6")]}, cfg)
    assert out["messages"][-1].content == "42"
    assert out["attempts"] == 2


def test_cap_hands_over_to_a_human():
    app = fresh(always_wrong=True)
    cfg = {"configurable": {"thread_id": "c"}}
    out = app.invoke({"messages": [HumanMessage("9 + 1")]}, cfg)
    assert out["__interrupt__"][0].value["last_draft"] == "11"
    assert tutor.model.calls == 1 + tutor.MAX_ATTEMPTS   # classify + solves
    out = app.invoke(Command(resume=10), cfg)
    assert out["messages"][-1].content == "10"
3 passed, 17 warnings in 0.08s

The warnings are a Python 3.15 deprecation inside langsmith, not in this code. The third test also pins the call budget: one classify call plus two solve calls, then a human. With a real model, the same test with a recorded or fake model catches a routing change that would quietly double your token bill.

Failure modes worth knowing#

Uncapped loops run for a long time. The recursion limit caps super-steps per run. Starting in LangGraph 1.1.4 the default is 10,007 super-steps, per the Graph API docs. Override it per run with recursion_limit as a top-level config key, or globally with the LANGGRAPH_DEFAULT_RECURSION_LIMIT environment variable. With the attempt cap removed and the model always wrong, this tutor would make roughly one model call every two super-steps, about 5,000 calls before LangGraph stops it. Here is the same graph with the cap removed and a limit of 12 set per run:

from langchain_core.messages import HumanMessage
from langgraph.errors import GraphRecursionError
import tutor

tutor.MAX_ATTEMPTS = 10**9          # remove the cap
tutor.model = tutor.StubModel(always_wrong=True)
app = tutor.build()
try:
    app.invoke({"messages": [HumanMessage("What is 2 + 2?")]},
               {"recursion_limit": 12})
except GraphRecursionError as e:
    print("GraphRecursionError:", str(e).splitlines()[0])
    print("model calls before the stop:", tutor.model.calls)
GraphRecursionError: Recursion limit of 12 reached without hitting a stop condition. You can increase the limit by setting the `recursion_limit` config key.
model calls before the stop: 7

Keep an attempt counter in state for every loop, and set recursion_limit per run as a backstop sized to your budget.

Stale state on a reused thread. Keys without reducers keep their last value across turns. Reset counters and flags in the first node, as classify does.

A missing reducer on a parallel key raises InvalidUpdateError, shown in step 2.

Side effects before interrupt() run again on resume. Move them after the pause or into a separate node.

Resuming on the wrong thread fails silently. In a quick check, Command(resume=...) on a thread with no pending interrupt raised no error and returned a normal-looking state dict, so a typo in the thread ID looks like success. Store the thread_id with the record the human is approving, and confirm get_state(cfg).next is non-empty before you resume.

InMemorySaver in production. A restart loses every paused run. Use a database-backed checkpointer before anyone waits on an approval.

Where to go next#

The graph here has one path at a time. Real workflows fan out to parallel branches and merge, retry failed nodes, and loop a writer against a reviewer. The workflow automation post builds those on the same primitives, and the local research assistant shows a planner fanning out to researchers with a local model. The quickest next step from this post is to swap StubModel for a real model and watch whether route_check still sends it back to solve as often as you expect.

Sources#