框架实验室：状态、事件、检查点与可重放运行时

参考：来源 F · 第 24 章进阶

学完你能做到

理解 Agent 框架真正管理的运行时对象
实现事件驱动状态更新和检查点
用最小实验比较框架而非比较宣传页

框架最有价值的部分通常不是 Agent() 这一行，而是长任务运行时：状态如何保存、事件怎样更新状态、失败从哪里恢复、人工确认怎样暂停、同一条轨迹怎样重放和评估。

事件驱动运行时：事件日志是事实，状态是由事件计算出的当前快照，检查点用于快速恢复。

最小状态 Schema

框架无关的业务状态

type AgentState = {
  goal: GoalContract;
  planVersion: number;
  tasks: Record<string, TaskState>;
  evidence: EvidenceRef[];
  budget: ResourceBudget;
  pendingApproval?: ApprovalRequest;
  lastEventId: string;
  stopReason?: StopReason;
};

三种运行拓扑。线性链、循环状态图和多 Agent 都能用同一套目标、工具契约和评估，只是调度方式不同。

比较维度	必须做的实验	不要只看
表达力	能否表示循环、分支、暂停和人工确认	示例代码多不多
状态	进程重启后能否恢复到正确节点	是否宣称有 memory
可观测	能否查看每步输入、输出、预算和版本	漂亮的流程图
可测试	能否替换模型/工具并重放固定轨迹	单次 demo 效果
可迁移	业务状态和工具契约能否脱离框架	社区热度

框架烘焙测试

25 分钟

用同一任务分别画线性链和循环状态图。
设计一个在人工确认处暂停、重启后恢复的测试。
列出更换框架时必须保持不变的状态 Schema、工具契约和评估集。

综合演算：用事件与检查点实现可重放运行时

研究 Agent 运行两小时后进程重启。系统必须恢复已下载论文、未完成队列和预算，而且不能重复付费下载或丢失人工确认。

本节追问：状态快照、事件日志和幂等执行如何协作？ 先不要急着看结论。沿着下面四步，逐项区分输入、决策、证据和失败信号。

四步案例推演。手机上可左右滑动查看；每个箭头都代表一次需要证据支撑的状态转换。

阶段	本步要做的决定	什么算证据	最常见的失败
定义事件	记录任务创建、工具请求、工具结果、确认和状态变更	事件不可变且有顺序与任务 ID	只覆盖保存最新大对象
建立快照	周期保存可快速恢复的结构化状态	快照指向已消费事件位置	每次恢复重放数百万事件
保证幂等	为外部副作用生成稳定动作 ID	重放不会重复扣费或发送	恢复后重新执行所有动作
验证恢复	故意在不同阶段杀进程并比较最终状态	恢复前后结果与审计链一致	只测试正常退出

阅读方式：先遮住后两列自己回答，再用“证据”和“失败”两列检查理解。

常见误解

把框架内存中的对象当持久状态

实际上

可观察症状：部署、升级或崩溃后无法可靠恢复与迁移。

更可靠的修复：将业务状态和事件持久化到框架外部，并测试版本迁移。

案例工作坊 · 建议真正动手完成

25 分钟

定义研究任务的事件 Schema 和状态快照。
为下载、发邮件和付款分别设计幂等策略。
写三次故障注入与验收条件。

查看参考答案

可恢复运行时以持久业务状态为核心：事件提供审计与重放，快照缩短恢复时间，幂等键保护外部副作用。框架只负责实现这些语义。

迁移检查：换一个场景还会不会

为什么工具请求和工具结果要分成两个事件？