Spring AI 2.0 系列教程(四)——TodoWriteTool

让 AI Agent 执行一个多步骤的复杂任务，比如"给设置页面加上深色模式开关，然后跑一遍测试"，结果它改完代码就忘了跑测试。不是模型不够聪明，而是 LLM 在超长上下文里会"迷失在中途"—— buried 在上下文中间的任务指令最容易被忽略。

这篇文章要聊的 TodoWriteTool，就是 Spring AI 社区针对这个问题的官方解法。它的思路很简单：让 LLM 把隐式的任务规划变成显式、可追踪的任务清单。Agent 每一步该干什么、干完了什么，一目了然。

一、为什么 LLM 会"遗忘"中间的任务

1.1 Lost in the Middle：长上下文的结构性缺陷

2023 年斯坦福和 UC Berkeley 的研究提出了 "Lost in the Middle" 现象：当 LLM 处理的上下文长度超过一定阈值后，模型对位于上下文中间位置的信息召回率显著下降，而对开头和结尾的信息记忆相对较好。

这个效应在 AI Agent 的执行场景里被放大了。假设你给 Agent 的指令包含 5 个步骤：

1. 找出 Tom Hanks 评分最高的 10 部电影
2. 把这些电影两两分组
3. 把每组电影名倒序打印
4. 生成一份总结报告
5. 把结果写入文件

Agent 在执行第 3 步时，上下文里已经塞满了电影列表、分组逻辑、之前的输出结果。此时第 4、5 步的指令被埋在一堆中间内容里，模型"看不到"了，执行完第 3 步就直接返回了。

上图展示了问题核心：随着 Agent 逐步执行，中间累积的工具返回、中间结果占据了上下文的大部分空间，而尚未执行的后续任务指令被挤压到上下文中间，触发遗忘。

1.2 隐式规划的脆弱性

传统 Agent 的执行方式是隐式规划：LLM 拿到任务后，自己在内部"想"好步骤，然后一步接一步执行。这个计划只存在于模型的内部推理过程中，一旦某一步产生了大量输出，或者上下文被刷新，这个隐式计划就可能断裂。

上图的问题在于：计划是不可见的、不可恢复的。一旦断裂，Agent 不会意识到"我还有步骤没做"，而是直接以为任务已经完成了。

二、TodoWriteTool 的设计思路：把计划拉出来

2.1 从隐式到显式

TodoWriteTool 的核心设计只有一个：让 LLM 把任务计划写到一个外部结构化存储里，并在执行过程中持续更新它。

这样一来，计划不再是模型脑子里的一闪念，而是一个可以被追踪、校验、恢复的状态机：

关键区别在于：即使某一步产生了海量输出，Chat Memory 里始终保留着完整的任务列表和当前进度。LLM 每次做决策时，这个列表都会被注入到上下文中，确保"下一步该做什么"永远不会丢失。

2.2 TodoWriteTool 是什么

TodoWriteTool 是 Spring AI 的一个 Function Tool，它给 LLM 提供了三个原子操作能力：

• • 创建任务列表：把一个复杂任务拆成多个 todo item
• • 更新任务状态：标记某个任务为 pending、in_progress、completed 或 cancelled
• • 追加新任务：执行过程中发现遗漏的工作，动态补充到列表中

每个 todo item 包含三个字段：

2.3 强制单线程执行

TodoWriteTool 内置了一条硬性约束：同一时间只能有一个任务处于 in_progress 状态。

这条约束不是闲的。没有它，LLM 很容易陷入"假并行"——同时声称自己在做两件事，结果两件事都没做完。强制单线程让 Agent 必须专注完成当前任务，才能开启下一个。

2.4 LLM 什么时候会用它

TodoWriteTool 不是无脑滥用的。它的 tool description 里明确告诉 LLM：

当一项任务需要 3 个或更多 不同的步骤或操作时，请使用此工具。如果只有一个简单直接的、能在少于 3 个简单步骤内完成的任务，则跳过。

这意味着 LLM 会自主判断任务复杂度，只有真正需要拆解的任务才会触发 TodoWrite。简单问答、单步计算等场景不会引入额外的工具调用开销。

三、快速开始：三步接入 TodoWriteTool

3.1 添加依赖

<dependency>
<groupId>org.springaicommunity</groupId>
<artifactId>spring-ai-agent-utils</artifactId>
<version>0.4.0</version>
</dependency>

注意：该工具要求 Spring AI 版本为 2.0.0-SNAPSHOT 或 2.0.0-M2 及以上。

3.2 配置 ChatClient

最关键的配置有两点：Chat Memory 和 ToolCallAdvisor。

ChatClientchatClient= chatClientBuilder
    .defaultTools(TodoWriteTool.builder().build())
    .defaultAdvisors(
// 1. ToolCallAdvisor 接管内置的工具调用逻辑
        ToolCallAdvisor.builder()
            .conversationHistoryEnabled(false)
            .build(),
// 2. MessageChatMemoryAdvisor 保留完整对话历史
        MessageChatMemoryAdvisor.builder(
            MessageWindowChatMemory.builder().build()
        ).build()
    )
    .build();

Stringresponse= chatClient.prompt()
    .user("Find the top 10 Tom Hanks movies, group them in pairs, " +
"and print each title reversed. Use TodoWrite to organize your tasks.")
    .call()
    .content();

为什么必须关掉 conversationHistoryEnabled？

Spring AI 的 ChatModel 内置了工具调用历史管理，但它和 MessageChatMemoryAdvisor 是两套机制。如果两边同时记录工具消息，会导致重复和冲突。设置 conversationHistoryEnabled(false) 是为了让 MessageChatMemoryAdvisor 独占历史记录权，确保 TodoWrite 的每一次状态更新都能被准确存入 Chat Memory。

3.3 系统提示词：让 LLM 学会用 TodoWrite

单靠 tool description 不够。最佳实践是在 system prompt 里植入详细的任务管理指令。

下面是一份受 Claude Code 启发的系统提示词模板：

你是一个可靠的 AI 助手。在执行复杂任务时，请遵循以下规则：

1. 如果任务包含 3 个或更多步骤，必须先调用 TodoWriteTool 创建任务列表。
2. 每次开始执行一个新任务前，调用 TodoWriteTool 将该任务标记为 in_progress。
3. 任务完成后，调用 TodoWriteTool 将其标记为 completed。
4. 如果在执行过程中发现新的子任务，追加到现有列表中。
5. 同一时间只能有一个任务处于 in_progress 状态。
6. 所有任务完成后，向用户返回最终结果。

这套提示词把"何时创建列表""何时更新状态""能否并行"等关键行为都约束清楚了，能显著降低 LLM 的误操作概率。

四、事件驱动：让任务进度看得见

TodoWriteTool 在执行过程中会发布 TodoUpdateEvent，你的应用可以监听这个事件来实现实时进度展示。

4.1 定义事件和监听器

publicclassTodoUpdateEventextendsApplicationEvent {
privatefinal List<TodoItem> todos;

publicTodoUpdateEvent(Object source, List<TodoItem> todos) {
super(source);
this.todos = todos;
    }

public List<TodoItem> getTodos() {
return todos;
    }
}

@Component
publicclassTodoProgressListener {

@EventListener
publicvoidonTodoUpdate(TodoUpdateEvent event) {
intcompleted= (int) event.getTodos()
            .stream()
            .filter(t -> t.status() == Todos.Status.completed)
            .count();
inttotal= event.getTodos().size();

        System.out.printf(
"\nProgress: %d/%d tasks completed (%.0f%%)\n",
            completed, total, (completed * 100.0 / total)
        );
    }
}

4.2 在 ChatClient 中注册事件处理器

@Autowired
ApplicationEventPublisher applicationEventPublisher;

ChatClientchatClient= chatClientBuilder
    .defaultTools(TodoWriteTool.builder()
        .todoEventHandler(event ->
            applicationEventPublisher.publishEvent(
newTodoUpdateEvent(this, event.todos())
            )
        )
        .build()
    )
// ... 其他配置
    .build();

运行时你会看到类似这样的实时输出：

Progress: 0/4 tasks completed (0%)
Progress: 1/4 tasks completed (25%)
Progress: 2/4 tasks completed (50%)
Progress: 3/4 tasks completed (75%)
Progress: 4/4 tasks completed (100%)

这个事件机制非常适合在前端展示进度条，或者在日志里追踪 Agent 的执行轨迹。

五、完整执行流程示例

下面是一个真实的执行流程，展示 Agent 如何处理"查找 Tom Hanks 的 10 部高分电影，两两分组，倒序打印片名"这个任务。

第一步：创建任务列表

LLM 分析任务后，发现需要 4 个步骤，于是调用 TodoWriteTool：

[
{"id":"1","content":"Find top 10 Tom Hanks movies","status":"pending"},
{"id":"2","content":"Group movies in pairs","status":"pending"},
{"id":"3","content":"Print inverted titles","status":"pending"},
{"id":"4","content":"Final summary","status":"pending"}
]

第二步：按序执行并更新状态

Progress: 0/4 tasks completed (0%)
[ ] Find top 10 Tom Hanks movies
[ ] Group movies in pairs
[ ] Print inverted titles
[ ] Final summary

LLM 开始执行第 1 个任务，调用 TodoWriteTool 将其标记为 in_progress：

[
{"id":"1","content":"Find top 10 Tom Hanks movies","status":"in_progress"},
  ...
]

查询完成后标记为 completed，并开始下一个：

Progress: 1/4 tasks completed (25%)
[✓] Find top 10 Tom Hanks movies
[→] Group movies in pairs
[ ] Print inverted titles
[ ] Final summary

第三步：持续迭代直到完成

Progress: 2/4 tasks completed (50%)
[✓] Find top 10 Tom Hanks movies
[✓] Group movies in pairs
[→] Print inverted titles
[ ] Final summary

Progress: 4/4 tasks completed (100%)
[✓] Find top 10 Tom Hanks movies
[✓] Group movies in pairs
[✓] Print inverted titles
[✓] Final summary

在整个过程中，如果某一步出错或需要额外操作（比如发现某部电影信息不全需要补充查询），LLM 可以动态追加新任务到列表中，确保最终交付的完整性。

六、关键要点与使用建议

如果你的 Agent 在处理复杂任务时经常漏步骤，直接加上 TodoWriteTool。 它的额外开销极小——LLM 自己会根据任务复杂度决定是否创建列表，简单任务不会触发不必要的工具调用。

几个实操建议：

1. 1. 必须配 Chat Memory：TodoWriteTool 依赖 Chat Memory 来持久化任务列表。没有 Memory，每次上下文刷新后列表就会丢失，等于白搭。
2. 2. 必须配 ToolCallAdvisor：把内置的工具调用历史关掉，让 MessageChatMemoryAdvisor 统一管理，否则工具消息可能丢失。
3. 3. 系统提示词要细：在 system prompt 里明确"什么时候创建列表""什么时候更新状态""能否并行"等规则，LLM 的遵循率会高很多。
4. 4. 进度事件别浪费：TodoUpdateEvent 可以用来驱动前端进度条、写执行日志、做监控告警，生产环境强烈建议接入。

适用场景：

• • 多步骤代码生成（写代码 -> 写测试 -> 跑测试 -> 修 bug）
• • 数据分析流水线（拉数据 -> 清洗 -> 计算 -> 可视化 -> 导出）
• • 文档处理（读取 -> 摘要 -> 翻译 -> 格式化 -> 输出）
• • 任何需要"按顺序做 N 件事"的场景