# DeepAgents - Deep Dive

> **TL;DR**: DeepAgents is LangChain AI's open-source agent harness that implements "Agents 2.0" architecture - moving beyond simple tool-calling loops to agents with explicit planning, external memory, and subagent delegation. Inspired by Claude Code, it enables AI agents to tackle 100+ step tasks without losing context or forgetting their goals.

---

## The Problem: Why Shallow Agents Fail

Traditional AI agents (what DeepAgents calls "Shallow Agents" or "Agent 1.0") work like this:

```
User Prompt → LLM → Tool Call → Execute → Result → Loop
```

This seems fine for simple tasks. But as tasks get complex, shallow agents hit a wall:

### The Five Fatal Flaws

| Problem | What Happens | Example |
|---------|--------------|---------|
| **Context Overflow** | Tool outputs fill the context window, pushing original instructions out | Agent forgets the task after processing large HTML files |
| **Loss of Goal** | Amid 100s of intermediate steps, agent loses focus | Started building login, ends up refactoring unrelated code |
| **Implicit Planning** | Plans only via chain-of-thought ("I think I should...") | No way to track progress or recover from failures |
| **No Backtracking** | When wrong path taken, agent rarely recognizes and recovers | Keeps trying same failed approach repeatedly |
| **Cost Explosion** | Long task sequences = massive token consumption | Simple research task costs $50+ in API calls |

### The Scale Problem

> "Agent task length is doubling every 7 months, yet shallow architecture hasn't evolved."

- Shallow agents excel at **5-15 step tasks**
- They fail catastrophically at **100+ step tasks**
- Production systems need **500+ step capabilities**

---

## What is DeepAgents?

DeepAgents is an **agent harness** (not a framework) that implements the "Agents 2.0" architecture. Built by LangChain AI, it's directly inspired by successful production systems:

- **Claude Code** (Anthropic) - Planning, filesystem access, detailed prompts
- **Manus** (Microsoft) - Filesystem for long-running memory
- **Deep Research** (Anthropic) - Hierarchical research patterns

### Key Insight

> "Instead of trying to build monolithic 'superintelligent' models with thousands of specialized tools, the breakthrough came from elegant, reusable, well-defined components composed into a coherent system."

---

## The Four Pillars of Deep Agents

```
┌─────────────────────────────────────────────────────────────────────┐
│                    DEEP AGENTS ARCHITECTURE                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────────┐    ┌──────────────────┐                      │
│  │  PILLAR 1        │    │  PILLAR 2        │                      │
│  │  Explicit        │    │  Filesystem      │                      │
│  │  Planning        │    │  Backend         │                      │
│  │                  │    │                  │                      │
│  │  write_todos     │    │  read_file       │                      │
│  │  read_todos      │    │  write_file      │                      │
│  │  update status   │    │  edit_file       │                      │
│  └────────┬─────────┘    └────────┬─────────┘                      │
│           │                       │                                 │
│           └───────────┬───────────┘                                 │
│                       │                                             │
│              ┌────────▼────────┐                                    │
│              │   DEEP AGENT    │                                    │
│              │   (LangGraph)   │                                    │
│              └────────┬────────┘                                    │
│                       │                                             │
│           ┌───────────┴───────────┐                                 │
│           │                       │                                 │
│  ┌────────▼─────────┐    ┌───────▼──────────┐                      │
│  │  PILLAR 3        │    │  PILLAR 4        │                      │
│  │  Subagent        │    │  Context         │                      │
│  │  Delegation      │    │  Engineering     │                      │
│  │                  │    │                  │                      │
│  │  task tool       │    │  system prompts  │                      │
│  │  orchestrator    │    │  few-shot        │                      │
│  │  specialists     │    │  middleware      │                      │
│  └──────────────────┘    └──────────────────┘                      │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### Pillar 1: Explicit Planning

Instead of implicit chain-of-thought planning, agents create **structured todo lists**:

```python
# Agent uses write_todos tool
write_todos([
    {"task": "Research existing auth implementations", "status": "completed"},
    {"task": "Design database schema", "status": "in_progress"},
    {"task": "Implement JWT middleware", "status": "pending"},
    {"task": "Write integration tests", "status": "pending"},
    {"task": "Update API documentation", "status": "pending"}
])
```

**Benefits**:
- Explicit progress tracking
- Easy to spot when stuck
- Plans adapt as new information emerges
- Failed steps get marked and alternatives tried

### Pillar 2: Filesystem Backend

Instead of accumulating tool outputs in context, agents **offload to files**:

| Tool | Purpose |
|------|---------|
| `ls` | List files and directories |
| `read_file` | Read file contents |
| `write_file` | Create new files |
| `edit_file` | Modify existing files |
| `glob` | Pattern-based file matching |
| `grep` | Search file contents |

**Why This Matters**:
- Large API responses → stored in `/workspace/data.json`
- Research notes → stored in `/workspace/research/`
- Code snippets → stored in `/workspace/code/`
- Context window stays clean and focused

### Pillar 3: Subagent Delegation

Complex tasks get broken into **isolated subagents**:

```
Orchestrator Agent
    │
    ├── task("research_specialist", "Find best auth libraries")
    │       └── Returns: "JWT recommended, analysis in /research/auth.md"
    │
    ├── task("code_specialist", "Implement JWT based on /research/auth.md")
    │       └── Returns: "Implementation complete in /src/auth/"
    │
    └── task("test_specialist", "Write tests for /src/auth/")
            └── Returns: "15 tests passing, coverage 94%"
```

**Benefits**:
- Each subagent starts with **clean context**
- Specialists can have **custom tools and prompts**
- Failures are **isolated** - one bad subagent doesn't crash everything
- **Parallel execution** possible

### Pillar 4: Context Engineering

DeepAgents uses **comprehensive system prompts** inspired by Claude Code:

- Detailed instructions for each scenario
- Few-shot examples of proper tool usage
- Error handling and recovery guidance
- State management instructions

**Surprising Finding**: Effective deep agents use remarkably few tools:
- Claude Code: ~12 tools
- Manus: <20 tools

The key is giving agents access to a **computer** (bash + filesystem) rather than specialized tools for every task.

---

## How It Works Technically

### Installation

```bash
# Core package
pip install deepagents

# CLI with terminal UI
pip install deepagents-cli

# Evaluation framework
pip install deepagents-harbor
```

**Requirements**:
- Python 3.11+
- Anthropic API key (for default Claude Sonnet model)

### Basic Usage

```python
from deepagents import create_deep_agent

# Create agent with defaults
agent = create_deep_agent()

# Or with customization
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    tools=[custom_tool_1, custom_tool_2],
    system_prompt="You are a coding assistant specialized in Python..."
)

# Invoke the agent
result = agent.invoke({
    "messages": [{"role": "user", "content": "Build a REST API for user management"}]
})
```

### Default Middleware Stack

DeepAgents comes with battle-tested middleware:

| Middleware | What It Does |
|------------|--------------|
| **TodoListMiddleware** | Task planning and progress tracking |
| **FilesystemMiddleware** | File operations and context offloading |
| **SubAgentMiddleware** | Subagent spawning and delegation |
| **PatchToolCallsMiddleware** | Tool call handling and validation |
| **SummarizationMiddleware** | Auto-summarizes when context exceeds 170K tokens |
| **HumanInTheLoopMiddleware** | Interrupt points for human approval |
| **AnthropicPromptCachingMiddleware** | Token efficiency optimization |

### Architecture Diagram

```
┌─────────────────────────────────────────────────────────────────┐
│                     DEEPAGENTS EXECUTION FLOW                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   User Request                                                  │
│        ↓                                                        │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │  Middleware Stack                                        │   │
│   │  ├── System prompt injection                             │   │
│   │  ├── Tool availability                                   │   │
│   │  └── Context management                                  │   │
│   └─────────────────────────────────────────────────────────┘   │
│        ↓                                                        │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │  LangGraph StateGraph                                    │   │
│   │  ├── State: messages, todos, files                       │   │
│   │  ├── Nodes: agent, tools, subagents                      │   │
│   │  └── Edges: conditional routing                          │   │
│   └─────────────────────────────────────────────────────────┘   │
│        ↓                                                        │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │  Execution Loop                                          │   │
│   │  1. Read context (messages, files, todos)                │   │
│   │  2. LLM generates action (tool call or response)         │   │
│   │  3. Middleware processes tool calls                      │   │
│   │  4. Tool executes in sandbox                             │   │
│   │  5. Result fed back, context updated                     │   │
│   │  6. Loop until task complete                             │   │
│   └─────────────────────────────────────────────────────────┘   │
│        ↓                                                        │
│   Final Response                                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## Real-World Patterns

### Pattern 1: Multi-Day Development Project

```python
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="/workspace/my-project"),
    system_prompt="""
    You are a senior developer. For any feature request:

    1. PLANNING PHASE
       - write_todos with detailed breakdown
       - Each todo should be completable in 1-2 hours
       - Include testing and documentation todos

    2. IMPLEMENTATION PHASE
       - Work through todos in order
       - Store all code in /workspace/
       - Mark todos as you complete them

    3. REVIEW PHASE
       - Run tests (bash tool)
       - Update documentation
       - Mark remaining todos complete
    """
)
```

### Pattern 2: Research with Subagents

```python
agent = create_deep_agent(
    system_prompt="""
    For research tasks, use subagents:

    1. task("search_specialist", "Find sources on [topic]")
    2. task("analysis_specialist", "Analyze findings in /research/")
    3. task("synthesis_specialist", "Create summary report")

    Store all intermediate findings in /workspace/research/
    Final report goes in /workspace/report.md
    """
)
```

### Pattern 3: Error Recovery

```python
agent = create_deep_agent(
    system_prompt="""
    When tools fail:

    1. DON'T retry blindly
    2. Update todos to mark failure: "Step 1 (FAILED: timeout)"
    3. Add alternative approach as new todo
    4. Store error details in /workspace/errors.md
    5. Try the alternative

    Example recovery:
    - "Install package via pip" (FAILED: network error)
    - "Install package via conda" (NEW: trying alternative)
    """
)
```

---

## DeepAgents vs Other Frameworks

### Position in the AI Agent Stack

```
┌─────────────────────────────────────────────────────────────────┐
│                         AI AGENT STACK                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  FRAMEWORK LAYER (Define)                                       │
│  ├── LangChain: Workflows and tool bindings                     │
│  ├── CrewAI: Role-based collaborative agents                    │
│  └── AutoGen: Multi-agent coordination                          │
│                                                                 │
│  RUNTIME LAYER (Execute)                                        │
│  └── LangGraph: Stateful agent execution ← DeepAgents uses this │
│                                                                 │
│  HARNESS LAYER (Validate & Test)                                │
│  └── DeepAgents: Opinionated defaults + testing ← THIS          │
│                                                                 │
│  DEPLOYMENT LAYER (Serve)                                       │
│  ├── Modal: Serverless execution                                │
│  ├── Daytona: Cloud development                                 │
│  └── LangServe: API hosting                                     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Comparison Table

| Aspect | DeepAgents | LangGraph | CrewAI | AutoGen |
|--------|-----------|----------|--------|---------|
| **Type** | Harness | Runtime | Framework | Framework |
| **Use Case** | Production defaults | Custom workflows | Team-based agents | Research |
| **Learning Curve** | Low | Moderate | Low | High |
| **Planning** | Built-in | Manual | Limited | Limited |
| **Filesystem** | Built-in | Manual | Limited | Limited |
| **Subagents** | Built-in | Manual | Teams | Limited |
| **Best For** | Long-horizon tasks | Maximum control | Collaborative | Experiments |

### Key Distinction

**DeepAgents is a wrapper, not a replacement:**

- Write agents with **LangChain** (define)
- Deploy with **LangGraph** (runtime)
- Test with **DeepAgents** (validation)

---

## The LangChain AI Ecosystem

DeepAgents is part of a larger ecosystem:

| Tool | Purpose |
|------|---------|
| **LangChain** | Core framework for LLM apps |
| **LangGraph** | Graph-based orchestration (DeepAgents' runtime) |
| **LangSmith** | Observability and debugging |
| **LangServe** | Deployment and API serving |
| **DeepAgents** | Opinionated agent harness |

### Related Repositories

| Repo | What It's For |
|------|---------------|
| `deepagents` | Core Python library |
| `deepagents-cli` | Terminal UI with sandbox providers |
| `deepagents-harbor` | Evaluation framework |
| `deepagentsjs` | JavaScript implementation |
| `deepagents-quickstarts` | Pre-built example patterns |

---

## Market Context & Adoption

### AI Agent Market (2025-2026)

| Metric | Value |
|--------|-------|
| Global AI agents market (2025) | $7.6B |
| Projected market (2034) | ~$200B |
| CAGR (2025-2030) | 45.8% |
| Executives increasing AI budgets | 88% |
| Enterprises with agents in production | 57% |
| Fortune 500 using agent/copilot builders | 90% |

### Real-World Performance

- **ServiceNow**: 52% reduction in customer service handling time
- **Human-AI teams**: 60% more productive than human-only teams
- **Coding agents**: From 13.86% (2024) to 80%+ task completion (2025)

---

## How DeepAgents Can Help Us Achieve Our Goals

Looking at our "Software Development in the Age of AI" repository, DeepAgents connects directly to our mission:

### 1. **Solves the Context Problem We Document**

Our repo discusses how AI "forgets" context. DeepAgents provides concrete solutions:

| Our Documentation | DeepAgents Solution |
|-------------------|---------------------|
| Context window limits | Filesystem backend offloading |
| Losing track of goals | Explicit todo planning |
| No memory between sessions | Persistent filesystem storage |
| Single-threaded execution | Subagent delegation |

### 2. **Complements Our Other Deep Dives**

| Our Deep Dive | DeepAgents Connection |
|---------------|----------------------|
| **CCPM** | Both use explicit planning; DeepAgents is the execution layer |
| **Vibe Kanban** | Both solve parallel agent execution; different interfaces |
| **MCP Servers** | DeepAgents can use MCP tools via LangChain integration |
| **Parlant** | Both emphasize structured agent behavior |
| **olmOCR** | DeepAgents can orchestrate document processing pipelines |

### 3. **Enables Our Playbook Vision**

We can create playbooks that leverage DeepAgents:

| Playbook | DeepAgents Pattern |
|----------|-------------------|
| "Implementing a feature" | Planning → subagent delegation → review |
| "Debugging complex issues" | Systematic investigation with file storage |
| "Code review automation" | Multi-agent analysis with different specialists |
| "Documentation generation" | Orchestrator with writer/reviewer subagents |

### 4. **Aligns with Our Philosophy**

- **Open source** (like all our documented tools)
- **Transparent architecture** (middleware is inspectable)
- **Production-ready** (tested patterns, not research prototypes)
- **Composable** (use what you need, skip what you don't)

### 5. **Practical Application**

For developers using Claude Code (our primary focus), DeepAgents explains **why** Claude Code works:
- The planning system (todos)
- The filesystem access
- The detailed system prompts
- The subagent patterns

Understanding DeepAgents helps you build your own Claude Code-like experiences.

---

## Quick Reference

### Installation

```bash
pip install deepagents
export ANTHROPIC_API_KEY="your-key"
```

### Basic Agent

```python
from deepagents import create_deep_agent

agent = create_deep_agent()
result = agent.invoke({
    "messages": [{"role": "user", "content": "Your task here"}]
})
```

### With Custom Tools

```python
from langchain_core.tools import tool

@tool
def my_tool(input: str) -> str:
    """Tool description"""
    return "result"

agent = create_deep_agent(tools=[my_tool])
```

### With Filesystem

```python
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="/workspace")
)
```

---

## Key Links

| Resource | URL |
|----------|-----|
| GitHub Repository | https://github.com/langchain-ai/deepagents |
| Documentation | https://docs.langchain.com/oss/python/deepagents |
| LangChain Blog | https://blog.langchain.com/deep-agents/ |
| Deep Agents Quickstarts | https://github.com/langchain-ai/deepagents-quickstarts |
| LangGraph | https://github.com/langchain-ai/langgraph |
| LangSmith | https://smith.langchain.com/ |

---

## Quick Stats

| Metric | Value |
|--------|-------|
| Creator | LangChain AI |
| Release | October 2025 |
| License | Open Source |
| Default Model | Claude Sonnet 4.5 |
| Python Version | 3.11+ |
| Core Dependencies | LangChain, LangGraph |
| Package | `pip install deepagents` |
| Latest Version | 0.2.9 (Dec 2025) |

---

## Bottom Line

DeepAgents represents the evolution from "AI that helps you code" to "AI that can code autonomously on complex projects."

**The key insight**: Shallow agents fail at long tasks not because LLMs aren't smart enough, but because the **architecture** doesn't support it. DeepAgents provides that architecture:

1. **Explicit planning** so agents don't lose track of goals
2. **Filesystem backend** so context doesn't overflow
3. **Subagent delegation** so complex tasks decompose cleanly
4. **Context engineering** so agents know how to behave

If you've ever watched an AI agent spiral into confusion on a complex task, DeepAgents explains why and provides the solution. It's the architecture behind successful production systems like Claude Code, now available as open-source components you can use in your own agents.

For our repository focused on AI-assisted development, DeepAgents is essential knowledge - it's the blueprint for how modern AI coding assistants actually work.

---

*Document created: January 2026*
*Sources: [GitHub - langchain-ai/deepagents](https://github.com/langchain-ai/deepagents), [LangChain Blog](https://blog.langchain.com/deep-agents/), [LangChain Documentation](https://docs.langchain.com/oss/python/deepagents), [Agents 2.0 Overview](https://www.philschmid.de/agents-2.0-deep-agents)*
