Spring AI Agent 模式：利用 TodoWriteTool 解决任务遗忘

研究表明，大语言模型存在一个被称为'Lost in the Middle'的问题——当上下文变长时，模型对中间位置的信息注意力会显著下降。开头和结尾的内容记得清清楚楚，中间的任务就容易被'遗忘'。当你的 Agent 需要同时处理文件编辑、测试执行、文档更新等多个步骤时，某些重要步骤就可能悄无声息地消失了。

你有没有遇到过这种情况：让 AI Agent 执行一个复杂的多步骤任务，结果它做到一半就悄悄跳过了某个关键步骤？比如你让它修改代码、运行测试、更新文档，最后发现测试根本没跑。

这不是个例。Claude Code 给出了一个思路：让规划变得显式且可观察。

具体做法是引入一个专门的 TodoWrite 工具，让 Agent 在执行任务前先列出待办清单，然后逐项完成、逐项打勾。这样一来，Agent 不再是'心里默默记着要做什么'，而是'白纸黑字写下来，做一件划一件'。

本文将介绍 Spring AI 中的 TodoWriteTool，探讨其如何为 Agent 带来结构化的任务管理能力。

TodoWriteTool 是什么

简单来说，TodoWriteTool 是一个让大语言模型能够创建、跟踪和更新任务列表的 Spring AI 工具。

它的设计灵感来自 Claude Code 的 TodoWrite 功能，核心思想是把隐式的规划变成显式的、可追踪的工作流。完整实现可以在 GitHub 上找到：TodoWriteTool.java

当 Agent 收到一个复杂任务，比如'在设置页面添加深色模式开关并运行测试'，它会先用 TodoWriteTool 把任务分解成若干子任务：

创建深色模式开关组件 - 在 Settings 页面添加 UI 组件
添加状态管理 - 使用 context 或 store 管理深色模式状态
实现主题样式 - 添加深色主题的 CSS 样式
运行测试 - 确保功能正常工作

每当需要更新计划——无论是创建初始任务、标记进度，还是添加新发现的工作——LLM 都会调用这个工具。

任务状态的生命周期

这个工具接受一个待办项列表，每个待办项包含 id、content（要做什么）和 status（状态）。每个待办项遵循简单的生命周期：

pending - 待办，还没开始
in_progress - 进行中，正在处理
completed - 已完成

这里有一个重要的约束：同一时间只能有一个任务处于 in_progress 状态。

这个设计强制 Agent 专注于顺序执行，而不是分散地尝试并行处理多个任务。对于 LLM 来说，这种约束能有效避免注意力分散导致的遗漏。

执行过程中的进度展示看起来是这样的：

Progress: 2/4 tasks completed (50%) [✓] 查找 Tom Hanks 前 10 部电影 [✓] 将电影两两分组 [→] 打印反转后的标题 [ ] 最终总结

LLM 如何知道何时使用这个工具

工具描述中包含了使用指导：

"当任务需要 3 个或更多不同的步骤或操作时使用此工具。如果只有一个简单任务，且可以在 3 个简单步骤内完成，则跳过使用。"

这种自治行为意味着 Agent 会根据任务复杂度自主决定是否创建任务列表。简单任务直接执行，复杂任务先规划再执行。

为了获得更好的效果，建议在系统提示词中加入详细的任务管理说明。项目中提供了一个参考示例 MAIN_AGENT_SYSTEM_PROMPT_V2，这是一个受 Claude Code 启发的提示词模板。

还有一点需要注意：TodoWrite 模式依赖 Chat Memory 来保留任务列表更新并将其传递给 LLM。同时，启用 ToolCallAdvisor 可以替代内置的 ChatModel 工具调用，确保所有工具消息都被记录在聊天记忆中。

快速开始

第一步：添加依赖

<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。

第二步：配置 Agent

ChatClient chatClient = chatClientBuilder
    .defaultTools(TodoWriteTool.builder().build())
    .defaultAdvisors(
        ToolCallAdvisor.builder()
            .conversationHistoryEnabled(false).build(),
        MessageChatMemoryAdvisor.builder(
            MessageWindowChatMemory.builder().build()
        ).build()
    )
    .build();

将 conversationHistoryEnabled 设置为 false 是为了禁用内置的工具调用历史，改用 MessageChatMemoryAdvisor 来管理。

第三步（可选）：事件驱动的进度更新

这个工具会发布事件，你的应用可以用来实时更新 UI。比如定义一个专门的 ApplicationEvent 和事件监听器：

@Component
public class TodoProgressListener {
    @EventListener
    public void onTodoUpdate(TodoUpdateEvent event) {
        int completed = (int) event.getTodos().stream()
            .filter(t -> t.status() == Status.completed)
            .count();
        int total = event.getTodos().size();
        System.out.printf("Progress: %d/%d (%.0f%%)", completed, total, completed * 100.0 / total);
    }
}

然后在 todoEventHandler 中添加事件发布：

TodoWriteTool.builder()
    .todoEventHandler(event -> applicationEventPublisher.publishEvent(
        new TodoUpdateEvent(this, event.todos())))
    .build();

这意味着什么

TodoWriteTool 为 Spring AI Agent 带来了结构化的任务管理能力，把隐式的规划变成了显式的、可观察的工作流。通过让 Agent 的计划变得可见和可追踪，你能获得：

更可靠的执行 - 任务不会被悄悄跳过
更好的用户体验 - 用户能看到实时进度
更容易调试 - 出问题时能快速定位

核心要点：如果你的 Agent 在复杂任务上总是丢步骤，加上 TodoWriteTool 试试。开销很小——LLM 会根据任务复杂度自己决定是否需要任务追踪。

结合 Agent Skills（领域知识模块化）和 AskUserQuestionTool（交互式澄清），TodoWriteTool 为构建可靠的 AI Agent 奠定了基础。