Homeโ€บBlogโ€บAgentic AI System Designs
Agentic AI System Designs ยท Harness teardown

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.

FL
FrontierAGI Team
โš ๏ธ How to read this (as of 7 Nov 2026)Facts come from the deepagents GitHub repository (read 7 Nov 2026). LangChain's blog could not be reached from our build environment, so release details and the exact planning tool are marked โš ๏ธ. Build times, team sizes and costs are our estimates. Disclosure: Claude, made by Anthropic, helps write this site, and this series covers Anthropic, Google and OpenAI products.

1. Case file

MakerLangChain
CategoryHarness you embed
LicenceMIT
Built onLangGraph
Inspired byClaude Code (per README)
Released2025 โš ๏ธ

2. The whole system in one picture

๐Ÿ›๏ธ The whole system, layer by layer, with one task traced

โ” control (who calls whom)โ”… data (what comes back)โ–ญ solid border: runs on your machineโ”… dashed border: runs in the vendor's cloud
Press play to follow one task down through the layers and back, or tap any component.

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

๐Ÿงฌ Design DNA: the three decisions that define it

Harness as a libraryembed it in your own app
Filesystem as memoryoffload, keep pointers
Built on LangGraphstate, checkpoints, interrupts for free

๐Ÿ’ธ Where the tokens go in the traced task (our estimate)

Instructions and plan re-sent each turn30% ยท ~90k
Tool results kept in context15% ยท ~45k
Sub-agent work25% ยท ~75k
Model output15% ยท ~45k
Retries15% ยท ~45k

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

2025 Released by LangChain as an open-source package; README credits Claude Code as inspiration โš ๏ธ.
Nov 2026 Described as "the batteries-included agent harness" with sub-agents, pluggable filesystem backends, context offloading, human-in-the-loop, skills and MCP (README read 7 Nov 2026).

6. Where it breaks, and what it does about it

FailureLayerWhat happensWhat this system does about it
Context floodL4Large tool outputs fill the context.Offloading to files.
Sub-agent sprawlL2Too many delegated tasks, rising cost.Limit sub-agents and give each a narrow brief.
Lost runL2Crash mid-task.LangGraph checkpoints allow resuming.
Unsafe actionL6A tool does something irreversible.Human-in-the-loop interrupts on chosen tools.
Wrong backendL7Agent writes to a real filesystem in production.Use a sandboxed or remote backend.

7. Security and threat model

๐Ÿงฑ Trust boundaries

Leaves your machinewhatever context you send to the model provider you chose
Untrusted inputstool results, files, MCP responses
Powerful actionswhatever your tools can do: you define the blast radius
Controlschoice of backend (sandboxed vs local), human-in-the-loop interrupts, the tools you choose to expose

8. Standards it shares, and benchmarks

9. What people use it for

IndividualResearch agentsLong investigations that write findings to files.
TeamDomain coding agentsA coding agent tailored to an internal stack.
TeamData analysisPlan, run queries, store intermediate results.
EnterpriseAgents inside productsEmbed a long-running agent in your own app.
EnterpriseApproval workflowsPause for human sign-off before sensitive actions.
Beyond codeOperations runbooksMulti-step procedures with tools and checkpoints (typical uses).

10. How to build one from scratch

mini_deep_agents.py ยท Python 3, standard library only; scripted stub model
"""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()
$ python3 mini_deep_agents.py plan: [ ] reproduce failure | [ ] find cause | [ ] fix parse() | [ ] re-run tests plan: [x] reproduce failure | [x] find cause | [x] fix parse() | [x] re-run tests main context: 4 messages, 125 chars; files: ['dates.py', 'findings.md', 'tests.log', 'tests2.log'] without offloading, the two test logs would add 1738 chars to the context
PhaseWhat you buildTime*Team*Cost*
0 ยท PrototypeLoop with tools and a written plan1 week1$10โ€“25k
1 ยท MemoryFilesystem backend, offloading, sub-agents1โ€“2 months2$100โ€“250k
2 ยท DurableCheckpoints, resume, human interrupts (or adopt LangGraph)2โ€“4 months3โ€“5$300โ€“800k
3 ยท ExtensibleMCP, skills, pluggable backends2โ€“3 months3โ€“6$300โ€“700k
4 ยท ProductionTracing, evals, deployment3โ€“6 months5โ€“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.

๐Ÿงฎ 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

HarnessL1InterfacesL2Sessions & orchestrationL3Agent loopL4Context engineL5ToolsL6Policy & safetyL7ExecutionL8Model & telemetry
Claude CodeTerminal, IDE, desktop, web, Slack; Agent SDKSessions with resume; subagents; cloud sessions on the webOne general think โ†’ act โ†’ observe loopCLAUDE.md, auto memory, compactionBuilt-in file/shell/search tools, MCP, skillsPermission rules and modes, hooksYour machine (optional sandboxing โš ๏ธ); cloud for web sessionsClaude models; transcripts, cost and usage telemetry
CodexTerminal, IDE, web (chatgpt.com/codex)Parallel cloud tasks; local sessionsAgent loop per taskAGENTS.md, repo contextShell, file edits, MCPApproval modes โš ๏ธOS sandbox locally โš ๏ธ; container per cloud taskOpenAI models; task logs and diffs
Gemini CLI / JulesTerminal (CLI); browser + GitHub (Jules)Interactive session vs asynchronous taskAgent loop (CLI); plan-then-execute (Jules โš ๏ธ)GEMINI.md context filesBuilt-in tools, MCPConfirmations in the CLI; plan approval in Jules โš ๏ธYour machine (CLI); cloud VM (Jules โš ๏ธ)Gemini models (CLI "not optimized for Gemini 4+")
Deep AgentsYour own app (library)LangGraph threads; sub-agentsPlanning loop on LangGraphFilesystem as memory; offloadingYour tools, MCP, skillsHuman-in-the-loop interruptsPluggable backends: local, sandboxed, remoteAny chat model; LangGraph state and tracing
Hermes AgentTerminal + Telegram, Discord, Slack, WhatsApp, Signal, emailGateway, subagents, cron schedulerAgent loop (details on its docs site โš ๏ธ)Curated memory, FTS5 session search, user modelTools, self-written skills (agentskills.io), Python RPC scriptsDepends on backend and configuration โš ๏ธSix backends: local, Docker, SSH, Modal, Daytona, Vercel SandboxModel you configure โš ๏ธ

One line per layer; our reading of each project's documentation and code as of 7 Nov 2026.

HarnessRuns whereOpen sourceSubagentsPersistent memorySkillsMCPSandboxHuman approvalAsync / cloud tasks
Claude CodeTerminal, IDE, desktop, webโ€”โœ“โœ“โœ“โœ“โ—โœ“โœ“
CodexTerminal, IDE, cloudโœ“ (CLI)โ—โ—โ—โœ“โœ“โœ“โœ“
Gemini CLI / JulesTerminal (CLI), cloud VM (Jules)โœ“ (CLI)โ—โ—โ—โœ“โ—โœ“โœ“
Deep AgentsYour Python / JS appโœ“โœ“โ—โœ“โœ“โ—โœ“โ€”
Hermes AgentTerminal + 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

Start here๐Ÿงญ Four ways to build an agentHarness๐Ÿงฐ Claude CodeHarness๐Ÿงฐ CodexHarness๐Ÿงฐ Gemini CLI, Antigravity & JulesHarness๐Ÿงฐ Deep Agents (this article)Harness๐Ÿงฐ Hermes AgentFramework๐Ÿงฑ OpenAI Agents SDK ยท comingFramework๐Ÿงฑ Google ADK ยท comingFramework๐Ÿงฑ LangChain / LangGraph ยท comingFramework๐Ÿงฑ CrewAI ยท comingFramework๐Ÿงฑ Claude Agent SDK & Microsoft Agent Framework ยท comingRuntimeโš™๏ธ Amazon Bedrock AgentCore ยท comingRuntimeโš™๏ธ LangSmith Deployment ยท comingRuntimeโš™๏ธ Temporal ยท comingRuntimeโš™๏ธ Vertex AI Agent Engine & Azure AI Foundry ยท comingBuilder๐Ÿงฉ n8n ยท comingBuilder๐Ÿงฉ Zapier Agents ยท comingBuilder๐Ÿงฉ Microsoft Copilot Studio ยท comingBuilder๐Ÿงฉ Make ยท coming

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.

14. Sources