---
title: "Deep Agents Part 3: Built-in Tools and Customization"
description: "Exploring the powerful built-in tools that make Deep Agents capable of complex tasks: planning tools, virtual file systems, sub-agent delegation, and extensive customization options"
author: "Colin McNamara"
tags: ["AI","Tools","Python","Agent Customization","Software Architecture"]
date: 2025-08-07
url: https://colinmcnamara.com/blog/deep-agents-part-3-tools-customization
---

# Deep Agents Part 3: Built-in Tools and Customization

The true "deepness" of the [deepagents library](https://github.com/hwchase17/deepagents) emerges from its suite of specialized built-in tools and the extensive customization options available to users. These components empower agents to perform complex tasks, manage information, and delegate responsibilities effectively.

## Built-in Tools: The Agent's Toolkit

The deepagents library comes equipped with several crucial built-in tools that are fundamental to its operation. These tools interact primarily with the agent's internal `DeepAgentState`, particularly the `to-dos` and `files` attributes.

### 1. Planning Tool (write_to_dos)

The planning tool is the cornerstone of what makes a "Deep Agent" deep. It's designed to help the agent formulate and update its plan by creating and managing a "to-do" list.

**Key Features:**
- Based on ClaudeCode's TodoWrite tool
- Updates the `to-dos` attribute within the `DeepAgentState`
- **Important**: Overwrites the entire to-dos list with the LLM-generated payload (not incremental updates)
- This design helps the agent keep the full plan in context
- Includes a 140-180 line detailed description embedded within the tool definition itself
- After updating, inserts a confirmation message into the agent's context window

**Why It Matters:**
The planning tool enables agents to:
- Break down complex tasks into manageable steps
- Track progress across long-running operations
- Maintain focus and context over extended periods
- Adapt plans based on intermediate results

**Task State Management:**
```mermaid
stateDiagram-v2
 [*] --> pending
 pending --> in_progress : Agent starts task
 in_progress --> completed : Task finished
 in_progress --> pending : Task paused/deferred
 completed --> [*]
 
 note right of pending : Initial state when todo created
 note right of in_progress : Agent actively working on task 
 note right of completed : Task successfully finished
```

The extensive description guides the LLM on:
- When and when not to use the tool
- Usage examples and best practices
- How to manage task states ('pending', 'in progress', 'completed')
- Real-time status updates

### 2. File System Tools

The virtual file system is a game-changer for agent persistence and information management. As detailed in [Harrison Chase's presentation](https://www.youtube.com/watch?v=TTMYJAw5tiA), this system operates as a dictionary within LangGraph's State object.

```mermaid
graph TB
 subgraph "File System Tools"
 LS["ls()"]
 READ["read_file()"]
 WRITE["write_file()"]
 EDIT["edit_file()"]
 end
 
 subgraph "Mock File System"
 STATE["DeepAgentState.files"]
 DICT["Dict[str, str]"]
 end
 
 subgraph "Tool Operations"
 LIST["List Operations"]
 READ_OP["Read Operations"]
 WRITE_OP["Write Operations"] 
 EDIT_OP["Edit Operations"]
 end
 
 LS ---> STATE
 READ ---> STATE
 WRITE ---> STATE
 EDIT ---> STATE
 
 STATE ---> DICT
 
 LS ---> LIST
 READ ---> READ_OP
 WRITE ---> WRITE_OP
 EDIT ---> EDIT_OP
```

**The Four Tools:**

#### ls
Lists the names of files (the keys of the files dictionary) present in the virtual file system. This helps agents understand what information is available.

#### read_file
Reads content from a specified file with sophisticated features:
- Supports line offsets and limits for large files (default: 2,000 lines)
- **Important**: Truncates lines longer than 2,000 characters to prevent context overflow
- Detailed description inspired by Claude Code
- Specific return format handling for empty files
- Returns content in `cat -n` format with line numbers

#### write_file
Writes content to a file:
- Overwrites existing content if the file already exists
- Sends a tool message confirming the update
- Enables agents to persist analysis results, generated code, or research findings

#### edit_file
Performs exact string replacements within files:
- Uses string replacement rather than line-based patching
- Claude models are explicitly "trained on this str_replace functionality"
- Includes checks for string existence and uniqueness before replacement
- Prevents common editing errors

**Virtual File System Advantages:**
- **Scalability**: "A lot easier to scale" without file I/O overhead
- **Concurrency**: Avoids conflicts when running multiple agents
- **Isolation**: Each agent has its own file space
- **Simplicity**: No need for complex file permissions or directory management

### 3. Sub-Agents (Task Tool)

The ability to delegate to sub-agents is perhaps the most powerful feature of deepagents, enabling true hierarchical task decomposition.

```mermaid
graph TB
 subgraph "Main Deep Agent"
 MA["Main Agent<br/>(LangGraph ReAct)"]
 TT["task Tool"]
 MS["Main State<br/>(DeepAgentState)"]
 end
 
 subgraph "Sub-Agent Registry"
 GP["general-purpose<br/>(Built-in)"]
 CS1["Custom Sub-Agent 1"]
 CS2["Custom Sub-Agent 2"]
 end
 
 subgraph "Sub-Agent Execution"
 SA["Selected Sub-Agent<br/>(LangGraph ReAct)"]
 SS["Sub-Agent State<br/>(Isolated Context)"]
 ST["Sub-Agent Tools"]
 end
 
 subgraph "Task Flow"
 TD["Task Description"]
 SAT["Sub-Agent Type"]
 TR["Task Result"]
 end
 
 MA ---> TT
 TT ---> TD
 TT ---> SAT
 TD ---> SA
 SAT ---> SA
 SA ---> SS
 SA ---> ST
 SA ---> TR
 TR ---> MS
 
 TT -.- GP
 TT -.- CS1
 TT -.- CS2
```

#### General-Purpose Sub-Agent
A default "general-purpose" sub-agent is always available:
- Possesses the same instructions and tools as the main agent
- Can handle any task the main agent can
- Useful for parallel processing or context isolation

#### Custom Sub-Agents
Users can define specialized sub-agents by providing:
- **name**: How the main agent will call it
- **description**: What the sub-agent specializes in
- **prompt**: Custom instructions for the sub-agent
- **tools**: Optional list of specific tools (defaults to all available tools)

#### Benefits of Sub-Agents

**Context Quarantine:**
Sub-agents prevent the main agent's context from being polluted. When invoked:
- The sub-agent receives a fresh context with only a single user message
- The main agent's conversation history is "wiped out" from the sub-agent's view
- Only the final message and file changes are returned to the main agent

**Specialized Processing:**
Sub-agents can be tailored for specific tasks:
- Research sub-agent with internet search tools
- Code analysis sub-agent with syntax checking
- Data processing sub-agent with numerical tools

**Parallel Execution:**
Multiple sub-agents can work simultaneously on different aspects of a problem.

## Customization via create_deep_agent

The `create_deep_agent` function is the primary entry point for users to instantiate and tailor a Deep Agent. It allows for extensive customization through several parameters:

### Required Parameters

#### tools
A list of functions or LangChain @tool objects that the main agent (and any sub-agents) will have access to. This is how you provide external capabilities like:
- Internet search tools
- Database access
- API integrations
- Custom business logic

```python
def internet_search(query: str) -> str:
    """Search the internet for information."""
    # Implementation here
    return results

tools = [internet_search]
```

#### instructions
A string of text that serves as part of the deep agent's prompt. This allows you to tailor the agent's behavior or role for specific tasks:

```python
instructions = """You are an expert researcher specializing in 
quantum computing. Focus on peer-reviewed sources and provide 
citations for all claims."""
```

### Optional Parameters

#### subagents
Define custom sub-agents that the main agent can utilize:

```python
subagents = [
    {
        "name": "data_analyst",
        "description": "Analyzes numerical data and creates visualizations",
        "prompt": "You are a data analysis expert...",
        "tools": [analyze_data, create_chart]
    }
]
```

#### model
Specify a custom LangChain model object. By default, deepagents uses:
> "claude-sonnet-4-20250514" with a high max_tokens value

This default is chosen because deep agents often require extensive writing for outputs like research reports.

#### state_schema
For tracking additional information beyond the default state attributes, you can pass a custom state schema that must inherit from `DeepAgentState`:

```python
class CustomDeepAgentState(DeepAgentState):
    project_metadata: dict = {}
    api_calls_count: int = 0
```

## The Importance of the System Prompt

While customizable instructions and explicit tool definitions are provided, the built-in system prompt is crucial:

### Foundation of Behavior
The deepagents library includes a detailed system prompt heavily inspired by Claude Code's prompt. This prompt provides:
- Detailed instructions on tool usage
- Workflow management guidelines
- Best practices for maintaining "deep" capabilities

### Tool Descriptions as Prompting
Much of the complexity and detailed guidance comes from the extensive descriptions of the built-in tools themselves. These descriptions:
- Guide the LLM on when and how to use each tool
- Provide examples and edge cases
- Establish patterns for effective tool usage

### Customization Balance
While the core system prompt is built-in, the `instructions` parameter allows you to:
- Add domain-specific knowledge
- Override certain behaviors
- Establish role-specific guidelines

The roadmap indicates future work to allow users to customize the full system prompt for even greater control.

## Real-World Applications

With these tools and customization options, Deep Agents can tackle complex real-world tasks:

- **Research Projects**: Break down research questions, gather information, synthesize findings
- **Code Development**: Plan features, implement code, write tests, document results
- **Data Analysis**: Load data, perform analysis, generate reports, create visualizations
- **Content Creation**: Research topics, create outlines, write drafts, revise content

## What's Next?

In our final post tomorrow, we'll cover practical usage patterns, integration with other tools, and the exciting roadmap for future developments in the deepagents project.

---

*This is Part 3 of a 4-part series on Deep Agents. Tomorrow we'll explore practical implementation, integration options, and the future roadmap of the deepagents project.*

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