2.4 TodoListMiddleware中间件

TodoListMiddleware中间件赋予了Agent 任务规划和追踪进度的能力，可以应对复杂的多步任务。
比如，当一个大任务需要被拆解为 3 个以上的子任务，且前面的步骤是后面步骤的前提时，如果不列Todo 列表，大模型在执行到第 3 步时，很容易忘记自己最初的目标，或者在工具返回大量报错信息后“应激”，直接跳过验证去回答用户。
此时， TodoListMiddleware 中间件强制它把计划挂在全局状态里，时刻提醒它“下一步该干什么”。

如果把普通的 Agent 比作“想到哪写到哪”的实习生，那么引入了 TodoListMiddleware 的 Agent
就是“先写方案、再列 CheckList、最后按部就班执行”的资深工程师。

典型场景：

• 任务链路长、步骤多，且有严格的先后依赖关系
• 需要在前端 UI 界面实时展示 Agent 的“思考与执行进度”
• ….

To-do list的创建和维护是通过调用write_todos工具实现的。

2.4.1 参数说明

1. system_prompt —自定义指导todo列表使用的提示词不提供则使用内置提示词，通常不必提供。
2. tool_description —自定义write_tools工具的描述信息不提供则使用内置描述，通常不必提供。

2.4.2 案例设计
我们设计一个较为复杂的任务：

1. 任务目标
   扫描工作目录，测试并修复工作区下的my_add.py文件。
2. 工具列表
   为了实现上述任务，提供一系列工具。
   list_files：扫描工作目录，列出其中的所有文件
   read_file：扫描指定文件，返回文件内容
   write_file：向指定文件写入内容
   run_tests：运行测试，底层基于pytest实现

2.4.3 代码
1、环境准备
在项目根目录下创建todo_workspace作为工作空间
在该目录下创建my_add.py，写入以下内容

在该目录下创建test_my_add.py，写入以下内容

我们提供的测试工具是基于pytest实现的，pytest用法如下
在PyCharm中打开终端，依次执行命令

然后执行

pytest -q

完整日志如下

分析

1. pytest会扫描目录下所有以test_ 开头或以_test 结尾的文件，视为测试文件
2. 然后执行测试文件中所有以test 开头的函数
3. 执行出错会打印到控制台，如上所示
4. 测试函数的逻辑是调用my_add.py中的add函数，得不到符合预期的结果则抛出异常。

2、业务代码
模型初始化

提供工具列表

继续：

4、分析
为了让 TodoListMiddleware 生效，Agent、工具和中间件三者之间必须满足特定的协同契约：

① todos列表的维护是通过工具调用实现的
此处展示了一次完整的todos列表更新流程

② todos列表的信息分为两部分：status和content，前者是状态，后者是内容
待办事项的状态共有三种取值：

• in_progress：正在进行
• completed：已完成
• pending：待执行

③ 每进行一个步骤，agent会更新To-do lists