前言agent或llm第一个蜕变是它可以执行工具了。但是agent开始变的强大其实是从LLM能力提升agent可以根据任务自主规划任务与执行开始的。今天我们就看下deepagents如何进行任务的规划与分解。为什么agent需要规划能力简单任务VS复杂任务对于简单的任务比如今天天气怎么样agent直接调用查询天气工具就好了但是对于复杂任务比如需要进行产品调研竞品对比分析的需求规划能力就很重要了。Agent没有规划会怎么样很容易步骤遗漏不完整还可能重复执行陷入死循环的境地无疾而终执行过程较长可能上下文爆炸遗留了重要记录稳定性不足Agent有时候执行的还可以有时候效果就不太行Agent有了规划能力就可以先规划好执行的步骤就可以按部就班的按照计划执行任务了。启用任务规划在新的版本V0.7中需要显式启用任务规划也就是TodoListMiddleware中间件同时会注入write_todos工具。对于简单的问答不需要启用对于需要多步执行等长程任务建议开启前端UI需要展示当前步骤、进度建议开启write_todos工具即便启用了TodoListMiddleware具体是否会任务规划也会看模型、提示词、具体需求任务的复杂度。任务的结构与状态主要就是content、status状态pending还没开始执行、in_progress进行中、completed已完成completed是agent写入的完成状态具体交付物是否完成还需进行检查。agent怎么使用write_todo1、制定计划2、逐步执行3、动态调整过程中可能会根据执行情况增加步骤任务的持久化任务清单todolist保存在agent state的todos字段与消息历史分开管理这样即便消息历史做了压缩也不会影响任务清单。多次invoke之间要自动接续清单需要配置CheckPointer并且复用同一个thread_idInMemorySaver 只能在当前进程保存检查点进程重启还要恢复需要使用数据库等持久化CheckPointersubagents 声明的子agent没有独立的Middleware需要规划能力需要在自己的spec启动Todo它也不会主动读取主agent的清单揭开Middleware的引擎盖我们使用create_deep_agent创建一个agent然后通过middleware设置中间件本质就是把一组中间件组装到了agent上。分清两类hook风格Hook执行方式适合场景Node-stylebefore_agent、before_model、after_model、after_agent编译成 Agent 图中的独立节点按生命周期顺序运行校验、状态更新、审计、人工中断Wrap-stylewrap_model_call、wrap_tool_call包裹一次模型或工具调用可以不调用、调用一次或多次 handler重试、缓存、降级、请求或响应转换简单理解就是Node-style是在节点之间的操作在某个节点之前之后执行很典型的就是在某个操作之前需要人工确认Wrap-style是节点内的操作当前节点执行出问题的补救处理等如模型调用失败的重试一些中间件默认中间件FilesystemMiddleware注入7个文件操作工具并执行permissions权限策略SummerizationMiddleware上下文自动压缩可配置触发阈值PatchToolCallsMiddleware补齐历史消息中缺失的工具响应Prompt caching等模型相关能力是否启用取决于模型和Harness profile好像在哪个章节看到过claude模型有这个能力通过专用参数配置SubAgentMiddleware有subagents配置默认包含general-purpose子agent提供task工具。我好像在其他AI开发工具也见过这个子agentSkillMiddleware通过skills参数启用注入技能包AsyncSubAgentsMiddleware传入异步子agent启用MemoryMiddleware传入memory参数启用注入AGENTS.md记忆HumanInTheLoopMiddleware掺入interrupt_on参数启用拦截指定工具调用等待人工审批通过middleware设置TodoListMiddleware等可选策略按需加入与默认 Middleware 同名的实例会在原位置换默认实例而不是在末尾再叠加一个原位置换是完整实例替换不会把新旧配置按字段合并理解了如上配置方式你就可以看懂deepagent内部是怎么拼装出来的自己按需添加新能力比如PII数据脱敏这个还是很有必要的或者模型降级、调用次数限制等这两个对于agent运行稳定具有很大的价值PatchTooCallMiddleware干了点啥正常的消息记录模型发出工具调用请求后会有一个对应的工具执行结果消息通过tool_call_id把两条消息关联起来。但是工具执行可能被取消那么就只有工具请求消息缺少了工具执行结果的消息。基于hooks就可以在每次执行agent也就是befor_agent hook中检查消息为缺失的消息补上ToolMessage说明这次调用被取消。它只是进行消息补全不会进行工具执行、重试。TodoListMiddleware与write_todos添加TodoListMiddleware后agent会自动获得1write_todos工具可以创建和管理任务清单2todos状态保存任务及状态供后续步骤和UI使用跨轮次调用需要CheckPointer支持3规划指导提示词引导agent在遇到复杂问题的时候先规划再去执行如果发现agent的规划行为需要专门引导的时候可以自定义TodoListMiddleware的系统提示词SummerizationMiddleware在langchain中也有一个同名的总结压缩中间件但是二者在实现上存在一些差异执行位置langchainbefore_model独立节点执行deepagentswrap_model_call在节点内部消息处理langchain执行把就消息替换为摘要保留近期消息deepagents保留原始消息另外记录摘要和截断位置本次模型输入使用摘要近期消息历史保存langchain不负责将旧消息写入backenddeepagents将待总结的旧消息写入backend摘要中附上保存路径任务规划与上下文管理的协同在长时间运行的任务中任务规划和上下文管理需要协调工作问题场景假设agent正在执行一项有10个步骤的任务然后执行到第6步骤的时候对话历史已经非常长了包括前面5个步骤的搜索结果、文件读写操作、中间思考过程等等。这个时候deepagents的上下文管理会自动介入1工具执行结果卸载将工具执行结果卸载到文件系统执行结果只保留前面几行完整内容的路径2对话总结如果上下文还是超过配置的触发阈值旧消息就会被总结压缩本次模型输入改为摘要近期消息。任务清单锚定由于任务清单与消息记录分开存储隐藏对话总结压缩不会营销任务清单的完整性。这份清单可以帮助agent1总共有多少步骤2哪些已经完成哪些还未执行3下一步该做什么清单是否及时更新、下一步是否合理取决于模型的行为。调试时需要结合任务执行情况和工具调用情况、最终产物一起看。代码实战让agent自己规划并执行多步骤研究任务。importosfromlangchain_openaiimportChatOpenAIfromtypingimportLiteralfromtavilyimportTavilyClientfromdeepagentsimportcreate_deep_agentfromlangchain.agents.middlewareimportTodoListMiddlewarefromdotenvimportload_dotenv load_dotenv()# 这个模型不太行MODELXingChenAGI/Xing4.0-29B# 这个模型当前任务可以胜任MODELQwen/Qwen3-8B# 配置模型modelChatOpenAI(# 多步骤规划任务建议使用能力较强、支持工具调用的模型modelMODEL,api_keyos.environ[SILICONFLOW_API_KEY],base_urlhttps://api.siliconflow.cn/v1,)# 搜索工具tavily_clientTavilyClient(api_keyos.environ[TAVILY_API_KEY])definternet_search(query:str,max_results:int5)-dict:搜索互联网获取最新信息。returntavily_client.search(query,max_resultsmax_results)# 创建 Agent并显式启用 write_todosagentcreate_deep_agent(modelmodel,tools[internet_search],middleware[TodoListMiddleware()],system_prompt你是一位专业的技术研究员。 面对复杂研究任务时你会 1. 先用 write_todos 制定研究计划 2. 逐步执行每个步骤及时更新进度 3. 将搜索结果写入文件系统整理 4. 最终输出完整的研究报告 ,)# 发起一个需要规划的复杂任务resultagent.invoke({messages:[{role:user,content:请调研 Agent 开发领域的三大 Harness 框架Deep Agents、Claude Agent SDK、Codex SDK对比它们的核心能力差异写一份简要分析报告。,}]})print(result[messages][-1].content)运行结果### Agent 开发领域的三大 Harness 框架分析报告 以下是对 **Deep Agents**、**Claude Agent SDK** 以及 **Codex SDK** 三大 AI Agent 开发框架的核心能力对比分析。 --- #### 1. **Deep Agents** - **核心能力** - **模型无关性**支持任意支持 tool calling 的模型如 GPT、Llama、Mistral 等。可以连接本地模型如 LM Studio或第三方云模型如 OpenAI、Anthropic。 - **功能模块化**内置多种核心能力包括 read_file、write_file、edit_file、glob、grep、execute 及 task 等涵盖文件操作、搜索、代码执行、任务执行等功能。 - **任务规划能力**使用 ReAct 架构和内置规划能力通过 write_todos 和执行树管理支持复杂、多步骤的代码修改或分析。 - **记忆系统**通过 Memory-First 协议能够跨会话记忆用户偏好、编码风格、项目上下文等信息。 - **技能系统Skills**可在 skills/ 目录下定义特定领域的任务能力如网页搜索、代码审查等按需加载。 - **部署灵活性** - **CLI本地运行**提供本地终端编程代理“Deep Agents CLI”用户可直接运行。 - **SDK嵌入应用**使用 create_deep_agent() 创建一个标准的 LangGraph 编译图可嵌入到任意 Python 应用中。 - **部署为服务**通过 Managed Deep Agents 在 LangSmith 上运行支持多用户、多任务的安全隔离。 - **子代理系统**支持真正的子代理运行能够将复杂任务拆分为多个并行子任务每个子代理有独立的上下文窗口。 - **安全性与隔离**支持文件资源或系统资源的沙箱隔离提供安全边界。 - **自定义与开源**完全开源MIT 许可支持自定义修改适合监管严格或开发需求多样化的场景。 --- #### 2. **Claude Agent SDK** - **核心能力** - **专为 Claude 设计**专为 Anthropic 的 Claude 模型如 Sonnet、Opus 等开发能充分发挥其强大、安全的模型能力。 - **内置工具链**内置文件操作工具如 edit_file、glob、子代理系统、执行脚本能力等从一开始就支持完整的工具链。 - **沙箱化执行**每个用户都有独立的 Sandboxed 环境确保任务执行与用户的其他操作互不影响。 - **调试与反馈机制**提供基于 evaluate() 的手段进行长期评测适用于构建高质量、可追溯的智能代理。 - **多语言支持**最初以 Python 和 TypeScript 为主正逐步扩展。 - **组织架构与行为**提供 query() 异步生成器使智能体在每一环节都返回治理与验证信息。 - **稳定性**已经在生产环境广泛验证适合企业级使用尤其强调 agent loop 的稳定性。 - **能力限制**虽然强大但其核心对用户是**闭源**的无法直接调整底层逻辑。 - **应用场景**适用于那些依赖 Claude 本身的扩展性、结合其精细的上下文管理和模型特性组建成完整代理的场景。 --- #### 3. **Codex SDK** - **核心能力** - **基于 GPT-5.3-Codex**该 SDK 针对 Codex 模型codex-1进行设计和优化结合多工处理和扎实的 AI 编程能力。 - **任务执行与自动化**Codex 可以自主完成代码编写、错误修正、测试执行、提交更改等任务适合构建全生命周期的 AI 编程助手。 - **沙盒执行**每项任务可在独立的云端沙盒中进行提供受控、安全的环境。 - **支持事件流**通过 Codex SDK开发者可以实时跟踪执行状态、输出内容、错误、token 使用情况等构建详细的操作日志和自动化依赖。 - **前端深度集成**支持终端浏览器和复杂用户界面操作可生成图像并处理视觉信息适合处理复杂任务。 - **插件支持**支持接入多种工具和插件如 GitHub、JIRA、CodeRabbit、Neon、Render 和 Superpowers 等实现全自动化的开发流程。 - **离线与远程调用**可部署为服务适合 CI/CD 持续集成甚至支持本地运行和远程访问。 - **局域网支持**提供辅助、更灵活的功能用于任何对 AI 视觉和操作有需求的开发场景。 - **能力局限**Codex 的核心技术依赖 GPT 模型因此需考虑模型 licensing 的限制并且需要 OpenAI 服务无法完全本地化。 --- #### 4. **三大框架的核心能力对比** | **项目** | **Deep Agents** | **Claude Agent SDK** | **Codex SDK** | |----------------------|----------------------------------------------------------------------------------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------| | **模型支持** | 支持任意 OpenAI 兼容模型如 GPT、Llama、Mistral甚至可部署本地模型。 | 专为 Anthropic 的 Claude 模型设计无法用于其他模型。 | 使用 GPT 模型Codex-1和 CLI。需依赖 OpenAI API。 | | **功能模块** | 高度模块化支持多种操作系统调用文件系统、shell、network。 | 架构较为紧凑内置文件操作、子代理系统、提交变更等适合构建高度定制化的 agent loop。 | 强调任务执行和自动化并对前端交互进行深入优化适合构建即开即用的助手和自动化工具。 | | **部署方式** | 支持三种部署CLI、SDK 嵌入应用、LangSmith 云端部署。 | 只能自托管受限于闭源核心。 | 支持 CLI、本地部署及云端服务适合自定义部署并企业级使用。 | | **开源程度** | **完全开源**MIT支持自定义与扩展。 | 对外套件开源Python 及 TypeScript 调用接口但内部核心是闭源的。 | 代码部分开源但核心 Codex SDK 是 OpenAI 的资源和模型整体是闭源的。 | | **能力扩展性** | 高度可扩展支持中间件、工具、环境解耦。可灵活插拔。 | 沙盒和 agent loop 已封装但用户无法直接修改底层逻辑扩展有限。 | 想在本地执行、部署、维护或者深度 custom 须依赖 Codex Cloud 接口。 | | **适合场景** | 适合希望本地部署、开放存取并高度自定义、控制模型行为的用户。 | 适合需要 Claude 精细的上下文管理和模型能力适合部署于 open source 或 business scenario。 | 更加灵活尤其适合需要与前端交互、调试 UI、执行长时间任务的超级助手任务。 | | **安全性** | 支持 Sandbox 即“状态隔离”的能力可全局支持沙箱 | 支持对每个沙盒环境隔离的完全封装。 | Codex SDK 支持沙盒环境执行任务但需保证访问权限、代码自由执行、云端信号不泄漏。 | --- #### 5. **总结与建议** - **Deep Agents** - 优点开源、模块化、高度灵活适合多模型、混合环境和本地部署。 - 缺点核心技术基于 OpenAI 兼容模型若希望独立使用非 OpenAI 模型需额外适配。 - 适用自定义 agent 构建适合有一定工程背景的开发者或企业级部署需求。 - **Claude Agent SDK** - 优点强大、安全、稳定性高能直接使用 Claude 预训练的 agent loop。 - 缺点核心闭源使用限制在 Claude 生态。 - 适用希望用 Claude 构建与自身平台集成、靠近 Claude 模型能力、且能独立执行任务如代码修改、编辑权限等的场景。 - **Codex SDK** - 优点功能丰富且支持事件流机制调试、测试、提交更改等流程清晰适合 CI/CD 自动化。 - 缺点依赖 GPT 模型与 OpenAI API代码执行与调试等限制较高相对 Claude 开发环境更灵活但执行效率和模型完整性可能受限。 - 适用需要与前端集成、执行图像生成和工具操作的助手适合部署到开源或闭源平台但需注意授权与限制。 --- ### 结论 选择三个框架中任何一个取决于你的应用场景 - 如果你 **注重开放性和灵活性与可扩展性**可以优先考虑 **Deep Agents**。 - 如果你 **依赖 Claude 的已有能力**并希望直接使用稳定且安全的循环结构**Claude Agent SDK** 是合适的选择。 - 如果你 **需要更图形化的交互能力**或者 **进行 CI/CD 自动化****Codex SDK** 是最优选项。 最终避免盲目比较框架区别 —— 实际能力是否值得投入最好结合你的具体开发需求来决定。deepagents能力全景基本就是三大类1、默认注册的必须有没有可能就出问题了。比如文件系统是最基础的东西没有这个工具调用执行可能都没法搞历史消息压缩总结没了这个上下文直接爆炸调用模型报错、长时间等待没了工具调用不全照样可能引起模型调用报错2、通过专用参数是扩展agent能力如支持子agent、skill、记忆、人工干预、异步3、通过Middleware配置则是更细的能力或功能优化以便提升agent性能或稳定性如规划能力、模型工具重试、模型降级、调用次数限制、信息脱敏等。结语本文从最开始的任务规划执行说起到介绍agent中间件的使用从而更好的理解了TodoListMiddleware的实现原理以及如何各种中间件的作用与使用。参考链接https://datawhalechina.github.io/deepagents-in-action/chapters/ch04-task-planning/