第 4 周 · Native Agent Harness 与事件协议

本周产出：agent-core、context-engine、版本化 event-protocol · 预计投入：15 到 20 小时 · 对应原 24 周编号：第 4 周

学前自测

1. Agent Loop 最简形态是什么？用五个词概括。

构建上下文 → 调模型 → 判断是否有工具调用 → 执行工具 → 把结果追加回上下文再调模型。没有工具调用就是终止条件。整个 Agent 框架生态，剥掉所有包装之后就是这个循环。

2. 为什么必须有 Max Steps？没有会怎样？

因为模型可能陷入循环：调工具失败 → 换个参数再调 → 又失败 → 再换。没有步数上限的 Agent 在遇到一个永远修不好的错误时会一直跑到你的账单爆掉。Max Steps 是最后一道保险，Token Budget、Cost Budget、Deadline 是前面几道。

3. 什么叫 Deterministic Replay？为什么 Agent 系统特别需要它？

把一次运行的所有事件记录下来，之后能用同一份事件流完整重现当时的执行过程。Agent 特别需要它是因为线上出问题时无法复现：同样的输入模型可能给出不同输出。事件回放让你至少能还原当时发生了什么，这是排查 Agent 故障的唯一可靠手段。

4. Output Validator 失败时，直接静默重试有什么问题？

问题有三个：预算被无声消耗、失败模式对运维不可见、模型拿不到具体的失败原因就只会重复同样的错误。正确做法是产生可见的纠正事件，把具体校验错误反馈给模型，并且在预算内计数。

学习目标

亲手实现框架无关的 Agent Harness、生命周期事件与验证闭环。

这是整个程序员基础版最核心的一周。写完这一周你会拥有一个判断力：看到任何 Agent 框架，你都能立刻定位它在哪一层做了什么，值不值得引入。第 7 周引入 Mastra 时，对比就是从这里出发的。

课程内容

Agent Loop
Model → Tool → Model
Stop Condition
Max Steps
Token Budget
Cost Budget
Deadline
Tool Call Deduplication
Infinite Loop Detection
Agent State
Final Answer
Execution Events
Cancellation
Recovery
Context Transform Hook
before / after Model 与 Tool Hook
Output Validator 与 Self-correction
Run / Turn / Message / Tool / Approval / Artifact 事件协议
Backpressure、steering 与 follow-up 队列语义
Deterministic Replay 与事件版本

实施任务

实现下面这个循环：

右侧四步是有工具调用时才走的分支，结果回灌进上下文再调一次模型。红色虚线是三道拦截，在循环的任意一步命中都直接跳到终止

实现 AgentHarness、ContextEngine 与版本化 AgentEvent discriminated union。Validator 失败时必须产生可见事件并在预算内纠正，不能静默重试。

动手挑战

制造一次死循环，然后用三种不同的机制分别拦住它。

具体做法：写一个必定失败的工具（比如查询一个不存在的商品 ID），让 Agent 去调用它。默认情况下 Agent 会不断重试。然后分别启用：

Max Steps：跑到第几步被拦住？
Tool Call Deduplication：同样参数的重复调用在第几次被识别？
Infinite Loop Detection：你的检测逻辑判断依据是什么，误报率怎么样？

三种机制的触发时机和代价都不一样。做完这个实验你会明白为什么生产系统三个都要有，以及为什么去重的判定条件比想象中难写。

Agent OS 里程碑

完成 agent-core、context-engine 与 event-protocol 的 Native Harness 版本。

验收标准

核心档（程序员基础版毕业线）

最大步骤数生效
重复 Tool Call 可检测
可中途取消
可输出统一事件流
可注入自定义 Stop Policy
Runtime Event 可由 JSONL snapshot test 稳定验证
20 条 Agent 测试全部通过

进阶档验收见程序员进阶版附录 B。

学后自测

1. 你的事件协议版本化了吗？加一个新事件类型会不会打破已有的回放？

事件协议必须带版本号，且消费方对未知事件类型要能安全忽略而不是崩溃。否则一旦线上有历史事件流，你就再也不敢改协议了。这个坑在第 9 周做 Trace Explorer 时会集中爆发。

2. 用户在 Agent 执行到第 5 步时点了取消，第 5 步正在执行的工具怎么办？

分情况：读操作直接中断；写操作要么等它完成再停（保证一致性），要么走补偿。绝对不能在写到一半时硬中断留下脏数据。取消的语义必须在设计时定清楚，不能等实现时随手决定。

3. JSONL 事件快照测试怎么保证稳定？时间戳和随机 ID 怎么处理？

必须做归一化：时间戳替换成序号或固定值，UUID 替换成可预测的序列。不归一化的快照测试每次跑都失败，很快就会被团队关掉，等于白写。

本周作业

packages/agent-core/：Harness 完整实现，含 Budget、Stop、Hook、Validator、Cancellation
packages/context-engine/：上下文构建、预算与 transform
packages/event-protocol/：版本化事件定义
20 条 Agent 测试 + JSONL 事件快照
docs/agent-loop.md：设计文档，画出你的循环图，标注每个预算和停止条件的拦截点

这一周的 Harness 是你作品集里技术含量最高的部分。面试时能打开这份代码逐层讲解，比任何简历描述都有说服力。

面试考点

这一周对应面试里的核心技术深度考察，几乎必考。

「你了解 Agent 的工作原理吗？」：不要背 ReAct 论文。直接讲你手写的循环，从 Build Context 讲到 Final Answer，每一步说明为什么这么设计。手写过和只用过框架的人，回答质量差距是断层式的。
「Agent 跑飞了怎么办？」：答四层预算（步数、Token、成本、时间）加三层检测（去重、循环检测、Validator）。能具体说出每一层的触发阈值怎么定，加分。
「怎么调试一个线上出错的 Agent？」：答事件流回放。讲清楚你记录了什么、怎么归一化、怎么重现。这个问题能筛掉大部分只做过 Demo 的候选人。
「你觉得 Agent 框架帮你做了什么？」：这一周之后你才有资格答这个问题。标准答法是框架帮你做了循环、事件和状态管理，但预算策略、错误分类、审批集成通常还是要自己写。中立客观地讲，不要贬低框架。
手写题：现场实现一个带 Max Steps 的 Agent Loop 骨架。这道题在中高级岗位高频出现。

复习与延伸

官方文档与论文

ReAct 论文：Reasoning 加 Acting 的原始范式
Anthropic：构建高效 Agent：Workflow 与 Agent 的边界，本周设计取舍的重要参考
Anthropic Agent SDK 概览

起手代码（测试即规格）

examples/week-04/ 是这一周的练习仓：19 条测试对应本周全部验收标准。模型和工具都是桩，不需要 API Key。

pnpm --filter @agent-os/example-week-04 test

里面埋了一个真实的契约缺口：AgentEvent 的 StopReason 枚举描述的是「模型为什么停」，而你的循环停止原因是「预算超了」，两者对不上，发 run_end 时必须做一次映射。这个缺口第 9 周做 Trace Explorer 时会再遇到。

本仓库对应源码

packages/harness-native/src/agent-loop.ts：Native Agent Loop 参考实现，先自己写完再对照
packages/harness-native/src/agent-loop.test.ts：测试写法参考，注意预算和取消是怎么测的
packages/contracts/src/event.ts：AgentEvent 的 discriminated union 定义

下一步：第 5 周 · Session/Context 精简版 + RAG 数据管道

第 4 周 · Native Agent Harness 与事件协议

On this page