DeerFlow：基于 LangGraph 的可扩展 AI 超级代理深度解析

DeerFlow 是一个基于 LangGraph 构建的 AI 超级代理（Super Agent）后端系统。它集成了沙箱执行环境、持久化记忆以及可扩展的工具集，旨在让 AI 代理能够在一个隔离且持久的环境中执行复杂任务，例如执行代码、浏览网页、管理文件，甚至将任务委托给子代理并行处理。

架构概览

DeerFlow 的系统架构设计清晰，通过 Nginx 作为统一反向代理，将请求分发至后端的 LangGraph 服务和 FastAPI 网关。

graph TD
    subgraph 用户请求
        A[Nginx 统一反向代理 :2026]
    end

    A -- "/api/langgraph/*" --> B[LangGraph 服务 :2024]
    A -- "/api/* (其他)" --> C[FastAPI 网关 :8001]
    A -- "/" --> D[前端应用]

    subgraph B
        direction LR
        B1[主代理 Lead Agent]
        B1 --> B2[中间件链]
        B1 --> B3[工具集]
        B1 --> B4[子代理]
    end

    subgraph C
        C1[模型管理]
        C2[MCP 服务]
        C3[技能管理]
        C4[记忆系统接口]
        C5[文件上传与产物]
    end

请求路由逻辑：

/api/langgraph/*：所有与代理交互、会话管理和流式响应相关的请求，全部转发到 LangGraph 服务。
/api/* (其他)：模型管理、技能配置、记忆系统、文件上传等辅助功能的 RESTful API 请求，由 FastAPI 网关处理。
/ (非 API)：指向 Next.js 构建的前端 Web 界面。

核心组件

DeerFlow 的强大功能由多个精心设计的核心组件协同实现。

主代理 (Lead Agent)

系统运行时的唯一入口点是 lead_agent。它通过 make_lead_agent(config) 工厂函数创建，整合了以下核心能力：

动态模型选择：支持根据任务需求选择具备思考（Thinking）和视觉（Vision）能力的不同模型。
中间件链：通过一系列中间件处理横切关注点。
工具系统：集成了沙箱工具、模型上下文协议（MCP）、社区工具和内置工具。
子代理委托：能够将复杂任务分解并并行委托给多个子代理执行。
系统提示词注入：动态地将技能、记忆上下文和当前工作目录信息注入到系统提示词中。

中间件链 (Middleware Chain)

中间件链是 DeerFlow 实现请求生命周期管理的关键。所有中间件按严格顺序执行，每个都负责一个特定的功能。

顺序	中间件名称	主要功能
1	`ThreadDataMiddleware`	为每个会话线程创建隔离的目录（工作区、上传区、输出区）。
2	`UploadsMiddleware`	将用户新上传的文件信息注入到当前对话的上下文中。
3	`SandboxMiddleware`	为代码执行获取并管理一个隔离的沙箱环境。
4	`SummarizationMiddleware`	（可选）当上下文接近模型 Token 限制时，自动进行摘要以缩减长度。
5	`TodoListMiddleware`	（可选）在计划模式下，跟踪和管理多步骤任务的执行状态。
6	`TitleMiddleware`	在首次交互后，自动为对话生成一个简洁的标题。
7	`MemoryMiddleware`	将对话内容加入队列，用于异步提取和更新长期记忆。
8	`ViewImageMiddleware`	（条件触发）当使用视觉模型时，将图像数据注入上下文。
9	`ClarificationMiddleware`	（必须最后执行）拦截代理提出的澄清式请求，并中断当前执行流程，等待用户反馈。

沙箱系统 (Sandbox System)

为了安全地执行代码，DeerFlow 提供了基于会话线程隔离的沙箱环境，其核心特性包括：

抽象接口：提供 execute_command、read_file、write_file 和 list_dir 等标准接口。
多样的提供者：内置本地文件系统提供者 (LocalSandboxProvider)，并支持社区贡献的 Docker 提供者 (AioSandboxProvider)。
虚拟路径映射：
- /mnt/user-data/{workspace,uploads,outputs} 会被自动映射到与当前会G话线程关联的物理磁盘目录。
- /mnt/skills 则指向项目中的 deer-flow/skills/ 目录。
内置工具：提供 bash, ls, read_file, write_file, str_replace 等基础沙箱工具。

子代理系统 (Subagent System)

DeerFlow 支持将任务异步委托给子代理，实现并行处理和能力扩展。

内置代理：提供一个具备完整工具集的通用代理 (general-purpose) 和一个专用于命令执行的 bash 代理。
并发控制：每轮对话最多可同时运行 3 个子代理，超时时间为 15 分钟。
后台执行：通过后台线程池管理子代理的执行，并通过 SSE 事件跟踪其状态。
调用流程：主代理调用 task() 工具 -> 执行器在后台启动子代理 -> 主代理轮询任务状态 -> 子代理完成后返回结果。

记忆系统 (Memory System)

通过大语言模型（LLM）驱动的持久化记忆系统，DeerFlow 能够跨越多个对话保留上下文。

自动提取：分析对话内容，自动提取用户的个人背景、工作信息、偏好以及关键事实。
结构化存储：将信息分类存储为用户上下文、历史记录和带有置信度评分的事实。
防抖更新：批量更新记忆，以减少对 LLM 的调用频率（等待时间可配置）。
提示词注入：将最重要的事实和上下文信息自动注入到代理的系统提示词中。
存储后端：使用 JSON 文件存储，并基于文件的修改时间（mtime）实现缓存失效。

工具生态 (Tool Ecosystem)

DeerFlow 整合了多种工具，赋予代理强大的能力。

沙箱工具：bash, ls, read_file, write_file, str_replace
内置工具：present_files, ask_clarification, view_image, task (用于调用子代理)
社区工具：
- Tavily (网页搜索)
- Jina AI (网页内容获取)
- Firecrawl (网页抓取)
- DuckDuckGo (图片搜索)
MCP (模型上下文协议)：支持任何实现了 MCP 协议的服务，可通过标准输入输出（stdio）、SSE 或 HTTP 方式进行通信。
技能 (Skills)：通过系统提示词注入的、特定领域的工作流。

API 网关

FastAPI 应用为前端提供了丰富的 RESTful API 接口。

方法	路由	功能说明
`GET`	`/api/models`	列出所有可用的大语言模型。
`GET/PUT`	`/api/mcp/config`	管理 MCP 服务的配置。
`GET/PUT`	`/api/skills`	列出并管理可用的技能。
`POST`	`/api/skills/install`	从 `.skill` 压缩包安装新技能。
`GET`	`/api/memory`	获取当前用户的记忆数据。
`POST`	`/api/memory/reload`	强制重新加载记忆数据。
`GET/POST`	`/api/memory/config` / `status`	获取记忆系统的配置和完整状态。
`POST`	`/api/threads/{id}/uploads`	上传文件，支持自动将 PDF/PPT/Excel/Word 转换为 Markdown。
`GET`	`/api/threads/{id}/uploads/list`	列出指定会话中已上传的文件。
`DELETE`	`/api/threads/{id}`	删除会话，并清理本地相关的线程数据。
`GET`	`/api/threads/{id}/artifacts/{path}`	获取代理在执行过程中生成的产物文件。

快速上手

环境准备

Python 3.12+
uv 包管理器
你的大语言模型提供商的 API 密钥

安装与配置

克隆并进入项目目录
```
cd deer-flow
```
创建配置文件
```
cp config.example.yaml config.yaml
```
安装后端依赖
```
cd backend
make install
```

编辑 config.yaml 在项目根目录的 config.yaml 文件中配置你的模型。环境变量（以 $ 开头）会被自动加载。

models:
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    supports_thinking: false
    supports_vision: true
  - name: gpt-5-responses
    display_name: GPT-5 (Responses API)
    use: langchain_openai:ChatOpenAI
    model: gpt-5
    api_key: $OPENAI_API_KEY
    use_responses_api: true
    output_version: responses/v1
    supports_vision: true

设置环境变量

export OPENAI_API_KEY="your-api-key-here"

运行项目

启动完整应用 (从项目根目录): 该命令会同时启动 LangGraph、Gateway、前端和 Nginx。
```
make dev
```
访问 `

仅启动后端服务 (从 backend 目录):

# 终端 1: 启动 LangGraph 服务
make dev

# 终端 2: 启动 Gateway API
make gateway

LangGraph 服务位于 API 位于

总结

DeerFlow 提供了一个高度模块化和可扩展的 AI 代理后端框架。通过其分层的架构、强大的中间件链、安全的沙箱环境以及先进的记忆和子代理系统，开发者可以构建出能够处理复杂、长期任务的智能应用。无论是作为个人项目还是企业级解决方案的基础，DeerFlow 都展示了下一代 AI 代理系统的巨大潜力。

👉 如果你需要 ChatGPT 代充 / Claude / Claude Code / 镜像 / 中转 API：

购买 / 了解更多：ai4.plus
备用入口：kk4099.com

架构概览#

核心组件#

主代理 (Lead Agent)#

中间件链 (Middleware Chain)#

沙箱系统 (Sandbox System)#

子代理系统 (Subagent System)#

记忆系统 (Memory System)#

工具生态 (Tool Ecosystem)#

API 网关#

快速上手#

环境准备#

安装与配置#

运行项目#

总结#