核心摘要

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

这一分解区分:

  1. 模型(Model):基于所给上下文生成概率性消息、结构化提案或工具调用参数。
  2. Harness:负责身份、已授权上下文、工具调用中介、持久状态、限制、审批、事件采集、取消与恢复。

应用和每个下游服务仍需执行自身授权并维护数据约束。Harness 的允许列表无法弥补工具服务权限过大的问题。

这种分层只有在职责明确时才有价值:

关注点 模型可以提出 Harness 必须控制 下游服务必须执行
任务计划 步骤与替代方案 步数预算、取消、Checkpoint 不适用
上下文 所需证据 授权检索、大小、来源 数据访问策略
Tool 调用 工具名称与参数 能力暴露、校验、审批 对象与 Tenant 鉴权
副作用 目标结果 Idempotency Key、超时、提交证据 事务不变量
完成状态 自报结果 终态规则与独立检查 权威最终状态

模型说「已完成」不能作为完成证据。Harness 应从测试、下游状态、Verifier 或明确的人工决策推导最终状态。

三次范式跃迁

graph LR A["Prompt:影响模型输出"] --> B["Specification:定义预期结果"] B --> C["Harness:强制运行时边界"]

三层解决的问题不同: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 控制循环

一套可用控制循环包含六个阶段:

  1. 准入:认证 Principal,加载 Policy,分配 Run ID,并拒绝不可能或未授权目标。
  2. 组装:只检索有权限的 Context,附加来源,预留输出空间,并只暴露任务范围内的 Tool。
  3. 提议:让模型生成消息、计划更新或类型明确的 Action Request。
  4. 决策与执行:校验请求,必要时取得绑定式审批,使用 Idempotency Key 调用 Tool,并记录权威结果。
  5. 评估:根据验收条件判断继续、重试、升级还是终止。
  6. Checkpoint:保存有界状态快照和恢复游标,不把生成文本当成权威状态。

循环必须有明确终态。succeeded、failed、cancelled、expired、escalated 和 outcome_unknown 在运营上完全不同。把它们都压成「completed」会使重试和事件响应变得不安全。

下面这个仅使用 Go 标准库的片段展示模型提案外部的策略边界:

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 绝对安全或自动自愈。应从系统可能产生的副作用出发,分配控制责任,测试失败与恢复路径,并逐步授予权限。

相关阅读

一手来源