Spring AI Agent 模式：为什么你的AI Agent总是忘事
研究表明，大语言模型存在一个被称为"Lost in the Middle"的问题——当上下文变长时，模型对中间位置的信息注意力会显著下降。开头和结尾的内容记得清清楚楚，中间的任务就容易被"遗忘"。当你的Agent需要同时处理文件编辑、测试执行、文档更新等多个步骤时，某些重要步骤就可能悄无声息地消失了。
你有没有遇到过这种情况：让AI Agent执行一个复杂的多步骤任务，结果它做到一半就悄悄跳过了某个关键步骤？比如你让它修改代码、运行测试、更新文档，最后发现测试根本没跑。
这不是个例。
研究表明，大语言模型存在一个被称为"Lost in the Middle"的问题——当上下文变长时，模型对中间位置的信息注意力会显著下降。
开头和结尾的内容记得清清楚楚，中间的任务就容易被"遗忘"。当你的Agent需要同时处理文件编辑、测试执行、文档更新等多个步骤时，某些重要步骤就可能悄无声息地消失了。
有没有什么好办法？Claude Code给出了一个思路：让规划变得显式且可观察。
具体做法是引入一个专门的TodoWrite工具，让Agent在执行任务前先列出待办清单，然后逐项完成、逐项打勾。这样一来，Agent不再是"心里默默记着要做什么"，而是"白纸黑字写下来，做一件划一件"。
这正是本文要介绍的Spring AI Agentic Patterns系列第三篇内容。前两篇我们讨论了Agent Skills（模块化能力）和AskUserQuestionTool（交互式工作流），这次我们来看看TodoWriteTool如何为Spring AI 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奠定了基础。
