* fix(agents): run the calls that fit when a batch crosses a per-tool loop limit One model response with 50 or more calls to the same tool lost every call: the per-tool frequency check stopped the run before any of them ran (#8214). - A per-tool limit now drops only the calls that would reach it; the calls within the limit run. A response in which no call fits still stops the run, and the identical-call hard limit still rejects the whole batch. - The capped tool stays blocked for the rest of the execution, whatever the frequency window counts. The cap is a record in the private loop_cap state channel, so it survives an approval pause, the resume's new run_id, a Gateway restart and context compaction. before_agent expires a record another run left behind, which gives a later task a fresh budget. - The run is loop_capped from the first dropped call, in the run record and in a subagent result. A resumed run is marked again from the record. - The model is told on its next call how many calls were skipped and how many were passed on, followed by the wrap-up instructions. The notice is read from the record on every model call and cleared once the model has answered. - The Gateway treats loop_cap as a server-owned state channel. - middleware:loop_detection gains the action reject_excess. * fix(agents): count after the window eviction and keep the cap record readable Review follow-up for #8267: - A call reaches a per-tool limit when the window would hold that many calls to its tool after taking the call in and dropping its oldest entry, as on main. Counting before the eviction rejected a call that only replaced an older call to the same tool, so 49 reads, one other call and one more read capped read_file where main admits 49 more. - The cap record holds only what its reader accepts. A tool whose name the reader would reject, or one past the record's size bound, is left out instead of making the next read discard every cap in the record. The record and its notice are still written, so the drop is explained and the execution stays loop_capped. - A dropped batch is audited once per tool that reached its limit in it, with that tool's own count and threshold. - Tests: a seeded comparison against a plain sliding window, the interleaved sequence, unnameable and overflowing records, and the per-tool audit rows. * fix(agents): report a partial loop cap when the run ends, not mid-run Review follow-up for #8267. runtime.context["stop_reason"] is read in two ways: the worker and Goal continuation read it when the run is over, while run-input admission, the todo middleware and end-of-graph input handling read it mid-run as "the run is ending" and skip their checks. A partial cap wrote it at the first dropped call, while the admitted calls of that response still had to run, so those calls skipped the checks: - input that arrived during inference no longer cancelled the planned calls, so obsolete writes ran after a steer; - two parallel write_todos calls both ran, each replacing the plan; - input that arrived as the run finished was dropped. A response with no call left is still a terminal stop and is reported at once. A partial cap is reported to the subagent channel at once and to the run context by after_agent, which runs after the end-of-graph input handling; another guard's earlier reason is kept. A run that pauses for approval no longer reports a reason; the run that resumes it reports loop_capped when it ends. Tests drive the three cases through real compiled graphs in the lead chain's middleware order. * fix(agents): undo a discarded response's loop accounting and report the guard that stopped the run Third review follow-up for #8267. - A response whose admitted calls another middleware discards before any of them runs (input admission on a steer, approval on calls it cannot address) no longer leaves a cap or counts toward a limit. As the next model call starts, the frequency window, warnings and cap record go back to their state before that response; caps from earlier responses stay. Before, a steer whose replacement needed the same tool had that write dropped as already capped. The undo runs in wrap_model_call, not a before_model hook, so no graph node is added and lead runs do not spend an extra super-step per turn of their recursion limit. - A partial cap reports to both channels only when the run ends, and only when no other guard has given the reason it stopped. A subagent that a later token-budget stop ended now reports token_capped, as its run context does, instead of loop_capped. Tests drive the steer cases through compiled graphs with real input admission, including a replacement that uses the capped tool and an earlier cap that must survive the undo, and the token-budget case sync and async. --------- Co-authored-by: AochenShen99 <sac1063467113@hotmail.com>
English | 中文 | 日本語 | Français | Русский | Português | 한국어
On February 28th, 2026, DeerFlow claimed the 🏆 #1 spot on GitHub Trending following the launch of version 2. Thanks a million to our incredible community — you made this happen! 💪🔥
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.
https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
Note
DeerFlow 2.0 is a ground-up rewrite. It shares no code with v1. If you're looking for the original Deep Research framework, it's maintained on the
1.xbranch — contributions there are still welcome. Active development has moved to 2.0.
Official Website
Learn more and see real demos on our official website. The landing-page case studies open as allowlisted, read-only showcases without requiring a sign-in.
Sister Projects
- LLM Space - Meet our secret weapon behind DeerFlow — one desktop tool to prototype agent ideas, inspect each harness step, replay failures, and benchmark performance.
Coding Plan from ByteDance Volcengine
- We strongly recommend using Doubao-Seed-2.0-Code, DeepSeek v3.2 and Kimi 2.5 to run DeerFlow
- Learn more
- 中国大陆地区的开发者请点击这里
InfoQuest
DeerFlow has newly integrated the intelligent search and crawling toolset independently developed by BytePlus — InfoQuest (supports free online experience)
One-Line Agent Setup
If you use Claude Code, Codex, Cursor, Windsurf, or another coding agent, you can hand it the setup instructions in one sentence:
Help me clone DeerFlow if needed, then bootstrap it for local development by following https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md
That prompt is intended for coding agents. It tells the agent to clone the repo if needed, choose Docker when available, and stop with the exact next command plus any missing config the user still needs to provide.
Quick Start
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make setup # interactive wizard: writes config.yaml and .env (about 2 minutes)
Then start DeerFlow with Docker (recommended) or run it locally:
# Docker
make docker-init # pull the sandbox image (once, or when the image updates)
make docker-start # start services
# Local development
make check # verifies Node.js 22+, pnpm, uv, nginx
make install
make dev
The local commands use the pnpm version pinned in frontend/package.json. If a
different global pnpm is on PATH, they use Corepack when available; otherwise
they report the version mismatch before installing frontend dependencies.
Run make doctor after setting model credentials. It reports obvious placeholder
API keys as incomplete configuration; replace them with real keys before testing
model calls.
Open http://localhost:2026.
- All configuration options, providers and manual setup: Configuration
- Docker details, sizing, upgrades, startup modes and production deployment: Running the Application
- Running on a server or exposing it beyond localhost: read the Security Notice first
From Deep Research to Super Agent Harness
DeerFlow started as a Deep Research framework — and the community ran with it. Since launch, developers have pushed it far beyond research: building data pipelines, generating slide decks, spinning up dashboards, automating content workflows. Things we never anticipated.
That told us something important: DeerFlow wasn't just a research tool. It was a harness — a runtime that gives agents the infrastructure to actually get work done.
So we rebuilt it from scratch.
DeerFlow 2.0 is no longer a framework you wire together. It's a super agent harness — batteries included, fully extensible. Built on LangGraph and LangChain, it ships with everything an agent needs out of the box: a filesystem, memory, skills, sandbox-aware execution, and the ability to plan and spawn sub-agents for complex, multi-step tasks.
Use it as-is. Or tear it apart and make it yours.
Guides
Each guide is the full reference for its topic. Open the one you need.
| Topic | Guide |
|---|---|
Models, providers, config.yaml, environment variables |
Configuration |
| Docker, local development, upgrades, production deployment | Running the Application |
| Sandbox modes, file system, uploads and outputs | Sandbox |
| Skills, built-in tools, script workflows, Claude Code integration | Skills & Tools |
| MCP servers | MCP Server |
| Sub-agents, task delegation and optional SQLite checkpoint history | Sub-Agents, Tool restrictions |
| Long-term memory | Long-Term Memory |
| Session goals, context compaction, task notes, evidence-based decisions | Context, Goals and Agent Decisions |
| Private knowledge retrieval (RAGFlow) | Private Knowledge Retrieval |
| Agentic browser control | Agentic Browser Control |
| Projects, instructions, document shelf | Projects |
| Scheduled tasks | Scheduled Tasks |
| Feishu, Slack, Telegram, Discord, DingTalk and other IM channels | IM Channels |
| File attachments, downloads and Office previews | File Previews |
| Token usage dashboard, workspace, chat archive | Workspace UI |
| Terminal workbench | Terminal Workbench (TUI) |
| Personal access tokens, stream actions, embedded Python client | API Access and Python Client |
| Trace correlation, LangSmith, Langfuse, Monocle | Tracing and Observability |
| Deployment risks, admin model, security recommendations | Security Notice |
Recommended Models
DeerFlow is model-agnostic — it works with any LLM that implements the OpenAI-compatible API. That said, it performs best with models that support:
- Long context windows (100k+ tokens) for deep research and multi-step tasks
- Reasoning capabilities for adaptive planning and complex decomposition
- Multimodal inputs for image understanding and video comprehension
- Strong tool-use for reliable function calling and structured outputs
More Documentation
- Install.md - Setup instructions written for coding agents
- Configuration Reference - Every
config.yamloption - Backend Architecture - Backend architecture and API reference
- Conversation Sharing - Expiring read-only snapshots, artifact previews and workspace copies
- Architecture Overview - How the services fit together
- Contributing Guide - Development environment, workflow and tests
- Changelog - Release notes
⚠️ Security Notice
DeerFlow can execute commands and read and write files. It is designed to run in a local trusted environment, and a Gateway admin account is equivalent to code execution on the host. Before you deploy it on a server or expose it to a network, read the full Security Notice and SECURITY.md.
Contributing
We welcome contributions! Please see CONTRIBUTING.md for development setup, workflow, and guidelines.
License
This project is open source and available under the MIT License.
Acknowledgments
DeerFlow is built upon the incredible work of the open-source community. We are deeply grateful to all the projects and contributors whose efforts have made DeerFlow possible. Truly, we stand on the shoulders of giants.
We would like to extend our sincere appreciation to the following projects for their invaluable contributions:
- LangChain: Their exceptional framework powers our LLM interactions and chains, enabling seamless integration and functionality.
- LangGraph: Their innovative approach to multi-agent orchestration has been instrumental in enabling DeerFlow's sophisticated workflows.
These projects exemplify the transformative power of open-source collaboration, and we are proud to build upon their foundations.
Key Contributors
A heartfelt thank you goes out to the core authors of DeerFlow, whose vision, passion, and dedication have brought this project to life:
Your unwavering commitment and expertise have been the driving force behind DeerFlow's success. We are honored to have you at the helm of this journey.