What Deep Agents is, and where it came from

The agent that falls apart at step forty

Most of us build our first agent the same way. You write a loop that calls the model, runs whatever tools it asks for, appends the results and calls the model again. For a handful of steps it works beautifully. The model looks something up, does a calculation, and answers.

Then you give it a real job, something like "read these twelve documents and write me a comparison", and somewhere around step forty it starts to drift. The context window is full of raw tool output. The plan it made at the start has scrolled out of view. It re-reads files it already read. Eventually it either runs out of room or confidently answers a slightly different question from the one you asked.

That loop was never wrong. It is the right core, the ReAct pattern of interleaving reasoning with actions (Yao et al., Oct 2022). What it lacks is everything around the loop that keeps a long task on track. It needs somewhere to put work that doesn't fit in the window, a way to split a big job into clean sub-jobs, a way to shrink history without losing it, and a way for a person to step in before something irreversible happens. That surrounding machinery is what people now call a harness, and Deep Agents is LangChain's.

Three layers, one graph

The single most useful fact about Deep Agents is that it doesn't add a runtime of its own. It sits on top of two layers you may already know, and the thing it hands back to you is an ordinary LangGraph graph. The figure below shows the stack. Read it from the bottom up, the way a request is actually built.

1. LangGraph, the runtimeAt the bottom is the engine that actually executes things. It is a state graph with reducers that merge updates, checkpoints that save state between steps, streaming, and interrupts that pause a run for a person. Every feature further up is built on these four.
2. LangChain's create_agent(), the loopOne layer up, LangChain compiles the classic agent loop into a LangGraph graph with a model node, a tools node and edges between them. It also defines middleware hooks, the points where extra code can run before, after or around each call. Everything in the layer above works through those hooks.
3. Deep Agents, the harnessThe top layer is a set of ready-made middleware plus a file backend, covering subagents, skills, memory, permissions and per-model profiles. None of it is a new execution engine. It is configuration and code plugged into LangChain's hooks.
4. create_deep_agent(), the one call you makeThis function assembles the middleware stack and the backend, then calls create_agent() with them. What comes back is a compiled LangGraph StateGraph, the same kind of object you would get if you built the graph yourself.

So everything you already know about LangGraph still applies. You invoke it, stream it, checkpoint it and interrupt it exactly as you would any graph. When something behaves strangely, you can debug it with the same tools. There is no hidden scheduler and no second event loop.

A few numbers are worth keeping in your head before we go further. They are the defaults you get if you pass nothing at all, and later parts explain each one.

Package

deepagents 0.7.35

Default model

claude-sonnet-4-6

Default backend

StateBackend()

Recursion limit

9,999

Python

3.11 or newer

The recursion limit is the one that surprises people. It caps how many steps a single run may take, and most graphs never get near it. A deep agent can take hundreds of model and tool calls on one task, so the harness sets the ceiling at 9,999 rather than let a long run die halfway through.

Six promises the harness makes

If you strip the marketing away, Deep Agents makes six promises. Each one answers a specific way the step-forty agent fell apart, and each gets its own part later in this series.

• Files are the working memory. Instead of keeping everything in the conversation, the model gets ls, read_file, write_file, edit_file, delete, glob and grep over a virtual filesystem, plus execute when the backend can run shell commands. Notes, drafts and big outputs live there, outside the window.
• Delegation keeps context clean. A task tool hands a job to a subagent that works in its own context and returns only its final answer. The messy middle never touches the main conversation.
• Long runs don't overflow. Huge tool results are moved into files automatically, and once the conversation reaches 85% of the window it is summarized, with the originals saved so nothing is lost.
• Storage is pluggable. Those files can live in graph state (the default), in a LangGraph Store, on disk, or in a remote sandbox, and a path prefix decides which.
• People stay in control. Any tool call can pause for a person to approve, edit, reject or respond, and filesystem permissions can deny or pause by path.
• Instructions scale. Skills are listed in one line each and read only when needed. Memory (an AGENTS.md file) sits in the prompt, and the agent can edit it.

Most of these are about the context window. That is not an accident, and it is the thread we will keep pulling for the rest of the series.

What you get for free

LangChain's plain create_agent already gives you the loop, with a model, tools, middleware and structured output. create_deep_agent returns the same kind of graph, but with a stack already installed. The fairest way to see what the harness adds is to put the two side by side and ask, for each concern, "what do I have before writing any code?"

Read down the right-hand column and a pattern appears. Almost every row is something you could add to a plain agent yourself. Summarization, approvals and a todo list are all available as LangChain middleware. What Deep Agents really sells is the assembly, with those pieces chosen, ordered and tuned to work together, plus the two things LangChain doesn't ship at all, a filesystem and subagents.

The "Planning tool" row is the interesting outlier. The harness used to plan by default, and now it doesn't. To see why, we need the history.

Where it came from, in four ingredients

In July 2025, LangChain published a launch post that looked closely at the agents that were clearly working on long tasks at the time, namely Claude Code, Manus and OpenAI's Deep Research. Different products, different companies, but under the hood they shared a recipe. The post boiled it down to four ingredients and packaged them as a library.

Each ingredient fixes a failure from our step-forty agent. The prompt told the model how to work on long tasks. The planning tool kept the plan visible, so it couldn't scroll away. Subagents meant a messy research detour happened in someone else's window. The filesystem gave the agent a place to put things that would otherwise clog the conversation, an idea with roots in research like MemGPT, which treats the context window as a small, fast memory backed by a larger external store (Packer et al., Oct 2023).

The interesting part is what happened next. The library kept growing, and then, a year in, it deliberately removed two of its own founding ingredients. The timeline shows the path.

1. Jul 2025 · the launchThe four ingredients ship as a library, with a long built-in system prompt, write_todos, subagents and a filesystem kept in graph state.
2. Oct 2025 · 0.2 · storage and long runsFiles are no longer tied to graph state, because pluggable backends arrive. So do the two mechanisms that stop long runs from overflowing, which are evicting large tool results to files and summarizing history.
3. Apr 2026 · 0.5 · work that outlives a callAsync subagents can run remotely while the main agent keeps going, and the file tools learn to read PDFs, audio and video.
4. May 2026 · 0.6 · tuning per modelA code interpreter, harness profiles that adjust the stack per model, a more efficient state channel (DeltaChannel) and a new event stream for tracing.
5. Jul 2026 · 0.7 · the lean harnessThe surprising release. The built-in base prompt is removed and the todo list becomes opt-in. LangChain's release post reports about 65% fewer base prompt tokens, with evals that held steady or improved.
6. Oct 2026 · skills grow upSkills, the on-demand instruction files, gain their own tools, pinning (always loaded) and reloading.
7. Nov 2026 · 0.7.35, where this series startsEverything in these posts was checked against this release and the main branch at the time of writing.

Stop five deserves a closer look. Why would a project remove the prompt and the planning tool that defined it? The release post doesn't frame it this way, but the most likely reading is that models caught up. A model that already plans well and already knows how to work through a long task doesn't need "make a todo list" spelled out on every call. Those instructions just cost tokens. A harness should carry what the model can't do on its own, and nothing more. As models improve, a good harness gets thinner.

That's a useful lens for the whole series. When you see a piece of the stack, ask what failure it prevents, and whether the model you are using still has that failure.

A vocabulary for the rest of the series

Most of what Deep Agents does falls under one name, context engineering, which means deciding what goes into the model's window on each call. It matters because a model's window is not a neutral container. Information buried in the middle of a long context is used less reliably than information at the start or the end (Liu et al., "Lost in the Middle", Jul 2023), so a cluttered window hurts quality well before it runs out of room.

You'll hear five moves named in talks and posts about context engineering. Each maps to a concrete mechanism in Deep Agents, and once you know the five, you can place almost any feature we meet later.

The moves work as a cycle. Offloading and reducing keep the window small. Retrieval brings back exactly the piece you need, when you need it. Isolation stops one subtask's mess from leaking into another. Caching makes the part that never changes cheap to send again. Parts 6 and 7 cover the first two and the last in depth, and parts 8 and 9 are all about isolation.

If you learned Deep Agents from an older tutorial

Because the project moves fast, a lot of published material predates the 0.7 changes. If you're coming from a blog post or a video, these are the things most likely to trip you up.

• write_todos is no longer on by default. Add TodoListMiddleware if you want it.
• There is no built-in base prompt. BASE_AGENT_PROMPT still exists, but it's deprecated and unused.
• Backend factories like backend=lambda rt: StateBackend(rt) are gone. Pass an instance.
• instructions= and a subagent's "prompt" key are now both system_prompt.
• interrupt_config is now interrupt_on, with allowed_decisions.
• deepagents-cli became deepagents-code, run as dcode.
• MultiServerMCPClient has been replaced by LangChain's own langchain.mcp.MCPAdapter.
• write_file used to fail on an existing file. It now overwrites.

Next

We now have a map. Deep Agents is a harness made of middleware and a file backend, sitting on LangChain's loop, sitting on LangGraph. In part 2 we'll build a first deep agent, look at every argument create_deep_agent() takes, and watch, layer by layer, how the system prompt the model actually receives gets assembled.