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 参数列表,自动注入能力:

python 复制代码
agent = create_agent("模型标识", middleware=[TodoListMiddleware()])

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

适用场景与局限

适用场景

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

局限

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

总结

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

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

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

相关推荐
ZerekZhang6 小时前
Harness:把裸模型变成能用的 Agent
agent·maf·harness
学无止境小袁同学19 小时前
LangGraph 深度指南
语言模型·框架·agent·并发·上下文·langgraph·长期记忆
Cosolar20 小时前
2026 年 Java AI Agent 生态全景盘点:50+ Java 开源项目的分类、实测与选型判断
人工智能·架构·agent
张一凡9321 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent
qinglongcn21 小时前
怎么让 200 轮的长任务不崩——三层保全策略
agent·ai编程
数字工作台1 天前
给 LangGraph 加一道可审计记忆:替换默认 Checkpointer,实现防篡改 + 崩溃不丢数据
python·agent
阿里云大数据AI技术1 天前
如何用 STAROps Elasticsearch 智能助手看穿“搜索变慢”
人工智能·agent
小七-七牛开发者1 天前
Anthropic:Agent 不必一直运行,也能持续工作
agent·claude·deepseek·anthropic·alwaysonagent
xyphf_和派孔明1 天前
第十章: Agent Skill的调用机制解读
langchain·llm·agent
Csvn1 天前
所有问题都喂最贵的模型?规则路由实测:30 个问题里 16 个能交给便宜模型(C03)
人工智能·aigc·agent