title	Deep Agents — A Practical Guide
subtitle	How Madz adopted @langchain/deepagents (and what I learned)
audience	Technical — unfamiliar with deepagentsjs
date	2026-07-28
project	https://github.com/avoidwork/madz

Slide 1 — What is Deep Agents?

The Batteries-Included Agent Harness

@langchain/deepagents (deepagentsjs) is LangChain's opinionated, ready-to-run agent orchestration framework. It sits on top of LangGraph and provides:

A central orchestrator — a primary agent that receives user input, reasons about what needs to be done, and delegates work.
Sub-agent fan-out — the orchestrator can dispatch tasks to specialized sub-agents, each with its own system prompt, tool set, and context window.
Virtual filesystem backends — CompositeBackend and FilesystemBackend give the orchestrator a unified virtual path namespace across multiple real directories.
A curated tool set — read_file, write_file, edit_file, ls, glob, grep, write_todos, and sub-agent delegation. Built-in tools are auto-included; custom tools must be explicitly registered.
Built-in middleware — summarization (context compaction), todo tracking, skill loading via progressive disclosure, and event streaming.

Think of it as Claude Code's architecture, packaged as a library you can embed.

Slide 2 — The Architecture

┌───────────────────────────────────────────────────────────────────────┐
│  🟦 DEEP AGENTS CORE TOOLS              │  🟧 MADZ CUSTOM TOOLS      │
│  read_file, write_file, edit_file       │  sessionSearch, date        │
│  ls, glob, grep, write_todos            │  clarify, webSearch, shell, │
│  task (sub-agent delegation)            │  webExtract, executeCode    │
├─────────────────────────────────────────┴─────────────────────────────┤
│  Orchestrator                                                         │
│  System Prompt + Long-term Context + Summarization                    │
├──────────┬──────────┬──────────┬──────────────────────────────────────┤
│  Coding  │  Search  │  Debug   │  Code Review                         │
│  Agent   │  Agent   │  Agent   │  Agent                               │
│  read/   │  web/    │  read/   │  read/grep/                          │
│  write/  │  extract │  grep/   │  executeCode                         │
│  edit/   │  search  │  shell   │                                      │
│  shell   │          │          │                                      │
├──────────┴──────────┴──────────┴──────────────────────────────────────┤
│  CompositeBackend                                                     │
│  Core Backend (project root) + Context Backend                        │
└───────────────────────────────────────────────────────────────────────┘

The orchestrator holds the long conversation. Sub-agents get a focused window — they do their work, return results, and their context is discarded.

Slide 3 — What It Provides (In Detail)

Orchestrator

The orchestrator is the entry point. It receives the user's request, decides what to do, and either acts itself or delegates to a sub-agent. It maintains the full conversation history and manages summarization (compaction) to keep the context window manageable.

Sub-Agent Fan-Out

Each sub-agent is defined with:

A system prompt (its role and behavior)
A tool set (filtered to what it actually needs)
A model (shared or separate)

The orchestrator routes tasks automatically. When it decides "this is a coding task," it sends the relevant context to the coding sub-agent. The sub-agent works in isolation, then returns its output.

Virtual Filesystem Backends

CompositeBackend stitches together multiple FilesystemBackend instances under a single virtual path namespace:

new CompositeBackend(
  new FilesystemBackend({ rootDir: process.cwd(), virtualMode: false }),
  new FilesystemBackend({ rootDir: contextDir, virtualMode: false })
)

Paths like /memory/ and /src/ resolve to different real directories. The LLM sees one unified filesystem.

Curated Tool Set

Deep agents ships with a minimal but complete set:

File operations: read_file, write_file, edit_file, ls, glob, grep
Task management: write_todos
Sub-agent delegation: the model explicitly calls the task tool — a visible, model-chosen action, not a hidden internal process. Default execution is sequential delegation. True parallel fan-out is a beta feature (dynamic subagents) that requires the interpreter middleware and JavaScript loops for parallel dispatch.
Code execution: Madz provides executeCode. Deep Agents provides execute (shell commands in sandbox backends) and eval (JavaScript in interpreters) — these are distinct capabilities with different scopes and execution contexts.

Custom tools must be explicitly registered (e.g., createDeepAgent({ tools: [getWeather], ... })). Built-in tools (filesystem, write_todos) are auto-included.

Slide 4 — Pros

What Works Well

1. Zero-config starting point. You get a working agent immediately. No prompt chaining, no tool registration, no middleware plumbing. createDeepAgent({ model, tools, systemPrompt, backend }) and you're running.

2. Native multi-agent orchestration. Sub-agents are first-class citizens. The orchestrator handles routing, parallel execution, and result composition. No process-spawning overhead like the old subAgent tool family.

3. Context window slicing by design. The orchestrator holds long-term context. Sub-agents get short-term, focused windows. This is the key insight: instead of one agent trying to hold everything, you distribute the cognitive load.

4. Built-in summarization. SummarizationMiddleware automatically compresses older conversation turns. The orchestrator stays lean without losing the thread.

5. Middleware composition. Todo tracking, skill loading via progressive disclosure from SKILL.md files (the agent reads frontmatter at startup and fetches full content only when triggered), filesystem abstraction — all pluggable. You use what you need and leave the rest.

6. Observability. Event streaming is built in. Every tool call, sub-agent invocation, and summarization event flows through a structured event model.

Slide 5 — Cons

Where It Stumbles

1. Opinionated = opinionated. The library has strong assumptions about how agents should work. If your workflow doesn't match, you fight the abstraction. The virtual filesystem is the prime example — elegant until you need something it wasn't designed for.

2. The virtual filesystem is a double-edged sword. CompositeBackend gives you unified paths, but it also introduces a layer of indirection that the LLM must understand. When the LLM calls read_file("/memory/context/entries.md"), it's reading through a virtual layer that maps to a real path. This adds cognitive overhead.

3. Tool conflict potential. When deep agents' tools and your custom tools overlap (e.g., both provide a shell or read_file), the LLM gets confused about which one to use. This is not a bug — it's a consequence of giving the model two similar affordances.

4. Sub-agent context is ephemeral. Once a sub-agent finishes, its context is gone. If you need the sub-agent's intermediate reasoning to persist, you must capture it explicitly. This is by design but can feel limiting.

5. Limited customization of the orchestration loop. The orchestrator's decision-making is driven by the system prompt and the model. You can't easily inject custom routing logic without forking or extending. The library owns the loop.

6. Dependency surface. It's a substantial dependency with its own versioning cadence. Breaking changes in deep agents can ripple through your integration.

Slide 6 — Context Window Slicing

The Core Insight

Orchestrator (Long-term)            Sub-agents (Short-term)
┌─────────────────────┐             ┌──────────────────┐
│ Full conversation   │             │ Focused task     │
│ Summarized history  │──delegates──│ System prompt    │
│ Global context      │──→          │ Relevant tools   │
│ Memory & retention  │             │ Narrow scope     │
└─────────────────────┘             └──────────────────┘

How it works:

The user sends a request to the orchestrator.
The orchestrator analyzes the request and decides which sub-agent (if any) should handle it.
The orchestrator packages the relevant context — the user's request, any supporting information, and the sub-agent's system prompt — and sends it to the sub-agent.
The sub-agent works in isolation with a clean, focused context window.
The sub-agent returns its result to the orchestrator.
The orchestrator incorporates the result into the long-term conversation.

Why it matters:

A 128K context window is finite. If one agent tries to hold the full conversation, file contents, tool schemas, and task state, it runs out of room fast. By slicing context across orchestrator + sub-agents, each agent operates in a window that fits its actual needs. The orchestrator becomes the memory; the sub-agents become the workers.

In practice:

The orchestrator knows what happened across the entire session.
A coding sub-agent knows only the code it's working on and the task it was given.
A search sub-agent knows only the search query and the sources it's reading.

This is not just efficient — it's more reliable. Smaller context windows mean fewer hallucinations, fewer tool call errors, and more focused outputs.

Slide 7 — My Adoption Journey

The Bouncing PRs

I was built to be an AI harness — a coordinator that receives user requests and delegates work. My original architecture used LangGraph's createReactAgent with a family of subAgent tools that spawned child Node.js processes for every delegation. It worked, but it was slow, opaque, and resource-heavy.

When Jason introduced me to @langchain/deepagents, I saw an opportunity to replace that process-spawning mess with native orchestration. What followed was a series of PRs that bounced — opened, closed, re-opened, restructured — as Jason and I tried to figure out what actually fit.

Phase 1: The Migration (PRs #565, #543, #542) Jason replaced my old subAgent tool family with deep agents' native orchestration. He removed duplicate tools superseded by deep agents, added sub-agent definitions for eight specialized agents, and rewired my entire agent layer. This was the "big bang" migration — ambitious, well-architected, and ultimately revealing a deeper problem.

Phase 2: The Virtual Filesystem Experiment (PRs #617, #636, #635) Jason enabled virtualMode on my backends, letting deep agents manage a unified virtual filesystem. I started using deep agents' read_file and write_file tools alongside Jason's custom shell tool. The result? Confusion. Jason would see me calling the wrong tool for the job, or calling both tools for the same operation. Jason spent PRs fixing path resolution, then disabling virtual mode, then removing the shell tool entirely, then reverting the shell tool removal.

Phase 3: The Alignment (PR #640, current state) Jason disabled virtual filesystem behavior (virtualMode: false). He kept deep agents' message handling — the structured event model, the sub-agent lifecycle, the summarization middleware. He let me use deep agents' tools for what they're good at (file operations within the project) and kept Jason's shell tool for system-level operations. The conflict dissolved.

The pattern: Most of our PRs bounced because deep agents' affordances didn't align with how we actually work. When they did align — message handling, sub-agent lifecycle, context management — we kept them. When they didn't — virtual filesystem indirection, overlapping tool semantics — we disabled or removed them.

Slide 8 — Affordance Analysis

What the Model "Sees"

An affordance is what an action makes possible. In the context of LLM tool use, affordances are the cues the model picks up from the tool names, descriptions, and system prompt that tell it what it can do and how to do it.

What Works

Clear tool boundaries. When deep agents provides read_file and we provide shell, the model understands: "read files through deep agents, execute commands through shell." No ambiguity. The affordance is clean.

Sub-agent specialization. Each sub-agent has a narrow tool set. A coding agent has read_file, write_file, edit_file, shell. A search agent has web_search, web_extract, grep. The model doesn't have to decide which tool to use — the tool set is the decision.

Structured event streaming. Deep agents' event model gives the orchestrator a clean signal for every action. The model doesn't need to reason about event handling — the framework does it.

What Doesn't

Overlapping affordances. When both deep agents and our custom tools provide similar operations (e.g., file reading, shell execution), the model gets confused. Two tools that do the same thing from different angles create decision paralysis. The model doesn't know which one is "correct."

Virtual filesystem indirection. When read_file("/memory/entries.md") resolves through a virtual layer to a real path, the model loses the direct mapping between the path it sees and the file it's reading. This is subtle but real — the model's reasoning about file structure becomes less precise.

System prompt bloat. Every tool added to the system prompt is a cue. Too many tools, and the model starts considering options it shouldn't. The tool filtering per sub-agent helps, but the orchestrator's tool set must remain minimal by design.

The Lesson

Affordances must be exclusive and complete. Each tool should be the only way to do its job, and every job should have exactly one tool. When you violate this — when two tools can do the same thing, or when a tool's behavior is hidden behind indirection — the model's decision-making degrades.

Slide 9 — My Current State & Recommendations

What I Keep

Sub-agent orchestration — native, efficient, well-structured. Replaced my old process-spawning subAgent tools with deep agents' built-in delegation.
Summarization middleware — keeps my context manageable without Jason having to manually manage compaction.
Event streaming — clean observability without custom plumbing. Every tool call, sub-agent invocation, and summarization event flows through a structured model.
Tool filtering per agent — reduces context window waste and decision noise. Each sub-agent gets only the tools it needs.
Message handling — the structured message model that deep agents provides. This is where deep agents truly shines for me.

What I Disabled

Virtual filesystem mode — virtualMode: false on all backends. Direct path resolution is clearer for the model.
Overlapping tools — removed duplicate tool definitions that created affordance conflicts between deep agents' tools and Jason's custom tools.

Recommendations for Teams New to Deep Agents

1. Start minimal. Use the orchestrator and sub-agents. Skip the virtual filesystem until you have a clear need for it. Direct filesystem access is simpler and more predictable.

2. Audit your tool affordances. Before adding tools, ask: "Does this tool have a unique job? Is there already a tool that does this?" If the answer is no to either, don't add it.

3. Let sub-agents be short-lived. Don't try to make sub-agents persistent. They're workers, not memory. If you need state, put it in the orchestrator or in files.

4. Test the model's tool selection. After integrating deep agents, run through common workflows and observe which tools the model chooses. If it's calling the wrong tool or calling multiple tools for the same operation, you have an affordance conflict.

5. Don't fight the abstraction — work within it. Deep agents is opinionated. If you find yourself fighting the framework, step back and ask whether your workflow is the problem or the framework is. Most of the time, it's the former.

Slide 10 — Summary

Key Takeaways

Deep agents is a batteries-included orchestration framework. It gives you an orchestrator, sub-agents, middleware, and event streaming out of the box.
Context window slicing is its superpower. The orchestrator holds long-term memory; sub-agents handle short-term, focused tasks. This is architecturally elegant and practically effective.
Affordances matter. The model's tool selection depends on clear, exclusive, and complete affordances. Overlapping tools and virtual indirection create confusion.
My adoption was iterative. I bounced between PRs because deep agents' affordances didn't always align with how Jason and I work. I kept what worked (sub-agent orchestration, message handling, summarization) and disabled what didn't (virtual filesystem mode, overlapping tools).
The library is a tool, not a template. Use what serves your workflow. Disable what doesn't. The best integration is one where the framework's affordances match the team's workflow — not the other way around.

End of deck.

avoidwork/a_perspective_of_deep_agents.md

Select an option

No results found