LangGraph: Stateful Agent Framework Guide

LangGraph is a low-level Python framework from LangChain Inc for building agents that keep state, run for a long time, pause for a human and resume after a failure. The library is MIT-licensed and installs with pip install -U langgraph. Hosted tracing and deployment run through LangSmith, which starts free. Checked 31 October 2026.

At a glance

What LangGraph is

The README calls it a "low-level orchestration framework for building, managing, and deploying long-running, stateful agents." Low-level is the keyword. It does not hand you a ready-made "researcher" or "coder" agent. It gives you the plumbing that a serious agent needs and leaves the design to you.

The plumbing comes from the README's own list:

• Durable execution. Agents persist through failures and resume from where they stopped.
• Human-in-the-loop. You can inspect and change agent state at any point.
• Memory. Short-term working memory for a run and long-term memory across sessions.
• Debugging. Visual traces through LangSmith.
• Deployment. A managed platform for long-running, stateful workflows.

The README names Klarna, Replit and Elastic as users. We take that as the vendor's claim.

The design owes something to older ideas. The acknowledgements say it is inspired by Pregel and Apache Beam, with an interface that draws on NetworkX. That tells you what to expect: you describe a graph, and the runtime walks it.

How it works

A LangGraph program has three parts.

1. State. A typed structure that every step can read and update. For chat agents the docs provide MessagesState, a list of messages.
2. Nodes. Plain functions that take the state and return updates. A node can call a model, call a tool, or run ordinary code.
3. Edges. Rules that say which node runs next. Edges can be fixed or conditional, so the model's output can choose the path.

You then compile the graph and invoke it. The docs' hello-world builds a StateGraph(MessagesState), adds a node, connects it with add_edge between START and END, compiles it, and runs graph.invoke with a user message. The node there is a mock model, so it runs without a key.

A rough sketch of the shape, simplified from the docs:

from langgraph.graph import StateGraph, MessagesState, START, END

def my_node(state: MessagesState):
    # call a model or tool here and return a state update
    return {"messages": [{"role": "assistant", "content": "hello"}]}

graph = StateGraph(MessagesState)
graph.add_node("my_node", my_node)
graph.add_edge(START, "my_node")
graph.add_edge("my_node", END)
app = graph.compile()

app.invoke({"messages": [{"role": "user", "content": "hi!"}]})

Treat that as an outline of the API, not a tested program. The exact current signatures are in the quickstart.

Why a graph and not a loop

A plain agent loop (call the model, run the tool, repeat) is fine for simple tasks. It gets hard when you want to:

• stop and ask a person before a risky step
• retry only one failed step, not the whole run
• run two branches in parallel and merge them
• let an agent sleep for a day and continue
• inspect exactly what state existed at step seven

A graph makes each of those a named place in the program. That is the case for LangGraph, and also its cost: you write more structure up front.

The LangChain family

Four names get confused, so here is how the docs relate them.

If you want an agent quickly, start with create_agent or Deep Agents. If you want to control every step, use LangGraph directly. The README itself points to Deep Agents for building agents quickly.

Install and first run

pip install -U langgraph
# or
uv add langgraph

The overview page does not state a minimum Python version.

You will also need a model package for whichever provider you use, plus its API key. LangGraph does not bundle a model. Because it is vendor neutral, you can connect to Claude, OpenAI, Gemini or a local model through LangChain's integrations or your own client.

What it costs

The library is free. The money question is LangSmith, the tracing and deployment service from the same company. From its pricing page on 31 October 2026:

Base traces are kept 14 days; extended traces are kept 180 days for an extra fee. Extra deployments are billed in LSUs, where 1 LSU is $1: for example 0.0675 LSU per vCPU-hour of runtime compute and 0.0090 LSU per GiB-hour of runtime memory. Database compute and memory are billed separately.

You do not have to use LangSmith. You can run LangGraph on your own server and trace with another tool. The hosted route buys you the deployment platform and a debugging UI.

Your model bill is separate and usually the larger one. See LLM API prices.

What it does well

• Control. Every branch is explicit. When something goes wrong you know which node did it.
• Durability. Resuming after a crash is a core feature, not a plug-in.
• Human approvals. Interrupts are first-class, which suits finance, support and anything touching production.
• Model neutrality. MIT license, any provider.
• Ecosystem. Tracing, evals and a deployment platform exist if you want them.

Limits and honest cautions

• More code for simple jobs. A one-prompt task does not need a graph.
• Learning curve. State reducers, checkpointers and conditional edges take time to feel natural.
• Tied to one company's ecosystem. The MIT license lets you leave, but the nicest tooling is LangSmith.
• Fast change. The repo ships frequently; version 1.2.19 landed on the day we checked. Pin versions in production.
• No coding-agent features. It is a framework for building agents, not a ready tool like Claude Code. For that, see AI coding agents.

MCP and tools

LangGraph agents call tools as ordinary functions. Connecting to MCP servers is possible through adapter packages in the LangChain ecosystem. For the protocol itself, see what are MCP servers and MCP vs API.

LangGraph versus the others

The full field is in AI agent frameworks and agentic AI frameworks.

Who should pick it

Pick LangGraph if:

• your agent runs for minutes to days and must survive restarts
• a human must approve steps
• you want to test and replay specific states
• your team writes Python and wants to see the control flow

Skip it if you want a drag-and-drop tool (see AI agent platforms), if your task is one prompt and a tool call, or if you only need a coding assistant.

A realistic first project

The best first LangGraph project is small and has a human in it. A support-triage agent is a good example, and it matches the shapes the README stresses.

1. Intake node. Takes the incoming ticket text and puts it in state.
2. Classify node. Asks a model for a category and a confidence.
3. Conditional edge. Routes billing tickets one way, bugs another, and low-confidence tickets to a person.
4. Draft node. Writes a reply using a knowledge lookup tool.
5. Interrupt. Pauses so a human can edit or approve the draft.
6. Send node. Posts the approved reply.

Every step above is a place where a plain loop would be awkward. The pause in step five can last hours, and durable execution means the run resumes from there rather than starting again. You can also test the classify node alone with a fixed set of tickets, which is hard when everything is one long prompt. Our guide to building a support triage agent covers the same flow without a framework, so you can compare the two.

Keep the first version to four or five nodes. Add tracing before you add features, so every run is visible from day one. Then write down the three inputs that fooled it and keep them as regression cases.

Moving in and out

Because LangGraph state is plain typed data and nodes are plain functions, the code you write is mostly your own logic. That makes leaving easier than with a framework that owns the prompts. If you outgrow it, the nodes can be lifted into another runtime. If you arrive from AutoGen, which Microsoft has archived, note that Microsoft points new users to its own Agent Framework; LangGraph is a separate path and not a drop-in.

Moving in from a hand-written loop is the common case. Keep the loop's functions, put them in nodes, and add the checkpointing last. Do it one step at a time and run the old and new versions against the same test inputs.

Testing a LangGraph agent

Because each node is a plain function, graphs are easier to test than one long prompt.

• Unit test nodes. Pass a hand-built state to a node and assert on the returned update. No model call is needed for nodes that run ordinary code.
• Stub the model. Replace the model client with a fixed response to test routing: given this classification, does the conditional edge pick the right branch?
• Replay failures. Keep the state that triggered a bad run and feed it back through the graph after a fix.
• Run a fixed task set. Thirty real inputs with expected outcomes, run after every prompt change.
• Check the pause. Test that an interrupt really stops the run and that resuming continues from the right node.

Deployment choices

You can run a compiled graph inside your own web service, on a queue worker for long jobs, or on the LangSmith deployment platform. The first two keep everything under your control and need a database for saved state. The third adds a managed runtime at the prices listed above. Start with the simplest option that survives a restart.

Finally, read the changelog before each upgrade. A fast-moving library can change import paths or defaults between minor releases, and a saved graph state from an old version may not load in a new one. Test an upgrade on a copy of your data first.

Our take

This is an editorial reading of the repository, docs and pricing page, not a hands-on test.

LangGraph is the framework to learn when you are serious about reliability. The reasons are stated in its own README: durable execution, interrupts and memory are the hard parts of agents, and it makes them primitives. The trade is that you write the structure yourself.

A sensible path is to start one level up. Use create_agent or a simple loop to find out what your agent needs. When you catch yourself building retry logic, approval steps or state saving by hand, drop to LangGraph. Keep the LangSmith question separate: you can adopt the library and ignore the paid service.

The main risk is not technical. It is churn. An active repo with frequent releases rewards teams that pin versions and read changelogs.

Checklist

• Decide if a plain loop is enough before adopting a graph
• Install with pip install -U langgraph in a virtual environment
• Define your state type first, then the nodes
• Add a human approval step before any risky tool
• Choose how you will trace: LangSmith or another tool
• Pin the LangGraph version in your lock file
• Re-check the LangSmith pricing page before you subscribe