Agent Harness 学习地图：从会用工具到能设计可靠系统

这不是一份名词表，而是一条学习路径。学习 Agent 的第一性原理是：模型只负责在当前信息下提出下一步，系统负责让下一步安全、可执行、可验证，并能在失败后继续。

1. 先建立一个最小模型

把一次 Agent 任务写成一个函数：

next_action = Model(goal, context, observations)
observation = Tool(next_action)
state = Reduce(state, next_action, observation)

如果只保留模型调用，系统像一次问答；如果把模型、工具、状态和验证放进循环，才开始具备 Agent 的性质。循环外的任务调度、上下文装配、权限、沙箱、恢复、评测和记忆，就是 Harness。

因此不要从“哪个框架 API 最漂亮”开始学，而要从一次任务的完整生命周期开始：目标进入，状态建立，模型决策，工具执行，结果验证，失败恢复，最终交付。

2. 推荐的渐进式学习顺序

第一步：理解 Agent Loop

先手写一个只有一个工具的 ReAct Loop。模型可以选择 inspect 或 finish，工具返回结构化结果，循环最多执行若干次。你要观察三个事实：模型会犯错；工具会失败；“模型说完成”不等于任务完成。

第二步：把循环变成可控制的 Runtime

引入 LoopSession、LoopTurn 和 StopReason。Session 保存任务的长期状态，Turn 表示一次模型决策和工具执行，StopReason 明确任务是完成、失败、等待用户，还是预算耗尽。

第三步：控制上下文与副作用

学习 Context Builder、Memory、Skill、Tool Gateway 和 Sandbox。这里的核心不是“让模型看到更多”，而是让模型看到足够、相关、可信、可追溯的信息，并把高风险动作隔离起来。

第四步：处理长程任务

短任务可以依赖当前上下文，长任务必须依赖状态、检查点、验证器和恢复包。你需要能回答：上下文爆炸怎么办？模型切换时传什么？工具超时后能否重试？用户中途追加要求后目标如何更新？

第五步：建立评测闭环

最后才谈模型升级和产品比较。没有固定任务集、轨迹记录、失败分类和回归门禁，所谓“模型变强了”只能是感觉。

3. 四个常见架构名词的统一解释

PlanAct、CodeAct 和 MultiAgent 都不是脱离 ReAct 的新物种。它们共享同一个循环：观察状态，提出行动，执行行动，再根据结果更新状态。区别只是行动的组织者不同。

  • ReAct：模型逐步决定下一次行动，适合探索性任务。
  • PlanAct：先产生计划，再执行计划；计划仍应被结果和验证器纠正。
  • CodeAct：把一段代码作为行动，让代码完成多个工具组合，表达力强但需要更严格的沙箱和权限。
  • MultiAgent：把一个循环拆成多个有角色边界的循环，解决并行、隔离或专门能力问题，但会增加通信和协调成本。

常见协作模式有四种：Agent Handoff 把状态交给另一个 Agent；Agent as Tool 把子 Agent 当工具调用；Leader & N Workers 由领导者拆分和合并；Agent2Agent 通过明确协议进行对等协作。选择标准不是“多 Agent 更先进”，而是任务是否真的存在可并行、可隔离或需要专门上下文的边界。

4. 四个产品如何公平比较

比较 Coding Agent 时，不要只比较模型名称或宣传功能，应该固定同一个仓库、同一个任务契约、同一个权限边界和同一个验收标准，然后观察五个维度：

  1. 上下文从哪里来，如何选择和压缩。
  2. Tool Call 如何执行，错误如何返回，权限在哪里控制。
  3. 任务如何规划，是否支持重规划、并行和用户介入。
  4. 编辑体验如何，局部修改和跨文件修改的边界是什么。
  5. 失败后能否恢复，是否有检查点、验证证据和可解释的状态。

可以用一句谨慎的画像表达差异：Claude Code 更突出 agentic 控制面和快速迭代；Codex 更适合从 Loop、代码状态和交付架构理解；Cursor 的优势在 IDE 上下文和局部编辑闭环；Kimi Code 更值得从长上下文、中文任务、并行和推理服务优化角度观察。以上是分析框架，不是脱离版本和配置的绝对排名。

5. 面试或系统设计时的答题骨架

先定义目标和成功标准，再画五层：任务层、Loop/Runtime 层、Context/Memory/Skill 层、Tool/Environment 层、Verify/Eval 层。之后只展开题目真正涉及的部分。

每个工程判断都用同一套句式：

问题是什么 → 为什么会发生 → 采用什么机制 → 失败时怎么恢复 → 用什么指标证明有效

例如被问“为什么要 Memory”，不要回答“因为上下文不够长”。应回答：长期任务需要跨 Session 保存稳定事实；保存前要区分事实、偏好、经验和临时状态；注入时按相关性、可信度和作用域筛选；冲突时保留来源并让新证据覆盖旧证据；最后用召回合理性、冲突率和局部更新正确率评估。

6. 最小实践项目

建议按四周完成一个小型 Coding Agent：

  • 第 1 周：实现 ReAct Loop、结构化 Tool、最大步数和基础日志。
  • 第 2 周：加入 Session/Turn、SSE 事件、取消、Steer、Followup 和 Interrupt。
  • 第 3 周：加入 Context Builder、L1/L2/L3 压缩、Verifier 和 Stop-Resume。
  • 第 4 周：加入 Sandbox、Rollout 采集、离线评测和一次故障演练。

每周必须有可运行产物和失败样本。只有写出“工具超时、上下文压缩错误、用户中断、恢复后重复副作用”的测试，知识才从概念变成能力。

7. 最终判断标准

真正理解 Agent，不是能背出更多框架名，而是能把一个模糊目标拆成状态、行动、约束和证据，并解释系统在不确定、被打断、工具失败和上下文受限时如何继续工作。