deepagents 已经把“长周期、多次工具调用”的那一类难题，变成了一套可执行的工程化方案，能够把 Demo 拉到接近生产的水平。
从实现上看，它不是单一技巧堆砌，而是三条主线相互配合：把复杂任务先拆成可检验的小步子；把大体积的工具输出丢进文件系统而不是堆在上下文里；把可以独立运行的子任务交给子 agent 去做。这样一来，原来令模型逐渐失焦、token 成本飙升的问题就得到缓解。顺带一提，项目是 LangChain 团队开源的，创建的 agent 实则是编译好的 LangGraph StateGraph，可以直接用 LangGraph 的流式输出、检查点和人机交互功能。
先说拆任务那块。deepagents 要求在执行前把复杂请求转成结构化的待办清单，内置的 write_todos、read_todos 就是用来做这事的。每条待办是原子级别、可验证的步骤，agent 会按列表去做并打勾。这个过程能显著降低随机试探导致的失败概率。个人觉得，这一步就像把“大工程”拆成一堆小活儿，谁都能按单子干活，不容易出岔子。
文件系统访问是另一个核心。系统提供了一套文件工具：ls、read_file、write_file、edit_file、glob、grep 等。关键点在于，体积大的工具输出不是塞进模型上下文，而是自动写成文件，agent 上下文里只留一个路径引用。举个例子，internet_search 返回了 100KB 内容，FilesystemMiddleware 会把它写到
/tool_results/internet_search_1.txt，之后的提示只引用这个路径。这样能把 token 成本拉下来，同时保留所有结果供后续处理或人工查看。
子 agent 委托是第三张牌。主 agent 用 task 工具把子任务派给子 agent，子 agent 在各自隔离的上下文和工具集里跑，互不干扰。可以通过 interrupt_on 参数来指定哪些工具调用需要人工审批，遇到这些就会暂停等人工输入。SubAgentMiddleware 负责创建这些独立执行环境。这个设计便于把并行或长期的子流程拆出去，降低主流程的复杂度。
为了保证中断场景能恢复执行，系统里还加了 PatchToolCallsMiddleware，专门处理人机交互打断后如何正确继续的问题。三者合起来，任务完成率明显提升。模块化中间件的设计也给扩展留了口子：每个能力被封成独立组件，想替换存储后端或加特殊工具，只需要换相应中间件实现。
讲到工程落地，就绕不开持久化和跨会话记忆问题。deepagents 内置的 StateBackend 只支持单次会话，想要跨会话保存用户偏好、长期任务进度或累计领域知识，就得接入持久化 backend。常见做法是把 Milvus 当做向量存储层，配合 StoreBackend，把重大对话和工具输出做成 embedding 存进 Milvus。每次任务执行时通过语义检索把相关历史找回来。Milvus 的计算存储分离、易水平扩展、支持高并发读写，适合放在生产环境里存海量向量数据。实际部署里会用 CompositeBackend 把不同路径路由到不同后端，列如把 /memories/ 指向持久化存储，其他临时文件还用本地或临时后端。
可定制性方面也很清楚。你可以附加自定义的 system prompt，这段会跟在中间件注入的默认指令后面，用来定义领域流程或约束。这里要注意：自定义 prompt 应该明确业务规则、允许行为和禁忌；不要把大量敏感数据、凭证或直接把工具实现写进去。工具方面可以按标准 Python 函数签名注册，docstring 会被当成工具描述。还可以写自定义 middleware 注入工具、改提示或挂钩 agent 生命周期。整体上，框架允许把专有 API、领域工作流和行为规则融进去，实现跨会话的知识积累和记忆管理。
在具体流程上，开发者常常这么做：先定义一套待办拆解策略和校验规则；把需要抓取的大量数据的工具标记为会把结果写文件；把长期记忆路径配置到 CompositeBackend 的 /memories/；接着把 Milvus 做为持久层挂上，配置好 embedding 转换；最后在需要人工审批的关键节点加上 interrupt_on，让流程能在必要时阻塞等待确认。create_deep_agent 返回的 agent 已经是 LangGraph 的 StateGraph，能享受流式输出、检查点和人工交互的能力，直接接进现有平台里比较方便。
再说几处细节。TodoListMiddleware 负责任务拆解和待办管理；FilesystemMiddleware 提供文件读写和搜索工具；SubAgentMiddleware 负责子 agent 的创建与委托。大体上，系统会把大型工具调用的输出自动写文件，提示里只放路径，这样模型不会被大段文本拖垮。子 agent 有独立的系统提示和工具集合，适合跑专项任务或长期流程。PatchToolCallsMiddleware 在恢复场景里很重大，能把中断前后的上下文变迁处理好，避免重复或遗漏操作。
从工程角度思考，deepagents 的模块化让迁移成本低。列如把文件存储迁到云端，只要实现一个新的 backend 交给 FilesystemMiddleware 就行。要把记忆层换成别的向量库，也只需替换 StoreBackend 的实现。这样做的好处是，通用框架不必一次覆盖所有垂直需求，遇到特定场景可以定制中间件和工具。
回过头说为何要做这套东西。长周期任务的痛点主要是上下文窗口和成本的矛盾：传统方案把所有工具结果堆进上下文，token 成本暴涨，模型在海量信息里越来越难聚焦。deepagents 的思路是重构信息流，把文件系统当成缓冲区，结果写文件、上下文只保留引用，再配合自动摘要和提示缓存，既保留了信息又避免了代价。再配上任务拆解与子 agent 分担，整个执行流程走向确定性而非随机探索。
如果要马上试一个轻量级的示例，常见做法是先用 CompositeBackend 把 /memories/ 指向持久化后端，把 /tool_results/ 指向本地磁盘；注册一个 internet_search 工具让大结果写 /tool_results/ 下；在 agent 的 system prompt 里附加领域约束；最后用 create_deep_agent 创建 agent，验证它能把一个复杂任务拆成 todo 列表，并把大段搜索结果写到文件，子任务派给子 agent，记忆成功落库并能被检索到。你会看到从交互到持久化、从拆解到委托，这套链路是连通的。
我这里记录了事件的来龙去脉和实现路径，按这个顺序去落地会比较清楚，也容易排查问题。个人感受是，这套设计很工程化，能把理论上的复杂流程变成可控的执行流。
暂无评论内容