传统 LangGraph 智能体迁移到 DeerFlow 实施手册

一、DeerFlow 是什么

DeerFlow（Deep Exploration and Efficient Research Flow）是字节跳动于2025年5月开源的一个社区驱动的深度研究框架。DeerFlow 2.0 是基于 LangGraph 1.0 构建的“超级智能体编排框架” ，它不是在 LangGraph 上加一层薄封装，而是围绕“超级智能体”理念进行的彻底重写。

可以这样理解三者关系：LangGraph 是状态机引擎（发动机），LangChain 是组件库（零件），而 DeerFlow 是整合了发动机和零件的完整整车——附带驾驶舱（Web UI）、安全系统（沙箱）、导航（记忆系统）和扩展接口（技能/工具系统）。

与原生 LangGraph 相比，DeerFlow 提供了以下开箱即用的能力：

能力	原生 LangGraph	DeerFlow 2.0
Web UI	需自行开发	内置 Next.js 聊天界面
沙箱执行	需自行集成	内置 Docker/本地沙箱
持久化记忆	需自行实现	内置跨会话记忆管理
子智能体调度	需自行编排	内置子智能体委托机制
技能/工具系统	需自行封装	内置可扩展技能库
多平台集成	需自行开发	原生适配飞书、Slack、Telegram

二、核心架构原理

DeerFlow 采用典型的分层架构，通过 Nginx 作为统一入口：

Client (Browser)
        │
        ▼
┌───────────────────────────────────────┐
│  Nginx (Port 2026)                    │
│  统一反向代理入口                       │
│  /api/langgraph/* → LangGraph Server  │
│  /api/*           → Gateway API       │
│  /*               → Frontend          │
└───────────────┬───────────────────────┘
                │
    ┌───────────┼───────────┐
    ▼           ▼           ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│LangGraph│ │ Gateway │ │Frontend │
│ Server  │ │  API    │ │Next.js  │
│ (2024)  │ │ (8001)  │ │ (3000)  │
└─────────┘ └─────────┘ └─────────┘

核心组件职责：

1. LangGraph Server（Agent 运行时） ：负责 Agent 创建与配置、Thread 状态管理、中间件链执行、Tool 编排和 SSE 流式响应。

2. Gateway API（FastAPI 应用） ：提供非 Agent 操作的 REST 端点，包括模型管理、MCP 配置、技能管理、文件上传等。

3. 中间件链（Middleware Chain） ：DeerFlow 2.0 构建了 14 层严格有序的中间件链，按顺序处理线程隔离目录创建、上传文件注入、沙箱环境获取、上下文摘要、任务清单追踪、记忆提取等横切关注点。

4. Lead Agent（主智能体） ：运行时入口点，通过 make_lead_agent(config) 创建，整合了动态模型选择、中间件链、工具系统、子智能体委托和技能注入。

三、软件下载与部署

3.1 环境要求

资源	规格要求
操作系统	Linux（推荐 Ubuntu 20.04+）
Python	3.12 或更高版本
Node.js	22 或更高版本
内存	至少 16GB（推荐 32GB）
存储	200GB SSD
Docker	20.10+（可选但推荐）

3.2 下载与部署

方式一：Docker Compose 一键部署（推荐）

# 克隆 DeerFlow 官方仓库
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

# 使用 Docker Compose 启动全套服务
docker-compose up -d

方式二：源码部署

# 1. 克隆仓库
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

# 2. 复制配置文件
cp config.example.yaml config.yaml

# 3. （可选）预拉取沙箱镜像（约 500MB+）
make setup-sandbox

# 4. 安装后端依赖（使用 uv）
cd backend
uv sync

# 5. 安装前端依赖
cd ../frontend
npm install

# 6. 启动服务
# 后端: cd backend && uvicorn deerflow.gateway.app:app --port 8001
# 前端: cd frontend && npm run dev

3.3 基础配置

配置文件 config.yaml 需放在项目根目录，核心配置项包括：

• 模型配置：配置 LLM 提供商（OpenAI、Ollama 等）
• 工具配置：启用/配置内置工具（Tavily、Brave Search 等）
• 沙箱配置：配置沙箱提供方（本地或 Docker）
• 记忆配置：配置向量数据库（Chroma 等）

四、迁移实施步骤

4.1 迁移策略总览

由于 DeerFlow 2.0 与 1.x 系列没有共享代码，是完全重写，迁移不是简单的代码复制，而是架构适配。幸运的是，DeerFlow 提供了 LangGraph 兼容 API（/api/langgraph/* 路径），使得现有 LangGraph 客户端可以基本不变地工作。

迁移的核心思路是：保留业务逻辑，适配框架接口。

4.2 第一步：评估现有 LangGraph 智能体

在开始迁移前，先梳理现有智能体的组成部分：

组件	迁移方式
State 定义	适配到 DeerFlow 的 AgentState 扩展机制
节点函数（Node）	封装为 DeerFlow 的 Skill 或 Tool
图结构（Graph）	由 DeerFlow Lead Agent 接管编排
工具（Tools）	注册到 DeerFlow 工具系统
检查点（Checkpointer）	由 DeerFlow 记忆系统接管
流式输出	适配 DeerFlow SSE 流式架构

4.3 第二步：Skill 化——将节点封装为 Skill

DeerFlow 的核心扩展机制是 Skill（技能） 。传统 LangGraph 中的每个节点，在 DeerFlow 中应封装为一个 Skill。

Skill 开发最佳实践：在 skills/custom/ 目录下创建自定义 Skill，避免直接修改 skills/builtins/，防止版本升级时产生合并冲突。

示例：将传统 LangGraph 节点迁移为 Skill

传统 LangGraph 节点写法：

def research_node(state: AgentState):
    # 执行研究逻辑
    query = state["query"]
    results = search_tool.run(query)
    return {"research_results": results}

DeerFlow Skill 封装写法：

# 在 skills/custom/research_skill.py
from deerflow.skills.base import BaseSkill

class ResearchSkill(BaseSkill):
    name = "research"
    description = "执行深度研究任务"
    
    async def execute(self, context, params):
        query = params.get("query")
        # 原有的研究逻辑保持不变
        results = await self.search_tool.run(query)
        return {"results": results}

4.4 第三步：Tool 化——将工具注册到工具系统

DeerFlow 的工具系统支持三种类型：

1. 内置工具：框架自带
2. MCP 工具：通过 MCP 协议集成
3. 自定义工具：遵循 LangChain BaseTool 规范注册

迁移自定义工具：

# 传统 LangGraph 工具
from langchain.tools import tool

@tool
def web_search(query: str) -> str:
    # 搜索逻辑
    return results

# DeerFlow 中通过 config.yaml 注册
# 或使用 MCP 协议暴露

DeerFlow 支持通过 config.yaml 控制工具的启用/禁用，无需修改代码。

4.5 第四步：适配 State 管理

传统 LangGraph 依赖自定义的 State 类型和 reducer 函数。DeerFlow 提供了 ThreadState 和 AgentState 两层状态管理：

• ThreadState：管理会话级别的状态（线程隔离）
• AgentState：管理 Agent 执行过程中的状态

迁移时，将原有 State 字段映射到 DeerFlow 的 AgentState 扩展字段中。

4.6 第五步：配置适配

将原有 LangGraph 的配置迁移到 DeerFlow 的 config.yaml：

# DeerFlow config.yaml 关键配置项
models:
  provider: openai  # 或 ollama
  model: gpt-4

tools:
  - tavily_search
  - brave_search
  # 自定义工具

skills:
  - research
  - analysis
  - reporting

sandbox:
  use: deerflow.community.aio_sandbox:AioSandboxProvider
  # 或 LocalSandboxProvider

4.7 第六步：迁移流式输出

传统 LangGraph 使用 astream 方法。DeerFlow 有两条并行的流式路径：

1. Gateway 路径：通过 HTTP SSE 服务浏览器和 IM 渠道
2. DeerFlowClient 路径：通过进程内调用服务 Jupyter、脚本

DeerFlow 订阅 LangGraph 的 stream_mode=["values", "messages", "custom"]：

• values：节点级 state 快照
• messages：LLM token 级 delta
• custom：显式 StreamWriter 事件

迁移建议：如果你的前端依赖自定义流式事件，使用 DeerFlow 的 StreamWriter 机制发送自定义事件。

4.8 第七步：集成 Web UI

迁移完成后，DeerFlow 内置的 Next.js Web UI 自动可用。访问 http://localhost:3000 即可使用聊天界面。

如果希望保留原有前端，DeerFlow 提供 LangGraph 兼容 API（/api/langgraph/*），原有客户端可以继续工作。

五、迁移检查清单

序号	迁移项	状态
1	环境准备（Python 3.12+、Node.js 22+、Docker）	☐
2	克隆 DeerFlow 仓库	☐
3	复制并配置 config.yaml	☐
4	部署 DeerFlow 服务（Docker 或源码）	☐
5	将原有节点函数封装为 Skill	☐
6	将原有工具注册到 DeerFlow 工具系统	☐
7	适配 State 定义到 AgentState	☐
8	配置模型、工具、技能到 config.yaml	☐
9	测试流式输出是否正常	☐
10	验证 Web UI 功能	☐
11	生产环境部署（配置持久化存储等）	☐

六、常见问题

Q: 我的 LangGraph 使用了自定义 Checkpointer，怎么办？

A: DeerFlow 内置了检查点机制，支持 Postgres 与 MongoDB 双存储模式。将原有检查点逻辑迁移到 DeerFlow 的记忆系统即可。

Q: 迁移后还能用 LangGraph 原生的 API 吗？

A: 可以。DeerFlow 的 Gateway 暴露了 /api/langgraph/* 路径，LangGraph SDK 客户端可以继续使用。

Q: DeerFlow 2.0 和 1.0 有什么区别？

A: DeerFlow 2.0 是围绕“超级智能体”理念的彻底重写，与 1.0 没有共享代码。2.0 引入了子智能体、持久化记忆、沙箱执行和可扩展技能系统。

Q: 迁移需要重写多少代码？

A: 业务逻辑（搜索、分析、报告生成等）基本可以保留，主要工作量在于将节点函数封装为 Skill 格式，以及将配置适配到 DeerFlow 的 config.yaml 格式。

七、参考资源

• 官方仓库：https://github.com/bytedance/deer-flow
• DeerFlow Book（二次开发指南）：https://github.com/hawkli-1994/deerflow-book
• 配置指南：backend/docs/CONFIGURATION.md
• API 文档：backend/docs/API.md
• 架构文档：backend/docs/ARCHITECTURE.md