【DeepAgents简介】个人学习笔记

[1. 用户输入指令](#1. 用户输入指令)

[2. 大模型根据指令上下文规划调用子智能体](#2. 大模型根据指令上下文规划调用子智能体)

[3. 子智能体调用工具](#3. 子智能体调用工具)

[4. 得出结果返回智能体](#4. 得出结果返回智能体)

[DeepAgents 的核心简介：](#DeepAgents 的核心简介：)

[长期记忆与上下文管理 (Memory & Context)DeepAgents 利用 LangGraph 的 Store 功能](#长期记忆与上下文管理 (Memory & Context)DeepAgents 利用 LangGraph 的 Store 功能)

[DeepAgents vs. LangChain vs. LangGraph](#DeepAgents vs. LangChain vs. LangGraph)

多智能体理解

用多智能体的三条铁律

多智能两种架构模式

[1.5.5 DeepAgents子代理入门](#1.5.5 DeepAgents子代理入门)

流程人机交互 (HITL)

后端类型概览

[Agent Skills (技能扩展)](#Agent Skills (技能扩展))

总结

DeepAgents 是一个基于 LangChain 和 LangGraph 构建的高级智能体（Agent）框架，专为处理复杂、长周期、多步骤的任务而设计。

它让开发者只需几行代码（create_deep_agent），就能获得一个具备规划能力、文件操作能力和团队协作能力 的强大智能体。

你可以把它理解为 LangChain 生态中的一个**"开箱即用"的智能体套件（Harness）** 。它不仅仅是让 AI 调用工具，而是赋予了 AI 像人类工程师一样做计划、管理文件、委派任务的能力，非常适合构建类似"OpenAI Deep Research"或"Claude Code"这样的深度应用。

智能体执行任务的标准四步流程

1. 用户输入指令

这不仅仅是简单的"说话"，而是意图识别与上下文构建的过程。

用户动作：输入自然语言（如"帮我分析上周销售数据并生成图表"）。
系统后台 ：
- 感知：系统接收指令。
- 上下文组装 ：系统会将你的指令与系统提示词 （定义角色、规则）、短期记忆 （当前对话历史）和长期记忆（用户偏好、知识库）打包在一起。
- 关键点 ：这一步决定了智能体"知道什么"。

2. 大模型根据指令上下文规划调用子智能体

这是**"大脑"的思考与决策**阶段（对应 DeepAgents 的主智能体或 Hermes 的父进程）。

推理：大模型（LLM）分析指令，判断这是一个复杂任务，单靠自己无法完成，需要拆解。
规划：
- 任务拆解：将"分析数据"拆解为"查询数据库"和"画图"两个步骤。
- 路由选择 ：决定调用哪个子智能体（例如：调用"数据分析专家"而不是"文案写作专家"）。
输出：生成结构化的调用指令（如 JSON 格式的 Action: call_sub_agent, Args: {task: "query_sales"}）。

3. 子智能体调用工具

这是**"手脚"的执行**阶段（对应 Hermes 的子代理或 DeepAgents 的 Worker）。

独立运行：子智能体接收到任务后，拥有自己独立的上下文（它不需要知道主任务的来龙去脉，只需要知道怎么干活）。
工具映射 ：子智能体根据自己的技能库，选择具体的工具（如 SQL_Executor 或 Python_Code_Interpreter）。
实际操作 ：
- 感知环境 ：读取文件、连接 API、搜索网络。
- 改变环境：写入数据、发送请求、生成文件。
关键点 ：这一步是 AI 从"虚拟"走向"现实"的关键，也是解决大模型"幻觉"的核心（因为它基于真实工具返回的数据）。

4. 得出结果返回智能体

这是**"闭环与整合"**阶段。

观察：工具执行完毕后，会返回一个"观察结果"（Observation），比如数据库返回的 JSON 数据或代码执行的成功日志。
反馈：子智能体将这个结果封装好，返回给主智能体。
整合：主智能体收到结果，判断任务是否完成。
- 如果完成：生成最终回复给用户（如"图表已生成，请看附件"）。
- 如果未完成（或出错）：重新规划（回到第 2 步），比如"数据查询失败，尝试换一种查询方式"。

DeepAgents 的核心简介：

核心定位：它是做什么的？

如果说 LangGraph 是"操作系统内核"（提供底层调度），LangChain 是"开发工具包"（提供组件），那么 DeepAgents 就是"预装好的高级应用"。

它解决了传统 Agent 在处理复杂任务时容易出现的**"短视"** （走一步看一步）、"失忆" （上下文溢出）和**"混乱"**（工具调用错误）问题。

四大核心能力

DeepAgents 通过内置的中间件和工具，赋予了 Agent 以下关键技能：

任务规划 (Planning)
- 机制：内置 write_todos 和 read_todos 工具。
- 作用：Agent 不会盲目执行，而是先将大任务拆解为结构化的待办清单（TODO List），并在执行过程中动态更新进度。这让 Agent 具备了全局视角。

read_todos：智能体执行任务时，用来 "读取" 当前的待办清单，知道下一步该做啥；
update_todos：执行中发现需要调整步骤（比如 "检索资料" 需要加 "筛选权威来源"）来修改清单；
delete_todos：删掉不需要的步骤（比如报告写完后，删掉 "检查完整性" 的重复项）。
**2.文件系统 (Filesystem)**高效上下文管理
- 机制：提供类似操作系统的文件读写能力（read_file, write_file, edit_file, ls, grep 等）。
- 作用：
  - 扩展记忆 ：将长文本、代码或中间结果写入文件，避免上下文窗口（Context Window）溢出。
  - 环境交互：可以直接操作代码库、读取配置文件，实现真正的"全栈"开发能力。

子代理委派 (Sub-agent Delegation)
- 机制：通过 task 工具，主 Agent 可以将特定任务"外包"给子 Agent。
- 作用：实现上下文隔离。主 Agent 负责统筹，子 Agent 负责专注执行具体模块（如专门负责搜索或专门负责写测试），互不干扰。

长期记忆与上下文管理 (Memory & Context)DeepAgents 利用 LangGraph 的 Store 功能

- 机制：自动摘要和文件卸载。
- 作用：当对话历史过长时，系统会自动将旧信息压缩或存入文件，确保 Agent 在长时间运行中不"变笨"。

DeepAgents vs. LangChain vs. LangGraph

为了帮你理清它们的关系，可以参考下表：

表格

框架	角色比喻	核心用途	适用场景
LangGraph	操作系统内核	底层状态管理、循环控制、持久化	需要精细控制工作流的底层开发。
LangChain	开发工具包	封装好的组件、链、基础 Agent	快速构建标准的问答或简单工具调用应用。
DeepAgents	高级应用套件	开箱即用的规划、文件、子代理能力	复杂工程任务（如写代码、深度研报、自动化运维）。

补充视角：两种常见的执行模式

两种主流的编排模式：

表格

模式	ReAct 模式	Plan-and-Execute 模式
流程特点	边想边做	先计划，后执行
第 2 步表现	思考一步，调用一步。	一次性生成所有子任务列表。
第 3 步表现	调用完工具立刻看结果，再决定下一步。	批量执行子任务，最后汇总。
适用场景	探索性任务（如搜索、调试）。	结构化任务（如写代码、做报表）。

多智能体理解

多 Agent 系统（Multi-Agent System, MAS）是由多个具备自主性、反应性、目标导向性的智能体（Agent）组成的协作体系，通过标准化通信与协同机制，共同完成单一智能体无法独立应对的复杂任务。

简单解释，就是将复杂任务，拆解成多个子任务，分发给专长的Agent进行处理，最后综合结果！本质分而治之！！

用多智能体的三条铁律

这三条铁律本质上是多智能体系统的 "入场许可"，只有满足其中至少一条，才值得我们承担多 Agent 带来的成本与复杂度代价：

问题极度开放 ：这类任务没有标准答案或固定流程，比如 "制定企业年度战略""开放式科研探索"，单体模型容易陷入局部最优，而多智能体可以通过多角色探索不同方向，动态调整路径。
存在领域冲突 ：当任务需要跨两个及以上专业领域时（比如 "医疗 + 法律""金融 + 工程"），单体模型的注意力会被分散，导致推理精度断崖式下跌。多智能体通过物理隔离不同领域 Agent，避免知识污染，保障各模块专业度。
需要多方向并行 ：任务天然可以拆分为多个互不依赖的子任务（比如 "多源数据采集""多版本方案并行设计"），多智能体可以利用分布式算力并行执行，大幅缩短整体耗时，实现 "1+1>2" 的效率提升。

只有符合这些条件时，多智能体才是 "宝贝"；否则，强行使用只会让系统陷入 "毒药" 般的成本与调试困境。

多智能两种架构模式

模式一：层级工作流 (Hierarchical / Orchestrator-Workers)

别名：指挥官模式、主从模式核心逻辑：中央集权。有一个"大脑"负责思考和分派任务，其他 Agent 只是干活的"手"。

运作方式：
1. 输入：用户给出一个复杂任务（比如"写一份新产品的上市策划案"）。
2. 主脑 (Orchestrator) ：主管 Agent 收到任务，它不直接干活，而是分析任务，把它拆解成几个子任务（如：市场调研、创意设计、文案撰写）。
3. 分发：主管把子任务分发给对应的垂直领域专家 Agent （Worker）。
4. 执行：Worker Agent 并行或串行工作，产出结果返还给主管。
5. 整合：主管汇总所有结果，整合成最终报告输出。
优点：
- 可控性强：主脑掌控全局，知道进度，方便纠错。
- 逻辑清晰：上下级关系明确，就像传统的公司组织架构。
缺点：
- 单点故障：主脑如果挂了或判断失误，整个任务就崩了。
- 通信瓶颈：所有信息都要经过主脑中转。

模式二：协作工作流 (Collaborative / Network)

别名：网状模式、专家会诊模式核心逻辑：去中心化。没有绝对的领导，大家都是平等的专家，坐在一起开会讨论，互相交换信息。

运作方式：
1. 输入：用户给出一个开放性问题（比如"评估这家公司的投资价值"）。
2. 共享：任务被扔到一个"共享会议室"（Shared State/Context）。
3. 自组织：不同的专家 Agent（定价、产品、财务、合规）根据自己的专长，从"会议室"里拿取信息，进行分析。
4. 交互：Agent 之间可以直接交流。比如财务 Agent 算出成本太高，直接告诉定价 Agent 调整价格，不需要经过领导批准。
5. 收敛：最后通过一个评估者 (Evaluator) 或规则来决定什么时候讨论结束，输出最终方案。
优点：
- 灵活性极高：适合解决极其复杂、没有标准答案的问题。
- 涌现能力：不同的专家碰撞可能产生意想不到的创新解法。
缺点：
- 容易失控：Agent 之间可能陷入无休止的争论（死循环）。
- 难以调试：很难追踪到底是谁做出的关键决策。

1.5.5 DeepAgents子代理入门

https://docs.langchain.com/oss/python/deepagents/subagents#configuration

深度代理可以创建子代理来委派工作。你可以在子代理参数中指定自定义子代理。子代理用于上下文隔离（保持主代理上下文的干净）以及提供专业指令。

子代理解决了上下文膨胀问题 。当代理使用输出较大的工具（如网页搜索、文件读取、数据库查询）时，上下文窗口会迅速被中间结果填满。子代理将这些详细工作隔离开来------主代理只接收最终结果，而非产生该结果的数十个工具调用。

什么时候使用SubAgent：

多步骤任务会让主代理的上下文变得杂乱
有需要 "专业技能 / 专属工具" 的环节

比如主代理要做 "股票分析"，其中 "基本面分析" 需要财务工具、"技术面分析" 需要 K 线工具，给这两个环节配专属子代理（带对应工具）
需要不同模型能力的任务（多模态）
当你想让主Agent专注于高层协调时

什么时候不应使用SubAgent：

任务简单，一步就能干完
需要中间信息连贯，不能拆

比如 "读一篇文章，然后总结核心观点"，拆给子代理读、再拆给另一个子代理总结，会丢上下文，不如主代理一次性干完。

将子代理定义为包含以下字段的词典：

字段名	类型	必填 / 可选	核心描述	继承规则（与主代理的关系）
name	str	必填	子代理的唯一标识；主代理调用 `task()` 工具时会使用该名称，也会作为 AIMessage / 流式输出的元数据，用于区分不同代理	-（无继承，需自定义）
description	str	必填	子代理的职能描述（需具体、以行动为导向）；主代理会根据此信息判断是否将任务委派给该子代理	-（无继承，需自定义）

异步执行：

高并发服务 ：用 FastAPI/Starlette 做接口时（比如给前端返回流式回答），astream() + 异步能同时处理成百上千个用户请求，不会因单个请求阻塞整个服务；
批量处理任务 ：需要同时调用智能体处理多个查询（比如你测试的 3 个问题），astream() 并发执行耗时≈最长单个任务，比同步 stream() 串行快几倍；
非阻塞主线程 ：在 GUI 程序（如 PyQt/Tkinter）、定时任务中调用智能体，astream() 异步执行不会让界面卡死 / 定时任务中断。

流程人机交互 (HITL)

https://docs.langchain.com/oss/python/deepagents/human-in-the-loop

有些工具作可能比较敏感，需要人工批准才能执行。深度代理通过 LangGraph 的中断功能支持人机参与的工作流程。您可以使用 interrupt_on 参数配置哪些工具需要批准

后端类型概览

DeepAgents 提供了四种标准的后端实现，适用于不同的开发和生产场景：

后端类型	存储介质	适用场景	类比
StateBackend (默认)	内存 (State)	临时文件、中间运算结果。会话结束即销毁。	浏览器的"无痕模式"
FilesystemBackend	本地硬盘	本地开发、调试、需要直接查看生成文件的场景。	电脑的本地磁盘
StoreBackend	数据库 (KV Store)	生产环境、跨 Agent 共享数据、持久化记忆 (Redis/Postgres)。	云盘 (iCloud/OneDrive)
CompositeBackend	混合存储	生产环境最佳实践。区分"临时文件"和"重要记忆"。	系统盘 (C盘) + 数据盘 (D盘)

Agent Skills (技能扩展)

DeepAgents 提供的 Skills（技能） 机制，是为智能体（Agent）注入领域知识与专业能力的核心方式。Skills 本质是可复用、可插拔的 "能力包"，核心由指令文档（SKILL.md）及配套资源构成，能让 Agent 在运行过程中，根据任务场景的实际需求动态加载、调用对应的技能知识，无需修改 Agent 核心逻辑即可快速扩展专业能力。

https://skillsmp.com/zh

核心概念：

SKILL.md ：技能的核心描述文件，是 Agent 学习和使用该技能的 "说明书"。文件整体分为两部分 ------ 头部的元数据（Frontmatter） （以 YAML 格式定义定义name 和 description）和正文的具体指令（以 Markdown 格式编写），Agent 会通过解析该文件掌握技能的使用方法、适用场景及操作流程。
渐进式披露 ：Skills 机制的核心优化策略，用于解决大模型上下文窗口有限的问题。Agent 启动时仅读取所有技能的元数据（轻量信息，占用极少上下文），仅记录 "技能名称、适用场景、触发关键词" 等基础信息；只有当用户任务匹配某一技能的触发条件时，Agent 才会加载该技能的详细指令内容，有效避免无关信息占用上下文，提升任务执行效率。（技能名称要和name相同）触发条件比较苛刻，skill尽量保持在十个左右

总结

你描述的流程正是**"大模型驱动智能体"** 的本质：
大模型负责"想"（规划），智能体架构负责"管"（调度），工具负责"做"（执行）。

在这个流程中，上下文 是血液，贯穿始终；工具是边界，决定了智能体能走多远。

【DeepAgents简介】个人学习笔记

智能体执行任务的标准四步流程

1. 用户输入指令

2. 大模型根据指令上下文规划调用子智能体

3. 子智能体调用工具

4. 得出结果返回智能体

DeepAgents 的核心简介：

核心定位：它是做什么的？

四大核心能力

**长期记忆与上下文管理 (Memory & Context)**DeepAgents 利用 LangGraph 的 Store 功能

DeepAgents vs. LangChain vs. LangGraph

多智能体理解

用多智能体的三条铁律

多智能两种架构模式

1.5.5 DeepAgents子代理入门

流程人机交互 (HITL)

后端类型概览

Agent Skills (技能扩展)

总结

长期记忆与上下文管理 (Memory & Context)DeepAgents 利用 LangGraph 的 Store 功能