Every team that ships an agent loop discovers the same ceiling: the agent handles a three-step task fine, then falls apart on a thirty-step one. LangChain’s deepagents harness packages the known fixes, planning, subagents, a filesystem, and context management, into one create_deep_agent call, and that genuinely removes most of the scaffolding work. What it does not remove is the production work: deciding where a human approves, how the output is judged, and who pays the token bill. We run agentic systems in production for clients, so this post covers both halves: what the harness gives you on day one, and the four things you still own before it can be trusted with real work.
What makes an agent “deep” in the first place
The word is doing real work. In LangChain’s own Deep Agents post, a shallow agent is an LLM looping through tool calls, and its shallowness is the “inability to plan over longer time horizons and do more complex tasks.” The loop is not wrong, it is just short-sighted: every decision competes for the same context window, and by step twenty the plan from step one has been crowded out.
A deep agent is the same tool-calling loop, extended with four things: a detailed system prompt, a planning tool, subagents, and a filesystem. The algorithm does not change. The implementation details around it do.
That recipe was not invented on a whiteboard. It is reverse-engineered from the agents that demonstrably sustain long tasks: Claude Code (a todo list plus spawned subagents), OpenAI’s Deep Research (long-horizon planning), and Manus (a filesystem as working memory). Each pillar attacks the same enemy from a different side. The planning tool is famously almost a no-op, writing the plan does nothing except force the plan to exist in context, which keeps the agent on course. Subagents give heavy subtasks a fresh context window and return one compact report. The filesystem is memory that survives outside the context window entirely.
What the harness gives you on day one
Until recently you assembled those four pillars yourself on LangGraph. The deepagents package (Python, 0.7.x line at the time of writing, on LangGraph and LangChain 1.0) pre-assembles them as middleware: filesystem, summarization, subagents, and prompt caching are included by default, per the customization docs. You bring the model, the tools, and the persona:
# deepagents 0.7.x
from deepagents import create_deep_agent
agent = create_deep_agent(
model="anthropic:claude-sonnet-4-6",
system_prompt="You are a research analyst. Cite every claim.",
tools=[search, fetch_url],
subagents=[{
"name": "researcher",
"description": "Searches and returns a structured, sourced summary.",
"system_prompt": "Research the question and return key points with sources.",
"tools": [search],
}],
)
result = agent.invoke({"messages": [{"role": "user", "content": "..."}]})Behind that call the main agent gets a task tool for delegating to subagents (including an always-available general-purpose one whose main job is context isolation: heavy intermediate tool calls stay in the subagent, only the conclusion comes back), a virtual filesystem with pluggable backends (in-memory state, local disk, a LangGraph store, or a sandbox), and summarization that keeps long runs inside the window. Because it compiles down to a LangGraph graph, the production plumbing LangGraph matured for two years, streaming, checkpointing, persistence, and tracing, comes along for free.
This is a real step change in how much you have to build. Our earlier agent builds spent the first week wiring exactly these pieces by hand.
What you still own before it touches real work
A harness default is a starting point, and the four decisions below are the difference between a demo and a system a business can rely on.
The human gate
create_deep_agent accepts an interrupt_on configuration that pauses the run before selected tool calls and waits for a person, built on LangGraph’s human-in-the-loop interrupts. The mechanism ships in the box. The policy does not: which actions pause, what the reviewer sees, and what signal decides that a case needs review at all are your calls. In our production systems that signal is never the model’s opinion of itself; we covered why, and what to gate on instead, in Stop asking the LLM how confident it is. A deep agent that can spawn subagents and write files is strictly more capable than a shallow one, which means an ungated one is strictly more capable of being wrong at scale.
The evals
The agent that produced the work cannot be the one that declares it done. That holds doubly for a deep agent, because a subagent’s confident summary is exactly the kind of output that reads as finished. Trace the runs (the harness integrates with LangSmith natively), build a small eval set from real cases before launch, and judge outputs with a separate checker, whether that is a validator, a cross-check against a system of record, or a second model. None of this is generated for you by any harness, and it is where most of our engineering time on client systems actually goes.
The token bill
Subagents buy quality with tokens. Anthropic’s write-up of their own production multi-agent system, How we built our multi-agent research system, is refreshingly concrete: the multi-agent setup “outperformed single-agent Claude Opus 4 by 90.2%” on their internal research eval, and in their data “multi-agent systems use about 15× more tokens than chats.” Both numbers are the trade: a deep agent is the expensive way to be right about hard tasks. Route it accordingly. Open-ended research and multi-file work earn the fan-out; a lookup or a classification does not, and a per-run cost ceiling belongs in the design, not in the postmortem.
Persistence and state
The default filesystem backend is in-memory state, which vanishes when the run ends. Fine for a demo, wrong for a system that resumes work or learns across runs. Production means choosing deliberately: a durable backend for files the agent should keep, a checkpointer for runs a human might resume next week, and permission rules on what the agent may write where. The going to production docs cover deployment, but the data-ownership decisions are, again, yours.
When we reach for a hand-built graph instead
The honest caveat from production: not every workflow wants a deep agent. The harness shines when the task is open-ended and the path is unknowable up front, research, multi-step coding, anything where the agent must decide its own next step. But a large share of real business workflows are the opposite: the steps are known, the order is fixed, and what the client is buying is consistency and auditability. For those we still build the LangGraph graph by hand, with deterministic routing and a gate at the judgment points, because a workflow you can draw on a whiteboard should be encoded as that drawing, not rediscovered by a planner on every run. The client systems we operate are mostly graphs with narrow agentic sections, and an occasional deep-agent node where a step is genuinely open-ended. The two compose cleanly, which is the quiet advantage of the harness being LangGraph underneath.
Conclusion
create_deep_agent collapses a week of scaffolding, planning, subagents, filesystem, and context management, into a function call, and it earns its place for open-ended, long-horizon tasks. Treat what it ships as the floor. The human gate, the evals, the cost ceiling, and the persistence model are still yours to design, and they are precisely the parts a client pays for. Start with the harness, spend your engineering time on the four things it cannot decide for you, and keep the deterministic graph in reach for the workflows that never needed a planner in the first place.
Sources
- Deep Agents, the LangChain blog post that defines the pattern
- Deep Agents overview in the LangChain docs
- Customizing the deepagents harness, LangChain docs
- How we built our multi-agent research system, Anthropic engineering
- LangGraph human-in-the-loop interrupts, LangChain docs
- LangChain and LangGraph 1.0 announcement