What is Deep Agents? A Batteries-Included AI Agent Framework

Mar 20, 2026

Purpose

Building AI agents from scratch is hard. I spent weeks wiring up prompts, tools, and context management before I got anything working. Then I discovered Deep Agents.

This post explains what Deep Agents is and why it matters. The key point is that it provides a production-ready agent architecture out of the box, with the same patterns used by Claude Code and other advanced AI applications.

Problem

I tried building agents the traditional way:

from langchain.agents import initialize_agent, Tool
from langchain_openai import ChatOpenAI

# Define basic tools
tools = [
    Tool(name="search", func=search, description="Search the web"),
    Tool(name="calculate", func=calculate, description="Do math")
]

# Initialize agent
llm = ChatOpenAI(model="gpt-4")
agent = initialize_agent(tools, llm, agent="zero-shot-react-description")

# Run agent
result = agent.run("What is 15% of 234?")

This works for simple tasks. But when I gave it complex, multi-step tasks, it failed:

User: Research the latest LangGraph features, write a summary, and save it to a file.

Agent: I'll help you with that.
[Agent searches for LangGraph features]
[Agent forgets what it was doing]
[Agent returns incomplete result without saving the file]

Result: "LangGraph is a framework for building agents..." (not saved anywhere)

Why did it fail?

No planning - Agent didn’t break down the task
No file operations - Agent couldn’t save results
No context management - Agent lost track of progress
No sub-agent delegation - Agent tried to do everything at once

What is Deep Agents?

Deep Agents is an “agent harness” from LangChain. It’s an opinionated, ready-to-run agent that works immediately.

From the README:

“Deep Agents is an agent harness. An opinionated, ready-to-run agent out of the box.”

The key insight: applications like Claude Code succeed because they implement four things:

Planning tool - Break down tasks, track progress
Sub-agents - Delegate work with isolated context
File system access - Read/write context files
Detailed prompts - Guide behavior precisely

Architecture Overview

Here’s how Deep Agents is structured:

┌─────────────────────────────────────────────────────────────┐
│                     Deep Agent                               │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  Planning   │  │ Filesystem  │  │   Shell     │         │
│  │ (write_todos)│  │ (read/write)│  │ (execute)   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                              │
│  ┌─────────────────────────────────────────────────┐       │
│  │              Sub-Agent Spawner                   │       │
│  │              (task tool)                         │       │
│  └─────────────────────────────────────────────────┘       │
│                                                              │
│  ┌─────────────────────────────────────────────────┐       │
│  │           Context Management                     │       │
│  │    (auto-summarization, large output files)     │       │
│  └─────────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
              ┌─────────────────────┐
              │   LangGraph Runtime │
              │ (streaming, persistence, checkpointing)
              └─────────────────────┘

Core Components

1. Planning with write_todos

The planning tool lets agents break down tasks and track progress:

Task: "Research LangGraph features and write a summary"

Todo List:
┌──────────────────────────────────────────┬──────────┐
│ Task                                     │ Status   │
├──────────────────────────────────────────┼──────────┤
│ 1. Search for LangGraph documentation    │ done     │
│ 2. Read key features from docs           │ done     │
│ 3. Write summary of features             │ in_progress │
│ 4. Save summary to file                  │ pending  │
└──────────────────────────────────────────┴──────────┘

This solves the “agent forgets what it’s doing” problem. The agent maintains a todo list and updates it as it works.

2. Filesystem Tools

Deep Agents includes full file operations:

Tool	Purpose
`read_file`	Read file contents
`write_file`	Create new files
`edit_file`	Make targeted edits
`ls`	List directory contents
`glob`	Find files by pattern
`grep`	Search file contents

This is crucial for context management. When the agent generates large outputs, it can save them to files instead of losing them in the chat history.

3. Shell Access

The execute tool runs shell commands:

# Agent can run commands
result = execute("pip install langgraph")

# With sandboxing support
result = execute("rm -rf /", sandbox=True)  # Blocked by sandbox

This gives agents real power to interact with the system.

4. Sub-Agent Spawning

The task tool spawns sub-agents with isolated context windows:

Main Agent
    │
    ├─── Task: "Research LangGraph" ───┐
    │                                   │
    │                            Sub-Agent A
    │                            (isolated context)
    │
    └─── Task: "Write summary" ────────┐
                                        │
                                 Sub-Agent B
                                 (isolated context)

This is the key to handling complex tasks. Instead of one agent trying to do everything, the main agent delegates to specialists.

5. Context Management

Deep Agents handles context automatically:

Large Output (>100KB) ───► Save to file ───► Return reference

┌──────────────┐         ┌──────────────┐         ┌──────────────┐
│ Agent Output │────────►│ Context Check│────────►│ Save to File │
│  (150KB)     │         │  (>100KB?)   │         │ output.txt   │
└──────────────┘         └──────────────┘         └──────────────┘
                                                         │
                                                         ▼
                         ┌──────────────────────────────────┐
                         │ Return: "Output saved to file"   │
                         │ Location: output.txt             │
                         └──────────────────────────────────┘

This prevents context overflow, a common problem with long-running agents.

Getting Started

Install Deep Agents:

pip install deepagents

Create a basic agent:

from deepagents import create_deep_agent

# Create a working agent immediately
agent = create_deep_agent()

# Run a complex task
result = agent.invoke({
    "messages": [
        {"role": "user", "content": "Research LangGraph features and write a summary file"}
    ]
})

print(result)

The agent will:

Break down the task (planning)
Search for information (shell/filesystem)
Delegate research to a sub-agent (task tool)
Write the summary to a file (filesystem)
Track progress throughout (todo list)

Comparison: Basic vs Deep Agents

Feature	Basic Agent	Deep Agents
Planning	Manual implementation	Built-in (write_todos)
File operations	Custom tools needed	Built-in (read/write/edit)
Shell access	Custom tool needed	Built-in (execute)
Sub-agents	Manual orchestration	Built-in (task tool)
Context management	Manual truncation	Auto-summarization
Production ready	Weeks of work	Out of the box

Under the Hood

Deep Agents is built on LangGraph:

from langgraph.graph import StateGraph
from langgraph.checkpoint.memory import MemorySaver

def create_deep_agent():
    """
    Create a compiled LangGraph with all middleware configured.
    Default model: Claude Sonnet 4.6
    """
    # Build the graph
    graph = StateGraph(AgentState)

    # Add nodes for each capability
    graph.add_node("planner", planner_node)
    graph.add_node("tools", tool_node)
    graph.add_node("context_manager", context_node)

    # Compile with persistence
    return graph.compile(
        checkpointer=MemorySaver()
    )

Key technical details:

Default model: Claude Sonnet 4.6
Runtime: LangGraph (streaming, persistence, checkpointing)
License: MIT
Provider agnostic: Works with any LLM supporting tool calling

When to Use Deep Agents

Good fit:

Complex multi-step tasks
Tasks requiring file I/O
Research and synthesis workflows
Code generation and modification
Tasks needing progress tracking

Not ideal:

Simple single-step queries
Chat-only applications
When you need minimal dependencies

My Experience

I tried Deep Agents for a documentation research task. Before Deep Agents:

My manual process:
1. Open browser
2. Search for documentation
3. Copy relevant sections
4. Paste into editor
5. Organize manually
6. Save file

Time: ~30 minutes
Error rate: Forgot to save twice

With Deep Agents:

agent = create_deep_agent()
result = agent.invoke({
    "messages": [
        {"role": "user", "content": "Research LangGraph checkpointer features and save a summary to checkpointer-summary.md"}
    ]
})

Agent process:
1. Broke down task into 4 subtasks
2. Spawned sub-agent for research
3. Compiled findings
4. Saved to checkpointer-summary.md

Time: ~2 minutes
Error rate: None (agent tracked progress)

Summary

Deep Agents is a batteries-included agent harness from LangChain. It provides a working agent immediately with planning, filesystem tools, shell access, sub-agent spawning, and context management built in.

The key insight is that successful AI applications (Claude Code, Deep Research, Manus) all implement the same pattern: planning + sub-agents + file access + detailed prompts. Deep Agents packages this pattern into a ready-to-use framework.

For developers tired of wiring up basic agent infrastructure, Deep Agents offers a production-ready starting point. The code is open source, the architecture is proven, and the default model (Claude Sonnet 4.6) handles complex reasoning well.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!