Harness Engineering：给 Agent 一套安全做事的环境

可以把模型想成提出操作建议的工程师，把 Harness 想成车间。工程师可以说“启动这台机器”，但车间仍要确认机器是否存在、操作是否安全、谁有权限、运行范围多大，以及结果记录在哪里。

一、先看懂建议怎样变成真实动作

1.1 Harness 到底是什么

Harness 是包在模型外面、把模型建议变成受控真实动作的软件环境。Harness engineering 就是设计这套环境里的工具、安全规则、执行空间、状态记录和恢复方式。

它之所以必要，是因为模型本身只产生文字或结构化的动作提议。模型可以建议读取文件、修改代码、运行命令，但真正接触文件系统、进程、网络和凭据的是外层程序。把这层程序设计好，Agent 才不只是“会说”，而是能够可靠地“做”。

1.2 跟着一次运行测试，看清 Harness 的组成

模型准备验证支付模块，提出“运行 payment tests”。Harness 接手后，会按顺序完成下面这些工作：

1. 找到工具：确认系统确实提供“运行测试”这项能力，而不是让模型随意发明命令接口。
2. 检查输入：确认测试目标、工作目录和参数有效，缺失时返回明确错误。
3. 判断权限：这次任务是否允许启动进程？若动作风险更高，是否必须先让人批准？
4. 限制范围：即使允许执行，也只开放需要的仓库目录、进程和网络范围。
5. 真正执行：管理超时、取消和资源限制，启动测试进程。
6. 整理结果：完整日志存到外部文件，只把退出码、关键错误和日志引用送回模型。
7. 留下记录：记录动作何时开始、是否完成和改变了什么，保证中断后能够判断是否需要继续。

少了其中任何一步都会出现具体问题：没有输入检查，错误参数进入真实环境；没有权限和隔离，Prompt 里的“请小心”挡不住危险动作；没有结果和状态记录，进程崩溃后只能靠模型猜之前发生了什么。

把这次 Tool Call 放回完整运行，就是一条反复交替的链：Harness 准备请求 → 模型提出动作 → Harness 检查并执行 → 结果成为 observation → observation 进入下一次请求 → 模型再决定下一步。Harness 承载每次动作；Agent Loop 决定这条链是否还要再走一轮。

二、拆开这套行动环境的关键部件

2.1 把七步收拢成一套运行环境

模型擅长在不完整信息下提出计划；运行时必须把不确定性关在确定边界里。什么工具对当前角色可见、参数是否符合 schema、哪些目录可写、网络连到哪里、结果如何序列化，都应由代码和策略拥有，而不是由模型临场决定。

最小 Harness 只要能准备请求、提供工具、检查输入与权限、受限执行并返回结果。成熟系统为了可重现和可恢复，会再补上版本化工具目录、事件记录、进度观察、artifact 和 checkpoint。下面的表把这两层放在一起，便于工程评审。

Harness 负责记录并暴露 evidence；一次 run 是否继续由 agent loop 决定，跨任务和跨版本的结果质量是否成立则由 evals 判断。Verifier 可以在 harness 内执行测试，却不能因此独占产品真值。

2.2 一次 Tool Call 要经过七个关口

Tool call 是模型输出的一段结构化提案。一个稳健 harness 不会把它直接映射成函数调用，而会把“解释、授权、执行、观察”拆开。

1. Parse：确认 tool call 结构完整，关联到当前请求。
2. Resolve：在当前可见 registry 中找到精确工具版本。
3. Validate：按 schema 检查类型、范围、互斥和必填字段。
4. Authorize：结合角色、资源、动作和环境决定 allow / deny / ask。
5. Isolate：建立文件、进程、网络和凭据边界。
6. Execute：管理超时、取消、并发、重试与幂等键。
7. Normalize：把 stdout、结构结果、错误与 artifact 变成稳定 observation。

async function dispatch(call, run) {
  const tool = registry.resolve(call.name, run.toolsetVersion)
  if (!tool) return observe("unknown_tool", call.id)

  const args = tool.schema.parse(call.arguments)
  const decision = policy.decide(run.actor, tool.capability, args)
  if (decision === "deny") return observe("denied", call.id)
  if (decision === "ask") return pauseForApproval(run, call)

  const box = await sandbox.open(tool.limits)
  events.append("tool.started", { runId: run.id, callId: call.id })
  try {
    const raw = await executor.run(tool, args, { sandbox: box })
    return normalize(raw, artifactStore)
  } finally {
    await box.close()
  }
}

{
  "call_id": "call_42",
  "tool": "run_tests@3",
  "arguments": { "target": "./payment", "mode": "read-write" },
  "policy": { "decision": "allow", "rule": "repo-test" },
  "sandbox": { "fs": "workspace", "network": "off", "timeout_s": 120 },
  "result": { "status": "failed", "exit_code": 1, "artifact_ref": "log://9f2" }
}

同一个 call_id 会留下三种不同用途的事实：artifact store 保存完整日志，事件或调用账本保存 proposed、allowed、started、completed 等状态，model view 只接收足够决定下一步的 observation。恢复时，Runtime 先读取账本并与真实环境对账，必要时再按引用打开 artifact；它不会把一段聊天记录当成副作用是否发生的权威答案。

2.3 工具设计决定 Agent 会做哪些动作

Prompt 篇关心模型看到的工具说明，以及“应该怎么用”；本篇关心 registry、版本、schema validator、权限、dispatcher 和 artifact，以及“实际上能不能执行”。工具不是越多越好：两个语义重叠的写工具、一个万能 shell 和模糊的自由文本参数，会让动作空间膨胀。模型既要猜工具，又要猜参数，还要从非结构输出里判断成功。

2.3.1 一个好工具要同时服务模型与运行时

大量输出不要整段塞回 context。Harness 可以把完整日志存成 artifact，只回填摘要、关键错误和可继续读取的引用。这同时改善 context budget 与恢复能力。

2.4 允许执行，不等于可以触达一切

Permission 回答“这个主体是否被允许做这个动作”；sandbox 回答“即便允许，动作实际能触达什么”。批准运行测试不等于允许访问整个主目录；允许读取仓库不等于允许把内容发到任意网络端点。二者必须组合。

• Capability scope：先不把无关工具暴露给模型。
• Policy decision：按动作、资源、主体和环境匹配规则。
• Human approval：只在高风险或含糊边界暂停，并展示可理解的 diff。
• Sandbox：用文件系统、网络、进程和凭据隔离限制 blast radius。
• Audit：记录谁提出、哪条规则允许、实际发生了什么。

三、进阶：让真实动作可恢复、可追查

3.1 进程中断后，不能只靠聊天记录恢复

Anthropic 的 Managed agents 把 session 看作围绕模型、harness 和 sandbox 的有状态环境。工程上至少要区分：UI 对话、模型可见 messages、append-only 事件、外部 artifact、checkpoint 与环境快照。它们生命周期不同，也服务不同恢复路径。

中断恢复时，最危险的做法是仅把旧聊天重新发给模型。运行时还需要知道哪些工具调用真正执行过、哪些在途、工作区是否改变、审批是否仍有效、外部对象是否已经创建。副作用状态必须从确定性记录恢复，不能让模型根据文本猜。

tool.proposed → tool.validated → policy.allowed → tool.started
→ runtime.crashed → run.recovered → effect.reconciled
→ observation.ready

3.2 用户和系统都要看见动作进行到哪里

只有最终文本和总 token 数，无法诊断 harness。需要把一次 run 串成 trace：request assembly、model events、tool proposal、policy decision、sandbox execution、observation、checkpoint 和 exit reason。敏感正文可以脱敏，但控制事件不能消失。

• 稳定的 run / turn / call id 关联所有事件；
• 记录 tool latency、排队、重试、取消和 artifact 大小；
• 区分模型错误、工具错误、策略拒绝、环境错误和用户中止；
• 保留退出原因与未完成工作，供 outer loop 判断下一步。

四、复盘：一个 Harness 至少回答六个问题

Harness 把“模型能想到”变成“系统能安全做到”。下一篇进入它内部不断前进的控制流：Agent loop 怎样让一次运行正确收敛。

官方资料

• OpenAI：Harness engineering
• OpenAI：Unrolling the Codex agent loop
• Anthropic：Building and evaluating trustworthy agents
• Anthropic：Managed agents
• Anthropic：Harness design for long-running applications

延伸阅读

• 菜鸟教程：Harness Engineering
• Martin Fowler：Harness engineering for coding agent users
• Learn Harness Engineering