KEEL · 龙骨 · A CURRICULUM FOR THE AI ERA

Agent Harness：把一次模型调用变成可解释的运行 — keel 龙骨

Agent Harness 的参考信息：Agent Harness：把一次模型调用变成可解释的运行

先把自己放进一个真实的值班场景：用户提交故障编号，模型判断下一步，程序决定是否查询工具，工具结果回到模型，运行最终以完成、失败、取消或等待审批结束。你要理解的不是某个框架的 API，而是这条运行为什么能够继续、为什么必须停止，以及每一步由谁负责。

下面先看一次请求会怎样走。随后再把这条路径拆成模型适配、消息协议、事件、状态、工具、策略、停止条件和服务接口。

先看一次请求怎样走

flowchart LR
    A[用户目标] --> B[Harness 接收运行]
    B --> C[准备上下文]
    C --> D[模型提出 Decision]
    D --> E{需要工具?}
    E -->|否| F[最终回答]
    E -->|是| G[校验、授权、执行]
    G --> H[Tool Result]
    H --> C
    F --> I[完成/失败/取消/等待审批]

Harness 不是“更聪明的模型”。它是包在概率模型外面的控制层：模型提出下一步，Harness 决定下一步是否可以发生、如何记录、何时停止。

读完这条路径，你应能解释什么

Model、Tool、Agent、Workflow、Agent Loop 和 Harness 的边界；
为什么模型输出是建议，工具执行才是动作；
Message、Context、State、Event 和 Checkpoint 分别保存什么；
Streaming 的增量事件为什么不等于运行完成；
Decision、Action、Result 如何成为稳定的内部协议；
工具调用前后哪些条件必须由程序校验；
状态机如何处理继续、完成、失败、取消和审批；
Timeout、Deadline、Cancellation、Retry 和 Idempotency 的区别；
为什么只读工具和副作用工具不能使用同一套自动执行策略；
如何通过事件、回放和确定性测试解释一次运行。

学习路线

章节	你会先解决的问题	主要产出
01. Agent 到底比一次模型调用多了什么？	建立 Model、Tool、Agent、Harness 的心智模型	一张责任边界图
02. 先让模型只做一件事：生成消息	看见模型适配器和消息的真实边界	第一次 Ollama 调用
03. 屏幕上的字为什么不等于运行完成？	区分流式增量和运行事件	一个事件时间线
04. 怎样把模型建议变成程序输入？	建立 Decision、Action、Result 协议	真实结构化输出
05. 让模型第一次用上只读工具	完成一次模型—Harness—工具往返	只读诊断查询
06. 把往返变成有边界的运行	用状态机、预算和停止条件收束循环	`Harness.run()`
07. 模型看到什么，系统保存什么？	分开 context、state、checkpoint 和 memory	上下文边界图
08. 失败、取消和重启怎样保持可解释？	处理 timeout、retry、cancel 和恢复	失败注入实验
09. 模型想做危险的事时谁来暂停？	建立策略、权限和人工审批边界	副作用工具审批
10. 怎样把一次运行还原出来？	用事件、测试和回放定位问题	运行评估报告
11. 把脚本放进 API 和 worker	映射到服务化项目边界	服务接口草图
12. 完成事件诊断助手	把所有边界连成一条垂直切片	结课项目

工具子系统会在 Tool Calling 课程中继续深入；持久记忆会在持久记忆课程中展开；多个专业执行者的任务、交接和汇聚见多 Agent 协作课程。Tool Call 获准后的幂等、未知结果、对账和补偿见现实世界执行课程；身份、委派、提示注入、隔离和审计见安全控制课程。这里先理解它们在一次 Harness 运行中的位置，不重复讲完所有实现细节。

把这条运行放进代码

代码和运行方式写在 project/README.md 中。先运行确定性示例，再接入真实 Ollama：

python courses/foundation/agent-harness/course/project/examples/01_chat.py
python courses/foundation/agent-harness/course/project/examples/03_structured_decision.py
python -m unittest discover -s courses/foundation/agent-harness/course/project/tests -v

第 03 个示例使用真实模型观察结构化输出；协议、状态和停止条件由测试中的固定响应验证。模型这次是否“碰巧答对”，不能替代程序不变量测试。

阅读和运行时，按这条顺序做

每一章都从一个具体现场开始。先停下来预测运行会发生什么，再运行最小示例，观察完整输出；接着故意破坏一个条件，用自测问题解释失败。代码注释说明“这一步为什么存在”，而不是重复变量名称。

从第 01 章开始。先读懂一次运行的责任边界，再打开完整 Harness 源码。

读完之后，如果想看真实工业级运行时如何做出这些取舍，往前走到「Harness 源码解剖室」板块：Claude Code Harness 是最直接的一例（同一个主循环，工业级实现），五个运行时的横向取舍见 Harness 对比与选型。这边的课给你的是心智模型，那边给的是别人的实现。

进入 keel 阅读