Skip to content
/
Tier A A6 Multi-agent orchestrator

DeerFlow

deerflow · bytedance/deer-flow · ★ 70k · last commit 2026-05-26

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker sandboxes, driven by progressive SKILL.md skill loading.

Best whenResearch and creation tasks require isolated sub-agent contexts and real execution sandboxes — not just bigger prompts or more context.
Skip ifExposing the service to LAN/internet without auth gateway, Using host bash execution in LocalSandboxProvider without trust
vs seeds
claude-flow(LangGraph-based orchestration, web frontend, sub-agents, memory system) but targets research-and-creation rather than c…
Primitive shape 6 total
Skills 6
00

Summary

DeerFlow — Summary

DeerFlow (Deep Exploration and Efficient Research Flow) 2.0 is a ByteDance open-source "super agent harness" that orchestrates sub-agents, memory, and execution sandboxes to research, code, and create. Built on LangGraph + LangChain + Python 3.12+, DeerFlow deploys as a Docker service with a Next.js/React web frontend, a Python LangGraph backend, and an embedded AioSandboxProvider (containerized execution). Sub-agents run in parallel with isolated contexts when possible; the lead agent fans out into dozens of sub-agents for research tasks and synthesizes the results into reports, slide decks, web pages, or generated visuals. Skills are SKILL.md files loaded progressively from a containerized sandbox filesystem. DeerFlow 2.0 is a ground-up rewrite with no code shared with v1 (which was a "Deep Research" framework); the v1 branch remains active. Claude Code integration ships as a Claude Code skill (claude-to-deerflow) that lets users drive DeerFlow from the Claude Code terminal. Multi-model via LangChain with provider support for OpenAI, Anthropic, Gemini, DeepSeek, vLLM, OpenRouter, Codex CLI, Claude Code OAuth, and more.

differs_from_seeds: DeerFlow is closest to claude-flow in scope (LangGraph-based orchestration, sub-agents, long-horizon tasks, web frontend) but targets a different use case — DeerFlow is a research-and-creation superagent (reports, slides, code, visuals) rather than a coding workflow assistant. Unlike claude-flow's 305-tool MCP server, DeerFlow's value is in its progressive SKILL.md system and containerized sandbox isolation. The AioSandboxProvider (Docker container isolation), the sub-agent parallel research pattern, and the Claude Code → DeerFlow skill bridge make DeerFlow unique in this batch.

01

Overview

DeerFlow — Overview

Origin

DeerFlow 2.0 is developed by ByteDance (the TikTok parent company) and open-sourced under MIT. Core authors: Daniel Walnut and Henry Li. The 2.0 release on February 28, 2026 hit #1 on GitHub Trending. DeerFlow v1 was a "Deep Research" framework; v2 is a complete ground-up rewrite positioning itself as a "super agent harness."

Philosophy

From the README:

"DeerFlow (Deep Exploration and Efficient Research Flow) is an open-source super agent harness that orchestrates sub-agents, memory, and sandboxes to do almost anything — powered by extensible skills."

"This is the difference between a chatbot with tool access and an agent with an actual execution environment."

"Most agents forget everything the moment a conversation ends. DeerFlow remembers."

Key design beliefs:

  1. Skills should be progressive — loaded only when needed (context-window efficiency)
  2. Sub-agents should be isolated — each sub-agent has its own context (no cross-contamination)
  3. Execution needs a real sandbox — the agent has "its own computer" via AioSandboxProvider
  4. Long-term memory is essential — builds persistent profile across sessions

Execution Mode Tiers

Four modes from simple to powerful:

  • flash: fast, minimal reasoning
  • standard: default
  • pro: with planning (plan mode)
  • ultra: with sub-agents (full research fan-out)

ByteDance / Volcengine Integration

The README recommends Doubao-Seed-2.0-Code, DeepSeek v3.2, and Kimi 2.5. ByteDance's Volcengine cloud platform is a recommended deployment target (with a China-specific enrollment link).

InfoQuest Integration

DeerFlow has integrated ByteDance's InfoQuest intelligent search and crawling toolset for enhanced research capabilities.

02

Architecture

DeerFlow — Architecture

Distribution

  • Type: Docker service (recommended) + local development
  • License: MIT
  • Runtime: Python 3.12+, Node.js 22+
  • Orchestration: LangGraph + LangChain

Quick Deploy

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make setup     # Interactive wizard: provider, search, sandbox, model config
make docker-start  # Docker (recommended)
# OR
make dev       # Local development

Architecture Components

deer-flow/
├── backend/           # Python LangGraph backend
│   ├── packages/
│   │   ├── harness/   # Core harness (DeerFlowClient, models, tools, sandbox)
│   │   └── gateway/   # HTTP Gateway API
├── frontend/          # Next.js React UI
├── skills/
│   └── public/        # Built-in skills (SKILL.md files)
├── .agent/
│   └── skills/        # Installed skills
├── config.yaml        # Main config (models, providers, sandbox)
├── docker-compose.yml
└── Makefile          # Setup wizard, docker targets, dev targets

Sandbox Providers

Provider Description Use case
AioSandboxProvider Docker containerized execution Production, multi-agent
LocalSandboxProvider Per-thread directories on host Dev (host bash disabled by default)

Sandbox filesystem:

/mnt/skills/public     # Built-in skills
/mnt/skills/custom     # User-installed skills
/mnt/user-data/
├── uploads/           # User files
├── workspace/         # Agent working directory
└── outputs/           # Final deliverables

Gateway

HTTP Gateway API + LangGraph API:

  • Default port: 2026
  • REST API: /api/threads, /api/models, /api/skills
  • LangGraph SSE streaming: /api/langgraph
  • Embedded Python client (DeerFlowClient) for in-process access

Config

config.yaml (generated by make setup):

  • models list with LangChain provider, model name, API key, base URL
  • Sandbox mode (aio/local)
  • Web search provider
  • Bash access policy
03

Components

DeerFlow — Components

Built-in Skills (skills/public/)

Skill Purpose
research/SKILL.md Web research + synthesis
report-generation/SKILL.md Long-form research reports
slide-creation/SKILL.md Presentation deck generation
web-page/SKILL.md Web page creation
image-generation/SKILL.md AI image generation
claude-to-deerflow/SKILL.md Drive DeerFlow from Claude Code

Skills are loaded progressively — only when the task needs them. This keeps context window lean.

Claude Code Integration Skill

The claude-to-deerflow skill lets Claude Code drive a running DeerFlow instance:

npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow

Capabilities:

  • Send messages + get streaming responses
  • Choose execution mode (flash/standard/pro/ultra)
  • Check DeerFlow health, list models/skills/agents
  • Manage threads + conversation history
  • Upload files for analysis

Sub-Agents

The lead agent spawns sub-agents on demand:

  • Each gets its own scoped context, tools, and termination condition
  • Parallel when possible
  • Return structured results to lead agent
  • Token usage attributed back to dispatching step

Core Tools

  • Web search (configurable provider: Tavily, InfoQuest, etc.)
  • Web fetch
  • File operations (read, write, edit)
  • Bash execution (configurable — disabled by default in LocalSandboxProvider)
  • MCP server tools (if configured)
  • Custom Python functions

LangGraph Integration

DeerFlow runs its multi-agent orchestration on LangGraph's state machine framework:

  • StateGraph for agent loop management
  • SSE streaming via LangGraph's protocol (values, messages-tuple, end events)
  • Strict tool-call recovery (strips raw tool-call metadata on forced-stop)

Memory System

Persistent across sessions — stores user profile, preferences, accumulated knowledge. Memory updates skip duplicate fact entries to prevent accumulation.

Gateway API

REST + LangGraph API at http://localhost:2026:

  • GET /api/models — list configured models
  • GET /api/skills — list installed skills
  • POST /api/threads — create/manage threads
  • DELETE /api/threads/{id} — delete thread data
  • PUT /api/skills/{name} — enable/disable skill

Makefile Targets

setup, dev, docker-start, docker-stop, config, doctor, test

05

Prompts

DeerFlow — Prompts

Prompt Architecture

DeerFlow uses two prompt channels:

  1. SKILL.md files — progressive skill instructions injected when task matches
  2. Gateway-generated follow-up suggestions — JSON array of next action suggestions

Verbatim Excerpt 1 — Skills Design Philosophy (from README)

A standard Agent Skill is a structured capability module — a Markdown file that defines 
a workflow, best practices, and references to supporting resources. DeerFlow ships with 
built-in skills for research, report generation, slide creation, web pages, image and 
video generation, and more. But the real power is extensibility: add your own skills, 
replace the built-in ones, or combine them into compound workflows.

Skills are loaded progressively — only when the task needs them, not all at once. This 
keeps the context window lean and makes DeerFlow work well even with token-sensitive models.

Technique: The progressive loading strategy is itself a prompting optimization — by injecting skills only when the task needs them, DeerFlow avoids polluting the context window with irrelevant instructions. This is analogous to HexAgent's lazy skill loading and thClaws' whenToUse matching.

Verbatim Excerpt 2 — Sub-Agent Context Isolation (from README)

**Isolated Sub-Agent Context**: Each sub-agent runs in its own isolated context. This means 
that the sub-agent will not be able to see the context of the main agent or other sub-agents. 
This is important to ensure that the sub-agent is able to focus on the task at hand and not 
be distracted by the context of the main agent or other sub-agents.

**Summarization**: Within a session, DeerFlow manages context aggressively — summarizing 
completed sub-tasks, offloading intermediate results to the filesystem, compressing what's 
no longer immediately relevant.

Technique: Isolation as a prompting strategy — giving each sub-agent a clean, focused context prevents cross-contamination and improves quality on specific sub-tasks. This is the inverse of claude-flow's shared context approach.

Verbatim Excerpt 3 — Strict Tool-Call Recovery (from README)

**Strict Tool-Call Recovery**: When a provider or middleware interrupts a tool-call loop, 
DeerFlow now strips provider-level raw tool-call metadata on forced-stop assistant messages 
and injects placeholder tool results for dangling calls before the next model invocation. 
This keeps OpenAI-compatible reasoning models that strictly validate `tool_call_id` sequences 
from failing with malformed history errors.

Technique: Defensive prompt engineering — the harness repairs malformed conversation state before the next model call rather than letting the model fail on invalid history.

09

Uniqueness

DeerFlow — Uniqueness

differs_from_seeds

DeerFlow is closest to claude-flow in scope (LangGraph-based multi-agent orchestration, web frontend, rich feature set, memory system) but differs in purpose and architecture. claude-flow is a coding workflow assistant; DeerFlow is a research-and-creation superagent optimized for long-horizon tasks (research reports, slides, websites, generated visuals). claude-flow's value is its 305-tool MCP server; DeerFlow's value is its progressive SKILL.md system and containerized sandbox isolation. The AioSandboxProvider (Docker container per task) goes beyond any seed's isolation mechanism. The ultra mode that fans out into potentially dozens of parallel sub-agents for a single research task is a pattern unique in the corpus. The Claude Code → DeerFlow bridge (claude-to-deerflow skill) is notable: it makes DeerFlow accessible from within Claude Code, inverting the usual direction (DeerFlow spawns Claude Code rather than Claude Code spawning DeerFlow). ByteDance's backing, the 69K+ stars, and the v1→v2 complete rewrite signal institutional investment in this direction.

Most Distinctive Features

  1. ultra sub-agent mode — dozens of parallel sub-agents for deep research
  2. AioSandboxProvider — Docker container isolation (the agent has "its own computer")
  3. Claude Code → DeerFlow bridge — drives DeerFlow from Claude Code terminal
  4. Progressive skill loading — skills loaded only when needed (context efficiency)
  5. ByteDance InfoQuest — custom search/crawl toolset from ByteDance

Observable Failure Modes

  • Heavy infrastructure: Full Docker stack (backend + frontend + sandbox containers); minimum 4 vCPU, 8 GB RAM for basic use
  • v2 breaking change: No backward compatibility with v1. v1 codebase on a separate branch.
  • LangGraph dependency: Tightly coupled to LangGraph's StateGraph pattern — harder to swap out than simpler frameworks
  • Volcengine commercial push: ByteDance's cloud platform is prominently recommended; some features may be optimized for Volcengine
  • No TDD: No test-first enforcement — research/creation agent doesn't fit TDD model
  • Security recommendation against public exposure: README explicitly warns not to expose to LAN/internet without auth gateway and IP allowlist
04

Workflow

DeerFlow — Workflow

Setup Workflow (once)

Step Description Artifact
1. Clone git clone + cd deer-flow Source checkout
2. Setup wizard make setup (2 min interactive wizard) config.yaml + .env
3. Validate make doctor Actionable fix hints
4. Start make docker-start or make dev Running service at :2026

Research Task Workflow

Phase Description Artifact
1. Thread creation POST /api/threads Thread ID
2. Message sent POST to thread or via web UI Task submitted
3. Lead agent plans Decomposes task into sub-agent scopes Internal plan
4. Sub-agents fan out Each sub-agent researches a different angle Sub-agent results
5. Summarization Completed sub-tasks summarized, offloaded to filesystem Context-efficient history
6. Synthesis Lead agent synthesizes results Report / slides / code / web page
7. Output delivery Files written to /mnt/user-data/outputs/ Final deliverables

Execution Modes

Mode Description
flash Fast, minimal sub-agents
standard Default balanced mode
pro Planning pass before execution
ultra Full sub-agent parallel research

Approval Gates

No formal approval gates in default mode. Bash access is configurable (disabled by default in LocalSandboxProvider for security). No human-in-the-loop requirement.

Claude Code → DeerFlow Workflow

  1. Install claude-to-deerflow skill in Claude Code
  2. Ensure DeerFlow is running at http://localhost:2026
  3. Use /claude-to-deerflow command in Claude Code
  4. Send tasks, stream responses, manage threads — without leaving the terminal

Phase-to-Artifact Map

Phase Artifact
Sub-agent research Structured results per sub-agent
Lead agent synthesis Report/slides/web page/code in /mnt/user-data/outputs/
Memory update Updated persistent memory (skips duplicates)
Thread creation LangGraph thread with full conversation history
06

Memory Context

DeerFlow — Memory & Context

Memory Architecture

Long-Term Memory

DeerFlow maintains persistent memory across sessions:

  • Stores user profile, preferences, accumulated knowledge
  • Injected into agent context on subsequent sessions
  • Memory updates skip duplicate fact entries (prevents endless accumulation)

Session Context

Within a session, DeerFlow manages context aggressively:

  • Sub-task summarization: Completed sub-tasks summarized, offloaded to filesystem
  • Result offloading: Intermediate results written to sandbox filesystem (/mnt/user-data/workspace/)
  • Context compression: Less-relevant content compressed

Thread State

LangGraph manages per-thread conversation state:

  • Thread ID identifies each conversation
  • Full history accessible via Gateway API
  • DELETE /api/threads/{id} removes DeerFlow-managed thread data

Context Compaction

Built into LangGraph's state management:

  • Sub-agent isolation prevents context blowup from parallel branches
  • Summarization of completed sub-tasks maintains lean lead agent context
  • Strict tool-call recovery repairs malformed history before next model call

State Files (Sandbox)

/mnt/user-data/
├── uploads/     # User-provided files
├── workspace/   # Agent working directory
└── outputs/     # Final deliverables (reports, slides, code, images)

No Explicit SOUL.md or MEMORY.md

DeerFlow does not use the Utah/thClaws workspace-markdown-file memory pattern. Memory is database-backed (LangGraph thread store).

Memory Persistence

Global — persists across sessions, stored in LangGraph's backend store (typically Redis or database in production Docker deployment).

07

Orchestration

DeerFlow — Orchestration

Multi-Agent Architecture

Lead agent + parallel sub-agents:

  1. Lead agent decomposes task into sub-agent scopes
  2. Sub-agents run in parallel when possible (each with isolated context, tools, termination condition)
  3. Sub-agents return structured results
  4. Lead agent synthesizes into final output

Each sub-agent's token usage is attributed back to the dispatching step.

Orchestration Pattern

parallel-fan-out — the lead agent fans out into many sub-agents (potentially dozens for research tasks), then converges to synthesize results.

LangGraph StateGraph

DeerFlow uses LangGraph's StateGraph for agent loop management:

  • State transitions tracked explicitly
  • SSE streaming via LangGraph protocol
  • Strict tool-call recovery for malformed history

Isolation Mechanism

Container (AioSandboxProvider) — Docker container isolation for production. Each task gets a sandboxed execution environment with its own filesystem view.

LocalSandboxProvider: Per-thread directories on host (no container) — file tools mapped to thread-specific dirs; host bash disabled by default.

Execution Mode

Interactive loop (via web UI or API) + event-driven (Claude Code skill drives DeerFlow remotely). Not a daemon in the traditional sense — the Docker service runs continuously but processes tasks on-demand.

Multi-Model

Yes — model-agnostic via LangChain provider abstraction. Config supports:

  • OpenAI (ChatOpenAI)
  • Anthropic (Claude Code OAuth)
  • Gemini
  • DeepSeek
  • OpenRouter
  • vLLM (with custom VllmChatModel)
  • Codex CLI (CodexChatModel)
  • Azure AI
  • Any OpenAI-compatible endpoint

Reasoning model toggle: supports_thinking: true with enable_thinking extra body param.

ACP Integration

ACP (Agent Communication Protocol) agents can be added as external coding agents (Codex, Claude Code OAuth) brought in as DeerFlow sub-agents.

Consensus Mechanism

None. Sub-agents report results to lead agent; lead agent synthesizes.

Plan Mode

Available in pro mode — agent proposes plan before executing.

08

Ui Cli Surface

DeerFlow — UI / CLI Surface

Web UI (Next.js)

Full-featured web frontend at http://localhost:2026:

  • Chat interface with streaming responses
  • Execution mode selector (flash/standard/pro/ultra)
  • Thread management
  • File upload
  • Model/skill management

Makefile CLI Interface

make setup     # Interactive wizard (2 min)
make dev       # Local development
make docker-start  # Docker start
make docker-stop   # Docker stop
make config    # Copy full config template
make doctor    # Validate config + provide fix hints
make test      # Run tests

No Dedicated CLI Binary

No standalone deerflow binary. The Makefile is the primary operational interface.

Claude Code Skill (claude-to-deerflow)

# Install in Claude Code
npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow

# Use in Claude Code REPL
/claude-to-deerflow "Research the latest developments in AI agents"

Environment variables for custom endpoints:

DEERFLOW_URL=http://localhost:2026
DEERFLOW_GATEWAY_URL=http://localhost:2026
DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph

Embedded Python Client

from deerflow.client import DeerFlowClient

client = DeerFlowClient()
response = client.chat("Analyze this paper", thread_id="my-thread")

# Streaming
for event in client.stream("hello"):
    if event.type == "messages-tuple" and event.data.get("type") == "ai":
        print(event.data["content"])

Observability

  • LangSmith tracing (optional)
  • Langfuse tracing (optional)
  • LangGraph's built-in state management + history

Port

Default: 2026

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k
A6 Multi-agent orchestrator

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k
A6 Multi-agent orchestrator

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k
A6 Multi-agent orchestrator

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k
A6 Multi-agent orchestrator

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

oh-my-openagent (omo) ★ 60k
A6 Multi-agent orchestrator

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…

gpt-engineer ★ 55k
A6 Multi-agent orchestrator

ARCHIVED — the original LLM-driven code generation experiment that generates entire applications from a prose specification file.