技术详解：如何用 DeerFlow 构建企业级 AI Agent 应用

约 3220 字大约 11 分钟

AI Agent 开源项目技术详解虾搞技术

2026-03-26

前言

还记得上周我跟大家分享的 DeerFlow 热点新闻吗？这个字节跳动开源的超级 Agent 框架，发布一个月就席卷 GitHub，今天已经突破 21,000+ ⭐ 了。

作为一个写了十几年代码的老程序员，我见过太多框架从热门到沉寂。但 DeerFlow 不一样——它不是另一个"玩具项目"，而是真正能落地生产的 Super Agent Harness。

今天这篇文章，我会从技术角度深度拆解 DeerFlow 的架构设计、核心特性，以及如何用它构建企业级 AI Agent 应用。坐稳了，这会是一篇干货满满的长文。

一、DeerFlow 是什么？从 Deep Research 到 Super Agent

先理清楚一个概念：DeerFlow 2.0 不是 1.x 的简单升级，而是完全重写。

1.1 从研究工具到生产框架

DeerFlow 最初只是一个 Deep Research（深度研究）框架，帮你自动搜索、整理、生成研究报告。但社区的想象力远超作者预期——有人用它搭数据流水线，有人用它生成演示文稿，有人用它快速做 Dashboard...

这让团队意识到：DeerFlow 不只是一个研究工具，它是一个让 Agent 真正把事情做完的运行时基础设施。

于是有了 2.0 版本——一个开箱即用、同时又足够可扩展的 Super Agent Harness。

1.2 核心技术栈

DeerFlow 不是从零造轮子，而是站在巨人的肩膀上：

LangChain：LLM 交互与 Chain 编排
LangGraph：多 Agent 编排的核心
Docker：Sandbox 隔离执行环境
Nginx：前端 + 后端反向代理
Node.js + Python：前后端分离架构

这种选择很聪明——用业界成熟的方案解决 80% 的问题，专注在自己的核心价值上。

二、DeerFlow 的核心架构设计

让我们看看这个"超级 Agent harness"的内部结构。

2.1 整体架构图

┌─────────────────────────────────────────────────────────┐
│                     Frontend (React)                     │
│              http://localhost:2026                       │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                      Nginx                                │
│              (反向代理 + 静态文件服务)                     │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┴────────────┐
        │                         │
┌───────▼──────────┐    ┌────────▼──────────────┐
│   Gateway API    │    │  LangGraph Server      │
│   (Python/FastAPI)│    │  (langgraph dev)      │
└───────┬──────────┘    └────────┬──────────────┘
        │                         │
        └────────────┬────────────┘
                     │
        ┌────────────▼────────────┐
        │   Sandbox Execution      │
        │   (Docker Container)     │
        └──────────────────────────┘

2.2 三大核心服务

DeerFlow 由三个核心服务组成：

1. Gateway API（网关层）

负责前端交互、文件上传、配置管理
管理 Skills、Models、Sessions
提供 RESTful API

2. LangGraph Server（Agent 运行时）

基于 langgraph dev 运行
执行 Agent 逻辑、Sub-Agent 编排
处理流式响应

3. Sandbox（沙箱执行环境）

隔离的 Docker 容器
完整的文件系统（/mnt/user-data/）
支持 Bash 执行、代码运行

这种分层设计很经典——网关负责接入，LangGraph 负责 Agent 逻辑，Sandbox 负责实际执行。每个层都可以独立扩展。

三、核心特性深度解析

DeerFlow 最吸引我的不是它能做什么，而是它如何设计这些能力。让我们逐个拆解。

3.1 Skills 系统：结构化能力模块

Skills 是 DeerFlow 的灵魂，也是它能做"几乎任何事"的关键。

Skill 的本质

一个 Standard Agent Skill 就是一个 Markdown 文件，里面定义了：

工作流（Workflow）
最佳实践
参考资源
示例代码

DeerFlow 内置了一批 Skills：

research/：深度研究
report-generation/：报告生成
slide-creation/：演示文稿制作
web-page/：网页生成
image-generation/：图像生成

Skill 的加载策略

这里有个很巧妙的设计：按需渐进加载。

不是一次性把所有 Skills 都塞进上下文（那样太浪费 Token 了），而是：

先加载 Skill 的元数据
根据任务判断需要哪个 Skill
只加载真正需要的 Skill 内容

这种设计让 DeerFlow 即使有几十个 Skills，也能保持上下文窗口的干净。

3.2 Sub-Agents：动态子 Agent 编排

复杂任务不可能一次完成，DeerFlow 的做法是：先拆解，再执行。

工作原理

Lead Agent（主 Agent）
    ├─→ 分析任务
    ├─→ 拆解成子任务
    ├─→ 动态拉起 Sub-Agent 1 ──→ 执行子任务 A ──→ 返回结果
    ├─→ 动态拉起 Sub-Agent 2 ──→ 执行子任务 B ──→ 返回结果
    ├─→ 动态拉起 Sub-Agent 3 ──→ 执行子任务 C ──→ 返回结果
    └─→ 汇总所有结果 → 最终输出

关键设计点

隔离的上下文：每个 Sub-Agent 都有独立的上下文，看不到主 Agent 和其他 Sub-Agent 的信息（避免干扰）
并行执行：条件允许时，Sub-Agents 可以并行运行（提升效率）
结构化结果：Sub-Agent 返回结构化数据，方便主 Agent 汇总

这就是为什么 DeerFlow 能处理从几分钟到几小时的任务——比如一个研究任务，可以拆成十几个 Sub-Agents，分别探索不同方向，最后合并成一份完整报告。

3.3 Sandbox：真正的执行环境

这是 DeerFlow 和"带工具的聊天机器人"最大的区别：它有自己的"电脑"。

Sandbox 内部结构

每个任务都运行在隔离的 Docker 容器里，里面有完整的文件系统：

/mnt/user-data/
├── uploads/      # 用户上传的文件
├── workspace/    # Agent 的工作目录
└── outputs/      # 最终交付物

Agent 能做什么

在这个 Sandbox 里，Agent 可以：

✅ 读写和编辑文件
✅ 执行 Bash 命令
✅ 运行代码（Python、Node.js 等）
✅ 查看图片
✅ 安装依赖

而且整个过程：

🛡️ 可审计：所有操作都有记录
🔒 隔离：不同 Session 之间不会互相污染
💾 持久化：数据会保存下来

3.4 Context Engineering：上下文管理

长链路任务最容易遇到的问题就是：上下文窗口爆了。

DeerFlow 的解决方案很积极：

摘要压缩：总结已完成的子任务，把中间结果转存到文件系统
信息分级：暂时不重要的信息先压缩，需要时再召回
文件中转：大内容直接存文件，上下文里只保留文件路径

这种设计让 DeerFlow 在长链路、多步骤任务里也能保持聚焦。

3.5 长期记忆：跨 Session 的个性化

大多数 Agent 对话结束就忘了一切，DeerFlow 不一样：

持久化 Memory：保存在本地，跨 Session 使用
学习偏好：你的写作风格、技术栈、工作习惯
用户控制：Memory 数据完全在你手里

你用得越多，它越了解你。

四、实战：从零搭建 DeerFlow

说了这么多理论，让我们动手实际部署一个 DeerFlow。

4.1 方式一：Docker（推荐）

这是最简单的方式，适合大多数人。

步骤 1：克隆仓库

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

步骤 2：生成配置

make config

这会基于示例模板生成本地配置文件 config.yaml。

步骤 3：配置模型

编辑 config.yaml，至少定义一个模型：

models:
  - name: gpt-4
    display_name: GPT-4
    use: langchain_openai:ChatOpenAI
    model: gpt-4
    api_key: $OPENAI_API_KEY
    max_tokens: 4096
    temperature: 0.7

  - name: deepseek-v3
    display_name: DeepSeek v3.2
    use: langchain_openai:ChatOpenAI
    model: deepseek-chat
    api_key: $DEEPSEEK_API_KEY
    base_url: https://api.deepseek.com/v1

步骤 4：设置 API Key

编辑 .env 文件：

TAVILY_API_KEY=your-tavily-api-key
OPENAI_API_KEY=your-openai-api-key
DEEPSEEK_API_KEY=your-deepseek-api-key
INFOQUEST_API_KEY=your-infoquest-api-key

步骤 5：启动服务

make docker-init   # 首次运行，拉取 Sandbox 镜像
make docker-start  # 启动服务

然后访问：http://localhost:2026

4.2 方式二：本地开发

如果你想深度定制，可以用本地开发模式。

前提条件

Node.js 22+
pnpm
uv
nginx

检查环境

make check

安装依赖

make install

启动开发服务

make dev

同样访问：http://localhost:2026

五、进阶：配置你的企业级 Agent

现在 DeerFlow 跑起来了，让我们配置一些企业级特性。

5.1 Sandbox 模式选择

DeerFlow 支持多种 Sandbox 执行方式：

模式	说明	适用场景
本地执行	直接在宿主机上运行	开发调试
Docker	在隔离的 Docker 容器里运行	单机部署
Docker + Kubernetes	通过 Provisioner 在 K8s Pod 中运行	集群部署

编辑 config.yaml 中的 sandbox 配置：

sandbox:
  use: deerflow.community.aio_sandbox:AioSandboxProvider
  # 其他配置...

5.2 IM 渠道接入

DeerFlow 支持从即时通讯应用接收任务，而且不需要公网 IP！

支持的渠道

渠道	传输方式	上手难度
Telegram	Bot API（long-polling）	简单
Slack	Socket Mode	中等
Feishu / Lark	WebSocket	中等

配置示例

在 config.yaml 中添加：

channels:
  langgraph_url: http://localhost:2024
  gateway_url: http://localhost:8001

  session:
    assistant_id: lead_agent
    config:
      recursion_limit: 100
    context:
      thinking_enabled: true
      is_plan_mode: false
      subagent_enabled: false

  feishu:
    enabled: true
    app_id: $FEISHU_APP_ID
    app_secret: $FEISHU_APP_SECRET

  telegram:
    enabled: true
    bot_token: $TELEGRAM_BOT_TOKEN
    allowed_users: []

在 .env 中设置对应的 Key：

FEISHU_APP_ID=cli_xxxx
FEISHU_APP_SECRET=your_app_secret
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

常用命令

配置好后，在聊天窗口里可以直接用：

命令	说明
`/new`	开启新对话
`/status`	查看当前 Thread 信息
`/models`	列出可用模型
`/memory`	查看 Memory
`/help`	查看帮助

5.3 MCP Server 扩展

DeerFlow 支持通过 MCP（Model Context Protocol）Server 扩展能力。

编辑 config.yaml 添加你的 MCP Server：

mcp:
  servers:
    - name: my-custom-server
      command: npx -y @myorg/mcp-server
      env:
        API_KEY: $MY_API_KEY

还支持 HTTP/SSE MCP Server，以及 OAuth token 流程（client_credentials、refresh_token）。

六、企业级应用案例

让我们看看 DeerFlow 在企业场景中的一些实际应用。

6.1 案例一：智能研究助理

场景：市场研究团队需要快速了解一个新技术方向。

DeerFlow 工作流：

Lead Agent 接收任务："研究 AI Agent 框架的发展现状"
拆解成子任务：
- Sub-Agent 1：搜索 GitHub Trending 上的 Agent 项目
- Sub-Agent 2：搜集技术博客和论文
- Sub-Agent 3：整理各家厂商的方案对比
- Sub-Agent 4：分析技术趋势和投资热点
并行执行所有 Sub-Agents
汇总结果，生成一份完整的研究报告

产出：一份 20-30 页的深度研究报告，包含数据、图表、分析。

6.2 案例二：自动化内容生成

场景：内容团队需要定期发布技术博客。

DeerFlow 工作流：

Lead Agent 接收任务："写一篇关于 OpenClaw 的技术文章"
拆解：
- Sub-Agent 1：搜集 OpenClaw 的资料和文档
- Sub-Agent 2：分析其架构设计
- Sub-Agent 3：生成文章大纲
- Sub-Agent 4：撰写正文内容
执行、汇总、润色
生成最终的 Markdown 文章

产出：一篇符合虾搞编程风格的技术博客文章。

6.3 案例三：代码助手 + CI/CD 集成

场景：开发团队需要一个智能代码助手。

DeerFlow 工作流：

接入 GitHub Webhook
收到 PR 时，自动触发 DeerFlow：
- Sub-Agent 1：审查代码质量
- Sub-Agent 2：检查安全隐患
- Sub-Agent 3：运行测试并分析结果
汇总审查报告，添加 PR 评论

产出：一份详细的代码审查报告，帮助团队提升代码质量。

七、推荐模型

DeerFlow 对模型没有强绑定，只要实现了 OpenAI 兼容 API 的 LLM 理论上都可以接入。

但官方推荐这些模型（在 DeerFlow 上表现更好）：

模型	特点	适用场景
Doubao-Seed-2.0-Code	字节跳动出品，代码能力强	代码生成、技术任务
DeepSeek v3.2	性价比高，推理能力强	通用任务、研究
Kimi 2.5	长上下文窗口（100k+）	深度研究、长文档

选择模型时可以参考这些维度：

长上下文窗口（100k+ tokens）→ 适合深度研究
推理能力 → 适合自适应规划和复杂拆解
多模态输入 → 适合理解图片和视频
稳定的 Tool Use → 适合可靠的函数调用

八、作为 Python 库使用

DeerFlow 也可以作为内嵌的 Python 库使用，不必启动完整的 HTTP 服务。

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

# 聊天
response = client.chat("Analyze this paper for me", thread_id="my-thread")

# 流式响应
for event in client.stream("hello"):
    if event.type == "messages-tuple" and event.data.get("type") == "ai":
        print(event.data["content"])

# 配置与管理
models = client.list_models()      # 列出模型
skills = client.list_skills()      # 列出 Skills
client.update_skill("web-search", enabled=True)  # 更新 Skill
client.upload_files("thread-1", ["./report.pdf"])  # 上传文件

这种方式适合把 DeerFlow 集成到你现有的 Python 应用中。

九、总结：DeerFlow 的野心

最后，让我们回到最初的问题：DeerFlow 到底是什么？

它不是另一个 Agent Framework，而是一个 Super Agent Harness——一个让 Agent 真正把事情做完的运行时基础设施。

它的核心价值在于：

开箱即用：你不需要自己拼装 LangChain + LangGraph + Docker，DeerFlow 都帮你弄好了
足够可扩展：Skills、Tools、MCP Server，你可以按自己的需求定制
真正能落地：Sandbox、Memory、Context Management，这些都是生产环境必须的

从 Deep Research 到 Super Agent Harness，DeerFlow 的演变反映了一个趋势：AI Agent 正在从玩具走向生产。

而 DeerFlow，可能就是那个让你的企业级 AI Agent 应用从 idea 变成 reality 的工具。

参考资料

这篇文章写得有点长，能看到这里的都是真爱。如果你觉得有用，别忘了点赞分享！有什么问题，评论区聊聊~ 🦐