实验 01 · Agent 循环逐帧播放器
对应第 03 章。本实验把一次 Agent 任务拆成逐帧事件，让你观察“模型输出工具调用”和“程序真的执行工具”发生在不同阶段。
1. 实验问题
很多人第一次看 Agent 日志，会把 assistant 写出的动作和电脑已经发生的动作混为一谈。这里用两个场景验证：列出目录，以及修复失败测试。先预测 history 在每一步会增加哪种角色，再按下一步。
你要寻找三个边界：任务何时进入 Runtime，工具意图何时由模型产生，真实结果何时回到模型。修复测试场景还有第二轮工具调用，可以看见失败观察怎样改变下一次决策。
2. 运行实验
切换场景不会改变五阶段骨架，只会改变每一阶段携带的数据。注意最后一步：模型没有新的工具调用，并且 Runtime 已拥有验证证据，循环才进入 completed。仅仅生成自然语言“已修复”不应绕过这一步。
3. 观察记录
尝试回答：
- assistant 消息与 tool 消息分别由谁产生；
- Executor 失败时，为什么循环不一定失败；
- 哪一步最适合加入审批；
- 哪一步最适合加入输出截断；
- 如果用户在重新验证前打断，应该保存哪些状态。
4. 改造挑战
回到 minimal_swe_agent.py，在每轮打印 turn、tool_name、call_id、result.ok 和 stop_reason。不要打印 API key 或完整大日志。然后运行 dry-run，确认即使不调用真实模型，你也能解释每条事件。
更进一步，把 history 从普通列表包进 AgentState，并为 running、completed、blocked、interrupted 写枚举。状态显式以后，界面和恢复逻辑才不会把所有停止都显示成成功。
5. 实验结论
Agent 的“智能”表现为下一动作可以根据新观察改变；Agent 的“工程”表现为每次变化都有结构化状态和边界。逐帧播放器隐藏了模型内部推理，却足够解释系统为什么行动、行动是否发生以及为什么结束。