mirror of
https://gitee.com/wanwujie/deer-flow
synced 2026-04-03 06:12:14 +08:00
8039da2fc4
Updated the link for the original Deep Research framework to point to the correct branch.
224 lines
10 KiB
Markdown
224 lines
10 KiB
Markdown
# 🦌 DeerFlow - 2.0
|
|
|
|
DeerFlow (**D**eep **E**xploration and **E**fficient **R**esearch **Flow**) is an open-source **super agent harness** that orchestrates **sub-agents**, **memory**, and **sandboxes** to do almost anything — powered by **extensible skills**.
|
|
|
|
> [!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.x` branch](https://github.com/bytedance/deer-flow/tree/main-1.x) — contributions there are still welcome. Active development has moved to 2.0.
|
|
|
|
## Table of Contents
|
|
|
|
- [Quick Start](#quick-start)
|
|
- [Sandbox Configuration](#sandbox-configuration)
|
|
- [From Deep Research to Super Agent Harness](#from-deep-research-to-super-agent-harness)
|
|
- [Core Features](#core-features)
|
|
- [Skills & Tools](#skills--tools)
|
|
- [Sub-Agents](#sub-agents)
|
|
- [Sandbox & File System](#sandbox--file-system)
|
|
- [Context Engineering](#context-engineering)
|
|
- [Long-Term Memory](#long-term-memory)
|
|
- [Recommended Models](#recommended-models)
|
|
- [Documentation](#documentation)
|
|
- [Contributing](#contributing)
|
|
- [License](#license)
|
|
- [Acknowledgments](#acknowledgments)
|
|
- [Star History](#star-history)
|
|
|
|
## Quick Start
|
|
|
|
### Configuration
|
|
|
|
1. **Copy the example config**:
|
|
```bash
|
|
cp config.example.yaml config.yaml
|
|
cp .env.example .env
|
|
```
|
|
|
|
2. **Edit `config.yaml`** and set your API keys in `.env` and preferred sandbox mode.
|
|
|
|
#### Sandbox Configuration
|
|
|
|
DeerFlow supports multiple sandbox execution modes. Configure your preferred mode in `config.yaml`:
|
|
|
|
**Local Execution** (runs sandbox code directly on the host machine):
|
|
```yaml
|
|
sandbox:
|
|
use: src.sandbox.local:LocalSandboxProvider # Local execution
|
|
```
|
|
|
|
**Docker Execution** (runs sandbox code in isolated Docker containers):
|
|
```yaml
|
|
sandbox:
|
|
use: src.community.aio_sandbox:AioSandboxProvider # Docker-based sandbox
|
|
```
|
|
|
|
**Docker Execution with Kubernetes** (runs sandbox code in Kubernetes pods via provisioner service):
|
|
|
|
This mode runs each sandbox in an isolated Kubernetes Pod on your **host machine's cluster**. Requires Docker Desktop K8s, OrbStack, or similar local K8s setup.
|
|
|
|
```yaml
|
|
sandbox:
|
|
use: src.community.aio_sandbox:AioSandboxProvider
|
|
provisioner_url: http://provisioner:8002
|
|
```
|
|
|
|
See [Provisioner Setup Guide](docker/provisioner/README.md) for detailed configuration, prerequisites, and troubleshooting.
|
|
|
|
### Running the Application
|
|
|
|
#### Option 1: Docker (Recommended)
|
|
|
|
The fastest way to get started with a consistent environment:
|
|
|
|
1. **Initialize and start**:
|
|
```bash
|
|
make docker-init # Pull sandbox image (Only once or when image updates)
|
|
make docker-start # Start all services and watch for code changes
|
|
```
|
|
|
|
2. **Access**: http://localhost:2026
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed Docker development guide.
|
|
|
|
#### Option 2: Local Development
|
|
|
|
If you prefer running services locally:
|
|
|
|
1. **Check prerequisites**:
|
|
```bash
|
|
make check # Verifies Node.js 22+, pnpm, uv, nginx
|
|
```
|
|
|
|
2. **(Optional) Pre-pull sandbox image**:
|
|
```bash
|
|
# Recommended if using Docker/Container-based sandbox
|
|
make setup-sandbox
|
|
```
|
|
|
|
3. **Start services**:
|
|
```bash
|
|
make dev
|
|
```
|
|
|
|
4. **Access**: http://localhost:2026
|
|
|
|
## 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, sandboxed 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.
|
|
|
|
## Core Features
|
|
|
|
### Skills & Tools
|
|
|
|
Skills are what make DeerFlow do *almost anything*.
|
|
|
|
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.
|
|
|
|
Tools follow the same philosophy. DeerFlow comes with a core toolset — web search, web fetch, file operations, bash execution — and supports custom tools via MCP servers and Python functions. Swap anything. Add anything.
|
|
|
|
```
|
|
# Paths inside the sandbox container
|
|
/mnt/skills/public
|
|
├── research/SKILL.md
|
|
├── report-generation/SKILL.md
|
|
├── slide-creation/SKILL.md
|
|
├── web-page/SKILL.md
|
|
└── image-generation/SKILL.md
|
|
|
|
/mnt/skills/custom
|
|
└── your-custom-skill/SKILL.md ← yours
|
|
```
|
|
|
|
### Sub-Agents
|
|
|
|
Complex tasks rarely fit in a single pass. DeerFlow decomposes them.
|
|
|
|
The lead agent can spawn sub-agents on the fly — each with its own scoped context, tools, and termination conditions. Sub-agents run in parallel when possible, report back structured results, and the lead agent synthesizes everything into a coherent output.
|
|
|
|
This is how DeerFlow handles tasks that take minutes to hours: a research task might fan out into a dozen sub-agents, each exploring a different angle, then converge into a single report — or a website — or a slide deck with generated visuals. One harness, many hands.
|
|
|
|
### Sandbox & File System
|
|
|
|
DeerFlow doesn't just *talk* about doing things. It has its own computer.
|
|
|
|
Each task runs inside an isolated Docker container with a full filesystem — skills, workspace, uploads, outputs. The agent reads, writes, and edits files. It executes bash commands and codes. It views images. All sandboxed, all auditable, zero contamination between sessions.
|
|
|
|
This is the difference between a chatbot with tool access and an agent with an actual execution environment.
|
|
|
|
```
|
|
# Paths inside the sandbox container
|
|
/mnt/user-data/
|
|
├── uploads/ ← your files
|
|
├── workspace/ ← agents' working directory
|
|
└── outputs/ ← final deliverables
|
|
```
|
|
|
|
### Context Engineering
|
|
|
|
**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. This lets it stay sharp across long, multi-step tasks without blowing the context window.
|
|
|
|
### Long-Term Memory
|
|
|
|
Most agents forget everything the moment a conversation ends. DeerFlow remembers.
|
|
|
|
Across sessions, DeerFlow builds a persistent memory of your profile, preferences, and accumulated knowledge. The more you use it, the better it knows you — your writing style, your technical stack, your recurring workflows. Memory is stored locally and stays under your control.
|
|
|
|
## 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
|
|
|
|
## Documentation
|
|
|
|
- [Contributing Guide](CONTRIBUTING.md) - Development environment setup and workflow
|
|
- [Configuration Guide](backend/docs/CONFIGURATION.md) - Setup and configuration instructions
|
|
- [Architecture Overview](backend/CLAUDE.md) - Technical architecture details
|
|
- [Backend Architecture](backend/README.md) - Backend architecture and API reference
|
|
|
|
## Contributing
|
|
|
|
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, workflow, and guidelines.
|
|
|
|
## License
|
|
|
|
This project is open source and available under the [MIT License](./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](https://github.com/langchain-ai/langchain)**: Their exceptional framework powers our LLM interactions and chains, enabling seamless integration and functionality.
|
|
- **[LangGraph](https://github.com/langchain-ai/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:
|
|
|
|
- **[Daniel Walnut](https://github.com/hetaoBackend/)**
|
|
- **[Henry Li](https://github.com/magiccube/)**
|
|
|
|
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.
|
|
|
|
## Star History
|
|
|
|
[](https://star-history.com/#bytedance/deer-flow&Date)
|