If you have ever built an AI agent with a simple while loop — call the model, run the tool, append the result, repeat — you know the pain: the loop loses track after a few steps, a crash wipes out all progress, and there is no clean way for a human to step in before the agent does something irreversible.
LangGraph, an open-source project by the LangChain team, was built to solve exactly this problem. It is a low-level orchestration framework for stateful, long-running agents, and it has become one of the most popular foundations in the agent ecosystem (over 40k GitHub stars, used in production by companies like Klarna, Replit and Elastic).
Problem: why naive agent loops break#
Imagine an agent as a delivery driver who has to complete 20 errands around the city.
- A naive loop is a driver with no notepad. After every errand they must remember everything from memory. Get distracted, and they forget which packages are left. Crash the scooter (an exception, a timeout, a deploy), and the whole day’s work is gone.
- What you actually want is a driver with a clipboard: write down the state after every errand, so anyone can take over, and a supervisor can check the clipboard before a risky delivery.
That is the core insight of LangGraph: the agent’s state is a first-class citizen. The framework persists it, restores it, and lets you inspect and modify it while the agent runs.
Solution: model the agent as a graph#
LangGraph models an agent as a graph over a shared state. Let’s break the concepts down one by one.
1. State — the shared whiteboard#
State is a data structure (a TypedDict or Pydantic model) that flows through the whole graph. Every node can read it and write updates to it:
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph.message import add_messages
class State(TypedDict):
# add_messages is a "reducer": new messages are appended, not overwritten
messages: Annotated[list, add_messages]
query: strpythonThe Annotated[list, add_messages] part is a reducer: it tells LangGraph how to merge updates when multiple nodes write to the same field — append messages, don’t replace them.
2. Nodes — the steps#
A node is just a function that takes the current state and returns a partial update. Crucially, a node can be deterministic Python code (an API call, a validation step) or an LLM call — you mix both in the same graph:
from langgraph.graph import StateGraph, START, END
from langchain.chat_models import init_chat_model
llm = init_chat_model("anthropic:claude-sonnet-4-5")
def chatbot(state: State):
return {"messages": [llm.invoke(state["messages"])]}
graph = StateGraph(State)
graph.add_node("chatbot", chatbot)
graph.add_edge(START, "chatbot")
graph.add_edge("chatbot", END)
app = graph.compile()
app.invoke({"messages": [{"role": "user", "content": "hi!"}]})python3. Edges — the control flow#
- Normal edges (
add_edge) always go from A to B. - Conditional edges (
add_conditional_edges) route dynamically based on the state — this is where the “agent” part lives: the LLM decides whether to call a tool or finish.
The classic agent shape looks like this:
from langgraph.prebuilt import ToolNode, tools_condition
graph.add_conditional_edges("chatbot", tools_condition) # LLM decides
graph.add_node("tools", ToolNode(my_tools))
graph.add_edge("tools", "chatbot") # loop backpython4. Checkpointer — durable execution#
This is LangGraph’s superpower. Add a checkpointer and the graph saves state after every step:
from langgraph.checkpoint.memory import InMemorySaver
checkpointer = InMemorySaver() # use a DB-backed one in production
app = graph.compile(checkpointer=checkpointer)
app.invoke(
{"messages": [{"role": "user", "content": "hi!"}]},
config={"configurable": {"thread_id": "user-123"}},
)pythonThe thread_id identifies one conversation. If the process crashes mid-run, you re-invoke with the same thread ID and it resumes from the last checkpoint — the clipboard survives the scooter crash.
5. Interrupt — human-in-the-loop#
With persistence in place, pausing for human approval becomes trivial:
app.invoke(input, config, interrupt_before=["tools"])pythonThe graph stops right before the tools node, a human inspects (and can edit) the state, then resumes. This is essential for any agent that can send emails, execute code, or spend money.
Why this design wins#
| Capability | What LangGraph gives you |
|---|---|
| Durable execution | Persist through failures, resume long-running tasks |
| Human-in-the-loop | Inspect/modify agent state before risky steps |
| Memory | Short-term working memory + long-term cross-session persistence |
| Mixed logic | Deterministic code and LLM steps in one auditable graph |
| Observability | LangSmith tracing of every node and state transition |
Because the whole agent is a graph, you can visualize it, replay it, and debug it step by step — things a tangled while loop can never offer.
[!TIP] If you don’t want to wire graphs by hand, LangChain ships prebuilt agents (
create_react_agent) on top of LangGraph, and a higher-level Deep Agents package for agents that plan, use subagents and file systems. Start there, drop down to raw LangGraph when you need custom control flow.
When should you use it?#
Good fit: multi-step agents that call tools, need approval workflows, run for minutes/hours, or must survive restarts — customer support bots, coding agents, research pipelines.
Overkill: single-shot Q&A or simple RAG chains with no tool calls. A plain LLM call or a small chain is simpler; LangGraph shines exactly when state, loops and reliability start to matter.
Practical Examples#
A realistic customer-support agent graph:
Every box is one small, testable function; the checkpointer means a deployment in the middle of the day doesn’t destroy in-flight conversations. That combination — small pieces plus durable state — is what makes agents production-ready.