Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bytedance/deer-flow/llms.txt

Use this file to discover all available pages before exploring further.

Tools extend the agent’s capabilities, enabling it to interact with external systems, execute code, and perform specialized tasks.

​
Tool Architecture

DeerFlow’s tools come from multiple sources: 
Tools
├── Sandbox Tools      (bash, ls, read_file, write_file, str_replace)
├── Built-in Tools     (present_files, ask_clarification, view_image)
├── Community Tools    (web_search, web_fetch, image_search)
├── MCP Tools          (External tools via Model Context Protocol)
├── Sub-agent Tool     (task - delegate to sub-agents)
└── Custom Tools       (User-defined via config.yaml)

​
Tool Loading

Tools are assembled via get_available_tools(): 
from src.tools import get_available_tools

tools = get_available_tools(
    groups=["sandbox", "research"],  # From config.yaml
    include_mcp=True,                # Include MCP tools
    model_name="gpt-4",             # Current model
    subagent_enabled=True           # Include task() tool
)
Tool Sources (in order):
  1. Config-defined tools (via reflection)
  2. MCP tools (from enabled servers)
  3. Built-in tools
  4. Sub-agent tool (if enabled)

​
Sandbox Tools

Core filesystem and command execution tools:

bash

Execute shell commands in the sandbox

ls

List directory contents in tree format

read_file

Read file contents with optional line range

write_file

Write or append to files

str_replace

Replace text in files

Sandbox Tools Reference

Complete tool documentation

​
Built-in Tools

Tools available to all agents:

​
present_files

Make output files visible to the user. Usage: 
present_files([
    "/mnt/user-data/outputs/report.html",
    "/mnt/user-data/outputs/chart.png"
])
Validation:
  • Only files in /mnt/user-data/outputs can be presented
  • Files must exist
  • Returns artifact metadata for frontend display

​
ask_clarification

Request clarification from the user (interrupts execution). Usage: 
ask_clarification(
    question="Which data format would you like: CSV or JSON?"
)
Behavior:
  • Interrupts agent execution
  • Returns control to user
  • User response appended to conversation

​
view_image

Load image as base64 for vision-enabled models. Usage: 
view_image(
    path="/mnt/user-data/uploads/screenshot.png",
    description="Screenshot of the error"
)
Requirements:
  • Model must have supports_vision: true
  • Image formats: PNG, JPEG, GIF, WebP

Built-in Tools Reference

Detailed tool documentation

​
Community Tools

Pre-integrated external service tools:

​
web_search (Tavily)

Search the web for current information. Configuration: 
tools:
  - use: src.community.tavily:web_search
    group: research
Usage: 
results = web_search(
    query="Latest AI research papers 2026",
    max_results=5
)
Requires: TAVILY_API_KEY environment variable

​
web_fetch

Fetch and extract content from web pages. Providers: Tavily, Jina AI, Firecrawl Configuration: 
tools:
  - use: src.community.tavily:web_fetch
    group: research
  # Or
  - use: src.community.jina_ai:web_fetch
    group: research
  # Or
  - use: src.community.firecrawl:web_fetch
    group: research
Usage: 
content = web_fetch(
    url="https://example.com/article"
)

​
image_search (DuckDuckGo)

Search for images. Configuration: 
tools:
  - use: src.community.image_search:image_search
    group: media
Usage: 
images = image_search(
    query="mountain landscape",
    max_results=10
)

Community Tools Reference

All community tools

​
MCP Tools

Model Context Protocol (MCP) enables integration with external tools and services. Configuration (extensions_config.json): 
{
  "mcpServers": {
    "filesystem": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
    }
  }
}
Features:
  • stdio transport: Command-based servers
  • HTTP/SSE transport: Web-based servers
  • OAuth support: Automatic token management
  • Lazy loading: Tools loaded on first use
  • Cache invalidation: Detects config changes

MCP Integration Guide

Set up MCP servers

​
Sub-agent Tool

Delegate complex tasks to sub-agents. Configuration: 
subagents:
  enabled: true
Usage: 
task(
    description="Research AI frameworks",
    prompt="Research TensorFlow, PyTorch, and JAX",
    subagent_type="general-purpose",
    max_turns=20
)
Features:
  • Up to 3 concurrent sub-agents
  • Isolated contexts
  • Shared filesystem
  • 15-minute timeout

Sub-agents

Learn about task delegation

​
Custom Tools

Add your own tools via config.yaml: 
tools:
  - use: my_tools.custom:my_tool
    group: custom
Tool Function:
my_tools/custom.py
from langchain_core.tools import tool

@tool
def my_tool(param: str) -> str:
    """Tool description for the agent.
    
    Args:
        param: Parameter description
    
    Returns:
        Result description
    """
    # Tool implementation
    return f"Result: {param}"
Reflection System:
  • use: module.path:variable_name resolved via resolve_variable()
  • Validates against LangChain tool interface
  • Supports any callable that returns a LangChain tool

Creating Custom Tools

Build your own tools

​
Tool Groups

Organize tools into logical groups: 
tool_groups:
  - name: sandbox
    description: Filesystem and command execution
  
  - name: research
    description: Web search and content fetching
  
  - name: media
    description: Image search and generation
  
  - name: custom
    description: User-defined tools

tools:
  - use: src.community.tavily:web_search
    group: research
  
  - use: src.community.image_search:image_search
    group: media
Usage: 
# Load specific groups
tools = get_available_tools(groups=["sandbox", "research"])

# Load all groups
tools = get_available_tools(groups=["*"])

​
Tool Calling Flow

  1. Agent Decision: Agent decides to use a tool
  2. Tool Call Message: AIMessage with tool_calls
  3. Tool Execution: Tool function invoked
  4. Tool Message: ToolMessage with result
  5. Agent Processing: Agent processes result
Example: 
Agent: "I need to read the data file"
  → AIMessage(tool_calls=[{"name": "read_file", "args": {"path": "data.csv"}}])

System: Execute read_file("/mnt/user-data/uploads/data.csv")
  → ToolMessage(content="col1,col2\n1,2\n3,4")

Agent: "The data has 2 rows and 2 columns..."

​
Error Handling

Tools should handle errors gracefully: 
@tool
def my_tool(param: str) -> str:
    """My tool description."""
    try:
        result = do_something(param)
        return result
    except FileNotFoundError:
        return f"Error: File '{param}' not found"
    except Exception as e:
        return f"Error: {str(e)}"
Best Practices:
  • Return error messages as strings (not raise exceptions)
  • Include context in error messages
  • Suggest fixes when possible

​
Tool Permissions

Skills can restrict tool usage:
SKILL.md frontmatter
---
name: my-skill
allowed-tools:
  - bash
  - read_file
  - write_file
---
When this skill is loaded, only the specified tools are available.

​
Next Steps

Sandbox Tools

Filesystem and command tools

Built-in Tools

Core agent tools

MCP Integration

Connect external tools

Custom Tools

Create your own tools

Build docs developers (and LLMs) love

Get started for freeTalk to us