Skip to content

LangGraph: stateful agent workflows as graphs

  • How LangGraph represents a workflow as shared state, nodes and edges, and why that suits agents.
  • How to build a loop with a conditional exit, and how to bound it.
  • How interrupt() pauses a run for a human decision and Command(resume=...) continues it.
  • What checkpointers and stores persist, and which to use in production.
  • When a graph runtime is more machinery than the problem needs.

LangGraph is an open-source orchestration framework and runtime from the LangChain team for long-running, stateful agents. You describe a workflow as a graph: a typed state object, nodes (functions that read state and return updates) and edges (which node runs next, possibly decided at run time). The runtime adds what agent workflows need and plain function calls lack: cycles, durable checkpoints, pause-and-resume for human review, and streaming.

LangGraph does not require LangChain and does not prescribe prompts or agent designs. LangChain’s create_agent is itself a LangGraph graph, so the two are layers of one stack rather than competitors.

A simple LLM feature is a straight line: prompt in, answer out. Agent workflows are not:

  • They loop. Write code, run tests, fix, run again. Call a tool, read the result, decide what to call next.
  • They branch on results that are only known at run time.
  • They wait. A refund over a threshold needs a person’s approval, which may arrive tomorrow.
  • They fail midway. A process restart after step six should not repeat steps one to five, especially if step four charged a card.
  • They need to be inspected. When a run goes wrong you need to see the state at each step.

You can build all of this by hand with a while loop, a database table and a job queue. LangGraph is that machinery, already built and tested.

Concept What it is
State A typed schema (usually a TypedDict) shared by the whole graph. Each key can have a reducer that says how updates merge; without one, a new value replaces the old.
Node A function that receives the current state and returns a partial update. It can call a model, a tool, or ordinary code.
Edge A fixed link from one node to the next. START and END mark entry and exit.
Conditional edge A routing function that inspects state and returns the name of the next node. This is how branches and loops are expressed.
Command A return value that combines a state update with a routing decision (goto), for nodes that both change state and choose the next step.
Super-step One round of node execution. The recursion limit counts these.
Checkpointer Saves the state after each super-step under a thread_id, enabling resume, human review and replay.
Store Key-value storage for long-term memory shared across threads.

Nodes return only the keys they change. That, together with reducers, is what lets several nodes contribute to the same state safely.

The samples were run with Python 3.11 and langgraph 1.2.22 (pip install langgraph; it requires Python 3.10 or later). They use deterministic functions instead of model calls, so they need no API key. Save each as a .py file and run it with python. In a real workflow, a node would call a chat model at the points marked as simulated.

LangGraph refund workflow: a check_carrier node retries until the parcel is returned, then routes to issue_refund after human approval, or to escalate after five attempts; shared state is saved by a checkpointer after every step.

The example domain is refunds for an invented shop, OrdersPortal.

Before refunding, the workflow asks the carrier whether the parcel came back. The carrier API is unreliable, so the node is retried, and after too many failures the case goes to a person.

# lg_loop.py - a graph with a retry loop and a conditional exit
import operator
from typing import Annotated, Literal, TypedDict
from langgraph.errors import GraphRecursionError
from langgraph.graph import END, START, StateGraph
class RefundState(TypedDict):
order_id: str
attempts: int
carrier_status: str
log: Annotated[list[str], operator.add] # reducer: updates are appended, not replaced
def check_carrier(state: RefundState) -> dict:
"""Ask the carrier whether the parcel was returned. Simulated: succeeds on the third try."""
attempt = state["attempts"] + 1
status = "returned" if attempt >= 3 else "timeout"
return {"attempts": attempt, "carrier_status": status, "log": [f"carrier attempt {attempt}: {status}"]}
def issue_refund(state: RefundState) -> dict:
return {"log": [f"refund issued for {state['order_id']}"]}
def escalate(state: RefundState) -> dict:
return {"log": ["carrier unreachable: sent to a support agent"]}
def route(state: RefundState) -> Literal["issue_refund", "check_carrier", "escalate"]:
if state["carrier_status"] == "returned":
return "issue_refund"
if state["attempts"] >= 5:
return "escalate"
return "check_carrier" # loop back
builder = StateGraph(RefundState)
builder.add_node("check_carrier", check_carrier)
builder.add_node("issue_refund", issue_refund)
builder.add_node("escalate", escalate)
builder.add_edge(START, "check_carrier")
builder.add_conditional_edges("check_carrier", route)
builder.add_edge("issue_refund", END)
builder.add_edge("escalate", END)
graph = builder.compile()
result = graph.invoke({"order_id": "A1001", "attempts": 0, "carrier_status": "", "log": []})
print("\n".join(result["log"]))
try:
graph.invoke(
{"order_id": "A1001", "attempts": 0, "carrier_status": "", "log": []},
{"recursion_limit": 2}, # top-level config key, not under "configurable"
)
except GraphRecursionError as error:
print("stopped:", type(error).__name__)

Output:

carrier attempt 1: timeout
carrier attempt 2: timeout
carrier attempt 3: returned
refund issued for A1001
stopped: GraphRecursionError

Points to take from it:

  • The Literal return type on route tells LangGraph which nodes the conditional edge can reach, so no separate mapping is needed.
  • The loop is bounded twice: by the attempts counter in state (a business rule) and by recursion_limit (a safety net). Do not rely on the default limit as your bound. The LangGraph docs give the default as 10,007 super-steps from version 1.1.4, and the source confirms it (DEFAULT_RECURSION_LIMIT in langgraph/_internal/_config.py, overridable with the LANGGRAPH_DEFAULT_RECURSION_LIMIT environment variable, checked in langgraph 1.2.22). That is far more model calls than you want to pay for by accident, so set the limit explicitly on every run.
  • graph.get_graph().draw_mermaid() returns a Mermaid diagram of the compiled graph, which is useful in code review.

Refunds above 50 need a support agent’s approval. interrupt() stops the run inside the node and hands a payload to the caller. The checkpointer keeps the state until someone answers.

# lg_approval.py - pause for a human decision, then resume from the checkpoint
from typing import Literal, TypedDict
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import END, START, StateGraph
from langgraph.types import Command, interrupt
class RefundState(TypedDict):
order_id: str
amount: float
decision: str
def review(state: RefundState) -> Command[Literal["pay", "reject"]]:
if state["amount"] <= 50:
return Command(update={"decision": "auto-approved"}, goto="pay")
# Execution stops here. The payload is returned to the caller.
approved = interrupt({"question": "Approve refund?", "order_id": state["order_id"], "amount": state["amount"]})
if approved:
return Command(update={"decision": "approved by agent"}, goto="pay")
return Command(update={"decision": "rejected by agent"}, goto="reject")
def pay(state: RefundState) -> dict:
print(f" paying {state['amount']:.2f} for {state['order_id']}")
return {}
def reject(state: RefundState) -> dict:
print(f" no payment for {state['order_id']}")
return {}
builder = StateGraph(RefundState)
builder.add_node("review", review)
builder.add_node("pay", pay)
builder.add_node("reject", reject)
builder.add_edge(START, "review")
builder.add_edge("pay", END)
builder.add_edge("reject", END)
graph = builder.compile(checkpointer=InMemorySaver()) # a checkpointer is required for interrupt()
config = {"configurable": {"thread_id": "refund-A1002"}}
print("first call:")
paused = graph.invoke({"order_id": "A1002", "amount": 180.0, "decision": ""}, config)
print(" waiting on:", paused["__interrupt__"][0].value)
print(" next node:", graph.get_state(config).next)
print("resume with the agent's answer:")
final = graph.invoke(Command(resume=True), config)
print(" decision:", final["decision"])

Output:

first call:
waiting on: {'question': 'Approve refund?', 'order_id': 'A1002', 'amount': 180.0}
next node: ('review',)
resume with the agent's answer:
paying 180.00 for A1002
decision: approved by agent

Three rules make this pattern safe:

  1. A checkpointer and a thread_id are mandatory. The thread ID is the handle for the paused run; resuming with a different ID starts a new, empty run.
  2. The node restarts from its first line on resume. The value passed to Command(resume=...) becomes the return value of interrupt(), but any code before the interrupt() call runs a second time. Keep side effects after the interrupt or in a separate node, or make them idempotent.
  3. Payloads must be JSON-serializable, because they are stored and sent to a user interface.
Checkpointer Package Use
InMemorySaver included with langgraph Tests and experiments; state is lost when the process exits
SqliteSaver langgraph-checkpoint-sqlite Local, single-process workflows
PostgresSaver langgraph-checkpoint-postgres Production
# Fragment: requires a PostgreSQL database; not executed
import os
from langgraph.checkpoint.postgres import PostgresSaver
with PostgresSaver.from_conn_string(os.environ["CHECKPOINT_DB_URL"]) as checkpointer:
checkpointer.setup() # creates the tables on first use
graph = builder.compile(checkpointer=checkpointer)

A checkpointer is short-term, per-thread memory: conversation continuity, human-in-the-loop, recovery after a crash, and “time travel” (replaying from an earlier checkpoint for debugging). A store is the separate, long-term memory that spans threads, such as customer preferences. Checkpoints contain whatever is in your state, including customer data, so apply the same retention, access control and encryption rules as for any other database; LangGraph supports an encrypted serializer for checkpoints.

A graph node can be another agent, which is how multi-agent systems are composed. The LangChain docs describe several patterns; the most used are:

  • Subagents (supervisor): a main agent calls specialist agents as tools and all routing passes through it. Easiest to reason about and to trace.
  • Handoffs: the active agent changes based on state, and a tool call transfers control. Suits conversations that move between departments.
  • Router: a classification step sends the input to one or more specialists and combines the results.

Each extra agent multiplies model calls and adds places for context to be lost. Start with one agent and a good set of tools, and split only when a single prompt can no longer hold the instructions or tool list.

A compiled graph is an ordinary Python object: you can call it from a web service or a worker you run yourself, with a Postgres checkpointer for durability. The LangChain team also offers LangSmith Agent Server (previously named LangSmith Deployment; older articles call it LangGraph Platform), a hosted or self-hosted runtime with task queues, streaming endpoints and the Studio debugging UI. pip install "langgraph-cli[inmem]" and langgraph dev start a local in-memory server for development (not executed for this page). Check current licensing and pricing on the LangSmith site before depending on the managed option.

Seen from LangGraph, each alternative trades away explicit control of the graph for something simpler, or swaps the LLM-specific runtime for a general one.

If you choose instead You gain over LangGraph You give up from LangGraph Choose it when
Plain code with a loop No dependency, the easiest debugging Checkpoints, resume after a crash, interrupts, streaming of intermediate state Short, synchronous workflows with no pauses
LangChain create_agent A working tool loop in a few lines, plus middleware; it still runs on LangGraph Custom control flow: the loop shape is fixed A standard tool-calling agent
CrewAI Role and task abstractions that read like a team plan Control of each transition and of the state shape Role-based multi-agent pipelines
A workflow engine (Temporal, AWS Step Functions) Mature durable execution and operations tooling Message state, token streaming and LLM-oriented interrupts built in The organization already runs one and the LLM step is a small part
  • Unbounded loops. A router that never reaches END runs until the recursion limit. Put a counter in state and set recursion_limit explicitly.
  • Replayed side effects. Resume re-runs the interrupted node, and crash recovery re-runs the failed step. Payments, emails and tickets need idempotency keys.
  • State bloat. Appending every message and tool result makes each checkpoint larger and each model call costlier. Trim or summarize, and keep large documents outside the state.
  • In-memory checkpointer in production. Paused approvals disappear on restart. Use a database-backed saver.
  • Schema changes with runs in flight. A paused thread holds state in the old shape. Add keys with defaults and keep old node names routable until old threads finish.
  • Reducer mistakes. Forgetting a reducer on a list means the last writer wins and earlier entries vanish; adding one by accident duplicates data.
  • Parallel branches writing the same key without a reducer raise an update conflict.
  • Opaque runs. Without tracing you cannot tell which node chose badly. Stream updates in development and record traces in production.
  • The flow is a straight line. A function that calls a model is simpler than a three-node graph.
  • The steps are fully deterministic. Use a normal workflow engine or job queue.
  • A prebuilt agent loop is enough. Reach for create_agent first and drop down to LangGraph when you need custom control flow.
  • Nobody needs resume, approval or replay. Those features are the reason to accept the extra concepts.

1. How do nodes share data, and what is a reducer? All nodes read one state object and return partial updates. Each key may declare a reducer, a function that merges an update into the current value, for example operator.add to append to a list. Without a reducer the update overwrites the key.

2. What happens when a node calls interrupt()? The runtime saves a checkpoint, stops the run and returns the interrupt payload to the caller. Later, Command(resume=value) with the same thread_id restarts that node from its beginning, and interrupt() returns value. That is why code before the interrupt must be idempotent.

3. How do you stop an agent graph from looping forever? Track attempts in state and route to an exit when a budget is spent; set recursion_limit in the run config as a hard stop and catch GraphRecursionError; and add token or cost limits at the model layer. One bound is a business rule, the other is a safety net.

4. Senior scenario: a refund workflow paid a customer twice after a deployment restarted the workers. What went wrong and how do you redesign it? The payment ran in a step that was re-executed, either because the node also contained an interrupt or because the process died after paying and before the checkpoint was written. Redesign: isolate the payment in its own node placed after the approval, send an idempotency key derived from the thread ID and order ID so the payment provider rejects duplicates, record the payment reference in state, and make the node check for an existing reference first. Use a durable checkpointer, drain workers before deploys, and add a reconciliation job that compares payments with workflow state.

5. Senior scenario: the team wants five specialist agents under a supervisor for customer support. How do you evaluate that? Ask what one agent with the right tools cannot do. Measure a single-agent baseline on a graded set of real tickets first. Split out a specialist only where instructions conflict or the tool list is too long for reliable selection. If a supervisor is justified, keep routing in one place, pass each specialist only the context it needs, cap total model calls per ticket, and trace every handoff. Compare quality, latency and cost per ticket against the baseline before shipping.

  • LangGraph is a runtime for workflows that loop, branch, wait and resume.
  • State plus reducers is the contract between nodes.
  • Bound loops in state and with an explicit recursion_limit.
  • interrupt() needs a checkpointer and a thread ID, and the node re-runs on resume.
  • Use a database-backed checkpointer and idempotent side effects in production.
  • Prefer the simplest layer that works: plain code, then create_agent, then a custom graph.