Deep Agents, Taken Apart
LangChain's Deep Agents packages what makes coding harnesses work into an open-source library: planning, sub-agents, a filesystem used as memory, and context offloading, on top of LangGraph. Dismantled into eight layers.
1. Case file
- In one sentence.
- The patterns that make coding harnesses work, planning, sub-agents, a filesystem as memory and context offloading, packaged as an open-source library you can put inside your own product.
2. The whole system in one picture
๐๏ธ The whole system, layer by layer, with one task traced
Same eight-layer reference stack in every article of the series. Components and calls are drawn from the project's documentation and code; where internals are not public the drawing is inferred from documented behaviour. The monospace box shows what actually moves between layers at each step (simplified).
3. Layer by layer
L1๐ฅ๏ธ Interfaces ยท Where people (or other agents) talk to it
- What it does
- How you use it.
- How it is built here
- As a Python (or JS) library inside your own application; optional CLI โ ๏ธ.
- Design choice
- A harness you embed, not a product you open.
- Without it
- You could only use it the way its makers imagined.
L2๐งญ Sessions & orchestration ยท Who owns a task: sessions, background tasks, subagents
- What it does
- Runs and helpers.
- How it is built here
- LangGraph threads hold each run's state; sub-agents with isolated context windows.
- Design choice
- Reuse a mature graph runtime instead of inventing session handling.
- Without it
- Crashes lose progress and long runs cannot resume.
L3๐ Agent loop ยท How it decides the next step
- What it does
- The decision loop.
- How it is built here
- create_deep_agent() builds an agent that plans, reads and writes files and manages its own context.
- Design choice
- Package the patterns that make coding harnesses good, for any domain.
- Without it
- Every team rebuilds planning and delegation from scratch.
๐ How this loop compares with the other four, dial by dial, and its RSI level: Inside the Agent Loop
L4๐ง Context engine ยท What the model sees on each turn
- What it does
- Keeping the context small and useful.
- How it is built here
- A written plan โ ๏ธ, files as working memory, and offloading of large tool outputs to disk.
- Design choice
- The filesystem is the memory: anything big goes to a file, the context keeps a pointer.
- Without it
- Long tasks drown in tool output and lose the plot.
L5๐ ๏ธ Tools ยท What it can do
- What it does
- Actions.
- How it is built here
- Your own tools, MCP servers and skills.
- Design choice
- Bring your own tools; the harness provides the structure.
- Without it
- You are limited to built-in capabilities.
L6๐ก๏ธ Policy & safety ยท What it may do
- What it does
- Human control.
- How it is built here
- Human-in-the-loop interrupts before chosen actions.
- Design choice
- Approval as a graph interrupt: pause, persist, resume later.
- Without it
- No safe way to put a person in front of risky steps.
L7๐ฆ Execution ยท Where actions actually run
- What it does
- Where files and commands live.
- How it is built here
- Pluggable backends: local, sandboxed or remote.
- Design choice
- Execution is a plug-in, so the same agent can run on a laptop or in a sandbox.
- Without it
- Moving from prototype to production means rewriting the agent.
L8๐งฌ Model & telemetry ยท Which model, and what gets logged
- What it does
- Model and records.
- How it is built here
- Any chat model; LangGraph state checkpoints and tracing โ ๏ธ.
- Design choice
- Model-agnostic by design.
- Without it
- Locked to one provider.
4. Connecting the dots
- Layer 4 is the product.
- Planning, file memory and offloading are what make long runs work; the loop itself is ordinary.
- Standing on LangGraph.
- Layers 2 and 8 come from the graph runtime: threads, checkpoints and interrupts are inherited rather than built.
- Halfway between harness and framework.
- A harness in what it does, a framework in how you use it.
๐งฌ Design DNA: the three decisions that define it
๐ธ Where the tokens go in the traced task (our estimate)
An illustrative split for a ~300k-token task: about $1.20 at an assumed blended $4 per million tokens. Real numbers vary widely with the repo, the model and caching; the shape (context re-sent every turn dominates) is the point.
5. How it evolved
- โ ๏ธ LangChain's blog could not be reached; exact release dates are not verified.
6. Where it breaks, and what it does about it
| Failure | Layer | What happens | What this system does about it |
|---|---|---|---|
| Context flood | L4 | Large tool outputs fill the context. | Offloading to files. |
| Sub-agent sprawl | L2 | Too many delegated tasks, rising cost. | Limit sub-agents and give each a narrow brief. |
| Lost run | L2 | Crash mid-task. | LangGraph checkpoints allow resuming. |
| Unsafe action | L6 | A tool does something irreversible. | Human-in-the-loop interrupts on chosen tools. |
| Wrong backend | L7 | Agent writes to a real filesystem in production. | Use a sandboxed or remote backend. |
7. Security and threat model
๐งฑ Trust boundaries
8. Standards it shares, and benchmarks
- Interoperability.
- MCP tools, skills, and any model provider LangChain supports.
- Deploys like any LangGraph graph (see wave 3: LangSmith Deployment).
- Benchmarks.
- A library, so results depend on your tools and model. See the Benchmark Tracker for model scores.
9. What people use it for
10. How to build one from scratch
- Start small: plan, delegate, offload.
- This separate toy shows the Deep Agents ideas: a to-do plan, a sub-agent with its own context, and offloading big tool output to a filesystem. The model is a scripted stub.
"""mini_deep_agents.py โ a toy harness in the style of Deep Agents (illustrative).
A harness as a library: a to-do planner, sub-agents with isolated context, and a
filesystem used as working memory so large tool outputs do not flood the context.
The "model" is a scripted stub; standard library only.
"""
FS = {} # pluggable filesystem backend (here: a dict)
LIMIT = 200 # characters of tool output allowed into context
def tool_run_tests():
return "collected 812 tests\n" + "." * 811 + "F\nFAILED test_dates.py::test_iso - ValueError: not enough values"
def offload(name, text):
if len(text) <= LIMIT: return text
FS[name] = text; return f"[{len(text)} chars saved to /{name}; last line: {text.splitlines()[-1]}]"
def subagent(question):
ctx = [question, offload("tests.log", tool_run_tests())] # its own, throwaway context
FS["findings.md"] = "parse() splits on '/', test passes ISO '2026-11-07'"
return "see /findings.md", len(ctx)
def main():
todos = ["reproduce failure", "find cause", "fix parse()", "re-run tests"]
ctx = ["user: fix the failing date test"]
print("plan: " + " | ".join(f"[ ] {t}" for t in todos))
note, n = subagent("why does test_dates fail?")
ctx.append("subagent: " + note); todos[0] = todos[1] = None
FS["dates.py"] = "y, m, d = s.split('-')"; ctx.append("edit dates.py")
log2 = "collected 812 tests\n" + "." * 812 + "\n812 passed"
ctx.append(offload("tests2.log", log2))
print("plan: " + " | ".join("[x] " + t for t in ["reproduce failure", "find cause", "fix parse()", "re-run tests"]))
print(f"main context: {len(ctx)} messages, {sum(len(c) for c in ctx)} chars; files: {sorted(FS)}")
print(f"without offloading, the two test logs would add {len(tool_run_tests()) + len(log2)} chars to the context")
if __name__ == "__main__":
main()| Phase | What you build | Time* | Team* | Cost* |
|---|---|---|---|---|
| 0 ยท Prototype | Loop with tools and a written plan | 1 week | 1 | $10โ25k |
| 1 ยท Memory | Filesystem backend, offloading, sub-agents | 1โ2 months | 2 | $100โ250k |
| 2 ยท Durable | Checkpoints, resume, human interrupts (or adopt LangGraph) | 2โ4 months | 3โ5 | $300โ800k |
| 3 ยท Extensible | MCP, skills, pluggable backends | 2โ3 months | 3โ6 | $300โ700k |
| 4 ยท Production | Tracing, evals, deployment | 3โ6 months | 5โ10 | $1โ3M a year |
*Our estimates, not vendor figures: fully loaded engineer cost assumed at $250k a year (US-style salaries; lower elsewhere), plus model API and infrastructure. Treat as orders of magnitude.
- Build or extend?
- This is the "extend" option: if you need a long-running agent for your own domain, starting from Deep Agents (MIT) or the Claude Agent SDK skips phases 0โ3.
๐งฎ What would running your own cost a month?
Our model: model cost = tasks ร tokens ร price ร 30 days; people = engineers ร $250k รท 12; infrastructure (sandboxes, storage, logs) assumed at 15% of model cost. A blended price mixes cached input, fresh input and output; check your provider's current prices.
11. When to choose it
โ Choose it when
- A long-running agent for a non-coding domain.
- Open source (MIT) and model-agnostic.
- You already use LangChain or LangGraph.
โ ๏ธ Think twice when
- You want a finished coding product with a UI.
- You do not want to write or run code.
12. How it compares, layer by layer
| Harness | L1Interfaces | L2Sessions & orchestration | L3Agent loop | L4Context engine | L5Tools | L6Policy & safety | L7Execution | L8Model & telemetry |
|---|---|---|---|---|---|---|---|---|
| Claude Code | Terminal, IDE, desktop, web, Slack; Agent SDK | Sessions with resume; subagents; cloud sessions on the web | One general think โ act โ observe loop | CLAUDE.md, auto memory, compaction | Built-in file/shell/search tools, MCP, skills | Permission rules and modes, hooks | Your machine (optional sandboxing โ ๏ธ); cloud for web sessions | Claude models; transcripts, cost and usage telemetry |
| Codex | Terminal, IDE, web (chatgpt.com/codex) | Parallel cloud tasks; local sessions | Agent loop per task | AGENTS.md, repo context | Shell, file edits, MCP | Approval modes โ ๏ธ | OS sandbox locally โ ๏ธ; container per cloud task | OpenAI models; task logs and diffs |
| Gemini CLI / Jules | Terminal (CLI); browser + GitHub (Jules) | Interactive session vs asynchronous task | Agent loop (CLI); plan-then-execute (Jules โ ๏ธ) | GEMINI.md context files | Built-in tools, MCP | Confirmations in the CLI; plan approval in Jules โ ๏ธ | Your machine (CLI); cloud VM (Jules โ ๏ธ) | Gemini models (CLI "not optimized for Gemini 4+") |
| Deep Agents | Your own app (library) | LangGraph threads; sub-agents | Planning loop on LangGraph | Filesystem as memory; offloading | Your tools, MCP, skills | Human-in-the-loop interrupts | Pluggable backends: local, sandboxed, remote | Any chat model; LangGraph state and tracing |
| Hermes Agent | Terminal + Telegram, Discord, Slack, WhatsApp, Signal, email | Gateway, subagents, cron scheduler | Agent loop (details on its docs site โ ๏ธ) | Curated memory, FTS5 session search, user model | Tools, self-written skills (agentskills.io), Python RPC scripts | Depends on backend and configuration โ ๏ธ | Six backends: local, Docker, SSH, Modal, Daytona, Vercel Sandbox | Model you configure โ ๏ธ |
One line per layer; our reading of each project's documentation and code as of 7 Nov 2026.
| Harness | Runs where | Open source | Subagents | Persistent memory | Skills | MCP | Sandbox | Human approval | Async / cloud tasks |
|---|---|---|---|---|---|---|---|---|---|
| Claude Code | Terminal, IDE, desktop, web | โ | โ | โ | โ | โ | โ | โ | โ |
| Codex | Terminal, IDE, cloud | โ (CLI) | โ | โ | โ | โ | โ | โ | โ |
| Gemini CLI / Jules | Terminal (CLI), cloud VM (Jules) | โ (CLI) | โ | โ | โ | โ | โ | โ | โ |
| Deep Agents | Your Python / JS app | โ | โ | โ | โ | โ | โ | โ | โ |
| Hermes Agent | Terminal + chat apps | โ | โ | โ | โ | โ | โ | โ | โ |
โ built in ยท โ partial or via add-ons ยท โ not a feature. Our reading of each project's documentation as of 7 Nov 2026; check before relying on it.
13. The series
Agentic AI System Designs: four kinds of agent system, one teardown each
All of them on one page: Agentic Systems at a Glance.
๐ Glossary: 15 terms used across the series
- Agent loop
- The repeat cycle: the model picks an action, the harness runs it, the result goes back to the model.
- Harness
- Everything around the model that turns it into a working agent: loop, tools, context, policy, execution.
- Context window
- The text the model can see at once. Everything the agent knows on a turn has to fit in it.
- Context compaction
- Summarising older conversation so a long task keeps fitting in the context window.
- Tool schema
- A machine-readable description of a tool (name, inputs) that tells the model how to call it.
- MCP
- Model Context Protocol: an open standard for connecting agents to outside tools and data.
- Subagent
- A second agent with its own context, used for a side task; only its summary comes back.
- Skill
- A packaged set of instructions (and sometimes scripts) the agent loads when relevant.
- Hook
- Your own command that runs automatically before or after an agent action.
- Sandbox
- A restricted place to run commands so mistakes or attacks cannot reach the rest of the system.
- Approval mode
- The rule for what the agent may do without asking you first.
- Prompt injection
- Instructions hidden in data the agent reads (a file, a web page) that try to hijack it.
- Trace
- The full record of a run: every model call, tool call and result.
- AGENTS.md / CLAUDE.md / GEMINI.md
- Plain markdown files of project instructions that harnesses read at the start of a session.
- Asynchronous agent
- An agent you hand a task to and leave; it returns a result (often a pull request) later.