Preface

This is a book about LangGraph¹, the low-level framework for wiring language models into graphs you control. It builds the AI agent one part at a time — a state, a node, an edge, a loop — until you can see where the model’s decisions enter and where your code keeps the guardrails.

The method is build, run, observe, fix. Every chapter is built around a single runnable example. You can read the code on the page, but you are meant to run it, break it, and watch what happens. Prose can look correct and be wrong; a graph that runs shows you what it actually does.

Where this book came from

This book didn’t start as a book. It began as a pile of exercises — a self-taught tour through LangGraph, one small runnable program at a time, alongside a growing notebook of questions, dead ends, and the occasional oh, that’s why it works that way. Stage by stage, the notes outgrew their purpose, and turning them into chapters is what turned a working familiarity into something closer to understanding.

Much of what is sharp in these pages got sharp because writing a claim down made it fall apart, and I had to go run the code to find the truth.

Modern AI tooling is what made that pace realistic. An assistant won’t understand the framework for you. It will throw up scaffolding in minutes, let you try three designs in an afternoon, and — the underrated part — let you ask the questions that feel too dumb to ask a person, with no ego and no waiting. That is a new way to learn something hard, fast: build a little, poke at it, ask the naive question, run it, watch it break, ask again. As the Great Carmack put it:

Convince yourself that you can learn anything deeply, even though you can’t know everything.

— John Carmack, Lex Fridman Podcast #309

It is the same loop the book runs on, turned on your own understanding instead of on the code.

How this book is organized

The book climbs in three parts, each raising the stakes. First you build the machine — with no model in it. Then you give it a real LLM to decide with. Then you build the mechanisms it takes to run one in production.

Part I — Building Graphs teaches the core primitives. By the end you can build a working document-answering bot with branching, loops, tools, persistence, and human approval — with no language model in sight. Part I is self-contained: finish it and you can build real graphs.

Part II — Empowering Graphs with LLMs is where the examples meet a real model: structured output and its failure modes, tool-calling, typed state schemas, the Functional API, multi-agent supervisors, memory across turns, and streaming. That is the point where a graph stops being a hard-coded machine and starts making decisions of its own.

Part III — Graphs in Production is what it takes to run one for real: error handling and retries, serving over HTTP, observability, external tools over MCP, the internals of persistence, and a full retrieval-augmented generation (RAG) pipeline with evaluation.

That is the whole of this book. What the vocabulary is for — a coding agent, a debugging agent, each taken apart and rebuilt from these pieces — is a series of small books that follows it, one agent each. You can subscribe to the mailing list to hear about this book’s major updates and about each new book in the series as it comes out.

This online edition is a beta book in the old sense: every paragraph, code block and figure takes a comment. Hover beside one and click the mark that appears (on a phone, the marks follow you down the page). What you write goes to the author and to no one else, and the text you commented on travels with it, so a note still lands after the paragraph has been rewritten.

What this book does not cover

Out of scope, so you know where the edges are:

Hosted deployment — LangSmith Cloud, Hybrid, Standalone (langgraph.json), and Studio. 22 Serving over HTTP serves a graph over plain HTTP, which is what a platform automates. (LangSmith tracing itself is not out of scope — 23 Observability builds a tracer by hand and then shows the hosted one in LangSmith: the tracer you don’t write.)
deepagents — a harness on top of create_agent.
Generative UI and frontends — useStream, React streaming.
LangGraph.js — the concepts map one-to-one; the syntax differs.
Async at scale — full-async graphs, checkpointer concurrency, rate limiting.

Conventions

Code is Python 3.11+, tested on Python 3.11 with LangGraph 1.2.11. The 3.11 floor is the book’s, not LangGraph’s. The book’s State schemas use typing.NotRequired; LangGraph itself requires only 3.10+. Each example is a single self-contained file. The complete, runnable versions live in the companion repository — github.com/LgISP/langgraph-in-small-pieces — one runnable program per chapter under code/, a few of them spanning several files, with pinned dependencies and the end-of-chapter Challenge solutions under code/answers/.
If you are reading this some time after it was written, assume the library has moved. Install the companion’s requirements.txt into a virtual environment of its own and run the book against that, not against whatever pip install langgraph gives you today; the versions are frozen and dated in the Colophon. Where a later release changes something the book shows — a renamed parameter, a default that moved, a deprecation warning on an import — the companion’s COMPATIBILITY.md is where it is recorded, and a DeprecationWarning in your terminal is the cue to look there before you change the code.
Callout boxes flag three things:

Deep Dive

An internal detail or a sharper mental model. Skippable on a first read, valuable on the second.

Gotcha

A mistake that will bite you. These are almost always things the author hit by running the code, not by reading the docs.

Try it

A small change to make and re-run, so the lesson sticks.

Most chapters end with a Challenge, graded by how far it takes you from the chapter: 🥉 Bronze checks a claim the chapter made, usually by breaking something and reading the failure; 🥈 Silver extends the chapter’s code into a case it did not cover; 🥇 Gold, which many chapters carry, takes the idea past where the chapter stopped, and is open-ended enough to be a small project. Most come with a worked solution under code/answers/; a few are self-verifying by design, and say so.

Where this book sits

The LangChain docs offer three tiers for building agents. Deep Agents is the batteries-included harness — planning, sub-agents, file tools, ready to go. create_agent, in the langchain package, is a minimal, configurable harness: a model, some tools, and middleware hooks. LangGraph is the layer under both, for when you need fine-grained control and want to mix deterministic steps with agentic ones. This book teaches the bottom tier. create_agent compiles to exactly the StateGraph + ToolNode loop you will wire by hand in Part II, and The whole loop in one line: create_agent shows the seam, where the hand-built loop and the one-liner meet.

One thing before we start: LangGraph is not LangChain

Same team, similar names — and the confusion is nearly universal. Here is the distinction, once, so it never gets in your way again. The short version is the one that matters for reading on: you do not need prior LangChain experience. The few pieces this book imports from it are introduced where the examples use them.

Deep Dive: LangGraph vs. LangChain

LangGraph is the low-level library for stateful, branching, looping, multi-step control — in a word, agents. It is the subject of this book.

LangChain today means two things. Since LangChain 1.0 the langchain package is an agent harness, create_agent plus middleware, and it is built on LangGraph: langchain 1.3 requires langgraph, and what create_agent returns is a compiled LangGraph graph with two nodes, model and tools. The original toolkit (chains, LCEL, prompt templates, output parsers, document loaders) lives on as a separate package, langchain-classic. Both rest on the same foundation, langchain-core, which holds the message types and the BaseChatModel interface.

So LangGraph does not depend on LangChain; the reverse is now true. Inside a graph you’ll still freely import a model class (ChatOpenAI, from langchain-openai) and the message types (from langchain-core). You do not need to know LangChain to follow along: we pull in the few pieces we need and explain each one where it appears.

The one thing to unlearn: LangChain’s old AgentExecutor. It now lives in langchain-classic; LangGraph is the recommended way to build agents, and it’s what we use throughout.

Drawn as a dependency picture, the relationship is a short stack: everything rests on one shared base, LangGraph sits directly on it, and the langchain harness sits on LangGraph.

flowchart TB
    core["langchain-core<br/>messages · BaseChatModel · tool specs · Runnable"]
    lg["langgraph<br/>StateGraph · nodes · edges · loops<br/>checkpointers · prebuilt ToolNode"]
    lc["langchain<br/>create_agent · middleware"]
    da["deepagents<br/>planning · sub-agents · file tools"]
    classic["langchain-classic<br/>chains · LCEL · prompt templates · parsers"]
    prov["Provider packages<br/>langchain-openai, langchain-anthropic, …<br/>ChatOpenAI · embeddings"]
    app["Your graph<br/>(the agent you build here)"]

    lg --> core
    lc --> lg
    da --> lc
    classic --> core
    prov --> core
    app -. "builds on" .-> lg
    app -. "imports ChatOpenAI" .-> prov
    app -. "imports messages" .-> core

First a working environment, then the smallest possible graph.

Official documentation: https://docs.langchain.com/oss/python/langgraph; API reference: https://reference.langchain.com/python/langgraph.↩︎