DeerFlow 2.0: From Deep Research Framework to Super Agent Harness

Core Question: How does an open-source agent evolve from a simple research tool into a “super brain” capable of executing complex, multi-step tasks?

DeerFlow 2.0 (Deep Exploration and Efficient Research Flow) is no longer just a deep research framework. It has been completely rewritten from the ground up to become an open-source super agent harness. It orchestrates sub-agents, manages memory, and utilizes sandbox environments to accomplish almost anything—all powered by extensible skills. Simply put, it doesn’t just chat with you; it possesses its own “computer” and “toolbox,” enabling it to actually get things done.

This article provides a comprehensive technical deep dive into DeerFlow 2.0’s architecture, core features, installation, and the philosophy behind its evolution.

AI Agent Workflow
Image Source: Unsplash

From Deep Research to Super Agent: A Paradigm Shift

Core Question: Why did DeerFlow completely rewrite the codebase, abandoning the 1.x foundation?

DeerFlow started as a framework for deep research. However, the open-source community pushed it far beyond our initial vision: developers built data pipelines, automatically generated slide decks, spun up dashboards, and automated content workflows—use cases we never anticipated.

This revealed a crucial insight: DeerFlow was more than a tool; it was a harness—a runtime providing the infrastructure agents need to actually complete work.

So, we rebuilt it from scratch. DeerFlow 2.0, built on LangGraph and LangChain, ships with batteries included: a filesystem, memory, skills, sandboxed execution, and the ability to plan and spawn sub-agents for complex tasks.

Author’s Insight: From “Tool” to “Partner”

“

“When developing DeerFlow 1.x, we focused primarily on how to make the model answer questions better. But as users engaged, we realized that ‘answering questions’ is just step one; users truly need to ‘solve problems.’ This perspective shift drove us to introduce the sandbox and filesystem in version 2.0. It’s like giving a smart brain a pair of hands—it’s no longer just theorizing; it can actually manipulate files and run code. This ’embodied’ agent is the future.” — DeerFlow Team

Core Features: The Four Pillars of DeerFlow 2.0

Core Question: What mechanisms allow DeerFlow 2.0 to handle “almost anything”?

DeerFlow 2.0’s robust capabilities rest on four pillars: Skills & Tools, Sub-Agents, Sandbox & File System, and Context Engineering.

1. Skills & Tools: The Building Blocks of Capability

Skills are what make DeerFlow versatile. A standard Agent Skill is a structured capability module—essentially a Markdown file defining a workflow, best practices, and resource references.

  • ▸
    Built-in Skills: The system ships with skills for research, report generation, slide creation, web page generation, and image/video generation.
  • ▸
    Extensibility: The real power lies in customization. You can add your own skills, replace built-in ones, or combine them into compound workflows.
  • ▸
    Progressive Loading: Skills are loaded only when a task requires them, not all at once. This keeps the context window lean and ensures high performance even with token-sensitive models.

Application Scenario:
Imagine you need a market analysis report. DeerFlow first loads the research skill to gather information, then activates the report-generation skill to structure the document. If visuals are needed, it automatically calls the image-generation skill. This dynamic scheduling mirrors a project manager assigning tasks to specialists on demand.

# Paths inside the sandbox container
/mnt/skills/public
├── research/SKILL.md
├── report-generation/SKILL.md
└── slide-creation/SKILL.md

2. Sub-Agents: The Art of Decomposition

Core Question: How does the agent avoid crashing or going off-track when facing complex, time-consuming tasks?

Complex tasks rarely fit into a single execution pass. DeerFlow employs a decomposition strategy: the lead agent can spawn sub-agents on the fly.

  • ▸
    Parallel Execution: Sub-agents run in parallel whenever possible, significantly shortening task duration.
  • ▸
    Structured Reporting: Sub-agents report structured results back to the lead agent, which synthesizes them into a coherent final output.

Application Scenario:
You need to prepare materials for a new product launch. The lead agent might spawn three sub-agents: one to write a press release, one to create a presentation deck, and another to generate promotional posters. These run simultaneously, and the lead agent aggregates the results into your workspace. This is the power of “one harness, many hands.”

Collaborative Agents
Image Source: Unsplash

3. Sandbox & File System: The Agent’s “Computer”

Core Question: How does DeerFlow ensure security while granting the agent real operational power?

This is the biggest differentiator between DeerFlow and standard chatbots. It doesn’t just talk about doing things; it has its own “computer.” Every task runs inside an isolated Docker container with a full filesystem.

  • ▸
    Real Operations: The agent reads, writes, and edits files. It executes bash commands, writes and runs code, and even views images.
  • ▸
    Security Isolation: All operations occur within a sandbox, ensuring zero contamination between sessions and full auditability.

File System Structure:

# Paths inside the sandbox container
/mnt/user-data/
├── uploads/          # User uploaded files
├── workspace/        # Agent's working directory
└── outputs/          # Final deliverables

This means you can ask it to “run this Python script to process the Excel sheet,” and it will actually execute it, placing the processed file in the outputs directory for you to download.

4. Context Engineering & Long-Term Memory

Core Question: How does the agent stay focused during long conversations and remember user preferences over time?

  • ▸
    Isolated Sub-Agent Context: Sub-agents operate in their own context scope, unable to see the main agent’s history or other sub-agents’ data. This ensures focus.
  • ▸
    Aggressive Context Management: Within a session, DeerFlow summarizes completed sub-tasks, offloads intermediate results to the filesystem, and compresses irrelevant information. This keeps the agent sharp across multi-step tasks.
  • ▸
    Long-Term Memory: While most agents forget everything when a session ends, DeerFlow builds a persistent memory of your profile, preferences, and accumulated knowledge. The more you use it, the better it understands your writing style and workflows. Data is stored locally and stays under your control.

Quick Start: Configuration and Deployment Guide

Core Question: How can you quickly set up and run DeerFlow 2.0 locally?

DeerFlow supports both Docker (recommended) and local development modes.

Step 1: Configuration

  1. Clone the Repository

    git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

  2. Generate Configuration Files
    Run the following command in the project root:

    make config

  3. Configure Your Model
    Edit the generated config.yaml file to define at least one model. Here is a GPT-4 example:

    models:
  - name: gpt-4                       # Internal identifier
    display_name: GPT-4               # UI display name
    use: langchain_openai:ChatOpenAI  # LangChain class path
    model: gpt-4                      # Model identifier for API
    api_key: $OPENAI_API_KEY          # Recommended: use env var
    max_tokens: 4096                  # Max tokens per request
    temperature: 0.7                  # Sampling temperature

  4. Set API Keys
    For security, avoid hardcoding API keys in the config file. Use one of these methods:

    • ▸
      Option A (Recommended): Edit .env file
      Create or edit the .env file in the project root:

      TAVILY_API_KEY=your-tavily-api-key
OPENAI_API_KEY=your-openai-api-key
    • ▸
      Option B: Export Environment Variables

      export OPENAI_API_KEY=your-openai-api-key

Step 2: Launch the Application

Option 1: Docker Deployment (Recommended)

This ensures environment consistency and is the fastest way to start.

  1. Initialize and Start:

    make docker-init    # Pull sandbox image (only once or when updated)
make docker-start   # Start services

  2. Access: Open your browser at http://localhost:2026.

Option 2: Local Development

Suitable for debugging or contributing to the project.

  1. Check Prerequisites:
    Ensure you have Node.js 22+, pnpm, uv, and nginx installed.

    make check

  2. (Optional) Setup Sandbox:
    If using Docker-based sandbox locally:

    make setup-sandbox

  3. Start Services:

    make dev

  4. Access: Visit http://localhost:2026.

Coding Setup
Image Source: Unsplash

Advanced Configuration: Sandbox Modes & MCP Extension

Core Question: How can the execution environment be customized for different security and performance needs?

Diverse Sandbox Modes

DeerFlow supports three sandbox execution modes:

  1. Local Execution: Runs sandbox code directly on the host. Good for debugging but offers less isolation.
  2. Docker Execution: Runs code in isolated Docker containers. This is the recommended default, balancing security and convenience.
  3. Kubernetes Execution: Runs code in Kubernetes Pods via a provisioner service. Ideal for large-scale, enterprise-grade production environments.

(Refer to backend/docs/CONFIGURATION.md for detailed setup instructions.)

MCP Server Extension

DeerFlow supports the Model Context Protocol (MCP), allowing you to connect external data sources, APIs, or custom toolchains. This extensibility ensures the agent’s capabilities can grow with your needs. See backend/docs/MCP_SERVER.md for the configuration guide.

Recommended Models: Choosing the Right “Brain”

Core Question: What are the specific requirements for models to function optimally with DeerFlow?

DeerFlow is model-agnostic and works with any LLM implementing the OpenAI-compatible API. However, to leverage its full potential, we recommend models with the following characteristics:

  • ▸
    Long Context Window (100k+ Tokens): Essential for deep research and multi-step task retention.
  • ▸
    Strong Reasoning Capabilities: Required for adaptive planning and complex task decomposition.
  • ▸
    Multimodal Input Support: Crucial for processing images and video content.
  • ▸
    Reliable Tool Use: Stable function calling and structured outputs are vital for the agent to operate tools and execute code effectively.

Practical Summary & Action Checklist

Summary

DeerFlow 2.0 is an open-source super agent harness that bridges the gap between text generation and actual execution. By integrating sub-agents, long-term memory, and a secure sandbox, it transforms LLMs into active problem solvers. Whether you are a developer building automation workflows or an enterprise seeking secure agent deployment, DeerFlow provides a robust, extensible foundation.

Deployment Checklist

Step Command / Action Notes
1. Clone git clone https://github.com/bytedance/deer-flow.git Get the source code
2. Config make config Generate initial files
3. Setup Edit config.yaml Define models and paths
4. Keys Edit .env file Add OPENAI_API_KEY, etc.
5. Launch make docker-init && make docker-start Docker mode (Recommended)
6. Access http://localhost:2026 Start using the platform

One-Page Summary

DeerFlow 2.0 Core Architecture

  • ▸
    Core Identity: Open-source Super Agent Harness (not just a chatbot).
  • ▸
    Key Components:

    • ▸
      Skills: Markdown-defined modules, loaded on-demand.
    • ▸
      Sandbox: Isolated Docker containers with real filesystem access.
    • ▸
      Sub-Agent: Parallel processing for complex tasks with result synthesis.
    • ▸
      Memory: Long-term persistent storage of user preferences and knowledge.
  • ▸
    Deployment: Docker (Recommended) / Local Development.
  • ▸
    Model Requirements: Long context, strong reasoning, multimodal, reliable tool use.

Frequently Asked Questions (FAQ)

1. What is the main difference between DeerFlow 2.0 and 1.x?
DeerFlow 2.0 is a ground-up rewrite with no shared code. It evolved from a deep research framework into a general-purpose agent harness, adding sandbox execution, sub-agent orchestration, and long-term memory. The 1.x version is maintained on a separate branch.

2. Is Docker mandatory for running DeerFlow?
No, local development mode is supported. However, Docker is highly recommended to ensure environment consistency and security isolation for the sandbox.

3. Which LLMs are compatible with DeerFlow?
DeerFlow is model-agnostic. Any LLM implementing the OpenAI-compatible API can be configured in config.yaml. Models with long context windows and strong reasoning (like GPT-4) are recommended for best performance.

4. How do I add custom skills?
Skills are defined in Markdown files. You can create a custom SKILL.md file in the /mnt/skills/custom directory. DeerFlow automatically recognizes and loads it at runtime.

5. Is it safe to let the agent execute code on my machine?
Yes, if using the Docker sandbox mode. Code runs in isolated containers, preventing direct access to your host machine’s core filesystem, ensuring security and auditability.

6. Can I use DeerFlow for commercial projects?
Yes. DeerFlow is open-sourced under the MIT License, allowing free use in commercial projects and modification.

7. How does the long-term memory feature work?
It is a built-in feature where the agent stores user preferences and interaction history locally. It accumulates knowledge over time, learning your style and needs without sending data externally.

8. How can I extend the agent’s tools?
Besides custom skills, you can configure MCP Servers to introduce external tools and APIs or write Python functions as custom tools integrated directly into the system.