What is LangGraph?
The LangGraph docs describe it as "a low-level orchestration framework and runtime for long-running, stateful agents". In plain words: you draw your agent as a graph. Each box is a Python function. Each arrow says which function runs next. One shared dictionary, the state, travels along the arrows and every function can read it and add to it.
Think of a metro map. The stations are your functions (LangGraph calls them nodes). The lines between stations are edges. Some stations are junctions where the train picks a line based on what it is carrying: those are conditional edges. And the train can go round a loop as many times as it needs before it reaches the last stop.
That loop is the reason LangGraph exists. An AI agent is a model that calls a tool, reads the result, and decides whether to call another tool. A plain Python while loop can do that, and our tool calling guide builds one. LangGraph adds what a bare loop does not give you for free: memory saved between calls, pausing for a human and resuming later, a hard stop on runaway loops, and a step-by-step stream of what happened.
LangGraph is open source under the MIT licence. It installs with pip install -U langgraph. We used version 1.2.24, released on PyPI on 20 November 2026, on Python 3.12.
LangGraph vs LangChain
This is the most common question, so here it is first. They come from the same company and do different jobs.
| LangChain | LangGraph | |
|---|---|---|
| What it is | Building blocks: one interface for many models, tools, prompts, retrievers, and a ready-made agent (create_agent) | The runtime that runs steps in order: state, nodes, edges, loops, checkpoints, interrupts |
| You write | Configuration: pick a model, a list of tools, a prompt | The control flow itself: which step runs after which, and when to stop |
| Best for | A standard tool-calling agent, quickly | Custom flows: approval steps, branches, retries, several agents, long-running jobs |
| Needs the other? | Its agents are built on LangGraph | No: "LangGraph does not require LangChain" |
In this guide we use one small piece of LangChain, langchain-core, for the message and tool classes, because LangGraph's prebuilt message state uses them. You could use plain dictionaries instead.
Our rule of thumb: start with a plain loop or LangChain's create_agent. Move to your own LangGraph graph when you need a step the standard agent does not have, such as "pause here until a manager approves".
The five ideas you need
- State. A typed dictionary that every node can read. Nodes do not change it directly. They return a small dictionary of updates.
- Nodes. Plain Python functions: state in, updates out. Add them with
add_node. - Edges.
add_edge(a, b)always goes from a to b.add_conditional_edgescalls your function to choose the next node.STARTandENDare the entry and the exit. - Reducers. Rules for merging an update into the state. With no reducer, the new value replaces the old one. With
operator.addon a list, new items are appended. Chat history usesadd_messages. - Compile.
compile()checks the graph and turns it into something you caninvokeorstream. This is also where you plug in a checkpointer for memory.
LangGraph runs the graph in super-steps, in the style of Google's Pregel system. In each super-step, every node that is due runs. Their updates are merged into the state, and with a checkpointer, a snapshot of the state is saved. That snapshot is what makes memory, pausing and resuming possible.
Step 1: your first graph, no model needed
Before any AI, here is a graph that sorts a support ticket. It has two nodes in a line. Notice the two fields in the state: category has no reducer, so it is replaced; log uses operator.add, so each node's entry is appended.
hello_graph.py
# hello_graph.py: the smallest useful LangGraph, no model needed.
import operator
from typing import Annotated, TypedDict
from langgraph.graph import StateGraph, START, END
class State(TypedDict):
ticket: str
category: str # no reducer: a new value replaces the old one
log: Annotated[list[str], operator.add] # reducer: new items are appended
def classify(state: State) -> dict:
text = state["ticket"].lower()
category = "refund" if "refund" in text or "money back" in text else "other"
return {"category": category, "log": [f"classify -> {category}"]}
def reply(state: State) -> dict:
return {"log": [f"reply for a {state['category']} ticket"]}
builder = StateGraph(State)
builder.add_node("classify", classify)
builder.add_node("reply", reply)
builder.add_edge(START, "classify")
builder.add_edge("classify", "reply")
builder.add_edge("reply", END)
graph = builder.compile()
result = graph.invoke({"ticket": "I want my money back for order A1042", "log": []})
print(result)
print(graph.get_graph().draw_mermaid())
Output
{'ticket': 'I want my money back for order A1042', 'category': 'refund', 'log': ['classify -> refund', 'reply for a refund ticket']}
---
config:
flowchart:
curve: linear
---
graph TD;
__start__([<p>__start__</p>]):::first
classify(classify)
reply(reply)
__end__([<p>__end__</p>]):::last
__start__ --> classify;
classify --> reply;
reply --> __end__;
classDef default fill:#f2f0ff,line-height:1.2
classDef first fill-opacity:0
classDef last fill:#bfb6fc
Two things to see. The log list holds both entries because its reducer appends: without Annotated[..., operator.add] the second node's entry would have replaced the first. And draw_mermaid() prints the graph as Mermaid text, which you can paste into any Mermaid viewer to see the boxes and arrows. It is the quickest way to check that you wired what you meant.
Step 2: build an agent as a graph
Now the real thing: a support agent for a made-up shop. The graph has two nodes. model asks the language model what to do. tools runs whatever tools the model asked for. After model, a conditional edge looks at the model's last message: if it asked for a tool, go to tools; if not, the answer is ready, so go to END. After tools, always go back to model.
First, the shop. Two tools: one reads an order, one pays a refund. The refund tool calls interrupt(), which we will use in Step 4; ignore it for now.
shop.py
# shop.py: a made-up shop with two tools. The data is fake so every answer can be checked.
from langchain_core.tools import tool
from langgraph.types import interrupt
ORDERS = {
"A1042": {"item": "Noise-cancelling headphones", "price_inr": 15999, "status": "shipped", "eta": "2026-11-24"},
"A1043": {"item": "USB-C charger", "price_inr": 1499, "status": "delivered", "eta": "2026-11-18"},
}
@tool
def get_order(order_id: str) -> dict:
"""Look up an order by its ID, for example A1042. Returns item, price, status and delivery date."""
return ORDERS.get(order_id.upper(), {"error": f"no order {order_id}"})
@tool
def issue_refund(order_id: str, amount_inr: int) -> str:
"""Refund money for an order. A human must approve every refund before it is paid."""
print(f" issue_refund started for {order_id}") # runs again on resume: see below
decision = interrupt({"action": "refund", "order_id": order_id, "amount_inr": amount_inr})
if not decision.get("approved"):
return f"Refund for {order_id} was NOT approved by a human. Do not promise one."
return f"Refunded INR {amount_inr} for {order_id}."
TOOLS = [get_order, issue_refund]
Next, the graph. MessagesState is LangGraph's prebuilt state: a single messages list whose reducer, add_messages, appends each new message to the history. The whole agent is three small functions and five lines of wiring.
agent_graph.py
# agent_graph.py: an agent as a graph: model -> (tools -> model)* -> end.
from langchain_core.messages import SystemMessage, ToolMessage
from langgraph.graph import StateGraph, MessagesState, START, END
from shop import TOOLS
TOOLS_BY_NAME = {t.name: t for t in TOOLS}
SYSTEM = SystemMessage("You are the support agent of an online shop. Use the tools for order facts. Today is 2026-11-20.")
def build(model, checkpointer=None):
def call_model(state: MessagesState) -> dict:
reply = model.invoke([SYSTEM] + state["messages"])
return {"messages": [reply]} # add_messages appends it to the history
def run_tools(state: MessagesState) -> dict:
results = []
for call in state["messages"][-1].tool_calls:
output = TOOLS_BY_NAME[call["name"]].invoke(call["args"])
results.append(ToolMessage(content=str(output), tool_call_id=call["id"]))
return {"messages": results}
def route(state: MessagesState) -> str:
return "tools" if state["messages"][-1].tool_calls else END
builder = StateGraph(MessagesState)
builder.add_node("model", call_model)
builder.add_node("tools", run_tools)
builder.add_edge(START, "model")
builder.add_conditional_edges("model", route, ["tools", END])
builder.add_edge("tools", "model")
return builder.compile(checkpointer=checkpointer)
A scripted model, so you can run this for free
To keep every output on this page exact and repeatable, we do not call a live model here. We use FakeMessagesListChatModel from langchain-core, which returns a list of replies you write, in order. It behaves like a model that always makes the same choices. That is exactly what you want when you are learning the graph, and later when you write tests for it.
scripted.py
# scripted.py: a stand-in model that replies with a fixed list of messages, in order.
# It keeps this tutorial free and repeatable. A real model is a one-line swap (see the guide).
from langchain_core.language_models.fake_chat_models import FakeMessagesListChatModel
from langchain_core.messages import AIMessage
def call(name, args, n):
return {"name": name, "args": args, "id": f"call_{n}", "type": "tool_call"}
def scripted(*replies):
return FakeMessagesListChatModel(responses=list(replies))
run_agent.py
# run_agent.py: watch the graph loop, one super-step at a time.
from langchain_core.messages import AIMessage
from agent_graph import build
from scripted import scripted, call
model = scripted(
AIMessage("", tool_calls=[call("get_order", {"order_id": "A1042"}, 1)]),
AIMessage("Your headphones (order A1042) have shipped and should arrive on 24 November 2026."),
)
graph = build(model)
question = {"messages": [("user", "Where is my order A1042?")]}
for step in graph.stream(question, stream_mode="updates"):
for node, update in step.items():
msg = update["messages"][-1]
print(f"[{node}] {msg.type}: {getattr(msg, 'tool_calls', None) or msg.content}")
Output
[model] ai: [{'name': 'get_order', 'args': {'order_id': 'A1042'}, 'id': 'call_1', 'type': 'tool_call'}]
[tools] tool: {'item': 'Noise-cancelling headphones', 'price_inr': 15999, 'status': 'shipped', 'eta': '2026-11-24'}
[model] ai: Your headphones (order A1042) have shipped and should arrive on 24 November 2026.
stream_mode="updates" prints what each node returned, one super-step at a time. You can see the loop run once: the model asks for get_order, the tools node runs it and returns the real order data, and the model answers with no tool call, so the conditional edge sends the graph to END.
Swapping in a real model is one line. Any LangChain chat model that supports tool calling works, for example ChatOllama(model="qwen2.5:3b").bind_tools(TOOLS) from langchain-ollama for a free local model, or the OpenAI, Anthropic or Google packages. bind_tools sends the tools' names, descriptions and argument schemas to the model on every call. The graph does not change at all. A real model will not always make the scripted choices, which is why the next steps matter: in our tool calling guide, a free 3B model picked the right tool 15 times out of 15 and the right arguments 14 times.
Step 3: memory with a checkpointer and thread_id
A compiled graph forgets everything after invoke returns. To remember a conversation, compile it with a checkpointer and pass a thread_id on every call. The checkpointer saves a snapshot of the state after each super-step, filed under that thread. Same thread, same memory. New thread, clean slate.
memory.py
# memory.py: a checkpointer + thread_id gives the graph memory between calls.
from langchain_core.messages import AIMessage
from langgraph.checkpoint.memory import InMemorySaver
from agent_graph import build
from scripted import scripted, call
model = scripted(
AIMessage("", tool_calls=[call("get_order", {"order_id": "A1042"}, 1)]),
AIMessage("Order A1042 has shipped."),
AIMessage("", tool_calls=[call("get_order", {"order_id": "A1042"}, 2)]), # turn 2: id taken from history
AIMessage("It should arrive on 24 November 2026."),
AIMessage("Which order do you mean? Please share the order ID."),
)
graph = build(model, checkpointer=InMemorySaver())
alice = {"configurable": {"thread_id": "alice"}}
bob = {"configurable": {"thread_id": "bob"}}
graph.invoke({"messages": [("user", "Is order A1042 shipped?")]}, alice)
graph.invoke({"messages": [("user", "When will it arrive?")]}, alice)
graph.invoke({"messages": [("user", "When will it arrive?")]}, bob)
for name, cfg in [("alice", alice), ("bob", bob)]:
state = graph.get_state(cfg)
history = list(graph.get_state_history(cfg))
print(f"{name}: {len(state.values['messages'])} messages, {len(history)} checkpoints")
print(" last reply:", state.values["messages"][-1].content)
Output
alice: 8 messages, 10 checkpoints
last reply: It should arrive on 24 November 2026.
bob: 2 messages, 3 checkpoints
last reply: Which order do you mean? Please share the order ID.
Alice's thread holds all 8 messages from both turns (her question, the tool call, the tool result and the answer, twice), saved as 10 checkpoints you can list with get_state_history. On her second turn the model is sent that whole history, which is how a real model can tell that "it" means order A1042; here our scripted reply plays that part. Bob asked the same words on a new thread and his state has just 2 messages: his question and the reply. The reply texts are scripted; the message counts are the proof that the two threads are separate.
InMemorySaver keeps the snapshots in RAM, so they vanish when the process stops. For a real app, use a database-backed saver: SqliteSaver from the langgraph-checkpoint-sqlite package for local work, or PostgresSaver from langgraph-checkpoint-postgres in production. The graph code stays the same.
Step 4: pause for a human before a refund
Some actions should never happen on the model's word alone: paying money, deleting data, sending an email. LangGraph's answer is interrupt(). Call it inside a node and the graph stops, saves its state through the checkpointer and hands you the value you passed in. Later, maybe minutes later, from another server, you resume it with Command(resume=...), and interrupt() returns that value. Our issue_refund tool in shop.py already does this.
approval.py
# approval.py: pause before a refund, let a human decide, then resume.
from langchain_core.messages import AIMessage
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import Command
from agent_graph import build
from scripted import scripted, call
def ask_for_refund(thread):
model = scripted(
AIMessage("", tool_calls=[call("issue_refund", {"order_id": "A1042", "amount_inr": 15999}, 1)]),
AIMessage("Done: see the tool result above."),
)
graph = build(model, checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": thread}}
result = graph.invoke({"messages": [("user", "Refund order A1042, it arrived broken.")]}, config)
return graph, config, result
for approved in (False, True):
graph, config, result = ask_for_refund(f"refund-{approved}")
print("paused:", result["__interrupt__"][0].value)
print("next node:", graph.get_state(config).next)
result = graph.invoke(Command(resume={"approved": approved}), config)
tool_msg = result["messages"][-2]
print(f"human said approved={approved} -> {tool_msg.content}\n")
Output
issue_refund started for A1042
paused: {'action': 'refund', 'order_id': 'A1042', 'amount_inr': 15999}
next node: ('tools',)
issue_refund started for A1042
human said approved=False -> Refund for A1042 was NOT approved by a human. Do not promise one.
issue_refund started for A1042
paused: {'action': 'refund', 'order_id': 'A1042', 'amount_inr': 15999}
next node: ('tools',)
issue_refund started for A1042
human said approved=True -> Refunded INR 15999 for A1042.
The first invoke did not finish. It returned early with __interrupt__ holding the refund request, and get_state shows the graph waiting at the tools node. Whatever the human decides goes back in through Command(resume=...), and the tool reads it as the return value of interrupt(). When the answer was no, no money moved: the refund line after interrupt() never ran, and the model got "NOT approved" as the tool result. The model could still word its reply badly, so check replies too, but the payment itself is gated by your code, not by the prompt, and no model output can get past it.
The rule that catches everyone: on resume, LangGraph does not continue from the line where it paused. It runs the whole node again from the top, and this time interrupt() returns the human's answer instead of pausing. Look at the output: "issue_refund started" is printed twice for each refund. So anything before interrupt() runs twice. Keep it free of side effects: never charge a card, write to a database or send a message before the interrupt. Do the real work after it.
Interrupts need a checkpointer and a thread_id, because the paused state has to be stored somewhere. Without them, there is nothing to resume.
Step 5: the recursion limit (and why old tutorials say 25)
A model can get stuck calling tools forever. LangGraph stops any run that takes too many super-steps and raises GraphRecursionError. Here is a graph with a loop and no exit, run once with a limit of 25 and once with the default.
recursion.py
# recursion.py: a graph that never reaches END is stopped by the recursion limit.
from typing import TypedDict
from langgraph.errors import GraphRecursionError
from langgraph.graph import StateGraph, START
class State(TypedDict):
steps: int
def think(state: State) -> dict:
return {"steps": state["steps"] + 1}
builder = StateGraph(State)
builder.add_node("think", think)
builder.add_edge(START, "think")
builder.add_edge("think", "think") # a loop with no way out
graph = builder.compile()
for config in ({"recursion_limit": 25}, {}):
try:
graph.invoke({"steps": 0}, config)
except GraphRecursionError as err:
print(str(err).splitlines()[0])
Output
Recursion limit of 25 reached without hitting a stop condition. You can increase the limit by setting the `recursion_limit` config key.
Recursion limit of 10007 reached without hitting a stop condition. You can increase the limit by setting the `recursion_limit` config key.
With no limit set, LangGraph 1.2.24 stopped this loop after 10,007 super-steps, not 25. That is a recent change. We read the source of past releases: up to version 1.0.5 (December 2025) the default was 25, which is the number most older tutorials quote. Version 1.0.6 (12 January 2026) raised it to 10,000, and the docs say it has been 10,007 since 1.1.4. LangChain's create_agent sets its own limit of 9,999 steps. So on current versions, a looping agent will not be stopped early by default.
Set the limit yourself, as a top-level key in the config (not under configurable): graph.invoke(inputs, {"recursion_limit": 25}). For a support agent, a few dozen steps is plenty. A runaway agent that makes ten thousand model calls is a large bill, not a feature.
When not to use LangGraph
- One model call is enough. Summarise, classify, extract: call the model API directly. A graph adds nothing.
- A standard tool loop. A plain
whileloop is about 30 lines (our tool calling guide has one), and LangChain'screate_agentgives you the same loop on top of LangGraph with less code. - You need your own control flow, state and pauses. This is where LangGraph earns its place: approval steps, branches, retries, several agents passing work, jobs that run for hours and must survive a crash.
Honest limits
- We used a scripted model. It proves how the graph runs, not how well a model behaves inside it. A real model will sometimes call the wrong tool, pass a bad argument or never stop. Test with your real model, and add the checks from our tool calling guide.
- The API moves fast. LangGraph 1.2.24 came out on the day we wrote this. The default recursion limit has changed twice since December 2025. Pin your versions and re-read the docs when you upgrade.
- More moving parts. A graph is easier to extend than a loop, and harder to read at first. For a three-step agent, it can be more framework than you need.
- In-memory checkpoints disappear.
InMemorySaveris for learning and tests. Paused approvals and chat history are lost on restart unless you use a database saver.
Frequently asked questions
What is LangGraph used for?
LangGraph is used to build AI agents and multi-step AI workflows where you control the flow: which step runs next, when to loop, when to stop, when to wait for a person. Typical uses are support agents with approval steps, research agents that loop over tools, and systems where several agents pass work to each other.
What is the difference between LangChain and LangGraph?
LangChain gives you building blocks (one interface for many models, tools, prompts and a ready-made agent called create_agent). LangGraph is the lower-level runtime that runs steps as a graph with state, loops, checkpoints and interrupts. LangChain's agents are built on LangGraph, but LangGraph does not require LangChain.
Is LangGraph free?
Yes. The LangGraph library is open source under the MIT licence and installs with pip install -U langgraph. You pay only for the model you call, and you can avoid that by using a free local model through Ollama, or a scripted test model as this tutorial does.
What is the default recursion limit in LangGraph?
In LangGraph 1.2.24, the default is 10,007 super-steps; our run hit exactly that. It was 25 up to version 1.0.5, which is why older tutorials say 25, and 10,000 from version 1.0.6 (January 2026). Set your own with graph.invoke(inputs, {"recursion_limit": 25}).
How does memory work in LangGraph?
Compile the graph with a checkpointer and pass a thread_id in config["configurable"] on every call. The checkpointer saves the state after each super-step under that thread, so the next call on the same thread continues from it. InMemorySaver is for learning; use SqliteSaver or PostgresSaver to keep memory across restarts.
What is human in the loop in LangGraph?
It means pausing the graph so a person can approve or edit something before it continues. Call interrupt() inside a node: the graph saves its state and returns the value you passed. Resume it with Command(resume=answer). On resume, the whole node runs again from the top, so keep side effects after the interrupt() call.
Crio AI Engineering
Build agents that work outside a demo
Crio's AI Engineering program is project-first: you build LLM apps, RAG pipelines and tool-using agents, then learn to evaluate, secure and ship them. Talk to the team about whether it fits you.
Sources
- LangGraph overview (what it is, "LangGraph does not require LangChain") · LangChain
- LangGraph Graph API: StateGraph, nodes, edges, reducers, super-steps, recursion limit · LangChain
- LangGraph persistence: checkpointers, InMemorySaver, SqliteSaver, PostgresSaver · LangChain
- LangGraph checkpointers: thread_id, get_state, get_state_history · LangChain
- LangGraph interrupts: interrupt(), Command(resume=...), rules of interrupts · LangChain
- LangChain agents: create_agent (recursion limit 9,999) · LangChain
- langgraph on PyPI (1.2.24, 20 November 2026; MIT; Python 3.10+) · PyPI
- langgraph source code on GitHub · GitHub
All code on this page was run on 20 November 2026 with Python 3.12.8, langgraph 1.2.24, langgraph-checkpoint 4.3.2 and langchain-core 1.8.4, and every Output block is the real output. The model is scripted (FakeMessagesListChatModel), so the model's replies are written by us; the graph, tools, checkpoints, interrupts and limits are LangGraph's real behaviour. The shop and orders are invented. The recursion-limit history was read from the langgraph 1.0.5 and 1.0.6 release files on PyPI and the Graph API docs on 20 November 2026.
Last updated: