DeerFlow: ByteDance's Open-Source SuperAgent

The Problem with a Single Agent

Imagine asking one person to do all of the following at once: research a topic, write a report, generate slides, produce supporting images, publish a webpage. Even a brilliant person buckles. They lose context jumping between research notes and slide layouts. They forget details between the report draft and the webpage code.

This is what happens when you send a complex request to a single AI agent. It does one thing at a time. It holds one context window. Earlier reasoning fades as the conversation grows. It has no way to step back and coordinate parallel efforts.

DeerFlow is ByteDance's answer: stop making one agent do everything. Start orchestrating many.

What DeerFlow Actually Is

DeerFlow (Deep Exploration and Efficient Research Flow) is an open-source SuperAgent harness. Not a single agent. An orchestration layer that spawns, coordinates, and synthesizes the work of multiple sub-agents. Version 2.0 shipped February 28, 2026. It hit #1 on GitHub Trending within hours. Over 89,000 stars since.

The word "harness" matters. A harness does not do the pulling -- the horses do. DeerFlow does not write your code or generate your slides directly. It decides which sub-agents to spawn, what tools each gets, how much context they carry, and how their results merge into a coherent output.

Think of it as a kitchen manager versus a chef. A single AI agent is one chef doing everything. DeerFlow is the manager who assigns the prep cook to chop vegetables, the pastry chef to handle dessert, the line cook to fire entrees -- then plates the final dish from everyone's work.

Built on LangGraph and LangChain. Python backend, React frontend. MIT license. Supports any LangChain-compatible model: GPT-4, DeepSeek v3.2, Gemini 2.5 Flash via OpenRouter, ByteDance's own Doubao-Seed models, and more.

Architecture: How the Pieces Fit

Four core layers, stacked like floors in a building. Understanding each floor clarifies why the system works the way it does.

The Lead Agent

At the top: the lead agent. It receives your request, breaks it into sub-tasks, decides which sub-agents to spawn, synthesizes their outputs. The lead agent is the only component that sees the full picture. It maintains the high-level plan and adjusts as sub-agents report back.

Sub-Agents

Each sub-agent gets a scoped assignment. A specific question to research. A piece of code to write. An image to generate. Sub-agents receive only the context they need -- not the full conversation history. This is deliberate. A sub-agent researching battery technology trends does not need to know the slide design sub-agent's layout preferences.

When tasks are independent, sub-agents run in parallel. When sub-agent A needs sub-agent B's output, the lead agent sequences them. All sub-agents finish. The lead agent synthesizes structured results into final output.

The core pattern: fan-out, then fan-in. A research task spawns twelve sub-agents exploring different angles, then converges into one report. A website task spawns sub-agents for content, styling, and deployment separately.

The Sandbox

Every task runs in isolation. Three execution modes:

1. Local -- code runs on the host machine. Fast. No setup overhead. No isolation.
2. Docker -- code runs in containers. Each task gets a dedicated filesystem at /mnt/user-data/ with uploads/, workspace/, and outputs/ directories.
3. Kubernetes -- code runs in K8s pods via a provisioner service. For teams running DeerFlow at scale.

The sandbox is not cosmetic. Sub-agents read files, write files, execute bash commands, view images -- all within their sandbox. A sub-agent's code crashes? It stays contained. Your host machine is untouched.

Skills and Memory

Skills are structured capability modules defined in Markdown with YAML frontmatter. Each skill describes a workflow: how to write a research report, how to generate a slide deck, how to build a web page. DeerFlow loads skills progressively -- pulling in definitions only when a sub-agent actually needs them. Context windows stay lean instead of front-loading every capability.

Built-in skills cover research, reports, slides, web pages, image and video generation. External skills install via .skill archives through the Gateway API.

Memory persists across sessions. DeerFlow automatically extracts user context, facts, and preferences from conversations. Stores them locally with confidence scores. Uses debounced updates to minimize LLM calls. Return after a week and DeerFlow remembers your project context, preferred output format, and accumulated knowledge.

Key Features Worth Knowing

InfoQuest Search Integration

DeerFlow integrates BytePlus's InfoQuest -- an intelligent search and crawling toolset. Not just a web search wrapper. InfoQuest handles structured crawling, content extraction, and result ranking tuned for research tasks. When a sub-agent needs to answer a factual question, it gets filtered, structured results rather than raw web pages.

Claude Code Bridge

The claude-to-deerflow skill deserves attention if you already use Claude Code. It lets you interact with a running DeerFlow instance directly from your terminal. Submit research tasks. Check status. Manage threads. Upload files. Without leaving Claude Code.

The workflow: you are deep in a coding session. You realize you need background research on an API migration strategy. Instead of switching to DeerFlow's web UI, send the research task from your terminal. DeerFlow's sub-agents fan out, research, compile a report. You keep coding. Report ready? Pull it back into your Claude Code session.

MCP Server Support

DeerFlow ships with core tools -- web search, web fetch, file operations, bash execution -- and extends via Model Context Protocol (MCP). Connect any MCP-compatible server to add capabilities: database access, API integrations, custom data sources. HTTP/SSE MCP servers support OAuth token flows for authenticated access.

Messaging Channels

DeerFlow connects to Telegram, Slack, and Feishu/Lark via long-polling or WebSocket. No public IP required. Send tasks from your phone's Telegram. DeerFlow's sub-agents work for an hour. Receive the completed report as a message. Commands: /new, /status, /models, /memory, /help.

Setting Up DeerFlow

Prerequisites

• Python 3.12+
• Node.js 22+
• pnpm
• Docker (recommended for sandbox isolation)

Docker Setup (Recommended)

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

# Generate config and set up environment
make config

# Edit config.yaml to add your model and API key
# Example model configuration:
# models:
#   - name: gpt-4
#     display_name: GPT-4
#     use: langchain_openai:ChatOpenAI
#     model: gpt-4
#     api_key: $OPENAI_API_KEY

# Pull sandbox image and start all services
make docker-init
make docker-start

Access DeerFlow at http://localhost:2026. Docker bundles everything -- backend, frontend, Nginx reverse proxy, sandbox -- so you skip individual dependency installation.

Local Development Setup

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

make config        # Generate configuration
make check         # Validate environment
make install       # Install dependencies
make setup-sandbox # Optional: set up Docker sandbox
make dev           # Start all services in dev mode

Model Configuration

DeerFlow works with any LangChain-compatible model. The config.yaml takes a list of models with provider-specific parameters. For OpenAI-compatible providers (including local models via Ollama or vLLM), set the base_url:

models:
  - name: deepseek-v3
    display_name: DeepSeek v3.2
    use: langchain_openai:ChatOpenAI
    model: deepseek-chat
    api_key: $DEEPSEEK_API_KEY
    base_url: https://api.deepseek.com

DeerFlow vs. Running Multiple CLI Agents Manually

You could achieve something similar by opening five terminals, running five separate Claude Code or Codex CLI sessions, and manually coordinating their work. Developers have done this since multi-agent workflows became practical in 2025.

The problem is coordination. Five independent agents:

• No shared plan. Each works from its own understanding. You are the orchestrator, relaying information, resolving conflicts, deciding next steps.
• No context isolation. Each accumulates full conversation history. No aggressive summarization. No offloading intermediate results. Context windows fill fast.
• No structured synthesis. Merging five outputs into one coherent deliverable is manual labor. DeerFlow's lead agent does this automatically.
• No persistent memory. Close the terminals, context is gone. DeerFlow persists memory across sessions.

DeerFlow's value is the orchestration layer itself. Planning. Scoped context distribution. Parallel execution. Automatic synthesis. The difference between five musicians playing in the same room and five musicians playing in an orchestra with a conductor.

That said, DeerFlow does not replace dedicated CLI coding agents. Claude Code is still better for deep, single-codebase refactoring. Codex CLI is still better for fast, sandboxed code generation. DeerFlow sits above them as a coordination layer for tasks that span research, content, and code simultaneously.

Monitoring Sub-Agents in Parallel

When DeerFlow fans out into multiple sub-agents, each in its own sandbox, the practical challenge is visibility. Which sub-agent is progressing? Which one is stuck? What is each doing right now?

Terminal layout matters. You want DeerFlow's web UI in one pane, backend logs in another, individual sub-agent outputs in their own terminals. Resizing and rearranging on the fly -- expanding the log pane when debugging, shrinking it when stable -- turns chaos into something manageable.

Limitations and Honest Considerations

Resource Requirements

DeerFlow is not lightweight. The full stack (LangGraph agent server, Gateway API, frontend, Nginx, Docker sandbox) requires meaningful resources. On a laptop, expect noticeable CPU and memory usage. Docker is cleaner but heavier than a single CLI agent.

Complexity Budget

DeerFlow solves a real problem -- multi-agent orchestration -- but adds abstraction you must understand and maintain. config.yaml, model configuration, skill system, MCP server setup, sandbox modes. All surfaces that can break. For simple coding tasks, this is overkill. DeerFlow earns its complexity on tasks that genuinely require parallel research, content generation, and code execution across multiple sub-agents.

ByteDance Origin

MIT-licensed open source. Code is auditable. But it originated at ByteDance, and some enterprise environments have policies about ByteDance-origin software. Review the source. Make your own assessment. MIT means you can fork, modify, self-host without restrictions.

Security Surface

Any system that executes code in sandboxes, connects to external MCP servers, and installs third-party skills has a broader attack surface than a single-process CLI agent. Docker sandbox provides isolation. But skill installation and MCP OAuth flows are trust boundaries worth auditing for production deployments.

Model Cost

DeerFlow amplifies model usage. Ten sub-agents means ten times the LLM calls. On pay-per-token pricing, a complex research task can burn significant API credits. Monitor token usage, especially when experimenting with high sub-agent counts.

Who Should Use DeerFlow

DeerFlow is not for everyone. It fits developers and teams who:

• Handle tasks spanning research + code + content regularly. Investigating a topic, writing code from findings, producing a report or presentation -- DeerFlow's orchestration genuinely saves time.
• Need persistent context across long-running tasks. Hours, not minutes. DeerFlow's memory and intermediate-result offloading handle context limits that single agents hit.
• Want to integrate multiple AI tools into one workflow. MCP support and skill system combine search, code execution, image generation, and custom tools under one orchestrator.
• Run teams needing asynchronous AI task submission. Telegram/Slack/Feishu channels let members submit tasks and receive results without accessing the web UI.

For quick coding tasks, stick with Claude Code or Codex CLI. For multi-step projects crossing research, code, and content boundaries, DeerFlow is worth the setup cost.