00

How to read this manual

This manual explains the LangChain Python stack at one pin, and every listing in it comes from a capture of a real run that you can check yourself.

Who this manual is for

You write Python and you have called a chat model API. You have seen LangChain code, maybe from the 0.x years, with chains, AgentExecutor, and langchain_community imports. Today pip install langchain on Python 3.11 gives you version 1.5.0, and most of that code no longer imports.

This manual is for the engineer who must decide if the 1.x stack fits, and then build on it. It starts with that decision, measured on a task suite with local and Claude models. Each part then opens with a position that our runs support, and most parts end with a small program that applies it.

Four projects share the LangChain name: LangChain, LangGraph, LangSmith, and Deep Agents. Their packages have their own version numbers. So this manual names the package with each version, such as langchain 1.5.0 and langchain-core 1.8.0. Section 1.1 says what each project does.

What you can do after this manual

  • Install the stack from a lockfile on Python 3.11 or later, and say which package each import comes from.
  • Build an agent with create_agent, and predict each model call, tool call, and checkpoint of a run.
  • Choose a structured output strategy and a set of middleware, and predict the order in which their hooks run.
  • Stream a run in the mode you need, and keep a conversation across turns and restarts with a checkpointer.
  • Pause a run for human approval, resume it, and say which code runs again on the resume.
  • Count the attempts of each retry layer, and make a side effect safe when a crash replays it.
  • Connect MCP tools, a retriever, Deep Agents, and LangSmith tracing, and find the cause of a failure from its message.
  • Serve an agent from FastAPI with Postgres, approvals, spans, and evals, and size it from the model server.

How this manual was made

We pinned the stack at the langchain 1.5.0 release of 2026-11-11 and checked every fact again on 2026-11-14. We read the source code of each package at its tag. We read the documentation at one commit of its repository, and we ran what both of them say.

PackageVersionCommit
langchain1.5.0c2f4036e
langchain-core1.8.0a4b4a7b9, the same libs/core tree as c2f4036e
langgraph1.2.2208a20169
langgraph-checkpoint, langgraph-prebuilt4.3.2, 1.1.208a20169
langgraph-checkpoint-sqlite3.1.35bd231cb
deepagents0.7.38c858b364
langsmith0.14.1715dd2a78
langchain-openai, langchain-anthropic, langchain-ollama1.8.0, 1.7.10, 1.1.0their own tags

The sources have a rank. When two of them disagree, the higher one wins, and the section says so.

RankSourceWhat the manual takes from itCited as
1The source code at the tags aboveevery class, parameter, default, and error textcode
2The documentation at docs.langchain.com, built from commit 04d4d4a of its repository, MIT licensethe documented behaviour, in our own wordsdocs
3The changelog and the release notes of each packagewhen a change came, and in which packagedocs for the changelog page, code for a release
4The capture kit in capture/every listingthe file name
5The lab recordings in capture/lab/every measured numberthe file name

GitHub issues and pull requests are evidence for a behaviour at the pin, and the text names each one by its number. The product pages at www.langchain.com have no open license. Section 1.1 states their claims in our words and sets each one beside our result.

The documentation site serves its main branch, and no docs tag matches a package release. A page can describe a newer or an older behaviour than the pin. Where a page and the code disagree, the code wins, and the section shows both.

The capture kit and the lab

Capture kit: the program in capture/ that drives the stack in one Python process and writes what it sees to capture/out/. It covers LangChain, LangGraph, Deep Agents, langchain.mcp, and the LangSmith SDK.

The kit uses no fake chat model. Where a scenario needs a model, it calls Qwen3 4B Instruct, qwen3:4b-instruct-2507-q4_K_M, through ChatOllama. The settings are temperature 0, seed 42, num_ctx 16384, and num_predict 512. We recorded those captures on the x86 server guest, on CPU, on 2026-11-14. Each file names its model, its settings, the machine, and the date.

The other captures call no model, such as the versions, the messages, the graph structure, and the store. They run offline with no keys, and they give the same bytes on every run. The kit masks values that change on every run, such as message ids and the timings in each reply. A real model answers in its own words. So a listing shows what the model did on our run, even where the prompt asked for more.

Lab recording: a run against a real model or a real database on one of our machines, kept as raw files in capture/lab/. capture/run.py computes a summary of each data set into capture/lab/summary/, and each chart reads one summary.

We recorded on two machines. The Mac is an Apple M1 Max with 10 cores and 64 GiB, with Ollama and PostgreSQL 14. The x86 server guest has 32 vCPU and 48 GiB, with PostgreSQL 16, Redis 7, and Ollama 0.31.1 on CPU. The two machines differ, so this manual never sets a number from one beside a number from the other.

The Mac is a shared laptop, and other work ran on it during every timed run. Read each time from the Mac as an upper bound for that machine. The local models of the lab were Qwen3 0.6B, 1.7B, 4B, 8B, 14B, and 30B-A3B, and gpt-oss 20B, on Ollama, with nomic-embed-text for embeddings. The capture kit used Qwen3 4B Instruct on the x86 server guest. So did the failure drill of section 8.7 and the crash matrix of section 5.3. So did the lab runs T05, T07, T08, T11, T17, T18, and T19.

Task-suite bench: the 99 tasks of section 1.2, each checked by the state that its tools leave. Claude Haiku 5.5 (claude-haiku-5-5) and Claude Sonnet 5.5 (claude-sonnet-5-5) ran through the Anthropic API from the Mac. The budget had a cap, and every call is in a cost ledger. The bench method gives the tasks, the settings, and the rows not to use.

Claude Haiku 5.5 also ran the 20 evals of the production service in section 9.6, with every call in the same kind of ledger. It also ran 60 attacks on the file rules of section 8.4, for $0.021. The rule matrix of that section has no model. A scripted caller drives the permission layer, and the section says so. Every other model time in this manual is the time of a local model.

Conventions

  • A citation such as {{docs oss/python/langchain/models}} stays in the source of a section and renders nothing. The reader view shows no file paths.
  • Every source is stated in our own words. Quote marks hold only literal strings, such as output and error text.
  • A citation with the key docs names the page path at docs.langchain.com, read at docs commit 04d4d4a.
  • A listing is cut from one capture file. … on its own line marks lines we cut, and the note under the title says what.
  • <uuid-1>, <hex-1>, and <time> in a listing are masks. The same token means the same value inside one file.
  • A paragraph that starts with We measured names the machine and the number of runs. Its numbers come from one summary file.
  • A run is one call of invoke or stream. A step is one superstep of the LangGraph loop. A turn is one human message and everything up to the reply.

A first run, offline

You need Python 3.13 for the kit, because the captures were made with it. The stack itself needs Python 3.11 or later. From the manual directory, create the virtual environment and run the check:

bash
python3.13 -m venv capture/.venv
capture/.venv/bin/pip install -r capture/requirements.txt
python3 capture/run.py --check

The check runs the 19 model-free scenarios again into a temporary folder and compares each file with capture/out/. It checks that each of the 36 recorded files names its model. It also checks the structure that the manual relies on, such as the message types and the tool names. It then rebuilds the lab summaries from the raw recordings and compares them too. It does not call a model, so it prints one skipped: line for the recorded scenarios. python3 capture/run.py --check --live records them again when Ollama runs on your machine.

This is the scenario behind section 1.3. It builds an agent with one tool and a system prompt, and it asks one question:

pythonthe agent of the first runFull log
def agent_run(cap):
    m = llm()
    agent = create_agent(m, tools=[add], system_prompt="You add numbers.")
    out = agent.invoke(ASK)
The scenario function from the kit. llm(), the add tool, and ASK come from capture/common.py.

llm() builds ChatOllama on Qwen3 4B with the settings above. The model called add with 2 and 3 and then said the sum. The run ended with four messages:

jsonthe messages at the end of the first runFull log
    "type": "HumanMessage",
    "content": "What is 2 + 3?",
…
    "type": "AIMessage",
    "content": "",
…
    "type": "ToolMessage",
    "content": "5",
…
    "type": "AIMessage",
    "content": "2 + 3 = 5.",
Each message is cut to its type and content. The ids and the tool call are cut.

To use another model, pass a model string such as "openai:gpt-4.1" in place of m, and install the provider package. Section 3.2 shows how the string resolves.

How the parts are ordered

Part 1 is the decision. It sets each project and its claims beside our results, compares harnesses on the task suite, and follows one agent run to the last checkpoint. Part 2 goes inside the runtime: supersteps, channels, the checkpoint write path, interrupts, streams, and checkpoint growth, from traces of real runs. Part 3 installs the stack and explains the model, the messages, the tools, and the prompt.

Part 4 is the agent that create_agent builds: its graph, structured output on each provider, many tools, and middleware. Part 5 is state, memory, and durability: streams, checkpointers, crashes, stores, long threads, and serialization. Part 6 is LangGraph control flow: state and reducers, Send and Command, the functional API, interrupts, approvals, time travel, subgraphs, and error handlers.

Part 7 connects retrieval, MCP, Deep Agents, and LangSmith. Part 8 operates and debugs: Agent Server, Agent Chat UI, cost, security, migration from 0.x, symptoms, a failure drill, and the limits at the pin. Part 9 builds one production service end to end, with FastAPI, Postgres, approvals, OpenTelemetry spans, faults, evals, and several workers. It runs that service on Qwen3 4B, Qwen3 14B, and Claude Haiku 5.5. The table below lists every part:

PartWhat it covers
1 · The decisionWhat the four projects claim, beside our runs. Then a harness shoot-out on a task suite with five local models and two Claude models. Then one create_agent run from invoke to the last checkpoint.
2 · Inside the runtimeSupersteps and channel versions, colliding writes, and the checkpoint write path. Then interrupt and resume in the code, where each stream mode comes from, and checkpoint growth, all traced on real model runs.
3 · Models, messages, and toolsThe package map and the install, init_chat_model and model profiles, messages and content blocks, tools with ToolRuntime and their errors, and the system prompt.
4 · The agent, structured output, and middlewareThe graph that create_agent builds, and which structured output strategy works on which provider. Then many tools and the tool selector, middleware hooks and their order, the built-in classes, retries, and guardrails. Last, a SQL agent with approved writes.
5 · State, memory, and durabilityStream modes and stream_events v3, checkpointers and threads, durability modes and crashes, stores, summarization and long threads, serialization, and an assistant that survives a restart.
6 · LangGraph control flowStateGraph and reducers, Send and Command, and the functional API. Then interrupts, human review, time travel, subgraphs, and the error handlers and limits of a node.
7 · EcosystemRetrievers and vector stores, a retrieval agent, and MCP tools through langchain.mcp. Then Deep Agents 0.7 measured on the task suite, a deep agent with a subagent, LangSmith tracing, and evaluation.
8 · OperateAgent Server under langgraph dev, up, and deploy, Agent Chat UI in front of it, and the cost of each layer. Then security, with the file rules of Deep Agents, migration from 0.x, a table of symptoms, a failure drill, and the limits of this edition.
9 · ProductionOne FastAPI service with create_agent, Postgres, and approvals, run on Qwen3 4B, Qwen3 14B, and Claude Haiku 5.5. The run endpoint and its stream, the owner check, and approvals with an idempotency key. Then OpenTelemetry spans with LangSmith off, faults and shutdown, evals that check state, and workers and cost.
R · ReferenceLookup tables for create_agent, middleware, streams, persistence, environment variables, and errors. Then a glossary, the sources and conflicts, the figure index, how the manual was made, and the method of the task-suite bench.

Each section ends with a short list of actions. Read those first when you need an answer today. Read the rest when you want the reason.

Four lessons go deeper into the ideas that this manual applies. The LangGraph state machines lesson and the stateful graphs lesson build graphs from first principles. The agent framework tradeoffs lesson compares frameworks. The durable execution lesson explains checkpoints and replay. This manual stays with LangChain.

Colour in figures

Each hue keeps one meaning in every figure:

violetyour code: the caller, its input, and its config
blueLangChain: create_agent, middleware, messages, and tools as objects
indigoLangGraph: the graph, its nodes, the Pregel loop, and its streams
plumthe chat model and each model call
greentools and the results they return
oliveservices outside the process: providers, LangSmith, Ollama
amberlifecycle: steps, next nodes, interrupts, and resumes
tealdurable state: checkpoints, stores, and their rows
rosefailure: exceptions, error messages, and repeated side effects
greyoutside LangChain: Python, packages, the machine, and the operator

Figure 0.1 teaches the arrow styles with exchanges from our captures. A solid arrow is a call, and a dashed arrow in the same ink is its reply. The other six styles each mark one kind of event, and the colour of the arrow matches the table above.

Fig. 0.1reading a sequence figure in this manualsequence
Reading a sequence figure in this manual Six lifelines: your code, the agent graph from create_agent, the chat model Qwen3 4B on Ollama, a tool, the checkpointer, and LangSmith outside the process. Eight numbered rows use the eight arrow styles: invoke with What is 2 + 3? as a solid ink call, the system prompt You add numbers. as a solid plum model call, the tool call add with a=2 and b=3 as a dashed ink reply, checkpoint step 1 as a solid teal durable write, next tools as a dashed amber state change, the custom stream value lookup A-17 as a dotted indigo stream, seven POST /runs requests as a dashed olive outside effect, and RuntimeError disk on fire as a dashed rose failure. your code agent.invoke agent graph create_agent chat model Qwen3 4B tool add, flaky_disk checkpointer InMemorySaver LangSmith outside 1 invoke: What is 2 + 3? a call · solid ink 2 system: You add numbers. a model call · solid plum 3 tool_calls: add(a=2, b=3) a reply · dashed ink 4 checkpoint step 1 a durable write · solid teal 5 next: tools a state change · dashed amber 6 custom: lookup A-17 a stream · dotted indigo 7 POST /runs, 7 times an outside effect · dashed olive 8 RuntimeError: disk on fire a failure · dashed rose
Each arrow style marks one kind of exchange, and every label is a real name, message, or count from the capture kit. Read each numbered row from the tail of the arrow to its head. The note under each label names the style.

LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11