---
title: "Deep Agents Part 1: Beyond 'Shallow' – Introducing Deep Agents"
description: "Exploring the evolution from simple single-step AI agents to sophisticated 'Deep Agents' capable of handling complex, long-horizon tasks with advanced planning and execution capabilities"
author: "Colin McNamara"
tags: ["AI","LangGraph","Python","Open Source","Agent Architecture"]
date: 2025-08-05
url: https://colinmcnamara.com/blog/deep-agents-part-1-beyond-shallow
---

# Deep Agents Part 1: Beyond 'Shallow' – Introducing Deep Agents

In the dynamic landscape of Artificial Intelligence, Large Language Models (LLMs) have ushered in an era of intelligent agents capable of interacting, reasoning, and performing tasks. However, a significant limitation quickly emerged: while these agents excel at simple, single-step operations, they often falter when confronted with more intricate problems demanding sustained planning, deep analysis, and long-term execution.

This is the fundamental distinction that the [deepagents Python library](https://github.com/hwchase17/deepagents) seeks to address.

## The Core Problem: Why "Shallow" Agents Fall Short

A "shallow" agent typically performs simple, single-step tasks by calling tools in a basic loop. While useful for straightforward operations, these agents struggle when faced with:

- Multi-step problems requiring sustained context
- Tasks demanding long-term planning and execution
- Complex workflows needing deep analysis of various problem aspects
- Situations requiring delegation and parallel task management

In contrast, a "Deep Agent" is an AI agent designed to handle longer, more complex tasks by employing advanced planning and execution capabilities. Unlike shallow agents that might struggle with maintaining context over time, deep agents can:

- Plan over longer time horizons
- Delve deeply into complex problems
- Maintain context and focus throughout prolonged, multi-faceted activities
- Delegate subtasks to specialized sub-agents

```mermaid
graph TD
 subgraph "Shallow Agent Architecture"
 SU["User Input"] ---> SL["LLM"]
 SL ---> ST["Tool Call"]
 ST ---> SL
 SL ---> SO["Simple Output"]
 end
 
 subgraph "Deep Agent Architecture"
 DU["User Input"] ---> DA["create_deep_agent"]
 DA ---> DP["Planning Tool"]
 DA ---> DFS["File System Tools"]
 DA ---> DSA["Sub-Agent System"]
 DA ---> DPR["System Prompts"]
 
 DP ---> DL["LangGraph Engine"]
 DFS ---> DL
 DSA ---> DL
 DPR ---> DL
 
 DL ---> DO["Structured Output + Files"]
 end
```

## The "Aha!" Moment: Inspiration and Project Origins

The development of deepagents was not conceived in a vacuum. It drew substantial inspiration from existing applications that had already demonstrated advanced agentic behavior.

The project was primarily inspired by **Claude Code**, an application developed by Anthropic that showcased advanced capabilities, particularly in tasks like code generation. The initial objective behind deepagents was to generalize and enhance Claude Code's inherent, general-purpose capabilities, making them more widely accessible and adaptable.

Other significant conceptual contributors included applications like "Deep Research" and "Manus". These applications highlighted how specific architectural components could be combined to create more capable and robust agents.

The overarching goal was to translate these demonstrated "deep" agent behaviors into a general-purpose Python package that any developer could use.

## The Four Pillars of Deep Agent Architecture

To achieve the sophisticated capabilities of a "Deep Agent," the deepagents library integrates four key architectural components. These pillars work in concert to empower agents to tackle complex, multi-step tasks effectively:

```mermaid
graph TB
 subgraph "deepagents Package"
 CDA["create_deep_agent()"]
 
 subgraph "Required Parameters"
 TOOLS["tools: List[Callable]"]
 INST["instructions: str"]
 end
 
 subgraph "Optional Parameters"
 SUB["subagents: List[SubAgent]"]
 MOD["model: ChatAnthropic"]
 end
 
 subgraph "Built-in Components"
 PT["Planning Tool"]
 FST["File System Tools<br/>ls, read_file, write_file, edit_file"]
 SP["System Prompts"]
 GPS["general-purpose SubAgent"]
 end
 
 subgraph "Output"
 LG["LangGraph Agent"]
 end
 end
 
 TOOLS ---> CDA
 INST ---> CDA
 SUB ---> CDA
 MOD ---> CDA
 
 CDA ---> PT
 CDA ---> FST
 CDA ---> SP
 CDA ---> GPS
 
 PT ---> LG
 FST ---> LG
 SP ---> LG
 GPS ---> LG
```

### 1. A Planning Tool
This component empowers the agent to formulate and track a structured plan, often taking the form of a to-do list. It's crucial for helping the agent manage complex tasks and maintain its focus over time.

### 2. Sub-Agents
These are specialized, modular agents that the main agent can delegate specific sub-tasks to. Sub-agents are vital for "context quarantine" (isolating specific sub-tasks to prevent the main agent's context from becoming polluted) and for applying custom instructions to focused operations.

### 3. Access to a File System (Virtual)
Deep Agents can interact with a simulated, in-memory file system to persist information across different steps of a task. This virtual file system (represented as a dictionary) allows agents to read, write, and edit files, which is essential for tasks like research, report generation, or code development.

The use of a virtual system rather than a real one is a key design choice – it's "a lot easier to scale this" and avoids conflicts when running multiple agents concurrently.

### 4. A Detailed System Prompt
A comprehensive and meticulously crafted set of instructions is provided to the LLM to guide its core behavior. This prompt dictates how the agent should effectively utilize its tools, manage workflows, and maintain its "deep" capabilities. The importance of this prompt for creating a "deep" agent cannot be understated.

## Behind the Scenes: Project Details & Technical Foundation

The deepagents project is released as a Python package, making it readily usable for developers. Harrison Chase's [presentation on Deep Agents](https://www.youtube.com/watch?v=TTMYJAw5tiA) provides excellent insights into the project's design philosophy.

### Repository Information:
- The project is hosted on GitHub under the repository [hwchase17/deepagents](https://github.com/hwchase17/deepagents)
- As of writing, the repository has garnered significant community interest with over 1.1k stars and 134 forks
- It operates under the MIT License
- The project's codebase is entirely in Python (100.0%)
- Key contributors include Harrison Chase (hwchase17), who is a prominent figure in the project, alongside amrrs, ryaneggz, and HanzlaJavaid

### Technical Foundation (High-Level):
- deepagents is fundamentally built on top of **LangGraph**, which serves as its robust agent runtime
- Agents created using `create_deep_agent` are essentially LangGraph graphs
- The core algorithm relies on LangGraph's `create_react_agent` wrapper, implementing a "react agent" loop where the LLM decides whether to stop or take an action, receives feedback, and continues the iterative loop
- The project uses a custom `DeepAgentState` object, which inherits from LangGraph's `AgentState`

## Getting Started: Installation and Default Model

### Requirements
- Python 3.11 or higher
- Core dependencies: `langgraph`, `langchain`, `langchain-anthropic`

To begin using Deep Agents, the package can be easily installed via pip:

```bash
pip install deepagents
```

When creating a Deep Agent using the `create_deep_agent` function, you have the option to specify a custom LangChain model object. However, deepagents comes with a sensible default:

> By default, deepagents will use `claude-sonnet-4-20250514` with a 64,000 token context window

This default model is chosen with a high `max_tokens` value (64,000). This is a deliberate choice because deep agents often require extensive writing for outputs such as comprehensive research reports, making a large output token limit crucial for their effectiveness.

## What's Next?

In the next part of this series, we'll dive deeper into the technical foundations of deepagents, exploring LangGraph and the DeepAgentState object that manages the agent's complex operations and persistent information.

---

*This is Part 1 of a 4-part series on Deep Agents. Stay tuned for tomorrow's post where we'll explore the technical foundation that makes Deep Agents possible.*

**Learn more:**
- [Deep Agents GitHub Repository](https://github.com/hwchase17/deepagents)
- [Harrison Chase's Deep Agents Presentation](https://www.youtube.com/watch?v=TTMYJAw5tiA)
- [Deep Wiki - Deep Agents Documentation](https://deepwiki.com/hwchase17/deepagents)