bytedance / deer-flow

#14

65,5208,663+337 todayPython

An open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.

💡 Use Cases

最适合需要AI自动完成网络搜索、数据爬取、代码执行等多步骤复杂研究任务的场景。

深度市场调研

Problem: 开发者需要快速获取竞品信息、市场趋势和技术方案，但手动搜索、整理和分析耗时耗力。

Solution: 使用DeerFlow的搜索、爬取和Python执行能力，让AI代理自动收集网络信息，执行数据分析脚本，生成结构化报告。

Example: 调研某开源项目的技术架构、社区活跃度和竞品对比，AI自动搜索GitHub、技术博客，爬取相关数据，用Python分析后输出综合报告。

自动化数据收集

Problem: 开发者需要定期从多个网站收集数据，但网站结构各异，手动编写和维护爬虫脚本很繁琐。

Solution: 利用DeerFlow的智能爬取工具和Python执行环境，AI能理解网页结构并动态调整爬取策略，自动处理反爬机制。

Example: 每周自动收集电商平台商品价格、库存信息，AI识别不同网站的页面布局变化，调整爬取逻辑，将数据存入数据库。

多步骤任务编排

Problem: 开发者需要协调多个AI子任务（如搜索、分析、代码执行）来完成复杂工作流，但手动串联容易出错。

Solution: 使用DeerFlow的超级代理框架，通过配置子代理、记忆和沙箱，自动编排任务流程，确保各步骤正确衔接。

Example: 先搜索最新AI论文，再爬取相关代码仓库，接着用Python分析代码质量，最后生成技术评估文档，整个过程自动执行。

安全代码执行

Problem: 开发者需要让AI生成并执行代码来验证想法，但直接在主机上运行未知代码有安全风险。

Solution: 利用DeerFlow的Docker沙箱模式，将AI生成的代码在隔离容器中安全执行，避免污染主机环境。

Example: AI根据需求生成数据处理脚本，在Docker沙箱中运行该脚本处理敏感数据，完成后自动清理容器，确保安全。

📊 Project Info

Language: Python
Stars: ⭐ 65,520
Forks: 8,663
Today: +337
Ranking: #14
Collection: Overall
Trending Date: May 6, 2026
Last Push: 5/6/2026

🏷️ Topics

TypeScriptDocker智能体编排深度研究可扩展社区驱动AI开发者研究人员

📸 Screenshots

5分钟快速开始DeerFlow

DeerFlow是一个多智能体编排框架，通过Docker快速启动，构建能执行复杂任务的超级智能体。

🖥️ OS

macOSWindowsLinux

⚙️ Runtime

Docker最新稳定版

🔧 Tools

Git— 克隆代码库

📝 Steps

克隆项目

使用Git克隆DeerFlow仓库到本地。

克隆项目

$ git clone https://github.com/bytedance/deer-flow.git

✓Expected: 克隆完成后，进入deer-flow目录。

💡确保网络连接正常。

生成配置文件

从项目根目录运行命令生成本地配置文件。

复制示例配置文件

$ cd deer-flow && cp config.example.yaml config.yaml

✓Expected: config.yaml文件已创建。

💡如果config.example.yaml不存在，请检查项目结构。

配置模型和API密钥

编辑config.yaml设置模型，并在.env文件中添加API密钥。

创建.env文件并设置OpenAI API密钥

$ echo 'OPENAI_API_KEY=your_api_key_here' > .env

✓Expected: .env文件已创建，包含API密钥。

💡替换your_api_key_here为你的实际API密钥，支持其他模型如Anthropic。

启动Docker服务

使用Docker快速启动DeerFlow应用。

启动Docker容器

$ make docker-start

✓Expected: 服务启动成功，显示日志信息。

💡首次运行可能需要下载镜像，请耐心等待。

✅ 验证启动成功

访问Web界面确认DeerFlow已运行。

✓在浏览器中打开http://localhost:2026
✓看到DeerFlow界面或相关响应

⚡ Quick Tips

安装使用Docker可避免环境依赖问题，推荐新手使用。

配置确保config.yaml中至少配置一个模型，否则可能无法启动。

故障排除如果端口2026被占用，可修改docker-compose.yml中的端口映射。

🔍 Troubleshooting

❓ make docker-start命令失败

→ 检查Docker是否安装并运行，尝试docker-compose up手动启动。

❓ 无法访问http://localhost:2026

→ 确认服务已启动，检查防火墙或网络设置。

❓ API密钥错误导致模型无法调用

→ 验证.env文件中的API密钥是否正确，并确保有足够额度。

🎯 Next Steps

探索内置技能

尝试使用DeerFlow进行Web搜索或代码执行等任务。

查看官方文档

访问deerflow.tech了解更多功能和高级配置。

加入社区

参与GitHub讨论，获取帮助和分享经验。

Difficulty

中级

Est. Time

1-2天

Target Audience

具备基础Python和命令行知识的开发者，对AI智能体、LangChain/LangGraph有一定了解或兴趣，希望构建自动化复杂任务应用的研究者或工程师。

🎯 What You'll Learn

你将能够配置并运行DeerFlow框架，理解其核心概念（智能体、技能、沙箱），并利用它创建一个能执行多步骤任务（如研究、报告生成）的AI应用。

📋 Prerequisites

Python基础熟悉

DeerFlow是Python项目，需要能理解基本语法、包管理和虚拟环境。

命令行/终端操作熟悉

需要运行git、docker、make等命令来克隆项目、启动服务。

Git基础了解

用于克隆项目仓库。

Docker基础概念了解

项目推荐使用Docker运行，需要知道如何安装Docker和运行容器。

AI/LLM基础概念了解

了解大型语言模型（LLM）、API密钥、提示词等基本概念，有助于理解框架工作原理。

📚 Resources

🗺️ Learning Phases

环境准备与项目初探

⏱ 30分钟

安装基础软件

确保你的电脑已安装：1. Git。2. Python (3.10+)。3. Docker Desktop (推荐) 或 Docker Engine。

💡如果选择本地开发模式，Docker不是必须的，但Docker模式是官方推荐且最一致的体验方式。

克隆项目并浏览结构

使用 `git clone https://github.com/bytedance/deer-flow.git` 克隆项目到本地。打开项目文件夹，快速浏览README和目录结构，了解核心文件如 `config.yaml`, `.env.example`, `docker-compose.yml`。

💡注意README中关于2.0版本是重写的说明，确保你学习的是最新版本。

核心配置与首次运行

⏱ 1小时

生成配置文件

在项目根目录运行命令（根据README），从模板生成本地配置文件 `config.yaml` 和 `.env`。

💡通常命令类似 `cp .env.example .env` 和 `cp config.example.yaml config.yaml`，请以README为准。

配置LLM模型和API密钥

1. 编辑 `config.yaml`，在 `models` 部分至少配置一个你拥有的LLM（如OpenAI GPT-4o， Anthropic Claude等）。2. 编辑 `.env` 文件，填入对应模型的API密钥。这是项目运行的关键。

💡强烈建议使用 `.env` 文件管理密钥，不要直接写在 `config.yaml` 中。先从配置一个模型开始。

使用Docker一键启动

在项目根目录运行 `make docker-start` 或 `docker-compose up`（根据README指示）。等待所有服务（后端、前端、可能需要的provisioner）启动完成。

💡首次运行会拉取镜像，需要一些时间。观察终端日志，确保没有报错。

访问Web界面

打开浏览器，访问 `http://localhost:2026`。如果看到DeerFlow的Web界面，恭喜你，环境搭建成功！

💡如果无法访问，检查Docker容器是否全部正常运行，端口2026是否被占用。

概念理解与基础交互

⏱ 2-3小时

理解核心概念

阅读README的“Core Features”部分，重点理解：1. **Skills & Tools**：智能体能做什么。2. **Sub-Agents**：任务如何分解。3. **Sandbox & File System**：代码在哪里安全执行。4. **Context & Memory**：如何管理信息。

💡可以对照官方网站（deerflow.tech）的演示，直观感受这些概念如何运作。

运行第一个简单任务

在Web界面中，尝试输入一个简单的任务，例如：“请用中文介绍一下你自己”或“总结今天的主要科技新闻”。观察智能体如何规划、调用工具（如搜索）、并返回结果。

💡初次任务可能较慢，耐心等待。关注界面中任务分解和执行的步骤展示。

探索沙箱与文件系统

尝试一个涉及文件操作或代码执行的任务，例如：“创建一个名为hello.txt的文件，并写入‘Hello DeerFlow’，然后列出当前目录文件”。在Web界面中查看生成的文件和命令执行结果。

💡这能让你直观感受DeerFlow与普通聊天机器人的区别——它拥有一个可交互的隔离执行环境。

深入技能与配置

⏱ 2-3小时

查看内置技能(Skills)

在项目代码中查找 `skills/` 目录，浏览里面的 `.md` 文件。了解一个技能如何定义工作流、使用工具和最佳实践。例如，查看 `research.md` 或 `generate_report.md`。

💡技能是Markdown文件，易于阅读。这是理解智能体如何被“教导”完成特定任务的关键。

修改配置体验不同模式

根据“Sandbox Mode”指南，尝试修改 `config.yaml` 中的 `sandbox.mode` 设置（例如从 `docker` 改为 `local`，需谨慎），理解不同执行模式的区别。修改后需重启服务。

💡在Docker模式下修改为local可能因权限问题失败，此步骤主要为学习配置项，生产环境建议保持Docker模式。

尝试一个复杂任务

输入一个更复杂的多步骤任务，如：“研究一下大语言模型在2024年的主要进展，并生成一份包含关键点和引用的简短Markdown报告”。观察主智能体如何创建子智能体分工合作，并最终合成报告。

💡复杂任务耗时较长，可以清晰展示Sub-Agents的协同和Context Engineering的价值。

⚠️ Common Mistakes

❌ API密钥配置错误或未配置

✅ 确保在 `.env` 文件中填写的变量名与 `config.yaml` 中 `model` 配置的 `api_key_env_var` 字段完全一致，并且值正确。重启服务使配置生效。

❌ Docker端口冲突或权限问题

✅ 检查本地端口2026是否已被其他程序占用。在Linux/Mac上，如果Docker需要sudo权限，确保以正确方式运行，或将用户加入docker组。

❌ 未理解沙箱模式配置

✅ 新手请严格遵循README的Docker启动方式。不要随意更改 `sandbox.mode` 为 `local`，除非你清楚知道代码将在你的主机上直接执行带来的安全风险。

❌ 任务描述过于模糊

✅ 给智能体的指令应尽量清晰、具体。例如，“写一篇博客”不如“写一篇关于DeerFlow入门指南的博客，面向Python开发者，字数800左右”效果好。

❌ 忽略查看容器日志

✅ 当服务启动失败或任务执行出错时，第一时间使用 `docker-compose logs` 或 `docker logs <container_name>` 查看具体错误信息，这是调试的最重要依据。

🚀 Next Steps

1. **技能开发**：参考现有技能格式，为你自己的领域（如数据分析、社交媒体管理）创建自定义技能。2. **工具集成**：通过MCP服务器或Python函数集成新的工具（如数据库、内部API）。3. **研究架构**：阅读Architecture Overview和源码，理解LangGraph状态图如何驱动智能体协作。4. **参与贡献**：按照CONTRIBUTING.md指南，从修复文档错别字、增加测试或实现一个小功能开始，参与开源社区。5. **构建应用**：尝试将DeerFlow作为引擎，嵌入到你自己的Python应用或Web服务中，解决实际的自动化需求。