Everyone's first agent is the same agent. A while loop: send the model a prompt and some tools, execute whatever tool it calls, append the result, repeat until it stops. It's a genuinely great architecture. For tasks that take five steps.

Ask that same loop to do something long (research a topic thoroughly and write a report, refactor a codebase, plan a multi-part deliverable) and it falls apart in predictable ways. It forgets what it was doing. It stuffs its context window with raw tool output until the important stuff scrolls out the back. It does step one enthusiastically and then wanders off.

The interesting thing is that the fix turned out not to be smarter models. It was architecture. Claude Code and the deep research agents all converged on the same recipe, and LangChain's deepagents library packages that recipe so you don't have to rediscover it. I've been building with it, and I've had a fix merged upstream, so here's the beginner-friendly version of what it does and why.

The recipe, in plain English

A "deep agent" is a normal tool-calling agent plus four things:

1. A planning tool. The agent gets a to-do list tool and is prompted to write down its plan before acting, then update statuses as it works. Here's the counterintuitive part: the plan does almost nothing mechanically. Nothing forces the agent to follow it. Its value is that the plan keeps re-entering the context window every turn, it's a note the agent writes to its future self. Fifty steps in, when the original instruction is ancient history, the to-do list is what keeps the agent pointed at the goal instead of drifting.

2. A filesystem. The agent can write and read files. This solves the context-stuffing problem: instead of carrying a 40,000-token scrape result in its head forever, the agent saves it to research/source-3.md and pulls back only what it needs, when it needs it. Memory stops being "whatever fits in the context window" and becomes "whatever's on disk," with the context window acting as working memory. In deepagents this filesystem is pluggable (in-memory for safety, real disk, or a database) which is a nicer design than hardcoding any one of them.

3. Sub-agents. The main agent can delegate a chunk of work ("go research X and report back") to a fresh agent with a clean context. The sub-agent burns through fifty messy tool calls, and only its final summary returns to the parent. This is context quarantine: the parent stays clean and strategic while the dirty work happens elsewhere. It's the same reason a good tech lead doesn't sit in every debugging session.

4. A serious system prompt. The least glamorous pillar and arguably the load-bearing one. deepagents ships a long, detailed default prompt teaching the model how to use the planning tool, the filesystem, and delegation. A huge fraction of "my agent is dumb" complaints are actually "my agent was never told how to work."

None of these ideas is exotic. The insight is that they're a package: each one covers a failure mode the others create.

What using it feels like

The API surface is small. You hand it your tools and instructions, and you get back a LangGraph graph with all four pillars pre-wired:

from deepagents import create_deep_agent

agent = create_deep_agent(
    tools=[search_web, fetch_page],
    system_prompt=(
        "You are a research analyst. Investigate the topic thoroughly, "
        "save sources as you go, and write a final report to report.md "
        "with citations."
    ),
)

result = agent.invoke({"messages": [{"role": "user",
    "content": "How are retail media networks monetizing ad inventory?"}]})

I rebuilt an internal research workflow with it, the kind of task where my hand-rolled loop used to produce a confident, shallow answer after six tool calls. The deep agent version behaves differently in a way that's almost eerie to watch in a trace: it writes a plan, spawns sub-agents per research thread, files sources away, and then composes the report from its notes rather than from whatever survived in context. Same model, same tools. The difference is entirely the scaffolding.

The thing that sold me for real: watching it hit a dead end, update its own to-do list to reflect the new reality, and keep going. That's the behavior the plan-as-context trick buys you.

Where it fits

• Use deepagents when the task is long-horizon: research-and-write, multi-file code work, anything where a single context window can't hold the whole job. That's the regime the architecture exists for.
• Skip it for short tasks. A five-step workflow doesn't need planning overhead and sub-agents; a plain tool loop (or a simple LangGraph graph) is faster and easier to debug.
• It's built on LangGraph, so you keep the whole ecosystem: streaming, checkpointing for human-in-the-loop approval, LangSmith tracing. When you outgrow the defaults, you drop down a layer rather than rewriting.

It's also just a good learning codebase. Because the library is essentially "the deep agent pattern, written down," reading the source teaches you the architecture itself: the planning tool, the filesystem backends, the sub-agent spawning are each small, legible modules. That's how I ended up contributing upstream: I was reading the code to steal ideas and found an edge worth fixing. The maintainers move fast and review generously.

The bigger lesson

The industry spent two years asking "when will models be smart enough for long tasks?" and the answer, embarrassingly, was partly "the models were fine. Our while loops were lazy." Context is a budget. Plans are memory. Delegation is hygiene. Deep agents are what happens when you take those three sentences seriously.

If you've built the basic loop and felt it plateau, deepagents is the fastest way to feel the difference architecture makes: one pip install, one afternoon, and an agent that finally finishes what it starts.