[智能体-362]：Deep agent的框架

结合前面的术语、分层关系、模块职责与运行流程，完整梳理LangChain Deep Agents 整体框架，包含分层架构、核心模块、数据流、执行流程、周边依赖，同时衔接Harness、LangChain、LangGraph概念。

一、整体技术分层架构

Deep Agents 本质是面向复杂智能体的一站式 Harness，整体分为四层，自底向上依赖：

plaintext

┌─────────────────────────────────────────────────────┐ │ 应用层（业务调用） │ │ 业务代码 / 前端交互 / 任务发起 / 结果输出 │ └───────────────────────┬─────────────────────────────┘ │ ┌───────────────────────▼─────────────────────────────┐ │ Deep Agents 核心层（完整 Harness 驾驭框架） │ │ 任务规划、VFS、子代理编排、人机介入、沙箱、内置工具 │ └───────────────────────┬─────────────────────────────┘ │ ┌───────────────────────▼─────────────────────────────┐ │ LangChain 基础组件层（能力积木） │ │ 大模型、Prompt、Skill、Tool、记忆、消息管理 │ └───────────────────────┬─────────────────────────────┘ │ ┌───────────────────────▼─────────────────────────────┐ │ LangGraph 运行时内核（引擎/底盘） │ │ 状态管理、图编排、断点续跑、中断、流式输出 │ └─────────────────────────────────────────────────────┘

---

二、各层级详细说明

1. 底层：LangGraph 运行时（引擎）

整个框架的执行底座，Deep Agents 所有逻辑都基于它运行，不承载业务能力，只负责流程与状态。

核心模块

1. State 全局状态统一存储全链路数据：任务清单、VFS 文件索引、对话上下文、子代理状态、执行进度。
2. Graph 图引擎以「节点 + 边」组织执行逻辑，天然支持分支、循环、多分支并行，实现标准 Agent 循环：思考 → 行动 → 观察 → 复盘。
3. Checkpoint 检查点定时持久化全量状态，任务中断、服务重启后断点续跑，适配小时 / 天级长任务。
4. Interrupt 中断机制支撑人机介入，主动暂停流程，等待外部输入后恢复执行。
5. Stream 流式输出实时推送执行日志、中间结果、工具调用记录。

---

2. 基础组件层：LangChain（能力库）

提供通用原子能力，是 Deep Agents 调用的 “零件”，区分你定义的Skill / Tool。

核心模块

1. LLM/ChatModel大模型接入层，支撑所有推理、生成能力（Skill 的底层）。
2. Prompt & Message 管理系统提示词、对话历史、消息格式化，统一输入输出规范。
3. Skill 能力模型原生能力 + 上下文封装：摘要、改写、分析、文案生成等，纯推理、无外部调用。
4. Tool 工具外部能力封装：API、数据库、MCP 调用、文件操作等，需外部交互。
5. Memory 记忆组件短期会话记忆、历史消息压缩，辅助上下文管控。

---

3. 核心层：Deep Agents Harness（主体框架）

这是 Deep Agents 独有的上层封装，也是Harness 驾驭层的完整体现，是框架核心。

模块总览

• 任务规划器 Planner
• 虚拟文件系统 VFS
• 子代理编排器 Subagent Orchestrator
• 人机介入 HITL
• 安全沙箱 Sandbox
• 内置工具集
• 全局规则与系统提示词

模块详解

（1）Planner 任务规划器

Deep Agents 核心特性，显式任务管理，替代普通 Agent 隐式思考。

• 功能：将整体目标拆解为结构化待办清单（Todo），标记状态：pending / in_progress / completed / failed。
• 能力：执行中动态校验进度、任务失败自动重规划、调整执行顺序。
• 配套内置工具：write_todo、update_todo、list_todo。

（2）VFS 虚拟文件系统

解决 LLM 上下文窗口限制的核心组件。

• 形态：内存级虚拟文件，也可对接本地 / 对象存储持久化。
• 功能：存储长文本、完整代码、报表、执行日志等大容量数据；跨主代理 / 子代理 / 工具共享数据。
• 配套内置工具：read_file、write_file、ls、edit_file。
• 价值：超大内容脱离对话上下文，大幅降低 Token 消耗。

（3）Subagent Orchestrator 子代理编排器

实现分层多智能体协作。

• 角色划分：
  • 主代理：全局统筹、分发任务、汇总结果，不执行具体细节工作；
  • 子代理：专项角色（调研、编码、文案、审核），拥有独立上下文与专属工具。
• 特性：子代理之间上下文隔离，避免信息混杂；支持动态创建、销毁子代理。
• 配套内置工具：spawn_subagent。

（4）HITL 人机在回路

企业合规与风险管控模块。

• 触发时机：高危操作、关键决策、对外输出、计划变更。
• 能力：自动中断流程，支持人工审核、修改指令、驳回任务、补充信息，人工确认后恢复执行。
• 依赖：底层 LangGraph Interrupt 中断能力。

（5）Sandbox 安全沙箱

外部命令 / 代码执行的隔离环境。

• 防护对象：Shell 命令、Python 代码、脚本运行等高风险操作。
• 策略：网络隔离、资源配额、命令白名单、超时限制，防止越权、恶意操作。
• 支持主流沙箱后端：Modal、Daytona、Deno。

（6）内置工具集 & 全局规则

• 原生预装工具：规划类、文件类、子代理类、命令执行类，开箱即用。
• 系统提示词：全局统一约束所有代理的行为规范、思考逻辑、输出格式。

---

4. 顶层：应用层

业务接入入口，开发者仅需少量代码调用框架，无需关心底层流程。

• 任务发起、参数配置（模型、子代理、开关项）
• 结果接收、页面展示、日志查看
• 二次业务逻辑封装

---

三、框架完整执行数据流

以「复杂业务任务」为例，串联全模块运行顺序：

1. 应用层提交整体任务 → 传入 Deep Agents 主代理
2. Planner拆解任务，生成待办清单并写入全局状态
3. LangGraph驱动执行循环，依次取出待办任务
4. 任务分流：
   • 纯推理任务 → 调用LangChain Skill完成；
   • 外部操作任务 → 调用Tool，在Sandbox中安全执行；
   • 复杂专项任务 → 由Subagent Orchestrator创建子代理独立执行。
5. 大体积中间数据 → 存入VFS，仅摘要保留在对话上下文。
6. 关键 / 高危节点 → 触发HITL，人工介入后继续。
7. 每一步状态自动由LangGraph Checkpoint持久化。
8. 所有子任务完成后，主代理汇总全部结果 → 返回应用层。
9. 任务结束，全流程日志、状态、VFS 文件留存。

---

四、核心配置与开关（框架可定制项）

框架保留灵活配置，可按需开启 / 关闭能力：

1. enable_planning：开关任务规划器（默认开启）
2. enable_vfs：开关虚拟文件系统（默认开启）
3. human_in_the_loop：开关人机介入
4. subagents：自定义内置子代理角色
5. tools：挂载自定义 Skill / Tool
6. system_prompt：重写全局行为规则
7. 沙箱后端切换：配置不同代码执行环境

---

五、框架定位总结 & 对比

1. 本质：Deep Agents =LLM + LangChain组件 + LangGraph运行时 + 一体化Harness管控模块
2. 和普通 Agent 区别
   • 原生 LangChain Agent：只有基础循环 + 工具调用，无规划、VFS、子代理、沙箱；
   • Deep Agents：完整工程化 Harness，补齐长任务、高并发、企业合规、安全隔离等生产能力。
3. 和独立 Harness 关系Deep Agents 是 LangChain 生态下标准、成品、开箱即用的 Agent Harness 框架。