08. Agent 为什么需要状态机

如果 Agent 只调用一次模型，成功与失败两个状态或许已经足够。加入工具后，任务可能停在模型响应、等待授权、工具执行、结果回填等不同位置。

状态机是有限状态和合法转移组成的模型。它不负责让模型推理得更好，而是让运行时知道当前处境、下一步允许发生什么，以及中断后从哪里恢复。

一条工具轨迹至少有这些状态

这里最容易遗漏的是 unknown：进程中断后，运行时不能确认外部动作是否完成。它既不是明确失败，也不能直接当作成功。

对话历史不能替代状态

对话历史可以包含“模型要求调用工具”，却不一定能证明：

• 参数是否通过校验。
• 用户是否已经批准。
• 工具进程是否真正启动。
• 外部服务是否已经接受请求。
• 结果是否持久化。

如果只在内存中维护这些信息，CLI 退出后就会丢失。恢复时重新播放对话可能再次执行同一个工具。

状态转移要与事件写入绑定

运行时每次转移都应记录前一状态、后一状态、原因和关联标识。工具开始前先持久化 tool.started，完成后记录 tool.completed，然后再把结果回填给模型。

这仍然不能让本地日志与外部系统形成一个原子事务。原子事务指一组操作要么全部成功，要么全部失败。外部 API 往往不参与本地事务，所以有副作用的工具还需要幂等键或结果查询接口。

三个中断点能暴露不同问题

第三种最危险。若把“未记录结果”理解为“未执行”，恢复后会再次产生副作用。

计划、目标和状态不是同一件事

目标描述用户希望得到什么；计划描述准备采用哪些步骤；状态描述运行时当前位于哪个可执行阶段。模型可以修改计划，却不能把 tool_running 直接改成 completed。

状态转移由运行时根据事件确认。模型输出只能提出下一步候选动作。

状态机的验收方法

在每个边界强制终止进程，再从持久化记录恢复。检查：

• 是否从合法状态继续。
• 已完成的只读结果是否复用。
• 未知副作用是否先查询。
• 等待授权是否仍保持等待。
• 终态任务是否不会再次运行。

最终回答正确只能证明某次顺利路径成立。状态机要通过的是中断路径。

状态数据需要并发控制

同一任务可能同时收到工具完成、用户取消和超时事件。若三个处理器都读取旧状态再写入新状态，后写入者会覆盖先前决定。状态记录需要版本号或比较并交换机制：只有前一版本仍匹配时，转移才生效。

非法转移不能静默忽略。completed 之后出现 tool_started，或 denied 直接进入 recording，都应形成异常事件并停止自动推进。

恢复不是重新运行整个循环

恢复器先读取最后一个已提交状态，再检查未决外部动作和授权时效。只有能够证明安全的步骤才重新执行。模型历史可以帮助恢复语义目标，却不能替代工具进程、外部回执和权限记录。

一次恢复测试的通过条件不是“最终又得到答案”，而是没有重复已完成动作、没有跳过未决授权，并且新事件继续使用原轨迹标识和递增序号。

状态机回答“现在可以发生什么”

对话历史回答过去出现过哪些消息，状态机回答当前允许哪些转移。同一段历史可能对应尚未授权、正在执行、执行完成但尚未回填，或已经回填但尚未请求模型等状态。

转移表为每个状态列出允许事件。executing 再次收到 tool_started，或 waiting_approval 直接收到 tool_finished，都属于非法转移，运行时应拒绝并记录。

检查点必须与外部事实对齐

检查点是可以安全恢复的持久状态。只保存“第 3 轮”没有说明本轮工具是否改变外部系统。检查点至少关联调用参数、授权决定、执行意图、外部回执和结果记录。

本地状态停在 executing，远端查询却显示对象已经创建时，恢复逻辑应进入“结果待确认”，不能再次创建。

事件溯源与快照互补

事件溯源保存每次变化，能够解释过程；状态快照保存某个时点的当前状态，能够快速恢复。组合方式是定期生成带版本号的快照，并保留之后的事件。快照记录最后事件序号，恢复时不会重复应用同一事件。

两个工具结果同时到达时，使用乐观并发控制：只有状态版本仍等于读取时的版本，写入才成功；失败的一方重新读取并合并。测试让结果按相反顺序重复到达，最终状态必须包含两者且每个调用只完成一次。

四个性质比流程图更重要

随机生成事件序列可以覆盖人工未列出的组合。状态机的价值在于非法顺序能够被程序拒绝和回归测试，而不只在于把正常路径画成图。