LangGraph: stateful agent workflows as graphs
What you’ll learn
Section titled “What you’ll learn”- 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 andCommand(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.
Summary
Section titled “Summary”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.
Context and forces
Section titled “Context and forces”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.
The design: state, nodes, edges
Section titled “The design: state, nodes, edges”| 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.
Running the samples
Section titled “Running the samples”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.
Worked example: a refund workflow
Section titled “Worked example: a refund workflow”
The example domain is refunds for an invented shop, OrdersPortal.
A loop with a conditional exit
Section titled “A loop with a conditional exit”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 exitimport operatorfrom typing import Annotated, Literal, TypedDict
from langgraph.errors import GraphRecursionErrorfrom 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: timeoutcarrier attempt 2: timeoutcarrier attempt 3: returnedrefund issued for A1001stopped: GraphRecursionErrorPoints to take from it:
- The
Literalreturn type onroutetells LangGraph which nodes the conditional edge can reach, so no separate mapping is needed. - The loop is bounded twice: by the
attemptscounter in state (a business rule) and byrecursion_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_LIMITinlanggraph/_internal/_config.py, overridable with theLANGGRAPH_DEFAULT_RECURSION_LIMITenvironment variable, checked inlanggraph1.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.
Pausing for human approval
Section titled “Pausing for human approval”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 checkpointfrom typing import Literal, TypedDict
from langgraph.checkpoint.memory import InMemorySaverfrom langgraph.graph import END, START, StateGraphfrom 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 agentThree rules make this pattern safe:
- A checkpointer and a
thread_idare mandatory. The thread ID is the handle for the paused run; resuming with a different ID starts a new, empty run. - The node restarts from its first line on resume. The value passed to
Command(resume=...)becomes the return value ofinterrupt(), but any code before theinterrupt()call runs a second time. Keep side effects after the interrupt or in a separate node, or make them idempotent. - Payloads must be JSON-serializable, because they are stored and sent to a user interface.
Persistence and memory
Section titled “Persistence and memory”| 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 executedimport osfrom 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.
Multi-agent patterns
Section titled “Multi-agent patterns”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.
Deployment
Section titled “Deployment”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.
Trade-offs and alternatives
Section titled “Trade-offs and alternatives”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 |
Failure modes and operations
Section titled “Failure modes and operations”- Unbounded loops. A router that never reaches
ENDruns until the recursion limit. Put a counter in state and setrecursion_limitexplicitly. - 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.
When not to use it
Section titled “When not to use it”- 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_agentfirst 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.
Interview questions
Section titled “Interview questions”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.
Key takeaways
Section titled “Key takeaways”- 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.
Related pages
Section titled “Related pages”Official references
Section titled “Official references”- LangGraph overview (Python)
- Graph API: state, nodes, edges, recursion limit and the
_config.pysource (default recursion limit) - Interrupts
- Persistence and checkpointers
- Multi-agent patterns
- LangSmith Agent Server and local server
langgraphon PyPI (1.2.22 as of November 2026) and@langchain/langgraphon npm (1.7.4)