DeerFlow: ByteDance Open-Source SuperAgent for Deep Research & Code Execution

Pain Points vs Innovation

✕Traditional Pain Points	✓Innovative Solutions
Traditional single-agent frameworks such as early AutoGPT struggle to break down long-horizon complex tasks and often loop or fail midway	The SuperAgent Harness architecture treats the framework as an orchestration substrate rather than a single agent, enabling stronger extensibility
Mainstream research products such as Perplexity and OpenAI Deep Research are largely closed black boxes, limiting customization of LLMs, toolchains, and knowledge strategies	Docker isolation plus a persistent filesystem allows secure code execution, file writing, and full web app construction
Many open-source research pipelines lack code sandboxes and multimodal outputs, producing only plain text	Through litellm, DeerFlow unifies access to 100+ models including GPT-4, Claude, and Qwen, improving switching flexibility and cost control
Some multi-agent frameworks such as CrewAI still have gaps in RAG integration and MCP protocol support, making private knowledge onboarding expensive	The Human-in-the-Loop mechanism enables live plan revision in natural language, balancing automation with operator control
-	It natively produces reports, PowerPoint slides, and TTS podcast output, going beyond text-only research tools

Architecture Deep Dive

LangGraph Stateful Graph Workflow Engine

DeerFlow's orchestration layer is built on LangGraph and uses stateful graphs to model complex research workflows. Each agent node acts as an independent compute unit that shares context through structured messages, reducing the coupling of callback-style orchestration. Checkpoints allow tasks to pause and resume at any node, which is essential for Human-in-the-Loop plan revision. Combined with visual debugging, this makes multi-agent state tracing far easier.

Hierarchical Multi-Agent Role System

The system includes five roles, Coordinator, Planner, Researcher, Coder, and Reporter, each responsible for lifecycle control, decomposition, retrieval, code work, and synthesis. Clear role boundaries turn complex research into a well-scoped pipeline. Every role receives only the tools relevant to its task, following least-privilege design. Structured communication also improves reliability and parseability between stages.

Docker Isolation Sandbox Execution Environment

DeerFlow 2.0 uses isolated Docker containers to provide secure execution boundaries, along with a persistent filesystem and Bash access. Agents can run Python, install packages, write files, and even build web apps without contaminating the host system. Sandbox state persists across task steps so intermediate outputs can be reused naturally. With approval gates enabled, the model becomes more suitable for enterprise security requirements.

litellm-Powered Model-Agnostic Abstraction Layer

Through litellm, the system abstracts model access behind a unified interface spanning OpenAI, Claude, Qwen, Ollama, and more. Complex reasoning can be routed to stronger models while lighter tasks use cheaper ones. This keeps quality high while controlling API cost. Most model switching happens through configuration, which lowers migration overhead across clouds and private stacks.

RAG and MCP Dual-Channel Knowledge Expansion

DeerFlow provides two complementary extension channels, RAG and MCP, to bring in knowledge beyond the public web. On the RAG side, it can connect to stores such as RAGFlow and VikingDB and inject retrieved content into context. On the MCP side, external MCP Servers can expose private domains, knowledge graphs, and internal enterprise tools. This dual design makes DeerFlow effective for both internet research and internal knowledge workflows.

Deployment Guide

1. Clone the repository and install backend dependencies, requiring Python 3.12+

bash

1git clone https://github.com/bytedance/deer-flow.git && cd deer-flow && pip install -r requirements.txt

2. Copy the environment template and configure LLM API keys and search credentials

bash

1cp .env.example .env2# Edit .env, fill in OPENAI_API_KEY or ANTHROPIC_API_KEY, and TAVILY_API_KEY

3. Start the backend service, default port 8000

bash

1uvicorn src.app:app --host 0.0.0.0 --port 8000 --reload

4. Install frontend dependencies and start the Next.js dev server, requiring Node.js 18+

bash

1cd web && npm install && npm run dev

5. Optional, launch the full stack and sandbox with Docker Compose

bash

1docker compose up -d

Use Cases

Core Scene	Target Audience	Solution	Outcome
[Competitive Intelligence Research]	Market analysts and strategy teams	Enter a competitor name, let Researcher agents gather earnings, news, and product updates, Coder agents run comparisons, and Reporter agents produce charted reports plus PPT	Compresses 2 to 3 days of manual work into roughly 30 minutes while improving coverage and freshness
[Academic Literature Review Generation]	University researchers and thesis writers	Enter research keywords, then the system searches papers and web sources and combines them with a private RAG base to summarize methods, findings, and gaps	Produces structured reviews faster and reduces missed-source risk
[Automated Content Marketing Pipeline]	Content teams and solo creators	After a topic is entered, DeerFlow automates research, writing, chart creation, and podcast plus slide generation	Enables one operator to produce multimodal content that previously needed coordinated team effort

Frequently Asked Questions

What is the core difference between DeerFlow and OpenAI Deep Research?▾

DeerFlow is an open, self-hostable framework where teams control models, tools, and data flow. OpenAI Deep Research is closer to a closed cloud product, while DeerFlow also enables real code execution inside Docker sandboxes and more flexible private deployment.

What are the main upgrades from DeerFlow 1.0 to 2.0?▾

Version 2.0 is no longer just a research tool and instead becomes a SuperAgent Harness. Major changes include Docker sandboxes, standalone Memory and Skills systems, multi-tier SubAgent orchestration, and a backend structure better suited to enterprise extension.

Can DeerFlow run in a fully offline private environment?▾

Yes, if you switch models to local Ollama and disable or replace external search. RAG can also connect to internal enterprise instances, but offline quality depends heavily on local model strength.

Where are DeerFlow's sandbox security boundaries?▾

It uses Docker containers for baseline isolation, so code does not directly contaminate the host by default. The known concern is that policy-driven pre-authorization is still limited, which is why production deployments are safer with approval gates enabled.

How do I connect custom private tools or internal APIs?▾

There are two common paths, expose them through an MCP Server or register custom Tools directly in the backend Harness layer. The first is better for reusable cross-project services, while the second fits tightly coupled internal capabilities.

How does DeerFlow compare with CrewAI and AutoGen?▾

DeerFlow emphasizes LangGraph state orchestration, Docker-grade sandboxing, and report plus PPT plus podcast deliverables. CrewAI is more role-pipeline oriented, AutoGen is more conversation-driven, and DeerFlow is stronger in visual debugging, checkpoint recovery, and native RAG support.

Does DeerFlow support conversation history?▾

Yes, Conversation History is part of the 2.0-era Memory layer. That makes multi-turn research better suited to continuous project workflows instead of restarting from scratch every time.

How is the Dify path different from DeerFlow's native RAG path?▾

The Dify path fits teams already using Dify for knowledge and app orchestration. The native RAGFlow path is more direct for deployments that want retrieval tightly embedded inside DeerFlow workflows.

DeerFlow — ByteDance Open-Source SuperAgent Harness

What is it?

Pain Points vs Innovation

Architecture Deep Dive

Deployment Guide

1. Clone the repository and install backend dependencies, requiring Python 3.12+

2. Copy the environment template and configure LLM API keys and search credentials

3. Start the backend service, default port 8000

4. Install frontend dependencies and start the Next.js dev server, requiring Node.js 18+

5. Optional, launch the full stack and sandbox with Docker Compose

Use Cases

Limitations & Gotchas

Frequently Asked Questions