什么是 Agent Harness？与 Framework / Runtime 三层抽象有何区别？

难度: 中级 🆕 2026 新增（Harness 主题）​

简短回答​

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 三方一致）：​

​

#rHeCIHcuDBXv text { white-space: pre; }#rHeCIHcuDBXv .fb0 { stroke: var(--N900-FG, 0.15); }#rHeCIHcuDBXv .fb0 {stroke: rgba(31,35,41, 0.15)}#rHeCIHcuDBXv .fx0 { stroke-miterlimit: 10; }#rHeCIHcuDBXv .fx0 {stroke-miterlimit: 10}#rHeCIHcuDBXv .fa1 { fill: rgb(187, 191, 196); }#rHeCIHcuDBXv .fa1 {fill: rgb(187, 191, 196)}#rHeCIHcuDBXv .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#rHeCIHcuDBXv .fx1 {font-style: normal}#rHeCIHcuDBXv .fx2 { text-anchor: middle; }#rHeCIHcuDBXv .fx2 {text-anchor: middle}#rHeCIHcuDBXv .fx3 { dominant-baseline: central; }#rHeCIHcuDBXv .fx3 {dominant-baseline: central}#rHeCIHcuDBXv .fx4 { stroke: none; }#rHeCIHcuDBXv .fx4 {stroke: none}#rHeCIHcuDBXv .fc0 { fill: var(--text-caption); }#rHeCIHcuDBXv .fc0 {fill: #646a73}#rHeCIHcuDBXv .fa2 { fill: var(--text-link-disabled); }#rHeCIHcuDBXv .fa2 {fill: rgb(187, 191, 196)}#rHeCIHcuDBXv .fx5 { font: 400 16px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#rHeCIHcuDBXv .fx5 {font-style: normal}#rHeCIHcuDBXv .fx6 { text-anchor: start; }#rHeCIHcuDBXv .fx6 {text-anchor: start}#rHeCIHcuDBXv .fx7 { dominant-baseline: alphabetic; }#rHeCIHcuDBXv .fx7 {dominant-baseline: alphabetic}#rHeCIHcuDBXv .fc1 { fill: rgb(31, 35, 40); }#rHeCIHcuDBXv .fc1 {fill: rgb(31, 35, 40)}#rHeCIHcuDBXv .fx8 { font: 400 13px LarkHackSafariFont, LarkEmojiFont, ui-monospace, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Helvetica, "Noto Sans", Tahoma, "Nimbus Sans L", Arial, "Liberation Sans", "PingFang SC", "Hiragino Sans GB", "Noto Sans CJK SC", "Source Han Sans SC", "Source Han Sans CN", "Microsoft YaHei", "Wenquanyi Micro Hei", "WenQuanYi Zen Hei", STHeiti, SimHei, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji", system-ui; }#rHeCIHcuDBXv .fx8 {font-style: normal}#rHeCIHcuDBXv .fb1 { fill: var(--N900-FG, 0.15); }#rHeCIHcuDBXv .fb1 {fill: rgba(31,35,41, 0.15)}#rHeCIHcuDBXv .fb2 { fill: rgb(209, 217, 224); }#rHeCIHcuDBXv .fb2 {fill: rgb(209, 217, 224)}#rHeCIHcuDBXv .fa3 { fill: var(--bg-body); }#rHeCIHcuDBXv .fa3 {fill: #fff}ABC12345678模块LoopState / ContextToolMemoryHookSkillObservability职责ReAct 主循环：reason → tool call → observe → repeat；终止条件 / 超时 / 用户中断消息历史 + token 预算 + compaction 策略工具注册表 + schema + 执行沙箱会话/项目级 append-only 日志 + flush/replay生命周期事件 pre/post 拦截 → 策略执行Progressive disclosure 的领域知识包trace / replay / cost-latency 度量Claude Code 中的实现内置 agent loop，max_turns 可配75% 自动 compact + Memory tool内置工具 + MCP server + Skill bashCLAUDE.md + 12+ 事件，5 种 handler，PreToolUse 可硬拦三级懒加载（metadata / body / resources）trace JSON + Anthropic Console~/.claude/projects//memory/

​

关键判断：MCP 不是 Harness 的核心抽象（它是 Tool 层的一个 实现 选项），Slash Command 也不是（它是 Skill 的简化形式）。Harness 设计要回答的本质问题是：用户能扩展什么、不能扩展什么？​

三、为什么 Devin / Claude Code 不用 LangGraph 而自研？​

这是 2026 年最常被问的"反框架"问题，背后有四个硬约束：​

Post-training Coupling（模型权重绑死工具签名）​

OpenCode 团队在适配 Codex 模型时发现一个关键事实：Codex 模型在 post-training 阶段已经被 绑定 到 apply_patch 工具的语法（HumanLayer / Cline 同步证实）。要让 Codex 在自家 harness 里发挥水平，必须 模仿 Codex 的 apply_patch 签名。换句话说——模型对 harness 工具签名的"偏好"会被冻进权重。这就是"harness 不可随便换"的根本原因。​

延迟敏感（每步 < 100ms 是产品底线）​

ReAct 主循环每步开销 < 100ms 是代码 Agent 体验的硬标准。LangGraph 的多层抽象（state graph 序列化 / checkpointer 写盘 / event bus）很难压到这个水位，对话感会变"卡"。​

Hook / Sandbox 不可让渡​

生产 Agent 必须：​

•

拦截 rm -rf / git push --force 这类 destructive command（Hook）​

•

隔离 apply_patch 执行避免污染主机（Sandbox）​

这两类能力是"开箱即用"还是"自己写"，直接决定 Agent 能不能上生产。框架很难做到 opinionated 的 lifecycle hook + 多平台 sandbox。​

Trace 数据是核心 IP​

Harness 厂商把 trace 数据用来 fine-tune 自家模型（Claude Code 之于 Anthropic、Codex CLI 之于 OpenAI、Cline 之于 Cline.bot）。这些数据是"模型与 harness 协同进化"的飞轮，没人愿意走第三方框架把数据让出去。​

实证数据：Terminal Bench 2.0 的「harness > 模型」杠杆​

​

表格加载中...

​

HumanLayer 金句："It's not a model problem. It's a configuration problem."​

四、Framework vs Harness 的可视化对照​

​

表格加载中...

​

五、何时该用 Framework、Runtime、Harness？​

​

​

按要造的东西选层：加 LLM 能力用 Framework，领域 Agent 加 Runtime，代码 Agent 直接套 Harness，做下一代 Harness 才自研。​

六、代码示例：感受 Harness 与 Framework 的"opinionated"差异​

​

代码块​

Python

# 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​

​

核心洞察：Framework 让你"造 Agent"；Harness 让你"开 Agent"。Harness 的"opinionated default"反过来是约束，但也是让你少写 80% 基建代码的捷径。​

常见误区 / 面试追问​

•

误区 1：「Harness 就是另一种框架」 — 表面上都是"模型外面的代码"，但本质完全不同。Framework 是"unopinionated 积木箱"，需要你自己拼装 loop / memory / hook；Harness 是"opinionated 装配好的车"，loop / memory / hook 全部内置，你只能在框架预留的扩展点（CLAUDE.md / Hook / Skill / Subagent）做定制。换言之，Framework 给自由 + 责任，Harness 给约束 + 默认值。​

•

误区 2：「自研 Harness 是过度设计，直接用 LangGraph 就行」 — 对一般业务系统确实是过度设计，但对"代码 Agent / 通用电脑 Agent"这类需要 opinionated default + post-training coupling 的产品，框架抽象层会成为天花板。Devin / Claude Code / Codex / Cline 这些 SOTA 产品全部自研 harness 不是偶然。​

•

误区 3：「换模型不需要换 harness」 — Post-training coupling 让模型与 harness 形成深度绑定。Codex 模型脱离 apply_patch 签名性能会掉，Claude Sonnet 在 Claude Code 与在通用 chat 中表现是两个性格。模型与 harness 是一对深度耦合的系统。​

•

追问 1：「LangChain / OpenAI Agents SDK 算 Framework 还是 Harness？」 → 答：都是 Framework（LangChain 自家文档明确）。判断标准：是否给出 opinionated 默认 prompt + tool + sandbox + hook 全套？是否拿来就能跑出一个"有性格的 Agent"？LangChain / Agents SDK 不给默认 prompt 与默认 tool，所以是 Framework。DeepAgents（LangChain 2025-11 推出的 harness）才算 Harness。​

•

追问 2：「Harness 与 SDK 是什么关系？」 → 答：SDK 是"客户端库"层面的概念（OpenAI Agents SDK、Claude Agent SDK），描述的是"如何调用 API 的 Python/TS 类库"；Harness 是"应用形态"层面的概念，描述的是"装配好的 Agent 产品"。Claude Code = harness，但底层用 Claude Agent SDK；Cursor = harness，底层有自家 Composer SDK。SDK 是 harness 的实现砖块之一。​

•

追问 3：「『Harness > 模型』杠杆数据点出自哪里？怎么验证？」 → 答：出自 Terminal Bench 2.0（2026-Q1）。同一个 Claude Opus 4.6 在不同 harness 中跑分差距 28 个排名位次。可参考 Artificial Analysis 的 Coding Agents Leaderboard 持续追踪。这背后的机制是：harness 的 system prompt + tool 选择 + context 工程 + retry 策略 + sandbox 隔离五者协同作用，对单步 ReAct 的正确率有乘法效应。​

•

追问 4：「Cline SDK 2026-05 为什么把 runtime 从 IDE 剥离？这意味着什么？」 → 答：意味着 Harness 进入"runtime 独立化"阶段。@cline/sdk 把 agent loop 从 VS Code 插件里彻底拆出，可在 CLI / Web / CI 任意 surface 上调用。这预示 2026-2027 行业方向：Harness 从"单一产品形态"演化为"runtime + 多 surface 适配器"——同一份 agent runtime 跑 IDE、跑终端、跑 CI、跑 Kanban。​

参考资料​

•

LangChain Blog — Agent Frameworks, Runtimes, and Harnesses — 三层抽象的官方定义出处​

•

Parallel.ai — What Is an Agent Harness? — "everything except the LLM itself" 经典定义 + 70% 性能数据点​

•

HumanLayer — Skill Issue: Harness Engineering for Coding Agents — "It's not a model problem. It's a configuration problem." 出处 + Post-training coupling 详解​

•

Addy Osmani — Agent Harness Engineering — Harness 6+1 抽象 + Ralph Loop / Sprint Contracts 高级模式​

•

Cline Blog — Introducing the Cline SDK — 2026-05 Runtime 与 IDE 解耦范式​

•

atalupadhyay — The Agent Harness: What It Is, Why It Matters — 从零构建 harness 的工程视角​

•

Anthropic — Equipping Agents for the Real World with Agent Skills — Progressive Disclosure 与 Harness 中 Skill 抽象的关系​

•

Artificial Analysis — Coding Agents Leaderboard — Terminal Bench 实时排行，「Harness > 模型」杠杆的持续证据​