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 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

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:

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 provides excellent insights into the project’s design philosophy.

Repository Information:

• The project is hosted on GitHub under the repository 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:

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
• Harrison Chase’s Deep Agents Presentation
• Deep Wiki - Deep Agents Documentation