从零搭建字节跳动开源智能体框架——Deer Flow实战教程：让AI自主完成多步骤研究与报告生成

Q: 一、Deer Flow到底是什么？先搞清楚再装

Deer Flow不是一个聊天机器人，也不是一个RAG工具，而是一个“指挥调度系统”。它把一个大任务拆解成多个子目标，让AI循环执行“思考->调用工具->观察结果->再思考”的闭环，直到任务完成。如果你使用过AutoGPT或者BabyAGI，那Deer Flow就是它们的“工业级加强版”，由字节跳动内部孵化，支持长时间运行、自动恢复、并行执行。 它的核心组件包括： 规划器（Planner）：负责把任务拆成步骤，形成依赖图。 执行器（Executor）：调用各种工具（浏览器、代码解释器、Shell等）完成具体步骤。 记忆模块（Memory）：保存中间结果和上下文，防止长任务丢失信息。 Agen

Q: 三、一步一步跑通Deer Flow

3.1 克隆仓库与安装依赖 打开终端，执行以下命令： git clone https://github.com/bytedance/deer-flow.git cd deer-flow python -m venv .venv source .venv/bin/activate pip install -r requirements.txt 这里建议使用虚拟环境，否则很容易污染系统Python。安装过程中如果提示flash-attn编译错误，不要慌张，那是可选项，可以注释掉再装。我们需要的核心依赖是langchain、playwright和duckduckgo-search。 接着安装浏览器

Q: 四、完整工作流程总结

通过上面两个例子，我们可以总结出Deer Flow的标准使用流程： 第一步：定义清晰目标。目标越明确，规划器生成的步骤越准确。例如“调研XX并输出Markdown报告”比“帮我看看AI框架”好得多。 第二步：设定步数上限。任务复杂程度与步数成正比。初学时建议设10步，跑通了再加到50步。 第三步：等待并监控日志。观察规划器拆解的步骤是否合理，如果发现某个步骤反复重试，可能是网络或API Key权限问题。 第四步：检查输出产物。Deer Flow把结果统一放在output/目录，包括中间文件、日志、最终报告。

Q: 五、容易被忽略的细节和陷阱

在实战中，我们踩了几个坑，现在一一列出。 5.1 Python版本必须锁定 如果在Python 3.12下安装，pydantic和langchain会出现兼容性错误。我们一开始用了Python 3.12，结果pip install报错堆栈长达几百行。切换到Python 3.10后一切正常。建议使用pyenv管理版本。 5.2 模型选择决定任务上限 官方文档默认支持GPT-4系列。我们用gpt-4o-mini跑长任务时，发现规划逻辑偶尔会“忘记”之前的步骤，导致重复执行。后来换成gpt-4o或claude-sonnet-4就好很多。如果预算有限，可以先用qwen-max-long这类支持256

最近，字节跳动开源的Deer Flow在GitHub上冲上热榜，短短时间收获超7.9万星。它定位为“长周期超级智能体外壳”，能让AI自主完成研究、编程、内容创作等需要多步骤推理的任务。很多人把它看作“AI智能体的脚手架”，但面对满天飞的概念，真正动手跑起来的人却不多。

这篇教程适合已经熟悉Python基础、接触过大模型API、但还没深入智能体框架的开发者。看完后，你将解决三个问题：第一，Deer Flow能做什么、不能做什么；第二，如何用30分钟在本机跑通一个真实任务；第三，在落地过程中有哪些坑必须避开。

下面，我们以“调研开源AI智能体框架生态并生成Markdown报告”为例，从零开始，手把手带你跑通Deer Flow。所有步骤基于Ubuntu 22.04 + Python 3.10 + 单张RTX 3090测试环境，代码和命令可直接复制。

一、Deer Flow到底是什么？先搞清楚再装

Deer Flow不是一个聊天机器人，也不是一个RAG工具，而是一个“指挥调度系统”。它把一个大任务拆解成多个子目标，让AI循环执行“思考->调用工具->观察结果->再思考”的闭环，直到任务完成。如果你使用过AutoGPT或者BabyAGI，那Deer Flow就是它们的“工业级加强版”，由字节跳动内部孵化，支持长时间运行、自动恢复、并行执行。

它的核心组件包括：

规划器（Planner）：负责把任务拆成步骤，形成依赖图。
执行器（Executor）：调用各种工具（浏览器、代码解释器、Shell等）完成具体步骤。
记忆模块（Memory）：保存中间结果和上下文，防止长任务丢失信息。
Agent外壳（Harness）：负责循环调度、错误重试、状态持久化。

简单说，你给它一个目标，它会像人类一样，先搜索资料，再读文档，然后写代码分析，最后生成报告，全程不需要你反复干预。

二、环境准备：安装前必看的依赖清单

在克隆代码之前，请确保本机满足以下条件：

依赖项	推荐版本	说明
操作系统	Ubuntu 22.04 / macOS 14+	Windows需要WSL2，否则部分工具不可用
Python	3.10 ~ 3.11	3.12会导致部分依赖编译失败
Node.js	18+	用于支持浏览器自动化工具
大模型API Key	OpenAI / Anthropic / 国内厂商均可	至少需要一种模型的访问权限

如果你使用的是国产GPU（如昇腾、寒武纪），需要额外安装适配层，本教程暂不涉及。

三、一步一步跑通Deer Flow

3.1 克隆仓库与安装依赖

打开终端，执行以下命令：

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

这里建议使用虚拟环境，否则很容易污染系统Python。安装过程中如果提示flash-attn编译错误，不要慌张，那是可选项，可以注释掉再装。我们需要的核心依赖是langchain、playwright和duckduckgo-search。

接着安装浏览器自动化工具：

playwright install chromium

这一步会下载约150MB的Chromium浏览器，用于让AI访问网页。

3.2 配置大模型API密钥

Deer Flow默认从环境变量读取密钥。我们创建一个.env文件：

cp .env.example .env
nano .env

写入以下内容（以OpenAI兼容接口为例）：

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-你的密钥
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL_NAME=gpt-4o-mini

如果你用的是国内模型，比如智谱GLM、阿里Qwen，也可以配置成OpenAI兼容模式。这里有一个关键细节：Deer Flow对模型上下文长度有硬性要求，建议选择至少128K上下文的模型，否则长任务跑到一半会丢失前面的记忆。

3.3 运行第一个任务：调研AI智能体框架

为了验证安装成功，我们先跑一个“小任务”。在项目根目录下执行：

python main.py --task "调研2025年开源AI智能体框架的前三名，对比它们的星标数和核心特点，输出中文Markdown报告" --max-steps 10

这个命令的意思是：让Deer Flow规划并执行调查任务，最多执行10个步骤。如果配置正确，你会看到类似下面的输出：

[规划器] 已生成4个步骤：
  1. 搜索“2025 open source AI agent framework”
  2. 访问前三名框架的GitHub页面
  3. 提取星标数和特性
  4. 合成Markdown报告
[执行器] 步骤1: 搜索中...
[工具] DuckDuckGo搜索返回14条结果，提取前5条
[执行器] 步骤2: 访问github.com/langgenius/dify ...
[观察] 页面标题: Dify - Build Agentic workflows
发现星标数: 151,129
[执行器] 步骤3: 继续访问...
...
[报告生成] 已完成，输出文件：output/report.md

整个执行过程取决于网络速度和模型响应时间。在测试环境中，10步任务大约耗时4分钟。结束后，打开output/report.md，你会看到AI自动生成的对比表格和结论。

3.4 让AI做更复杂的多文件编程任务

Deer Flow的强大之处在于它不止能搜索，还能写代码、执行代码。我们把任务升级一下：

python main.py --task "下载Python的requests库源码，统计其中函数定义的个数，并输出每个模块的函数分布，最后生成分析图表" --max-steps 20

在这个任务中，Deer Flow会调用Shell工具执行git clone，再用Python脚本分析代码，最后用matplotlib画图。你的工作就是等待，它会在output/目录下生成一张function_distribution.png。

这个例子展示了Deer Flow真正区别于普通聊天机器人的地方：它能够操作真实环境，而不只是“谈论”怎么做事。需要提醒的是，不要给任务赋予超过本机权限的操作，比如删除系统目录、向公网发送数据等，否则AI可能“很听话”地执行了。

四、完整工作流程总结

通过上面两个例子，我们可以总结出Deer Flow的标准使用流程：

第一步：定义清晰目标。目标越明确，规划器生成的步骤越准确。例如“调研XX并输出Markdown报告”比“帮我看看AI框架”好得多。
第二步：设定步数上限。任务复杂程度与步数成正比。初学时建议设10步，跑通了再加到50步。
第三步：等待并监控日志。观察规划器拆解的步骤是否合理，如果发现某个步骤反复重试，可能是网络或API Key权限问题。
第四步：检查输出产物。Deer Flow把结果统一放在output/目录，包括中间文件、日志、最终报告。

五、容易被忽略的细节和陷阱

在实战中，我们踩了几个坑，现在一一列出。

5.1 Python版本必须锁定

如果在Python 3.12下安装，pydantic和langchain会出现兼容性错误。我们一开始用了Python 3.12，结果pip install报错堆栈长达几百行。切换到Python 3.10后一切正常。建议使用pyenv管理版本。

5.2 模型选择决定任务上限

官方文档默认支持GPT-4系列。我们用gpt-4o-mini跑长任务时，发现规划逻辑偶尔会“忘记”之前的步骤，导致重复执行。后来换成gpt-4o或claude-sonnet-4就好很多。如果预算有限，可以先用qwen-max-long这类支持256K上下文的国产模型，性价比很高。

5.3 网络环境对搜索工具的影响

Deer Flow内置的搜索工具默认走DuckDuckGo，但在某些网络环境下会超时。解决办法是设置代理，或者在.env中把搜索器切换为“本地模拟搜索”（官方提供mock_search配置，用于离线开发）。如果你要批量运行，建议准备一个稳定的代理。

5.4 长时间任务会占用大量磁盘

AI在浏览网页时会保存截图、HTML快照、中间JSON文件。一个30步的任务可能产生2GB临时文件。运行结束后，记得清理workspace/目录。否则连续跑几个任务，磁盘就满了。

5.5 不要直接给AI root权限

Deer Flow支持执行Shell命令，这意味着如果任务描述里包含“删除所有文件”这样的恶意指令，AI可能真的会执行。强烈建议在Docker容器中运行Deer Flow，或者使用普通用户权限。

六、性能数据与效果评估

为了给读者一个直观参考，我们做了三组测试。需要说明的是，测试环境为个人PC，并非云服务器，结果仅供横向参考。

任务	步数	耗时	成功率	输出质量
调研开源框架并输出报告	10	4分12秒	100%	较好，但数据有滞后
统计Python库函数分布	15	6分48秒	100%	图表准确
从零搭建一个Flask登录页	8	3分05秒	80%	代码可运行，但缺少CSRF防护

从数据可以看出，Deer Flow在“资料搜集+归纳”类任务上表现出色，但在需要安全防御的编程任务上，它更像是“初级工程师”，需要人工审核。因此，不要把它当作完全自主的软件工程师，而是一个高效的初级实习生。

七、总结与最优方案推荐

如果你打算尝试Deer Flow，我推荐的最优方案是：

使用Docker部署，避免污染本机环境。
模型选择推理能力强的gpt-4o或qwen-max，不要用mini版跑长任务。
用--max-steps 20作为起点，先跑通一个中等任务，再逐渐增加复杂度。
每次运行前清理output/和workspace/，保持磁盘空间充足。
为AI指定一个“观察者”角色，让它每执行完一个步骤就输出一句总结，便于你快速定位问题。

Deer Flow作为一个开源项目，仍在快速迭代中。它的工程化程度已经超越了大多数AutoGPT类工具，特别适合用来做自动调研、竞品分析、数据处理流水线。如果你需要的是一个能稳定执行多步骤任务的Agent底座，它值得加入你的工具箱。

最后提醒一句：AI Agent的最终质量仍然取决于底层模型的能力和你的任务设计。工具只是放大器，不要指望“一键产生神级结果”。