diff --git a/README.md b/README.md index 13d0a49..5c35652 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,27 @@ -# 🦌 DeerFlow - v2 +# 🦌 DeerFlow - 2.0 -> Originated from Open Source, give back to Open Source. +DeerFlow is an open-source **super agent harness** that orchestrates **sub-agents**, **memory**, and **sandboxes** to do almost anything — powered by **extensible skills**. -A LangGraph-based AI agent backend with sandbox execution capabilities. +> [!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/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 @@ -82,19 +101,87 @@ If you prefer running services locally: 4. **Access**: http://localhost:2026 -See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed local development guide. +## 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. -## Features +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. -- 🤖 **LangGraph-based Agents** - Multi-agent orchestration with sophisticated workflows -- 🧠 **Persistent Memory** - LLM-powered context retention across conversations with automatic fact extraction -- 🔧 **Model Context Protocol (MCP)** - Extensible tool integration -- 🎯 **Skills System** - Reusable agent capabilities -- 🛡️ **Sandbox Execution** - Safe code execution environment -- 🌐 **Unified API Gateway** - Single entry point with nginx reverse proxy -- 🔄 **Hot Reload** - Fast development iteration -- 📊 **Real-time Streaming** - Server-Sent Events (SSE) support +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