# Deep Agents Architecture

> Use when an agent must run long-horizon, open-ended, parallelizable tasks (deep research, large multi-file code changes, hundreds of record lookups) and a single-loop agent drifts after 5-20 steps. Encodes the four-pillar deep-agents pattern — planning tool (write_todos), virtual filesystem for context offload, isolated subagents, long-term memory — plus the token/KV-cache economics that decide whether it's viable and a step-count rule for when NOT to use it. Reach for it past ~15-20 steps with separable sub-tasks; stay single-loop below that.

- Skill: `nsharandroidnstudio/deep-agents-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nsharandroidnstudio/deep-agents-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nsharandroidnstudio/deep-agents-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: nsharandroidnstudio (https://skillmd.com/u/nsharandroidnstudio)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/nsharandroidnstudio/deep-agents-architecture

---


# Deep Agents Architecture

**Core thesis (particula.tech):** *A deep agent is a four-pillar pattern — a planning tool (`write_todos`) to keep goals in attention, a virtual filesystem for context offload, isolated subagents to prevent context pollution, and long-term memory.* This is **not a model capability** — it's **scaffolding** that lets the same Claude/GPT model stay coherent across long-horizon tasks (60+ steps) where single-loop agents drift.

## When to use — and when not to

**Use when** the task is open-ended, runs long, and rewards parallel exploration:
- Deep research / competitive analysis (many parallelizable sources)
- Large multi-file code changes (what Claude Code does)
- Long data-gathering jobs (hundreds of records needing lookups)

**Do NOT use for:** classification, extraction, structured Q&A; latency-sensitive interactions (deep agents have many internal steps); tasks a better-instrumented single agent with the right tools would solve.

**Decision rule:** *Estimate the task's natural step count and whether sub-tasks are separable. Under ~15-20 steps with tightly coupled work, stay single-loop. Beyond that, with separable exploratory sub-tasks, the deep-agent pattern starts to pay for its 15x token premium.*

> **Common failure mode:** reaching for multi-agent orchestration on a problem a better-instrumented single agent would have solved.

## The four pillars

| Pillar | Mechanism | Problem solved |
|---|---|---|
| Planning tool | `write_todos` rewrites the structured plan each step | Goal drift / attention decay |
| Virtual filesystem | Read/write files as external context | Context-window overflow |
| Subagents | Delegate sub-tasks to isolated contexts | Context pollution |
| Long-term memory | Persist state across runs | Amnesia between sessions |

### Pillar 1 — Planning tool (`write_todos`)
Rewrite the goals into the **most recent slice of context on every iteration**, pushing the objective into the model's freshest attention right before it decides what to do next.
- Counters **attention decay** — tokens from ~40,000 positions earlier lose influence.
- Gives a **human-readable execution trace** for debugging.
- Front-loads reasoning to avoid redundant implicit recalculation.
- **Implementation note:** free-form markdown the model rewrites *in full* each loop works better in practice than a rigid task graph with strict state transitions. Track status per task (done / in_progress / pending).

### Pillar 2 — Virtual filesystem for context offload
Treat the filesystem as the model's **externalized memory** — a place where context is offloaded **losslessly** and recalled on demand. The agent uses `ls`, `read_file`, `write_file` like a researcher using a notes folder.
- **Discipline — restorable compression:** store distilled notes with recoverable detail, e.g. *"Source 7: competitor lists enterprise tier at $X/seat"*, keeping URLs so detail can be re-fetched. Don't dump raw tool output to disk.
- **Secondary function:** a **handoff medium between subagents** — without pulling a subagent's raw exploration into the orchestrator's context.

### Pillar 3 — Isolated subagents
**Context pollution** = failed tool calls, abandoned searches, and verbose dumps piling up in one window and degrading reasoning on everything downstream. Fix it by delegating sub-tasks to subagents with **isolated contexts** that return only clean summaries.

```
Orchestrator (Opus 4)
  ├─ writes plan, decomposes the query
  ├─ spawns Subagent A (Sonnet) → searches vendor docs → returns summary
  ├─ spawns Subagent B (Sonnet) → searches filings   → returns summary
  ├─ spawns Subagent C (Sonnet) → searches news      → returns summary
  └─ synthesizes clean summaries into final report
```
- **Result:** Anthropic's multi-agent research system **outperformed a single-agent Opus 4 baseline by 90.2%** on their internal research eval.
- **Critical limitation:** subagents work for **read-heavy, parallelizable** work; they're far harder to coordinate when sub-tasks must write to shared state or depend on each other's intermediate output. **Default to parallel-read, not parallel-write.**

### Pillar 4 — Long-term memory across runs
Persist selected state — facts, preferences, prior results, learned procedures — that survives after the agent finishes, in the same filesystem abstraction (Pillar 2) or an external store.
- **Selection discipline:** you can't reload everything — that reintroduces the overflow you fought to avoid. Be **opinionated about what persists**: stable facts, user preferences, reusable artifacts. Transient junk stays out.
- **Maturity note:** the least standardized pillar, the one most teams implement last — and where the most product differentiation hides.

## Token & KV-cache economics (what decides viability)

- **15x token premium:** Anthropic reported their multi-agent research architecture consumed **~15x more tokens** than a standard chat interaction. On **BrowseComp**, token usage alone explained **80% of the performance variance**.
- **KV-cache hit rate is the single most important production metric for a deep agent.** Claude Sonnet: **$0.30 / M cached tokens vs $3.00 / M uncached — a 10x difference.** At 15x volume, cache performance determines whether the system is affordable.

**Cache optimization rules:**
1. **Keep the prompt prefix stable** — the cache matches on exact prefix.
2. **Append, never insert** — add new context to the end.
3. **Avoid non-determinism near the front** — timestamps or reordered tool definitions destroy hit rate.
4. **Make file reads idempotent** — byte-identical text on repeated reads stays cacheable.

| Metric | Single-loop agent | Deep agent (multi-agent) |
|---|---|---|
| Token usage vs chat | ~1x | ~15x |
| Steps before drift | 5 to 20 | Dozens to hundreds |
| Primary cost lever | Total tokens | KV-cache hit rate |
| Best for | Narrow, latency-sensitive | Open-ended, exploratory |

## Incremental adoption path
*Add the planner first (cheapest, highest leverage), then the filesystem, then subagents, then memory.* Most teams find the **planner and filesystem alone get them most of the way**.

---

*Distilled from particula.tech, "Deep Agents Pattern: Planner, Filesystem, Subagents Architecture": https://particula.tech/blog/deep-agents-pattern-planner-filesystem-subagents-architecture*