企业官网建设流程全解析

前言

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_todo？

1、制定计划
2、逐步执行
3、动态调整，过程中可能会根据执行情况，增加步骤

任务的持久化

任务清单todolist保存在agent state的todos字段，与消息历史分开管理，这样即便消息历史做了压缩，也不会影响任务清单。

• 多次invoke之间要自动接续清单，需要配置CheckPointer，并且复用同一个thread_id
• InMemorySaver 只能在当前进程保存检查点，进程重启还要恢复，需要使用数据库等持久化CheckPointer
• subagents 声明的子agent没有独立的Middleware，需要规划能力，需要在自己的spec启动Todo，它也不会主动读取主agent的清单

揭开Middleware的引擎盖

我们使用create_deep_agent创建一个agent，然后通过middleware设置中间件，本质就是把一组中间件组装到了agent上。

分清两类hook

简单理解，就是Node-style是在节点之间的操作（在某个节点之前之后执行，很典型的就是在某个操作之前需要人工确认），Wrap-style是节点内的操作（当前节点执行出问题的补救处理等，如模型调用失败的重试）

一些中间件

默认中间件

• FilesystemMiddleware：注入7个文件操作工具，并执行permissions权限策略
• SummerizationMiddleware：上下文自动压缩，可配置触发阈值
• PatchToolCallsMiddleware：补齐历史消息中缺失的工具响应
• Prompt caching等模型相关能力，是否启用取决于模型和Harness profile（好像在哪个章节看到过，claude模型有这个能力）

通过专用参数配置

• SubAgentMiddleware：有subagents配置，默认包含general-purpose子agent，提供task工具。我好像在其他AI开发工具也见过这个子agent
• SkillMiddleware：通过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会自动获得
1）write_todos工具，可以创建和管理任务清单
2）todos状态，保存任务及状态，供后续步骤和UI使用，跨轮次调用，需要CheckPointer支持
3）规划指导提示词，引导agent在遇到复杂问题的时候先规划再去执行
如果发现agent的规划行为需要专门引导的时候，可以自定义TodoListMiddleware的系统提示词

SummerizationMiddleware

在langchain中也有一个同名的总结压缩中间件，但是二者在实现上存在一些差异

• 执行位置
  langchain：before_model独立节点执行，deepagents：wrap_model_call，在节点内部
• 消息处理
  langchain：执行把就消息替换为摘要，保留近期消息；deepagents：保留原始消息，另外记录摘要和截断位置，本次模型输入使用：摘要+近期消息
• 历史保存
  langchain：不负责将旧消息写入backend，deepagents：将待总结的旧消息写入backend，摘要中附上保存路径

任务规划与上下文管理的协同

在长时间运行的任务中，任务规划和上下文管理需要协调工作

问题场景

假设agent正在执行一项有10个步骤的任务，然后执行到第6步骤的时候，对话历史已经非常长了，包括前面5个步骤的搜索结果、文件读写操作、中间思考过程等等。
这个时候deepagents的上下文管理会自动介入：
1）工具执行结果卸载，将工具执行结果卸载到文件系统，执行结果只保留前面几行+完整内容的路径
2）对话总结，如果上下文还是超过配置的触发阈值，旧消息就会被总结压缩，本次模型输入改为摘要+近期消息。

任务清单锚定

由于任务清单与消息记录分开存储，隐藏对话总结压缩，不会营销任务清单的完整性。
这份清单可以帮助agent：
1）总共有多少步骤
2）哪些已经完成，哪些还未执行
3）下一步该做什么
清单是否及时更新、下一步是否合理，取决于模型的行为。调试时，需要结合任务执行情况和工具调用情况、最终产物一起看。

代码实战

让agent自己规划并执行多步骤研究任务。

importosfromlangchain_openaiimportChatOpenAIfromtypingimportLiteralfromtavilyimportTavilyClientfromdeepagentsimportcreate_deep_agentfromlangchain.agents.middlewareimportTodoListMiddlewarefromdotenvimportload_dotenv load_dotenv()# 这个模型不太行MODEL="XingChenAGI/Xing4.0-29B"# 这个模型当前任务可以胜任MODEL="Qwen/Qwen3-8B"# 配置模型model=ChatOpenAI(# 多步骤规划任务建议使用能力较强、支持工具调用的模型model=MODEL,api_key=os.environ["SILICONFLOW_API_KEY"],base_url="https://api.siliconflow.cn/v1",)# 搜索工具tavily_client=TavilyClient(api_key=os.environ["TAVILY_API_KEY"])definternet_search(query:str,max_results:int=5)->dict:"""搜索互联网获取最新信息。"""returntavily_client.search(query,max_results=max_results)# 创建 Agent，并显式启用 write_todosagent=create_deep_agent(model=model,tools=[internet_search],middleware=[TodoListMiddleware()],system_prompt="""你是一位专业的技术研究员。 面对复杂研究任务时，你会： 1. 先用 write_todos 制定研究计划 2. 逐步执行每个步骤，及时更新进度 3. 将搜索结果写入文件系统整理 4. 最终输出完整的研究报告 """,)# 发起一个需要规划的复杂任务result=agent.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/