Wend看源码-DeerFlow(基于LangGraph 的DeepResearch框架）

前言

        最近在学习 LangGraph 框架，为了更深入地理解其最佳实践，我开始在 GitHub 上寻找优秀的项目案例进行学习。恰巧，我在社区论坛看到字节跳动新推出的深度研究框架 DeerFlow 正是基于 LangChain + LangGraph 构建的——这完美契合我当前的学习目标！于是，我立刻下载了代码，开始探索这个框架的设计与实现。

DeerFlow 简介

        DeerFlow (Deep Exploration and Efficient Research Flow) 是一个社区驱动的开源框架，专注于深度研究自动化。其核心目标是将大型语言模型（LLM） 的强大能力与专业工具无缝结合，以提升智能研究和内容生成的效率。

        DeerFlow 的创新之处在于其基于 LangGraph 构建的多智能体协作架构。该框架通过状态图（StateGraph）工作流，精巧地编排了多个专注于特定任务的 AI 智能体（如研究员、编码器、规划器、报告器等）。这些智能体各司其职又协同合作，能够处理从简单的信息问答到生成复杂的专业研究报告在内的全流程研究任务。

DeerFlow 系统架构

DeerFlow 系统架构图

      在现代软件开发领域，模块化分层架构以其清晰的结构、良好的可维护性和扩展性，成为了系统架构设计的主流范式。鉴于此，本次 DeerFlow 的系统架构图同样采用分层架构进行设计与呈现。其中包括：

基础设置层（底层支撑）

        基础设施层作为系统运行的 “地基”，提供基础环境与部署保障：

• Docker 容器化：借助容器技术，封装应用及依赖，实现环境一致化，让 DeerFlow 能在不同平台稳定部署、快速启停。

• Python 环境（uv）：基于 uv 管理 Python 依赖，高效处理智能体层、服务层等 Python 代码运行需求，加速依赖安装与解析。

• Node.js 环境（pnpm）：用 pnpm 管理 Node.js 生态依赖（如表示层 next.js、react 项目），提升包管理效率，降低存储占用。

• 部署环境配置：涵盖服务器、网络等基础配置，适配本地开发、云端部署（如火山 FaaS 引擎场景 ），保障系统灵活交付。

• 火山 FaaS 引擎：接入字节火山引擎 Serverless 能力，支持按需弹性扩缩，应对研究任务的算力波动，优化资源利用与成本。

数据层（数据中枢）

        聚焦数据存储、流转与状态管控，为上层提供可靠数据支撑：

• 内存状态存储：临时存储智能体运行时的动态状态（如任务执行进度、中间结果 ），加速数据访问，适配实时性高的智能体交互场景。DeerFlow 中的状态存储目前仅采用基于内存的方式，后续会拓展支持SQLLite/PostgreSQL等 数据库存储的方式。

• 历史消息管理：留存智能体对话、任务执行等全链路历史，用于回溯分析、问题排查，也为研究流程优化（如复盘多智能体协同逻辑 ）提供数据依据。在复杂的研究流程中，历史数据的记录和分析有助于发现问题和优化流程。

• 会话状态管理：跟踪用户与系统的交互会话，维持上下文连续性（如用户研究需求的延续、多轮对话状态 ），保障服务层、智能体层响应的一致性。从用户交互的角度来看，会话状态的管理是保证用户体验连贯性的关键。

• 配置文件管理：存储系统参数（如智能体策略、服务调用阈值 ）、工具配置（网络搜索、代码执行参数 ）等静态配置，实现灵活调优与功能扩展。项目需要根据不同的研究场景和需求进行配置，配置文件管理可以方便地进行参数调整。

• 缓存管理：缓存高频访问数据（如常用研究工具结果、模型适配元数据 ），减少重复计算与外部调用，提升系统响应速度。在数据访问频繁的情况下，缓存管理能够有效提高系统性能。

服务层（能力聚合）

        核心服务与工具，为智能体层提供功能 “弹药”：

• MCP 服务：作为特定领域（或通用 ）的能力交互媒介，提供专业数据、业务逻辑支持（如研究场景中的行业知识查询、流程合规校验 ），赋能智能体处理领域级别的复杂任务。

• 工具服务：封装网络搜索、代码执行（如 Python 脚本运行 ）、文档解析等工具，通过标准化接口供智能体调用，扩展系统 “触手”（如研究员智能体用网络搜索工具采集信息 ）。

• 模型适配：对接多类语言模型（LLM ），处理模型调用、参数适配、结果解析，让智能体层能灵活选用合适模型（如规划任务用推理强的模型、生成报告用文本生成优的模型 ），解耦模型依赖。

智能体层（业务核心）

        DeerFlow的智能体均基于 LangGraph 框架构建，实现任务拆解、协同与智能执行：

DeerFlow 核心智能体

• LangGraph 核心工作流节点：依托 LangGraph 框架，编排研究任务流程（如协调器节点→规划器节点→研究员Agent→报告处理节点 ），驱动系统按标准化、自动化流程运转，是智能体层的 “大脑中枢”。

DeerFlow 拓展功能智能体

• 拓展功能智能体：聚焦专项能力，目前包括：播客生成Agent、PPT生成 Agent、文档处理Agent、提示词优化Agent 。按需扩展系统功能，与核心工作流智能体协同，补充研究流程的 “个性化需求”。

• 多智能体协同：支持智能体间分工（如研究员智能体负责信息采集、编码员智能体处理代码任务 ）与交互（通过消息传递、状态同步 ），模拟团队协作，高效攻克复杂研究课题。

表示层（用户交互）

        基于 next.js + react 构建前端界面，承担 “用户入口” 与体验交付：

• next.js Web：作为服务端渲染（SSR ）框架，优化首屏加载、SEO 等体验，承载研究任务创建、流程监控、报告查看等核心页面，保障用户操作流畅性。

• react：通过组件化开发，构建交互控件（如需求输入表单、智能体状态看板 ），实现灵活 UI 设计，让用户便捷触发研究流程、实时感知系统状态。

整体逻辑

        用户通过表示层发起研究需求→智能体层依托服务层工具与模型，经 LangGraph 编排多智能体协同执行→数据层保障任务状态、交互数据可靠流转→基础设置层提供稳定运行环境。各层松耦合设计，既便于功能迭代（如新增智能体类型、替换模型 ），又能通过分层协同，支撑 DeerFlow 完成深度研究、报告生成等复杂场景。

DeerFlow 核心模块

智能体核心组件

图结构配置

• src/graph/builder.py

def _build_base_graph():"""Build and return the base state graph with all nodes and edges."""builder = StateGraph(State)builder.add_edge(START, "coordinator")# 节点定义builder.add_node("coordinator", coordinator_node)builder.add_node("background_investigator", background_investigation_node)builder.add_node("planner", planner_node)builder.add_node("reporter", reporter_node)builder.add_node("research_team", research_team_node)builder.add_node("researcher", researcher_node)builder.add_node("coder", coder_node)builder.add_node("human_feedback", human_feedback_node)# 边定义builder.add_edge("background_investigator", "planner")# 条件边定义builder.add_conditional_edges("research_team",continue_to_running_research_team,["planner", "researcher", "coder"],)builder.add_edge("reporter", END)return builder

        DeerFlow 使用LangGraph图结构配置定义了系统的核心节点，包括节点的定义，普通边、条件边的定义。

智能体路由选择

• src/graph/builder.py

def continue_to_running_research_team(state: State):current_plan = state.get("current_plan")# 根据步骤类型选择智能体for step in current_plan.steps:if not step.execution_res:  # 找到未执行的步骤if step.step_type == StepType.RESEARCH:return "researcher"      # 研究类任务 → 研究员if step.step_type == StepType.PROCESSING:return "coder"          # 处理类任务 → 编码器breakreturn "planner"  # 默认返回规划器

智能体类型配置

• src/config/agents.py

# Define available LLM types
LLMType = Literal["basic", "reasoning", "vision"]# Define agent-LLM mapping
AGENT_LLM_MAP: dict[str, LLMType] = {"coordinator": "basic","planner": "basic","researcher": "basic","coder": "basic","reporter": "basic","podcast_script_writer": "basic","ppt_composer": "basic","prose_writer": "basic","prompt_enhancer": "basic",
}

        通过智能体类型配置，不同的节点可以采用不同类型的LLM ，以提高节点的适应性。包括basic 基础大模型、reasoning 推理大模型、vision 视觉大模型等。

工具配置

• src/graph/nodes.py

# 研究员工具配置
async def researcher_node(state: State, config: RunnableConfig):tools = [get_web_search_tool(max_search_results),  # 搜索工具crawl_tool,                               # 爬虫工具get_retriever_tool(resources)             # RAG检索工具]return await _setup_and_execute_agent_step(state, config, "researcher", tools)# 编码器工具配置
async def coder_node(state: State, config: RunnableConfig):tools = [python_repl_tool]  # Python代码执行工具return await _setup_and_execute_agent_step(state, config, "coder", tools)

        每个智能体都有自己所需的BaseTools。在DeerFlow初始化节点的时候，包含初始化基础工具的步骤。

MCP 协同配置

• src/graph/nodes.py

async def _setup_and_execute_agent_step(state, config, agent_type, default_tools):# 1. 提取MCP服务器配置mcp_servers = {}enabled_tools = {}for server_name, server_config in mcp_settings["servers"].items():# 检查是否为当前智能体类型配置if agent_type in server_config["add_to_agents"]:mcp_servers[server_name] = server_configfor tool_name in server_config["enabled_tools"]:enabled_tools[tool_name] = server_name# 2. 创建MCP客户端并加载工具async with MultiServerMCPClient(mcp_servers) as client:loaded_tools = default_tools[:]for tool in client.get_tools():if tool.name in enabled_tools:loaded_tools.append(tool)# 3. 创建智能体并执行agent = create_agent(agent_type, agent_type, loaded_tools, agent_type)return await _execute_agent_step(state, agent, agent_type)

        在creaet_agent 创建智能体前，DeerFlow 根据代理类型配置 MCP 服务器，然后将MCP 服务器的tools集合加载到loaded_tools 集合中，此时loaded_tools 便包括了base_tools 集合和MCP_tools 集合。

多智能体协同

        DeerFlow 的多智能体协同方案并没有采用LangGraph 官网提供的多智能体解决方案，而是采用节点路由的方式，并在节点中定义了创建智能体并执行智能体的方法。其中ReSearch Team Node 节点它本身是一个协调中心，实际的智能体选择逻辑则通过条件路由实现。

• 路由函数的核心逻辑

def continue_to_running_research_team(state: State):current_plan = state.get("current_plan")# 1. 边界条件检查if not current_plan or not current_plan.steps:return "planner"  # 没有计划，返回规划器# 2. 完成状态检查if all(step.execution_res for step in current_plan.steps):return "planner"  # 所有步骤完成，重新规划# 3. 找到第一个未执行的步骤for step in current_plan.steps:if not step.execution_res:  # 找到未完成的步骤break# 4. 根据步骤类型选择智能体if step.step_type and step.step_type == StepType.RESEARCH:return "researcher"      # 研究类任务 → 研究员if step.step_type and step.step_type == StepType.PROCESSING:return "coder"          # 处理类任务 → 编码器return "planner"  # 默认返回规划器

• 智能体执行完成后的状态更新和循环机制

DeerFlow 循环执行时序图

async def _execute_agent_step(state: State, agent, agent_name: str):# 1. 找到当前要执行的步骤current_step = next((step for step in current_plan.steps if not step.execution_res), None)# 2. 执行智能体任务result = await agent.ainvoke(agent_input)response_content = result["messages"][-1].content# 3. 关键：更新步骤执行结果current_step.execution_res = response_content# 4. 返回 research_team 继续循环return Command(update={"messages": [HumanMessage(content=response_content, name=agent_name)],"observations": observations + [response_content],},goto="research_team"  # 关键：返回协调中心)

DeerFlow BaseGraph

DeerFlow LangGraph 核心工作流编排

BaseGraph 具体节点简介

• 协调器节点（coordinator）：作为系统与用户交互的入口点，管理整个工作流的生命周期。它会根据用户输入启动研究过程，当遇到研究相关问题、事实询问或信息请求时，会将任务委派给规划器。同时，它还负责回应问候、进行闲聊，礼貌拒绝不适当或有害的请求，并确保以用户输入的语言进行回复。

• 背景调查节点（background_investigator）：此节点主要进行背景信息的调查和收集。它会使用选定的搜索引擎（如 Tavily）或网络搜索工具，根据用户的查询内容获取相关信息，并将这些信息以特定格式存储在状态中，为后续的规划和研究提供背景支持。

• 规划器节点（planner）：是系统中负责任务分解和规划的战略组件。它会分析研究目标，创建结构化的执行计划，判断是否有足够的上下文来继续研究，或者是否需要进行更多的调查。如果计划中的步骤都已执行完毕，或者当前步骤执行结果为空时，规划器会决定下一步的走向，如继续规划或分配给研究团队执行。

• 报告员节点（reporter）：作为研究输出的最终阶段处理器，负责汇总研究团队的发现。它会处理和组织收集到的信息，生成全面的研究报告，并将报告反馈给用户，标志着整个研究流程的结束。

• 研究团队节点（research_team）：是一个集合节点，代表整个研究团队。它会根据当前计划中未执行步骤的类型，将任务分配给研究员或编码员。研究团队会根据规划器制定的计划执行具体的研究任务，推动研究流程的进行。

• 研究员节点（researcher）：属于研究团队的一部分，主要使用网络搜索引擎、爬虫或 MCP 服务等工具进行网络搜索和信息收集。当规划器分配的任务类型为研究时，研究员节点会负责执行该任务，为研究提供所需的信息。

• 编码员节点（coder）：同样是研究团队的一员，主要使用 Python REPL 工具处理代码分析、执行和技术任务。当规划器分配的任务类型为处理时，编码员节点会负责执行该任务，完成代码相关的工作。

• 人工反馈节点（human_feedback）：当规划器判断当前没有足够的上下文来完成研究时，会将流程导向此节点。该节点允许用户提供额外的反馈和信息，以帮助系统进一步完善研究计划，继续推进研究流程。

BaseGraph 核心流程编排

        最后，我们总结下DeerFlow 的baseGraph核心工作流编排的大体流程：

•  启动与需求协调（协调器节点）

  • 用户需求接收：作为整个流程的起始点，协调器接收用户提出的研究需求，例如课题探索、问题分析等。

  • 系统工作流触发：协调器将用户需求转化为系统可执行的任务，成为连接用户需求与系统执行的关键 “桥梁”，促使系统正式进入工作流。

• 背景信息夯实（背景调研节点）

  • 工具调用：为了获取与研究需求相关的基础信息，系统调用多种工具，包括搜索工具（如 Tavily、Brave Search 等）和爬虫工具（如 Jina client）。

  • 信息采集：通过这些工具广泛采集信息，为后续的任务规划提供全面且丰富的 “素材”，解决 “研究依据从哪来” 的问题。

• 任务规划与决策（规划器节点）

  • 任务拆解与路径设计：规划器依据背景调研的结果，对研究任务进行细致拆解，并设计出具体的执行路径。明确哪些任务由研究员负责采集信息，哪些任务由编码员进行代码验证。

  • 人工反馈机制：若在规划过程中发现信息不足或者需要人工干预，系统会触发 “人工反馈” 环节。用户可以在此环节补充需求或调整研究方向，以确保任务规划的精准性。

• 团队协同执行（研究团队节点）

  • 研究员 Agent：借助互联网检索、RAG 检索（RAGFlow）以及 MCP 服务器等工具，专注于使用搜索和爬虫工具深入挖掘领域知识，包括行业数据、学术观点等，主要负责信息的收集与分析工作。

  • 编码员 Agent：借助代码执行工具（Python REPL），处理各类技术任务，如数据建模、算法验证等，实现 “信息 + 技术” 双维度的推进。

• 成果整合与输出（报告器节点）

  • 成果汇聚与整理：报告器收集研究员和编码员的工作成果，并对这些成果进行结构化整理。

  • 最终报告生成：经过整理后，生成涵盖研究结论、数据支撑、技术验证等内容的最终报告，形成从 “需求输入” 到 “成果输出” 的完整闭环。

参考文献

https://github.com/bytedance/deer-flow