DeerFlow 1.x (Deep Research)
Type: full-code · Vendor: ByteDance · Language: Python, TypeScript · License: MIT · Status: maintenance · Status in practice: mature · First released: 2025-05
Turn a single research question into an automated deep-research run by composing a planner, a supervisor that dispatches specialised worker agents, retrieval tools, and a final report writer over a stateful LangGraph graph.
Description. DeerFlow (Deep Exploration and Efficient Research Flow) is ByteDance's MIT-licensed open-source deep-research framework, first released around May 2025. The architecture catalogued here is the classic DeerFlow 1.x graph (the `main-1.x` branch), built on LangGraph and LangChain as a stateful multi-agent workflow. A coordinator node gates incoming requests and routes research questions onward; an optional background-investigator runs a preliminary web search to ground planning; a planner decomposes the question into a typed, multi-step plan; a human-feedback interrupt lets the user accept, edit in natural language, or auto-accept the plan; a research-team node then supervises the plan, dispatching each step to a ReAct researcher (web search, crawling, retrieval, MCP tools) or a coder (Python REPL); and a reporter synthesises the findings into a cited final report. Iteration is bounded by max_plan_iterations and max_step_num. The project has since moved to a separate DeerFlow 2.0 "SuperAgent harness" on the `main` branch (a lead-agent plus dynamic subagents in Docker sandboxes), so the node names and file paths referenced here apply to `main-1.x`.
Agent loop shape. LangGraph state graph: coordinator -> (background_investigator) -> planner -> human_feedback -> research_team, which dispatches each plan step to researcher or coder (ReAct loops) and collects results back into shared state; the planner may re-plan up to max_plan_iterations before control passes to reporter, which writes the final report.
Primary use cases
- automated deep research over a single natural-language question
- long-form, cited report generation from web and private-KB sources
- plan-then-execute research with a human plan-review gate
- multi-agent workflows combining web search, retrieval, and Python analysis
Key concepts
- Orchestrator-Workers → orchestrator-workers — The research_team node is a supervisor that iterates the plan and dispatches each step to specialised worker agents (researcher, analyst, coder), collecting their outputs back into shared state.
- Plan-and-Execute → plan-and-execute — The planner node produces an explicit, typed multi-step Plan (validated to a Pydantic model) that the research_team then executes step by step, separating planning from execution.
- Human-in-the-Loop → human-in-the-loop — The human_feedback node interrupts the run to surface the plan; the user can accept it ([ACCEPTED]), edit it in natural language ([EDIT_PLAN], looping back to the planner), or enable auto-accept to skip review.
- ReAct → react — The researcher and coder workers are ReAct agents that interleave reasoning with tool calls; they are constructed via a create_react_agent / create_agent factory and bound to search, retrieval, MCP, and Python-REPL tools.
- Agentic RAG → agentic-rag — The researcher dynamically attaches web-search tools (Tavily, DuckDuckGo, Brave, Arxiv, Wikipedia) and private knowledge-base retrievers (RAGFlow, VikingDB, Milvus, Qdrant) and reasons over the retrieved content.
Patterns this full-code implements —
- ★★Orchestrator-Workers
The research_team node is a supervisor that iterates the plan and dispatches each step to specialised worker agents (researcher, analyst, coder), collecting their outputs back into shared state.
- ★★Plan-and-Execute
The planner node produces an explicit, typed multi-step Plan (validated to a Pydantic model) that the research_team then executes step by step, separating planning from execution.
- ★★Human-in-the-Loop
The human_feedback node interrupts the run to surface the plan; the user can accept it ([ACCEPTED]), edit it in natural language ([EDIT_PLAN], looping back to the planner), or enable auto-accept to s…
- ★★ReAct
The researcher and coder workers are ReAct agents that interleave reasoning with tool calls; they are constructed via a create_react_agent / create_agent factory and bound to search, retrieval, MCP,…
- ★★Agentic RAG
The researcher dynamically attaches web-search tools (Tavily, DuckDuckGo, Brave, Arxiv, Wikipedia) and private knowledge-base retrievers (RAGFlow, VikingDB, Milvus, Qdrant) and reasons over the retri…
- ★★Routing
The coordinator node is the entry point that classifies the request, handling greetings or small talk with a direct response and handing research questions off to the planner (optionally via backgrou…
- ★★Replan on Failure
When the planner judges that context is insufficient it re-plans, bounded by max_plan_iterations; once the cap is reached control passes to the reporter rather than looping indefinitely.
- ★★Model Context Protocol
Worker agents can be extended with external tools via the Model Context Protocol; configured MCP servers are loaded through MultiServerMCPClient and their tools merged into the agent's tool set at ru…
Neighbourhood
Click any neighbour to follow the lineage. Scroll to zoom, drag to pan.
Anti-patterns avoided
- ✕Unbounded Loop
The plan/re-plan cycle is bounded: the planner re-plans only while plan_iterations is below max_plan_iterations (default 1), and each plan is capped at max_step_num steps, so the graph cannot loop in…
- ✕Unbounded Subagent Spawn
The 1.x research_team dispatches each step to a fixed roster of worker roles (researcher, analyst, coder) via static conditional edges rather than dynamically spawning an open-ended number of subagen…
Alternatives & relatives
- full-code · framework
DeerFlow 2.0 is a ground-up rewrite that shares no code with 1.x: it replaces the fixed LangGraph research graph with a general SuperAgent harness (a lead agent that dynamically spawns sandboxed suba…
- full-code · framework
LangGraph
DeerFlow's graph is built on LangGraph, which supplies the stateful nodes, conditional edges, and the interrupt() primitive behind the human-feedback plan review.
- full-code · framework
AutoGen
Both orchestrate multiple specialised agents, but AutoGen is conversation-driven and general-purpose whereas DeerFlow is a fixed plan-and-execute graph specialised for deep research.
- full-code · framework
CrewAI
CrewAI composes role-based agents over tasks for similar research-automation goals; DeerFlow differs by foregrounding an explicit, human-reviewable plan and a bounded re-planning loop.
Listed as alternative by (4)
References
Provenance
- Last analyzed:
- Last updated:
- Verification status: partial