核心摘要
Harness Engineering 设计模型外部的运行时控制层,包括身份、允许使用的工具和资源、状态转换、预算、审批、可观测事件、评测与恢复。Agent = Model + Harness 只是便于划分职责的简写,并非行业标准或安全证明。
本文只负责学科定义与边界:Agent Harness 术语承担简明定义,架构篇承担组件与数据流,实战篇承担实现,评测篇承担测试。
引言:从"提示词"到"脚手架"
团队可以从探索式 Vibe Coding 转向明确的 Spec Coding,但规格无法强制执行运行时权限。模型仍可能请求未授权 Tool、重复副作用、突破预算、消费过期状态或输出错误格式。
Harness Engineering 让这些运行时问题变得明确且可测试,但不会让模型行为天然安全,也不会把鉴权职责转移到 Prompt 中。
Harness Engineering 是什么?
Harness Engineering 是构建 AI Agent 外部运行时控制层的工程学科。模型提出内容或动作后,Harness 负责验证调用主体身份、筛选可用能力、校验请求、执行策略、记录状态与证据、限制预算,并明确标记完成或失败状态。
部分应用无需 Tool 也有价值,加入 Harness 也不会自动带来自主性、正确性或安全性。关键价值是职责分离:概率性模型输出应被视为不可信提案,只有确定性控制或独立授权允许后才能产生副作用。
模型与运行时职责
核心定义:Agent = Model + Harness
这一分解区分:
- 模型(Model):基于所给上下文生成概率性消息、结构化提案或工具调用参数。
- Harness:负责身份、已授权上下文、工具调用中介、持久状态、限制、审批、事件采集、取消与恢复。
应用和每个下游服务仍需执行自身授权并维护数据约束。Harness 的允许列表无法弥补工具服务权限过大的问题。
这种分层只有在职责明确时才有价值:
| 关注点 | 模型可以提出 | Harness 必须控制 | 下游服务必须执行 |
|---|---|---|---|
| 任务计划 | 步骤与替代方案 | 步数预算、取消、Checkpoint | 不适用 |
| 上下文 | 所需证据 | 授权检索、大小、来源 | 数据访问策略 |
| Tool 调用 | 工具名称与参数 | 能力暴露、校验、审批 | 对象与 Tenant 鉴权 |
| 副作用 | 目标结果 | Idempotency Key、超时、提交证据 | 事务不变量 |
| 完成状态 | 自报结果 | 终态规则与独立检查 | 权威最终状态 |
模型说「已完成」不能作为完成证据。Harness 应从测试、下游状态、Verifier 或明确的人工决策推导最终状态。
三次范式跃迁
三层解决的问题不同:Prompt 表达意图,Specification 把意图转成验收条件,Harness 控制一次运行如何取得证据并产生副作用。它们都不能替代服务级访问控制或产品治理。
Harness Engineering 的核心组件
生产 Harness 通常至少拆分以下关注点:
1. 护栏系统 (Guardrails)
策略执行层在运行前解析已经认证的调用主体、租户、资源、操作和用途。输入过滤可以减少干扰,但提示词注入检测不是授权边界;工具参数还需要 Schema 校验和业务含义校验。
2. 记忆管理 (Memory Management)
Harness 需要区分临时 Context、持久 Workflow State 与长期 Memory。检索内容进入模型前必须执行访问控制;Checkpoint 需要版本、保留、删除、并发和迁移规则。
3. 工具调用中介与执行
工具层只开放用途明确、权限有限的操作,并负责参数校验、超时、幂等、结果限制、密钥脱敏以及副作用记录。沙箱可以缩小事故影响范围,但不能取代授权或宿主机加固。
4. 预算、审批、证据与恢复
步数、时间、Token、重试次数、数据量、并发数和成本限制必须由模型外部控制。高影响操作可以暂停,等待针对具体副作用的持久化审批。可观测事件用于评测和事件响应;重试机制还必须处理幂等性和结果未知的情况。
5. 独立评估
运行时不能把生成模型的置信度或自我审查当作充分证据。应由确定性测试、Schema 校验、策略引擎、独立 Evaluator 或人工复核判断步骤是否通过。Anthropic 关于长任务 Agent 的实践把 Planner、Generator 与 Evaluator 分开,部分原因正是让评估可以跨 Context Reset 延续,并减少对生成阶段假设的继承。
独立 Evaluator 仍可能是概率性的,也会出错。需要记录其 Model、Rubric、证据与分歧;安全和鉴权等确定性不变量仍是硬门禁。
Agent Harness 控制循环
一套可用控制循环包含六个阶段:
- 准入:认证 Principal,加载 Policy,分配 Run ID,并拒绝不可能或未授权目标。
- 组装:只检索有权限的 Context,附加来源,预留输出空间,并只暴露任务范围内的 Tool。
- 提议:让模型生成消息、计划更新或类型明确的 Action Request。
- 决策与执行:校验请求,必要时取得绑定式审批,使用 Idempotency Key 调用 Tool,并记录权威结果。
- 评估:根据验收条件判断继续、重试、升级还是终止。
- Checkpoint:保存有界状态快照和恢复游标,不把生成文本当成权威状态。
循环必须有明确终态。succeeded、failed、cancelled、expired、escalated 和 outcome_unknown 在运营上完全不同。把它们都压成「completed」会使重试和事件响应变得不安全。
下面这个仅使用 Go 标准库的片段展示模型提案外部的策略边界:
package main
import (
"errors"
"fmt"
)
type Run struct {
Tenant string
RemainingStep int
AllowedTools map[string]bool
IdempotentTools map[string]bool
}
type Proposal struct {
Tenant string
Tool string
EffectDigest string
}
type Approval struct {
EffectDigest string
Granted bool
}
func admit(run *Run, proposal Proposal, approval Approval) error {
if run.RemainingStep <= 0 {
return errors.New("step budget exhausted")
}
if run.Tenant == "" || run.Tenant != proposal.Tenant {
return errors.New("tenant denied")
}
if !run.AllowedTools[proposal.Tool] {
return errors.New("tool denied")
}
if !run.IdempotentTools[proposal.Tool] {
return errors.New("tool is not retry-safe")
}
if !approval.Granted || approval.EffectDigest != proposal.EffectDigest {
return errors.New("approval does not match effect")
}
run.RemainingStep--
return nil
}
func main() {
run := Run{
Tenant: "tenant-a",
RemainingStep: 2,
AllowedTools: map[string]bool{"invoice.read": true},
IdempotentTools: map[string]bool{"invoice.read": true},
}
proposal := Proposal{
Tenant: "tenant-a",
Tool: "invoice.refund",
EffectDigest: "sha256:refund-request",
}
approval := Approval{EffectDigest: "sha256:refund-request", Granted: true}
if err := admit(&run, proposal, approval); err != nil {
fmt.Println("blocked:", err)
return
}
fmt.Println("admitted")
}
示例故意不调用 Model 或 Tool,它要表达的契约是:生成参数保持惰性,直到可信代码允许这个精确副作用。
Harness 与相邻工程学科的边界
| 学科 | 核心问题 | 不能替代 |
|---|---|---|
| Prompt Engineering | 模型应如何理解并回答请求? | 鉴权、状态、恢复 |
| Agent 编排 | 下一个运行哪个组件或 Worker? | Policy 与业务不变量 |
| Harness Engineering | 一次运行在什么权限、限制、证据和恢复规则下继续? | 下游服务鉴权 |
| DevOps 与 SRE | 服务如何构建、部署、观测和恢复? | Agent 每一步决策 |
| 应用安全 | 哪个身份能访问哪些资源与副作用? | 模型评测 |
Harness Engineering 与这些领域有交集,但关注对象不同:它控制的是下一步行为具有概率性、状态可能跨越一个上下文窗口的模型驱动运行。
为什么 Tool-Using Agent 需要运行时控制?
随着 MCP (Model Context Protocol) 的普及,AI 获得了访问本地文件、数据库和外部 API 的统一接口。但这种能力的释放也带来了巨大的风险。
MCP 统一了客户端与服务端描述和调用能力的方式,但不会自动提供最终用户授权、租户隔离、最小权限或安全的副作用处理。Harness 必须把协议调用绑定到应用身份与策略,每个服务端也要独立执行访问控制。
同一原则也适用于框架 Sandbox、浏览器 Profile、代码容器和云凭据。隔离可以缩小事故影响范围,但 Sandbox 内的凭据仍决定进程能够访问什么。初始状态应没有任何权限,再按单个任务与生命周期授予最小能力。
上线前必须设计的失败模式
上下文漂移
长任务可能在压缩时丢掉约束,复用过期 Policy,或继承被污染的 Memory。需要版本化 Context,保留来源引用,在重置后重新校验权限,并在必要证据缺失时停止运行。
重复副作用或结果未知
下游已经提交后仍可能发生超时。应使用 Idempotency Key、持久化尝试记录,并在重试前对账。「没有响应」不等于「没有产生副作用」。
审批漂移
用户可能只批准某个接收人或金额,模型却随后修改参数。应对完整规范化请求进行绑定,任何字段变化都使原审批失效。
Evaluator 耦合
Generator 与 Evaluator 如果共享相同上下文和假设,可能对同一个错误结论达成一致。能用确定性检查时优先使用,隔离评估证据,并跟踪人工分歧。
无界自主运行
缺少限制时,一个可恢复错误可能演变成持续花费、冲击下游服务或反复修改状态的循环。步数、时间、重试、Token、数据量、并发与成本预算必须在模型外部执行。
如何评测 Harness
评测对象是完整运行,而不只是最终文本:
- 任务成功与验收条件覆盖;
- 未授权读取、写入、目的地与跨 Tenant 尝试;
- 重复副作用与结果未知;
- Tool、Model、网络和状态存储故障后的恢复;
- 审批绑定与取消行为;
- Trace 完整性与密钥泄露;
- p50、p95 与 p99 延迟;
- 每个成功任务成本与人工修正时间。
使用代表性的正常、边界、对抗、长任务和故障注入案例。模型能力评测与 Harness 评测应分开:更强模型可能在普通任务上掩盖薄弱 Harness,但控制系统仍会在对抗或部分失败场景下暴露问题。
结语
Harness Engineering 把隐式 Agent 胶水代码变成明确的运行时控制系统。它可以降低并暴露风险,却不能让 Agent 绝对安全或自动自愈。应从系统可能产生的副作用出发,分配控制责任,测试失败与恢复路径,并逐步授予权限。
相关阅读
- Agent Harness 术语定义 — Agent Harness 核心概念速查
- AI Agent Harness 架构详解 — Harness 组件解剖:状态管理、工具注册、安全层
- AI Agent 评估与 Harness Engineering 实战 — 如何评估 Agent 在 Harness 下的表现
- Harness Engineering 实战:MCP + LangGraph — 动手构建自主 Agent 运行环境
- 多 Agent 系统开发完全指南
- MCP 协议完全指南
- AI Agent 开发实战指南