LangGraph Tutorial: Build a Stateful AI Agent in Python, Step by Step

LangGraph describes itself as "a low-level orchestration framework and runtime for long-running, stateful agents." In practice you build a graph:

• State is a schema whose keys are channels. Every node receives the current state.
• Nodes are functions. They return a partial update (only the keys they changed), not the whole state.
• Edges say what runs next. Normal edges are fixed; conditional edges call a routing function and go wherever it returns.
• Reducers decide how an update merges. Without one, a new value overwrites the old one. With operator.add, lists are appended. For chat messages, use add_messages, which appends new messages and updates existing ones by ID.
• A checkpointer saves the state after every step under a thread_id. That single feature gives you memory, pause and resume, human-in-the-loop and crash recovery.

MessagesState is a prebuilt state with one messages key that already uses add_messages. When you need more keys, subclass it or write your own:

import operator
from typing import Annotated, TypedDict

from langchain.messages import AnyMessage
from langgraph.graph.message import add_messages


class State(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]  # append chat messages
    notes: Annotated[list[str], operator.add]            # append strings
    attempts: int                                         # plain overwrite

You must call compile() before you can invoke or stream a graph. Compiling checks the structure and attaches the checkpointer.

You need Python 3.10 or newer (LangGraph's PyPI minimum). Use 3.11+ if you want to run the local dev server and Studio later, because the LangGraph CLI requires it.

We'll use uv, but pip install -U langgraph langchain "langchain[openai]" works the same. langgraph is the runtime. langchain gives you init_chat_model, message classes and the @tool decorator, and the [openai] extra installs the OpenAI integration. LangGraph doesn't require LangChain, but nearly every official example uses it for models and tools, and so do we.

Any provider works. For Anthropic, install "langchain[anthropic]", set ANTHROPIC_API_KEY and use an anthropic:... model string; for Gemini, "langchain[google-genai]" and GOOGLE_API_KEY.

Start with the smallest useful graph: one node that calls the model. init_chat_model takes a provider:model string, so switching providers is a one-line change.

Three things to notice:

• The node returns {"messages": [reply]}, a partial update. Because MessagesState uses the add_messages reducer, the reply is appended to the conversation instead of replacing it.
• START and END are special nodes. Every graph needs an edge out of START.
• You can pass messages as plain dicts. LangGraph converts them to message objects.

Run it with uv run hello.py. The result is the final state, so result["messages"] holds both your question and the model's answer.

Now the real agent: a support agent for an online store with two tools, lookup_order and issue_refund. This is the ReAct pattern (reason, act, observe, repeat), written as a graph:

• bind_tools(tools) tells the model which tools exist, using each function's name, type hints and docstring as the schema.
• ToolNode(tools) is a prebuilt node that runs every tool call in the last AI message and returns the results as ToolMessages.
• tools_condition is a prebuilt routing function: it returns "tools" if the last message has tool calls, and END otherwise. That's why the tool node must be named "tools".
• The edge from "tools" back to "agent" closes the loop. The model sees the tool results and decides whether to call more tools or answer.

Both ToolNode and tools_condition live in langgraph.prebuilt, and unlike create_react_agent they aren't deprecated. If you want to see the loop with no helpers at all, our LangChain vs LangGraph comparison writes the tool node and router by hand.

Save this as agent.py; the next steps import builder from it. The graph is compiled at module level so the dev server in a later section can find it.

Right now every invoke starts from scratch. To make the agent remember a conversation, compile the same builder with a checkpointer and pass a thread_id in the config. LangGraph saves the state after every step under that thread; the next call with the same thread_id loads it first, and a new thread_id starts a fresh conversation.

• InMemorySaver keeps checkpoints in RAM and loses them on restart. Use it for development and tests.
• For production, use a durable saver: PostgresSaver from langgraph.checkpoint.postgres (package langgraph-checkpoint-postgres, with AsyncPostgresSaver for async code) or SqliteSaver (langgraph-checkpoint-sqlite).
• graph.get_state(config) returns a snapshot of the thread, so you can inspect exactly what the agent knows.

A checkpointer is short-term, per-thread memory. For facts that should survive across threads (a user's preferences, say), LangGraph has stores: builder.compile(checkpointer=..., store=InMemoryStore()), read and written from your nodes.

Letting a model issue refunds on its own is a bad idea. LangGraph's answer is interrupt(): call it anywhere in a node or a tool, and the graph saves its state, stops, and returns the payload you passed to it. Your app shows that payload to a human, then resumes the same thread with Command(resume=value). Inside the paused code, interrupt() returns that value.

First, change issue_refund in agent.py so it asks before acting:

from langgraph.types import interrupt


@tool
def issue_refund(order_id: str, amount: float) -> str:
    """Refund part or all of an order, in USD. A human must approve it."""
    decision = interrupt({"action": "issue_refund", "order_id": order_id, "amount": amount})
    if decision != "approve":
        return f"A human reviewer rejected the refund for {order_id}."
    return f"Refunded {amount:.2f} USD for order {order_id}."

Then run the graph with a checkpointer (interrupts need one, and you must resume with the same thread_id). With invoke, a pending interrupt shows up in the result under "__interrupt__".

Three rules from the LangGraph docs that save hours:

1. The node restarts from the beginning on resume. Here the whole tools node runs again, so anything before interrupt() executes twice. Keep side effects (the actual refund API call) after it, or make them idempotent.
2. Don't wrap interrupt() in a bare try/except. It pauses by raising a special exception, and a broad handler swallows it.
3. Keep the order of interrupts deterministic. Resume values are matched to interrupt() calls by position within the node.

For the common case of "approve this tool call", LangChain's create_agent also offers HumanInTheLoopMiddleware. interrupt() is the general version: it works in any node, including mid-workflow review steps that have nothing to do with tools.

Agents are slow, and invoke makes users stare at a blank screen until the end. graph.stream() yields output while the graph runs. The stream_mode argument picks what you get:

• "values": the full state after each step.
• "updates": only what each node changed, as {node_name: update}. Best for progress UIs ("looking up order...").
• "messages": LLM output token by token, as (message_chunk, metadata) tuples. metadata["langgraph_node"] tells you which node produced it. This works even though our node calls model.invoke(), not .stream().
• "custom" (your own events via get_stream_writer), plus "checkpoints", "tasks" and "debug" for tooling.

Pass a list, like stream_mode=["updates", "messages"], and each item becomes a (mode, data) tuple. Since LangGraph 1.1 you can also pass version="v2" to get every chunk as a dict with type, ns and data keys, which is easier to handle when you mix modes. LangGraph 1.2 added an event-streaming API, graph.stream_events(..., version="v3"), which the docs now point new applications to. The classic stream() call below is still the default and works the same as before.

You just built a ReAct agent by hand. For many apps you don't have to. LangGraph v1 deprecated create_react_agent from langgraph.prebuilt; its replacement is LangChain's create_agent, which builds the same model → tools → model loop and returns a compiled LangGraph graph. Checkpointers, thread_id, streaming and interrupts all work the same way. The migration is mostly a rename: create_agent(model, tools, system_prompt=...) instead of create_react_agent(model, tools, prompt=...).

Extra behavior comes from middleware rather than extra nodes: retries, model fallbacks, summarizing long histories, call limits, PII redaction and tool approval (HumanInTheLoopMiddleware).

Rule of thumb: use create_agent when your agent is "a model with tools". Write a StateGraph when you need steps the loop can't express: a fixed validation step, branching by ticket type, parallel research, an approval gate in the middle of a workflow. You can combine them too: a create_agent agent can be one node of a bigger graph.

Studio (now called LangSmith Studio in the docs) is a free visual interface for your graph: you see the nodes, send messages, watch state change step by step, and answer interrupts from the UI. It runs against a local dev server:

1. Install the CLI (it needs Python 3.11+): uv add "langgraph-cli[inmem]".
2. Add a langgraph.json (below) next to agent.py. Each entry in graphs is "./file.py:variable" and points at a compiled graph.
3. Put OPENAI_API_KEY and LANGSMITH_API_KEY in .env. Studio needs a LangSmith account, which is free to sign up for.
4. Run uv run langgraph dev. The API starts at http://127.0.0.1:2024, with API docs at /docs, and the CLI prints a Studio link (https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024). Safari blocks localhost connections; use langgraph dev --tunnel there.

Notice we point the server at graph, compiled without InMemorySaver: the server manages persistence and threads itself.

Deploying. You have three realistic options:

• LangSmith Deployment, LangChain's managed platform for stateful agents.
• Self-hosted Agent Server: langgraph build -t my-image produces a Docker image of the API server. Running it in production needs a LangSmith license key, plus your own Postgres and Redis.
• Plain Python: LangGraph is just a library. Wrap graph in FastAPI (or anything else), compile it with PostgresSaver, and deploy it like any other service. No license needed.

Use LangGraph when control flow is the hard part:

• Your workflow mixes fixed steps and LLM decisions: validate input, let the model plan, run a required approval step, then execute.
• You need branching, loops or parallel steps that don't fit a single model → tools loop.
• You need human approval in the middle of a process, or runs that pause for hours and survive restarts.
• You're building a multi-agent system and want to decide exactly who hands off to whom.

Skip it (or start higher up) when:

• Your agent is a model with a few tools. Use create_agent. See LangChain vs LangGraph for side-by-side code.
• Your problem reads like a team of specialists passing work down a line. CrewAI gets there with less code; see LangGraph vs CrewAI.
• You want type-safe agents with validated structured output and little framework. PydanticAI fits better.

For the full landscape (PydanticAI, CrewAI, OpenAI Agents SDK, Google ADK, Claude Agent SDK, Mastra and more), read our AI agent frameworks guide.

1. Copying a pre-1.0 tutorial. create_react_agent is deprecated, and so are MessageGraph and the old AgentState prebuilts. Custom StateGraph code, checkpointers, interrupt(), Command and Send work unchanged.
2. Returning the whole state from a node. Return only the keys you changed. Returning state["messages"] again through add_messages won't duplicate messages (it updates them by ID), but with operator.add your lists will double.
3. A list key without a reducer. Two nodes writing the same plain key in one step raises an error; give that key a reducer.
4. Forgetting the thread_id. Memory, interrupts and get_state all need {"configurable": {"thread_id": ...}}. Use a stable ID per conversation.
5. Using InMemorySaver in production. Every restart wipes every conversation. Switch to Postgres or SQLite before you ship.
6. Side effects before interrupt(). They run again on resume.

You now have a LangGraph agent with tools, memory, human approval and streaming: the same building blocks production agents use. Where to go next:

• Go deeper on LangGraph with the free LangChain Academy course picked above: subgraphs, map-reduce with Send, time travel and long-term memory with stores.
• Learn the agent fundamentals in a lighter framework with our free 8-lesson PydanticAI course: tools, multi-agent systems, memory, testing and evals, and production deployment. The concepts carry straight back to LangGraph.
• Compare every course worth your time in our best AI agent courses roundup, with free options and certificate details.