从零搭出一个可运行、可验证的最小系统
不只画架构图:下载零依赖脚手架,运行正常、拒绝、工具失败和上下文超限四条路径,再用测试证明边界真的生效。
- 能在本地一条命令运行零依赖 Mini Harness,并读懂事件流
- 能实现 Tool Schema、allow/ask/deny、Checkpoint 与 Outcome Verifier
- 能用四条 Eval 场景证明正常与失败边界,而不是只演示 Happy Path
怎样把 Model、Tool、Policy、State、Verifier 与 Eval 从概念接成一个能运行的 Agent?
这节课提供一个可以公开下载的零依赖 Node.js 脚手架。它默认使用 ScriptedModel,所以无需 API Key、无需安装第三方包,也不会把随机模型输出和 Harness Bug 混在一起。你先学会系统责任,再替换真实模型适配器。
脚手架不是 Claude Code、Codex 或 Hermes 的缩小复刻。它只保留生产 Agent 无法逃避的窄腰:Task、Model Adapter、Tool Contract、Policy、Loop、Transcript、Checkpoint、Verifier 与 Eval Harness。具体事件名和目录属于教学实现。
完成标准不是“代码能启动”,而是四条路径都可重复:正常完成、权限拒绝、工具失败、上下文超限。每条路径都必须产生明确终态、事件记录和独立 Outcome 证据。
先记住这句话把 Mini Harness 当成一条可检查的生产链:模型只提出下一步动作;工具合同负责参数;Policy 决定 allow、ask、deny;Runtime 执行动作并记录事件;Verifier 检查真实 Outcome;Eval Harness 用多条场景重复验收。每一层都能单独替换,但责任不能消失。
第一步:先读合同,再运行 Happy Path
下载 README、mini-harness.mjs 与测试文件,确认 Node.js 20 或更高版本。运行正常场景时,先不要改代码;逐行观察 task.started、model.requested、tool.requested、policy.decided、tool.completed、observation.added、verifier.completed 与 turn.completed。
事件不是为了好看。它们让 CLI、Web、日志、恢复和 Eval 共享同一事实。若界面只从字符串猜状态,审批、中断和重连迟早分叉。
第二步:让工具和权限成为确定性合同
Model Adapter 返回工具名和参数,但 Tool Registry 必须检查工具是否存在、参数类型、工作区路径和副作用。只读搜索可以 allow;文件写入进入 ask;读取密钥或越出工作区直接 deny。Policy 的结果要写回 Transcript,让后续步骤继续遵守。
审批拒绝不是异常。Harness 应保留已有证据,取消写入,给出可交接方案并结束为 completed_with_limits。测试必须证明目标文件没有变化。
第三步:把真实结果与模型自述分开
Verifier 不读取模型说了什么,而是检查外部状态:文件是否包含期望修复、相关测试是否通过、Diff 是否只影响允许范围。模型可以组织最终说明,却不能给自己签发完成证书。
Transcript 记录发生过什么,Checkpoint 记录从哪里安全继续,Outcome 记录现实结果。三者用途不同:只有消息历史,很难在进程退出后判断一个写入是否已经发生。
第四步:从单次测试升级到 Agent Eval
单元测试保证 Tool、Policy 和 Verifier 的确定性逻辑;场景 Eval 把它们放回完整任务。正常路径检查完成,拒绝路径检查无副作用,工具失败路径检查恢复与诚实交接,上下文超限路径检查熔断事件、失败 Checkpoint 与第二次模型调用被阻止。
这仍只是最小回归集。接入真实模型后,每个 Task 应运行多次 Trial,并记录模型、Prompt、工具、Runtime 与数据版本;否则一次成功不能代表稳定托付。
第五步:只替换一个部件,观察新失败
当四条确定性路径全部通过,再实现 LLM Adapter,把工具 schema 和当前上下文发送给真实模型。不要同时改 Loop、Policy 与 Verifier;一次只替换一个责任层,才能知道新增失败来自模型选错动作、参数不合法,还是系统实现。
你的扩展作业是新增一个窄工具、一条权限规则和一个 Outcome Grader。三者都应各有单元测试,并在一条端到端场景中共同出现。
这节课故意先用 ScriptedModel,而不接真实大模型。固定模型输出能把 Harness 本身的责任暴露出来:动作怎样校验、权限怎样暂停、工具怎样失败、状态怎样保存、Outcome 怎样验证。等这些边界可测试后,再替换 LLM Adapter。
根据目标与 Observation 提出结构化 tool call 或 final
按 schema 校验工具名称、路径和参数
依据资源和副作用给出 allow、ask 或 deny
执行工具、记录事件、保存 Checkpoint,并把 Observation 回填
检查文件与测试等 Outcome,并在四条场景重复运行
有术语没听懂?在这里用人话再看一遍7 个词+
- Model Adapter
- 把具体模型 API 翻译成 Harness 统一的 tool call 或 final 结果;更换模型不应重写权限和工具运行时。
- Tool Registry
- 保存可用工具、参数校验、风险元数据和执行函数的确定性目录。
- Policy
- 根据动作、资源、风险和用户授权输出 allow、ask 或 deny 的规则层。
- Transcript
- 按顺序记录模型请求、工具、审批、Observation 和终态的事件历史。
- Checkpoint
- 保存任务目标、当前位置、已产生副作用和恢复所需证据的安全继续点。
- Outcome Verifier
- 独立检查文件、测试或外部状态,判断任务是否真的完成。
- ScriptedModel
- 按预设动作返回的确定性模型替身,用于先稳定测试 Harness 本身。
同一个 Mini Harness,四类终态都要能运行
脚手架用四个隔离的窄任务分别触发成功、策略拒绝、工具恢复和上下文熔断。它们共享同一 Loop、Tool Contract、Policy、事件与 Verifier 接口,用来证明边界不依赖某条临时 Prompt。
- 01
正常路径:只读搜索自动允许,写入请求获批,Verifier 检查修复与测试。
- 02
权限拒绝:Policy 保存拒绝,文件不变化,Agent 交付补丁建议和接管信息。
- 03
工具失败:Runtime 返回结构化 ToolError,有限重试后诚实部分完成。
- 04
上下文超限:最小实现先熔断并保存失败 Checkpoint,阻止模型继续;生产扩展再加入可回源压缩。
四条路径共享同一 Harness 核心、Tool Contract 与事件协议;区别来自场景输入、确定性约束和终态,而不是临时改 Prompt。
下载、运行、改坏、再用测试证明你修好了。
这不是伪代码。完整包包含可执行主循环、四条故障路径、6 份教学访谈、研究扩展、13 项测试与逐步 README。默认使用 ScriptedModel,不需要 API Key,也不会访问你选择的实验目录之外。
node run.mjs normal
node run.mjs permission-denied
node run.mjs tool-failure
node run.mjs context-limit
node run.mjs all
node --test *.test.mjs- 先不改代码比较四条路径的事件、终态和真实副作用。
- 新增一个窄工具补参数校验、风险元数据、结构化错误与单元测试。
- 新增一条 Policy证明 deny 不会写入,ask 会暂停并保存审批结果。
- 新增 Outcome Grader让完成证据来自外部状态,不来自模型自述。
本章依据与证据边界6 条结论 · 8 份原始材料+
正文已经把关键来源放在相关概念旁边。这里保留完整核验清单:每条材料能支持什么、不能支持什么;不要求离开本站才能继续学习。
- [1]
OpenAI 对 Codex Agent Loop 的公开说明支持模型请求、工具结果回填与循环这一基本机制。
官方事实OPUnrolling the Codex agent loop官方工程文章 · 核验 2026-07-14 - [2]
OpenAI 的 Codex 安全实践支持把沙箱、审批、网络策略和审计作为 Harness 责任。
官方事实OPRunning Codex safely at OpenAI官方工程文章 · 核验 2026-07-14 - [3]
Anthropic 的 Agent Eval 方法区分 Task、Trial、Transcript、Outcome、Grader 与 Evaluation Harness。
官方事实ANDemystifying evals for AI agents官方工程文章 · 核验 2026-07-14 - [4]
Hermes 固定提交源码展示工具调用在执行前还要经过名称、参数与重复调用处理,执行结果再被写回会话。
固定源码观察NOHermes Agent tool loop (fixed commit)官方源码 · 核验 2026-07-14 - [5]
Hermes 固定提交的 Turn Finalizer 处理预算耗尽、完成判定、轨迹保存、资源清理与会话持久化。
固定源码观察NOHermes Agent turn finalizer (fixed commit)官方源码 · 核验 2026-07-14 - [6]
本站零依赖目录、事件名、四场景与 ScriptedModel 是教学实现,不是上述机构的官方脚手架。
本站推演ANDemystifying evals for AI agents官方工程文章 · 核验 2026-07-14
查看全部一手材料与源码证据 8 条
这份材料区分了由预定义代码路径控制的 Workflow 与由模型动态控制过程的 Agent,并强调先采用能工作的最简单方案。它还给出 Prompt Chaining、Routing、Parallelization、Orchestrator-Workers、Evaluator-Optimizer 等组合模式,以及何时值得承担 Agent 的延迟、成本和复合错误。
官方方法 · 核验 2026-07-11Writing effective tools for AI agents - with AI agentsAnthropic这份材料把工具定义为确定性系统与非确定性 Agent 之间的合同,说明工具名称、参数、描述、错误反馈和返回内容都会改变模型行为。它支持用真实任务和留出集评测工具,并强调更少重叠、边界清晰、返回高信号且 Token 高效的工具通常更可靠。
官方方法 · 核验 2026-07-11Demystifying evals for AI agentsAnthropic这份材料定义 Task、Trial、Grader、Transcript、Outcome、Evaluation Harness 与 Agent Harness,并强调评估 Agent 时实际评估的是模型与 Harness 的组合。它支持用多次 Trial、代码/模型/人工 Grader、Outcome 与轨迹联合评分,以及分别建设 Capability Eval 和 Regression Eval。
官方方法 · 核验 2026-07-11A practical guide to building agentsOpenAI这份指南面向产品与工程团队,给出 Agent 使用场景判断、Model/Tools/Instructions 基础结构、单 Agent 与多 Agent 编排和 Guardrail 设计。它支持从复杂决策、难维护规则和非结构化信息出发选择场景,并强调先强化单 Agent、从小范围真实用户验证开始。
官方产品实现 · 核验 2026-07-11Unrolling the Codex agent loopOpenAI这份材料逐步解释 Codex Harness 如何组装 instructions、tools 与 input,通过 Responses API 在一次 Turn 内循环完成模型推理和工具调用。它还说明对话增长、上下文窗口、Prompt Caching 与 Compaction 为什么属于 Harness 的核心工程责任。
官方产品实现 · 核验 2026-07-11Running Codex safely at OpenAIOpenAI这份材料展示 OpenAI 在真实内部工作流中如何组合 Sandbox、Approval、网络策略、身份凭证、规则和管理员强制配置。它也说明 Agent 原生遥测如何记录用户意图、审批、工具、MCP 与网络决策,让安全团队能够审计发生了什么以及为什么发生。
固定提交源码 · 核验 2026-07-11Hermes Agent conversation loopNous Research这段固定提交源码展示 Hermes 如何检查工具名、修复参数、限制委派数量、去重调用、执行工具,并把结果写回消息历史。它直接证明生产级 Agent Loop 在模型输出与真实动作之间还需要确定性处理。
固定提交源码 · 核验 2026-07-14Hermes Agent turn finalizationNous Research这段固定提交源码定义 Turn 结束时的预算与完成判定,并把轨迹保存、资源清理、会话持久化和清理错误纳入统一关账。它支持课程把 completed 视为需要系统证据与退出处理的状态,而不是模型的一句话。
本课对应面试题
离开这个模块之前,先自己回答这 1 个问题。
不打分、不记录。答不上来就点回那一课;能用自己的话讲清楚,再进入下一模块。已标记已读 0/1。
06.1为什么单元测试通过仍不等于 Agent 产品 Eval 通过?+
单元测试能证明某段确定性代码;Agent Eval 还要固定 Task 与环境、多次 Trial、检查 Transcript 和 Outcome、校准 Grader,并通过回归与发布门槛。