什么是 Agent Harness?与 Framework / Runtime 三层抽象有何区别?
题目
什么是 Agent Harness?与 Framework / Runtime 三层抽象有何区别?
参考答案
点击展开参考答案
Agent Harness 是 2025-2026 年新晋的行业术语,指**"模型之外的一切"**——围绕固定 LLM 构建的、有强意见的运行壳:默认 system prompt、Tool Registry、Context 工程、Hook 生命周期、沙箱与权限模型全套打包。LangChain 官方在 2025-10 提出的三层抽象很好地厘清了边界:Framework(LangChain / CrewAI / OpenAI Agents SDK)给你"积木";Runtime(LangGraph / Temporal / Inngest)给你"durable execution";Harness(Claude Code / Codex CLI / Cline / Devin)给你"一辆装配好的车"。Parallel.ai 的实证数据点出 harness 大约决定 Agent 70% 的实战表现,Terminal Bench 2.0 上同一个 Claude Opus 4.6 换 harness 可从 #33 跳到 ~#5——这就是为什么 Devin 和 Claude Code 都不用 LangGraph 而要自研。
Cheat sheet:
- 三层抽象(自下而上):LLM → Framework(积木) → Runtime(持久化执行) → Harness(装配好的代码 Agent)
- Harness ≠ Framework:opinionated vs unopinionated;前者只让你 customize 四件事(system prompt / tools / context / subagents)
- Harness 最小抽象 6+1:Loop / State / Tool / Memory / Hook / Skill +(Observability)
- 核心数据点:Terminal Bench 2.0「harness > 模型」杠杆 —— 同模型不同 harness 排名差异 28 位
- Post-training Coupling:Codex 模型权重已绑定
apply_patch工具签名,换 harness 等于丢能力
一、三层抽象:从 LangChain 官方说起
LangChain 官方博文(2025-10)首次系统化提出 Agent 软件栈的三层分类,迅速成为 2026 业界共识:
三层抽象自下而上:LLM → Framework(积木)→ Runtime(持久化执行)→ Harness(装配好的车)。
一句话区分:
- Framework 教你"如何拼装 Agent"
- Runtime 让你"Agent 拼装好后跑得稳"
- Harness 直接给你"拼装好且调好性格的 Agent"
二、Harness 的最小完整抽象(6+1)
社区收敛出的 Harness 通用抽象(Addy Osmani、HumanLayer、atalupadhyay 三方一致):
| 模块 | 职责 | Claude Code 中的实现 |
|---|---|---|
| Loop | ReAct 主循环:reason → tool call → observe → repeat;终止条件 / 超时 / 用户中断 | 内置 agent loop,max_turns 可配 |
| State / Context | 消息历史 + token 预算 + compaction 策略 | 75% 自动 compact + Memory tool |
| Tool | 工具注册表 + schema + 执行沙箱 | 内置工具 + MCP server + Skill bash |
| Memory | 会话/项目级 append-only 日志 + flush/replay | CLAUDE.md + ~/.claude/projects/<id>/memory/ |
| Hook | 生命周期事件 pre/post 拦截 → 策略执行 | 12+ 事件,5 种 handler,PreToolUse 可硬拦 |
| Skill | Progressive disclosure 的领域知识包 | 三级懒加载(metadata / body / resources) |
| Observability | trace / replay / cost-latency 度量 | trace JSON + Anthropic Console |
关键判断:MCP 不是 Harness 的核心抽象(它是 Tool 层的一个 实现 选项),Slash Command 也不是(它是 Skill 的简化形式)。Harness 设计要回答的本质问题是:用户能扩展什么、不能扩展什么?
三、为什么 Devin / Claude Code 不用 LangGraph 而自研?
这是 2026 年最常被问的"反框架"问题,背后有四个硬约束:
1. Post-training Coupling(模型权重绑死工具签名)
OpenCode 团队在适配 Codex 模型时发现一个关键事实:Codex 模型在 post-training 阶段已经被 绑定 到 apply_patch 工具的语法(HumanLayer / Cline 同步证实)。要让 Codex 在自家 harness 里发挥水平,必须 模仿 Codex 的 apply_patch 签名。换句话说——模型对 harness 工具签名的"偏好"会被冻进权重。这就是"harness 不可随便换"的根本原因。
2. 延迟敏感(每步 < 100ms 是产品底线)
ReAct 主循环每步开销 < 100ms 是代码 Agent 体验的硬标准。LangGraph 的多层抽象(state graph 序列化 / checkpointer 写盘 / event bus)很难压到这个水位,对话感会变"卡"。
3. Hook / Sandbox 不可让渡
生产 Agent 必须:
- 拦截
rm -rf/git push --force这类 destructive command(Hook) - 隔离
apply_patch执行避免污染主机(Sandbox)
这两类能力是"开箱即用"还是"自己写",直接决定 Agent 能不能上生产。框架很难做到 opinionated 的 lifecycle hook + 多平台 sandbox。
4. Trace 数据是核心 IP
Harness 厂商把 trace 数据用来 fine-tune 自家模型(Claude Code 之于 Anthropic、Codex CLI 之于 OpenAI、Cline 之于 Cline.bot)。这些数据是"模型与 harness 协同进化"的飞轮,没人愿意走第三方框架把数据让出去。
实证数据:Terminal Bench 2.0 的「harness > 模型」杠杆
| 配置 | 排名 |
|---|---|
| Claude Opus 4.6 + 通用框架 | #33 |
| Claude Opus 4.6 + Claude Code | ~#5 |
| Claude Opus 4.7 + Cline CLI | 74.2%(超过 Claude Code 同模型 69.4%) |
HumanLayer 金句:"It's not a model problem. It's a configuration problem."
四、Framework vs Harness 的可视化对照
| 维度 | Framework(LangChain / CrewAI / Agents SDK) | Harness(Claude Code / Codex / Cline) |
|---|---|---|
| 给什么 | abstraction primitives | opinionated runtime |
| 你要做的 | 自己写 loop / memory / hook / sandbox | 只 customize 4 件事:system prompt、tools、context(CLAUDE.md / AGENTS.md)、subagents |
| 学习曲线 | "如何用框架 API" | "如何调 harness" |
| 适合 | custom 工作流编排 | 通用 Agent 任务 |
| 模型耦合 | 模型无关(理论上) | 模型耦合(post-training coupling) |
| 输出 | SDK 代码 | CLI / IDE 扩展 |
五、何时该用 Framework、Runtime、Harness?
按要造的东西选层:加 LLM 能力用 Framework,领域 Agent 加 Runtime,代码 Agent 直接套 Harness,做下一代 Harness 才自研。
2026-09 新形态:厂商托管 Harness。OpenAI 发布 Agents API(09-10),把驱动 Codex 的 harness 以托管云服务形式开放(编排、长会话、工具调用)。三层抽象的 Harness 层从「自己装配 / 套用现成产品」延伸出第三个选项——直接用厂商托管的 harness 基建;与之对照,Claude Agent SDK 走「harness 砖块 + 自装配」路线(见 #099)。选型问题从「造还是套」变成「造、套、还是托管」。
六、代码示例:感受 Harness 与 Framework 的"opinionated"差异
# Framework 风格(LangGraph):自己拼装一切
from langgraph.graph import StateGraph, END
from langgraph.checkpoint.sqlite import SqliteSaver
from typing import TypedDict
class AgentState(TypedDict):
messages: list
next_step: str
def reason_node(state):
# 自己决定怎么调 LLM、怎么解析输出、怎么决定下一步
...
return {"messages": state["messages"] + [...], "next_step": "tool"}
def tool_node(state):
# 自己实现工具调度、参数解析、错误处理
...
graph = StateGraph(AgentState)
graph.add_node("reason", reason_node)
graph.add_node("tool", tool_node)
graph.add_conditional_edges("reason", lambda s: s["next_step"])
# ... 你还要自己写: compaction / hook / sandbox / memory / observability
# Harness 风格(Claude Code,伪代码视角):只配置 + 启动
# 用户视角:在项目根放一个 CLAUDE.md + .claude/ 目录
#
# .claude/
# ├── settings.json # permission allowlist / hooks
# ├── hooks/
# │ └── pre-commit.sh # 必须每次跑的 lint
# ├── skills/
# │ └── testing/SKILL.md # 写测试时按需加载
# └── agents/
# └── reviewer.md # subagent 定义
#
# 然后:
# $ claude
# 即得到一个"懂你 repo、懂你工具、懂你流程"的代码 Agent
# loop / memory / sandbox / observability 全部 opinionated 内置
核心洞察:Framework 让你"造 Agent";Harness 让你"开 Agent"。Harness 的"opinionated default"反过来是约束,但也是让你少写 80% 基建代码的捷径。
七、前沿动向:Harness 本身成为优化对象(2026-08)
前面六节讲的都是"人怎么设计 harness"。2026-08 集中出现的一批论文把它推到了另一个位置:不再只是人工设计的对象,而是可被搜索、演化、甚至在线训练的优化对象。这不是对"harness 决定约七成实战表现"的推翻,恰恰相反——正因为杠杆在 harness 上,把优化力气花在这一层才划算。以下均为社区单次实验、尚无独立复现,引用时连出处与日期一起标注。
最硬的量化实证是 StateM(arXiv 2608.15089,2026-08-15)提出的 harness scaling(不动模型权重,只把模型外面那层运行时做厚:持久状态、阶段局部上下文、受检状态转移、可恢复 runbook、带版本的过程性实践):Terminal-Bench 2.1 上同一个 GPT-5.5 xhigh 从 83.1% 提升到 92.1%(论文标题最好成绩 95.3%)——模型是常量,涨的分全部来自 harness。
方法侧两条路线:DarwinX(arXiv 2608.07545)冻结权重只演化 prompt / 工具 / 技能 / 控制流,适应度由 benchmark 自带 verifier(判定通过与否的校验器)给出、不需要标准答案,并用 preserve-and-extend 契约(新变体必须保住老能力,导致回归的一律拒绝)防退步;AutoDesign(arXiv 2608.13560)让 meta-optimizer 指导 code agent 按 rollout(完整任务轨迹)反馈递归改写自身 harness。共同点:把工程师从 harness 调参循环里换了出去。同期概念外延也在扩张——EnvHarness 把 harness 思路从"包住模型"搬到"包住环境"、Zetta ζ 做在线演化的运行时 critic,详见参考资料。
| 维度 | 手工设计 harness(当前主流) | 自动搜索 / 演化 harness(本期方向) |
|---|---|---|
| 谁来改 | 人:读 trace、改 prompt、加工具 | 演化循环 / meta-optimizer 按 rollout 反馈自动改写 |
| 优化信号 | 工程师判断 + 离线跑分 | benchmark 自带 verifier 的通过/失败信号,不需标准答案 |
| 防退步机制 | 人工回归测试 + code review | preserve-and-extend 契约:导致回归的变体直接拒绝 |
| 可解释性 | 高,改动都是人写的 | 低,搜出来的 harness 未必讲得清为什么有效 |
| 成熟度 | 生产在跑(Claude Code / Codex / Cline) | 论文阶段,单次实验、未经复现 |
短期内生产系统仍是手工设计的天下——可解释性和可回滚性不可让渡。但 StateM 那 9 个百分点说明这层还有大量未被人工榨干的空间,DarwinX / AutoDesign 给出了"让机器去榨"的可行路径。面试里被问到"harness 的未来",这条线比"再加个工具"更值得讲。