Skip to content
xw
博客

langraph

1 post with the tag “langraph”

DeerFlow 后端 LangGraph 实现全面分析

xiwang
xiwang
全栈开发者

背景上下文

Section titled “背景上下文”

本文档提供了关于 LangGraph 如何作为 DeerFlow AI 代理系统核心执行运行时的完整分析。它涵盖了后端代码库中使用 LangGraph 的所有组件、架构模式、实现细节和部署模型。

1. 宏观架构概述

Section titled “1. 宏观架构概述”

DeerFlow 完全基于 LangGraph 作为其核心执行引擎构建，利用 LangGraph 在状态管理、检查点 (Checkpointing)、中间件支持和流式执行方面的原生能力，来交付生产级的 AI 代理平台。

核心执行流程遵循标准的 LangGraph 代理模式：

  1. 用户输入被添加到线程状态中
  2. 执行前中间件处理并丰富状态
  3. LLM 生成响应/工具调用
  4. 执行后中间件处理模型输出
  5. 如果请求了工具，则执行工具，并将结果添加到状态中
  6. 循环重复直到生成最终响应
  7. 在每个回合之间，通过 Checkpointer 持久化完整状态

2. 核心组件深入

Section titled “2. 核心组件深入”

2.1 状态 Schema 定义

Section titled “2.1 状态 Schema 定义”

文件: backend/packages/harness/deerflow/agents/thread_state.py

  • 扩展了 LangChain 标准的 AgentState (LangGraph 的默认代理状态 Schema)，包含以下自定义字段：
    • sandbox: 隔离执行环境的引用
    • thread_data: 每线程的元数据，包括工作区路径
    • title: 自动生成的对话标题
    • artifacts: 代理生成的文件/输出
    • todos: 计划模式的任务跟踪列表
    • uploaded_files: 用户上传文件的引用
    • viewed_images: 供视觉模型使用的 Base64 编码的图像
  • 实现了自定义的 Reducer，用于在状态更新期间安全地合并 Artifact 和查看的图像

2.2 Checkpointer 与状态持久化

Section titled “2.2 Checkpointer 与状态持久化”

文件:

实现:

  • 可配置的 Checkpointer 工厂，支持 3 种持久化后端：
    1. InMemorySaver: 易失性的内存存储，用于测试/开发
    2. SqliteSaver: 基于文件的持久化存储，用于单实例部署
    3. PostgresSaver: 分布式的持久化存储，用于多实例生产部署
  • 提供单例和上下文管理器两种访问模式
  • 与 LangGraph 的 Checkpointing API 完全集成，实现在执行轮回之间自动持久化状态

2.3 中间件系统

Section titled “2.3 中间件系统”

所有中间件都实现了 LangGraph 的 BaseAgentMiddleware 接口，并在图 (Graph) 执行期间以严格预定义的顺序运行，从而在不修改核心图逻辑的情况下实现横切关注点 (cross-cutting functionality) 功能：

中间件文件路径目的
Thread Dataagents/middlewares/thread_data_middleware.py创建隔离的每线程目录 (workspace, uploads, outputs) 并将路径信息注入状态
Uploadsagents/middlewares/uploads_middleware.py跟踪用户上传的文件并将引用注入状态
Sandbox Lifecyclesandbox/middleware.py管理每个线程隔离执行沙盒的获取/释放
Dangling Tool Call Fixagents/middlewares/dangling_tool_call_middleware.py为缺少对应响应的中断的工具调用插入合成错误的 ToolMessages，防止 LLM 格式错误
Guardrailsguardrails/middleware.py针对配置的安全策略执行工具调用前的授权
Summarization(LangChain 內置中间件)可选的上下文摘要，在接近 Token 限制时触发，保留近期消息同时对旧消息进行摘要
Todo/Plan Modeagents/middlewares/todo_middleware.py通过 write_todos 工具实现用于任务跟踪的计划模式功能
Title Generationagents/middlewares/title_middleware.py在第一次完整轮次后自动生成对话标题
Memoryagents/middlewares/memory_middleware.py将对话轮次排队以进行异步的记忆提取和持久化
Image Viewagents/middlewares/view_image_middleware.py为支持视觉的模型将图像文件转换为 Base64
Deferred Tool Filteragents/middlewares/deferred_tool_filter_middleware.py过滤发送至 LLM 的延迟 MCP 工具 Schema（节省上下文 Token，工具可以在运行时通过 tool_search 发现）
Subagent Limitagents/middlewares/subagent_limit_middleware.py通过截断多出的并行任务调用来强制实行最大并发子代理限制
Tool Error Handlingagents/middlewares/tool_error_handling_middleware.py捕获工具执行错误并将其转换为 LLM 可处理的正确格式化的 ToolMessages
Token Usageagents/middlewares/token_usage_middleware.py跟踪图执行中跨所有 LLM 调用的 Token 消耗
Loop Detectionagents/middlewares/loop_detection_middleware.py检测并打破重复的工具调用循环
Clarificationagents/middlewares/clarification_middleware.py拦截 ask_clarification 工具调用并中断图的执行，以向用户返回澄清请求

2.4 图构建与代理工厂

Section titled “2.4 图构建与代理工厂”

文件:

实现:

  • make_lead_agent() 是主要的图入口点，并在 langgraph.json 中注册用于 LangGraph Server
  • 使用 LangChain 的 create_agent() 工具，该工具在内部构建带有标准代理节点（模型调用、工具执行、路由器）的 LangGraph StateGraph
  • 基于运行时配置动态地配置中间件、工具、LLM 模型和系统提示词
  • 在将其作为 Runnable 返回之前，使用配置好的 Checkpointer 编译生成该图

2.5 子代理系统

Section titled “2.5 子代理系统”

文件:

实现:

  • 子代理是在独立的线程池中运行的独立 LangGraph 代理
  • task 工具允许主代理将工作委托给子代理进行并行执行
  • 子代理执行器管理子代理任务的调度、执行和事件流处理
  • 每个子代理都有自己隔离的状态和执行流，并将结果反馈回通信给主代理

2.6 运行时执行接口

Section titled “2.6 运行时执行接口”

DeerFlow 支持 LangGraph 图的 3 种部署模型：

  1. 独立 LangGraph Server: 运行在 2024 端口，通过 HTTP API 访问 (在 langgraph.json 中配置)
  2. 嵌入式进程内: backend/packages/harness/deerflow/client.py 提供 DeerFlowClient，用于在进程内直接访问编译好的图而无需网络调用
  3. 频道集成 (Channel Integration): backend/app/channels/manager.py 使用 LangGraph SDK 与运行中的服务器交互，用于 IM 频道集成 (Slack/Feishu/Telegram)

3. 核心实现模式

Section titled “3. 核心实现模式”
  1. 动态图构建: 图在运行时通过可配置的组件 (中间件、工具、模型) 构建，而不是静态定义的
  2. 中间件优先的可扩展性: 所有横切功能都作为中间件实现，保持了核心图逻辑的清晰和易维护性
  3. 可插拔的持久化: Checkpointer 后端完全可配置而无需修改应用代码
  4. 层次化代理架构: 主代理将任务委派给子代理，每个子代理作为独立的 LangGraph 执行流运行
  5. 有状态执行: 完整的线程状态在轮次之间被持久化，从而实现了长时间运行的多轮对话和任务执行

4. 测试与验证

Section titled “4. 测试与验证”

所有与 LangGraph 相关的组件都有全面的单元测试：