LangGraph Agent 任务规划中间件：TodoListMiddleware 原理解析

简介

在复杂Agent链路中，大模型很容易丢失步骤、遗漏子任务、分不清当前执行进度。LangGraph 生态提供了 TodoListMiddleware，它是面向Agent的规划与任务管理中间件 ，内置 write_todos 工具，让智能体自主维护结构化待办清单，实现任务拆解、状态流转、进度跟踪，解决多步骤复杂任务失控问题。

该中间件属于 Agent 中间件体系，不侵入原有业务节点，通过拦截模型请求、注入系统提示词、注册工具、后置校验来实现规划能力，是原生可插拔的增强组件。

核心设计思想

1. 按需启用，不滥用：简单任务（少于3步）直接执行，只有复杂多步骤任务才使用待办，避免无谓 Token 消耗。
2. 状态驱动任务流 ：统一三种任务状态 pending / in_progress / completed，强制实时更新，禁止批量标记完成。
3. 全量覆盖更新 ：每次调用 write_todos 会替换整个 todos 数组，而非增量修改。
4. 调用约束 ：一轮模型推理内仅允许一次 write_todos 调用，禁止并行多次更新，规避状态覆盖冲突。
5. 解耦规划与结果输出：待办仅用于跟踪流程，最终业务答案必须在最后一次工具调用之后单独输出，不能把标记待办完成当成交付结果。

数据结构定义

Todo 任务项

单个待办条目，包含任务描述与状态：

• content：任务内容，要求可落地、描述清晰
• status：pending（未开始）/in_progress（进行中）/completed（已完成）

PlanningState

扩展 AgentState，新增 todos 字段存储任务列表，标记为 OmitFromInput，用户侧输入不可直接传入，由中间件托管更新。

WriteTodosInput

工具入参模型，仅接收完整的 todos 数组，每次调用代表一次全量更新。

中间件核心模块拆解

1. write_todos 工具

工具本质返回 LangGraph Command 对象，更新状态里的 todos，同时追加一条 ToolMessage 回写消息流。

同步与异步版本共用一套更新逻辑，适配同步/异步Agent运行时。

工具描述里完整定义了Agent的使用规范：适用场景、禁用场景、状态管理规则、卡点处理、任务拆解规范，会随系统提示词注入给大模型。

2. TodoListMiddleware 主体

构造函数支持自定义传入 system_prompt 和 tool_description，方便业务侧修改Agent引导规则，同时内部注册结构化工具 write_todos。

wrap_model_call / awrap_model_call（模型前置拦截）

拦截每一次大模型请求，自动拼接待办规划相关的系统提示词，引导模型理解什么时候、怎么使用待办工具。

• 原有系统提示存在：追加规划提示
• 无原有系统提示：直接使用规划提示作为系统消息

after_model / aafter_model（模型后置校验）

这是关键的防护逻辑：在模型输出之后、执行工具之前检查AI返回的tool_calls。

• 统计本轮内 write_todos 调用次数
• 如果存在≥2次并行调用，返回错误 ToolMessage，拒绝执行，提示一轮只能更新一次待办

原因：该工具是全量覆盖更新，多次并行调用会出现状态优先级歧义。

Agent 使用规则（中间件内置约束）

✅ 适合调用 write_todos

• 3步及以上的复杂任务、需要前置规划的任务
• 用户明确要求生成任务清单、一次性批量下发多个任务
• 任务方案需要根据中间结果动态调整、新增/删减子任务

❌ 禁止调用 write_todos

• 单一步骤简单问答、闲聊、信息查询
• 少于3个步骤即可完成的轻量操作

📌 任务状态铁则

1. 启动任务前，先标记为 in_progress，再执行
2. 任务全部做完才允许标记 completed；遇到阻塞、报错、依赖缺失，保持 in_progress，新增卡点任务
3. 已完成任务不可修改；无效任务直接从列表删除
4. 只要不是全部任务完成，列表必须至少有一项处于 in_progress
5. 不攒任务批量打勾，完成一项立刻更新状态

📌 输出规范

待办更新只做流程跟踪，不代表回答用户 。最终数据、摘要、分析结果，必须放在最后一次 write_todos 调用后的消息中返回。

接入方式简述

中间件和其他Agent中间件一样，在创建Agent时放入 middleware 参数列表，自动注入能力：

agent = create_agent("模型标识", middleware=[TodoListMiddleware()])

Agent 内部状态自动携带 todos，调用后可直接读取状态查看完整任务进度。

适用场景与局限

适用场景

• 代码重构、文档分析、多轮数据处理、调研类长流程Agent
• 需要对外暴露执行步骤、方便调试和观测的智能体
• 容易跳步骤、忘记前置依赖的复杂规划型Agent

局限

• 每次更新是全量覆盖，任务量大时会增加消息长度与 Token
• 单轮模型只能一次更新待办，不支持一轮多次增量修改
• 依赖模型遵循提示词规范，依然存在模型不遵守规则的风险

总结

TodoListMiddleware 是一套轻量化、可插拔、强约束的Agent规划中间件 ，它不是简单的工具封装，而是通过提示词引导 + 状态托管 + 后置校验三层机制，把"自主规划、分步执行、进度可观测"的能力标准化接入 LangGraph Agent。

对于构建长流程、复杂业务智能体，该中间件能显著降低Agent脱轨、步骤遗漏的问题，是生产级RAG/Agent应用里非常实用的基础增强组件。

本文基于 LangGraph Agent Middleware 源码解析，聚焦 TodoListMiddleware 设计与运行逻辑。