Deep Agents Architecture Decisions

When to Use Deep Agents

Use Deep Agents When You Need:

• Long-horizon tasks - Complex workflows spanning dozens of tool calls
• Planning capabilities - Task decomposition before execution
• Filesystem operations - Reading, writing, and editing files
• Subagent delegation - Isolated task execution with separate context windows
• Persistent memory - Long-term storage across conversations
• Human-in-the-loop - Approval gates for sensitive operations
• Context management - Auto-summarization for long conversations

Consider Alternatives When:

Backend Selection

Backend Comparison

Backend Decision Tree

Need real disk access?
├─ Yes → FilesystemBackend(root_dir="/path")
└─ No
   └─ Need persistence across conversations?
      ├─ Yes → Need mixed ephemeral + persistent?
      │  ├─ Yes → CompositeBackend
      │  └─ No → StoreBackend
      └─ No → StateBackend (default)

CompositeBackend Routing

Route different paths to different storage backends:

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    backend=CompositeBackend(
        default=StateBackend(),  # Working files (ephemeral)
        routes={
            "/memories/": StoreBackend(store=store),    # Persistent
            "/preferences/": StoreBackend(store=store), # Persistent
        },
    ),
)

Subagent Architecture

When to Use Subagents

Use subagents when:

• Task is complex, multi-step, and can run independently
• Task requires heavy context that would bloat the main thread
• Multiple independent tasks can run in parallel
• You need isolated execution (sandboxing)
• You only care about the final result, not intermediate steps

Don't use subagents when:

• Task is trivial (few tool calls)
• You need to see intermediate reasoning
• Splitting adds latency without benefit
• Task depends on main thread state mid-execution

Subagent Patterns