Deep Agents Part 3: Built-in Tools and Customization

The true “deepness” of the deepagents library 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:

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, this system operates as a dictionary within LangGraph’s State object.

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.

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

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:

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:

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:

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