Agent Harness，这篇104页的综述终于把它定义清楚了

现在聊 Agent，很难绕开一个词：Harness。

有一种说法很有意思：对于 Agent 来说，除了 model 以外，其他东西几乎都可以算 Harness。

这句话不一定严格，但它抓住了一个关键变化。过去我们讨论 Agent，经常把注意力放在模型能力上：规划够不够强，工具调用准不准，记忆能不能长程保持，多轮任务会不会跑偏。

这些问题当然重要。

但当 Agent 真正进入工程系统以后，问题会变得更具体：模型能看到什么上下文，能调用哪些工具，调用失败后怎么恢复，任务状态怎么保存，危险动作怎么拦截，执行过程怎么评估。

这些东西都在模型外面，却直接决定 Agent 最后的可靠性。

也正因为如此，大家都在说 Harness，但这个词一直有点模糊。工具调用算 Harness 吗？Memory 算吗？评估算吗？安全策略算吗？如果一个 Agent 效果不好，我们到底应该从哪个模块开始优化？

最近这篇 104 页的综述《Agent Harness for Large Language Model Agents: A Survey》做的事情，就是尝试把这个边界画清楚。

论文把 Agent Harness 定义为一个由六个组件组成的运行时基础设施：

H = (E, T, C, S, L, V)

分别是 Execution Loop、Tool Registry、Context Manager、State Store、Lifecycle Hooks 和 Evaluation Interface。

这篇论文目前最新公开版本是 Preprints.org v3，发布时间是 2026 年 4 月 28 日，页面明确标注为 preprint，还没有经过同行评审。所以我不会把它当成最终行业标准。

但它提供了一张很有价值的工程地图。

以后我们优化自己的 Agent 时，可以不再笼统地说“Agent 不稳定”或者“Harness 需要加强”，而是分组件去看：

1. 是执行循环没有收敛？
2. 是工具设计太宽？
3. 是上下文组织不清楚？
4. 是状态不可恢复？
5. 是安全拦截缺失？
6. 是评估轨迹不可观测？

更重要的是，这六个组件不是彼此孤立的。很多真实问题都发生在组件协同处。

比如工具调用失败，表面看是 T 的问题，但也可能是 C 没给够工具文档和业务上下文，E 的重试策略又只是重复错误动作，V 也没有记录完整失败轨迹。

所以这篇文章不是想把 Harness 拆成六个静态模块，而是借这六个模块，建立一套更清晰的 Agent 工程优化方式。

1. 一个真实 Agent 为什么会失败？

先看一个很典型的 Agent 任务。

用户说：

帮我修一下这个仓库里的测试失败问题，跑通以后提一个 PR。

从模型能力角度看，这个任务包括理解需求、阅读代码、定位失败、修改文件、运行测试、分析报错、继续迭代。

但放到真实执行环境里，它马上会变成一组系统问题：

1. 模型能不能拿到正确的仓库上下文？
2. 它应该先读哪些文件，而不是把整个仓库塞进窗口？
3. 它能调用哪些命令，权限边界在哪里？
4. 测试失败以后，错误信息如何结构化回传？
5. 执行到一半中断，任务状态能不能恢复？
6. 它要执行危险命令时，系统有没有硬拦截？
7. 最后如何判断它真的修好了，而不是只改了表面？

这些问题并不能完全靠“换一个更强模型”解决。

模型负责生成判断和动作，但这些动作能不能在真实系统里稳定发生，取决于外层运行时。

这就是 Harness 的位置：它不是模型的简单包装，而是模型能力转化为系统行为的中间层。

如果没有这层基础设施，Agent 很容易停留在 Demo。它可能偶尔能跑通，但难以被治理、复盘和持续优化。

2. 论文给出的定义：H = (E, T, C, S, L, V)

论文给出的形式化定义是：

H = (E, T, C, S, L, V)

对应六个组件：

E: Execution Loop        执行循环
T: Tool Registry         工具注册表
C: Context Manager       上下文管理器
S: State Store           状态存储
L: Lifecycle Hooks       生命周期钩子
V: Evaluation Interface  评估接口

可以把它理解成 Agent 的运行时底盘。

模型负责思考和生成动作，Harness 负责让这些动作在真实环境里可控、可恢复、可观测地发生。

图源：Agent Harness for Large Language Model Agents: A Survey。

这六个组件的价值，不在于概念完整，而在于它们分别对应生产环境里最常见的失败模式。

下面逐个看。

3. 六组件不是目录，而是六类失败模式

E：执行循环，解决失控问题

普通 LLM 调用通常是一次性的：

输入 -> 模型 -> 输出

Agent 不一样，它会循环执行：

观察环境 -> 思考 -> 选择动作 -> 执行动作 -> 观察新结果 -> 继续思考

这就是 Execution Loop。

只要有循环，就会有失控风险：

1. 工具调用失败后无限重试。
2. 反复读同一个文件。
3. 任务已经不可完成，但循环没有退出条件。
4. 模型不断扩展任务边界，越做越偏。

论文用 labeled transition system 这类形式化语言描述执行循环，本质上强调两件事：

1. Safety：系统不能进入危险或不可恢复状态。
2. Liveness：系统最终应该能到达某种终止状态。

从工程视角看，这里要落到更直接的设计：

1. 最大步数。
2. 最大耗时。
3. 最大 token。
4. 失败重试上限。
5. 人工确认节点。
6. 明确的终止条件。

如果没有这些边界，Agent 看起来是在自主执行，实际只是把风险交给了循环。

T：工具注册表，解决动作空间过大的问题

Agent 一旦接入工具，就不再只是生成文本。

它可以查数据库、发请求、改文件、跑命令、调内部 API。这个时候，Tool Registry 就变成了治理核心。

一个好的工具注册表至少要回答四个问题：

1. 工具有哪些，名称和语义是否清楚。
2. 参数 schema 是否严格。
3. 工具权限是否按任务范围收敛。
4. 工具调用失败后，错误是否结构化返回。

很多工具调用失败，不是模型完全不会用工具，而是工具设计本身给了模型过大的动作空间。

比如有两个选择。

第一种是给模型一个万能工具：

run(command: string)

第二种是提供更窄、更可验证的工具：

run_tests(target: string, timeout_seconds: int)
read_file(path: string, start_line: int, end_line: int)
edit_file(path: string, patch: string)

前者自由度很高，但治理难度也很高。后者牺牲了一部分自由度，却换来了更清晰的参数边界、权限边界和错误反馈。

但这里有一个很明确的 trade-off。

工具边界越粗，模型越自由，系统越难治理。一个 run(command: string) 看起来什么都能做，但权限边界、参数语义、错误类型和审计粒度都很模糊。

工具边界越细，系统越可控，但工具数量也会变多。工具一多，模型就要在更多候选项里做选择，容易出现选错工具、混淆参数、重复调用，甚至调用不存在工具的问题。

所以生产系统里的工具设计，不应该简单追求“工具越多越强”，也不应该只追求“工具越细越安全”。更合理的做法是分层设计。

1. 高频核心动作做成窄工具。 比如 read_file、run_tests、execute_sql、query_metadata，这些工具参数明确、返回稳定、权限容易控制。
2. 低频复杂动作保留组合空间。 不要把每一种业务变体都拆成一个新工具，否则工具列表会膨胀，模型选择成本会变高。
3. 工具 schema 要严格，但不要过度复杂。 参数应该有类型、枚举、必填项和约束；但如果 schema 本身过深、分支太多，模型仍然容易填错。
4. 工具描述要写清楚“什么时候用”和“什么时候不用”。 工具名只解决识别问题，描述才真正影响模型选择。
5. 不要一次性把所有工具都塞给模型。 更好的方式是根据任务阶段、权限、上下文动态暴露工具，让模型只在当前相关的工具集合里选择。
6. 工具错误要结构化返回。 工具失败时不要只返回一段自然语言报错，而要告诉模型是参数错误、权限错误、资源不存在、执行超时，还是业务规则不允许。

所以，工具设计的核心不是“给 Agent 更多能力”，而是给 Agent 一个足够表达任务、但不会让它迷路的动作空间。

这也是 Tool Registry 在 Harness 里的价值。

它不是一个简单的 API 列表，而是一个经过治理的动作空间。好的 Tool Registry 要同时控制三件事：模型能做什么、什么时候能做、做错以后如何恢复。

这也是 Harness Engineering 和 Prompt Engineering 的区别。

Prompt Engineering 试图用文字告诉模型“不要乱来”。Harness Engineering 则在工具层设计它到底能做什么、不能做什么、做错了怎么反馈。

C：上下文管理，解决信息组织问题

很多长任务失败，看起来是模型忘了前面做过什么。

但更准确地说，这是上下文管理失败。

Context Manager 要解决的问题，不是“怎么把更多内容塞进模型”，而是：

1. 当前这一步最需要哪些信息？
2. 哪些历史记录应该保留，哪些应该压缩？
3. 哪些信息应该从代码、文档、日志、数据库里检索出来？
4. 哪些信息虽然相关，但会干扰模型判断？
5. 长上下文模型来了以后，注意力稀释怎么处理？

这里有一个常见误区：以为长上下文可以解决上下文管理。

长上下文只是扩大了输入容量，不等于完成信息组织。上下文越长，越需要 Harness 告诉模型重点在哪里。

以代码 Agent 为例，一个比较实用的方式是渐进式暴露上下文：

1. 根目录只放短的导航说明，比如 AGENTS.md 或 README。
2. 复杂设计放到 docs/。
3. 任务相关信息按需检索。
4. 测试失败、日志、diff 单独结构化注入。
5. 历史对话定期总结，而不是原样堆叠。

这件事的本质是：不要让模型在一堆原始材料里找重点，而是让 Harness 先把信息整理成适合决策的形态。

S：状态存储，解决长任务中断和恢复问题

短任务可以只靠上下文。

长任务必须有状态。

比如一个 Agent 要完成一次代码迁移，可能需要几十轮操作：

1. 扫描旧接口。
2. 生成迁移计划。
3. 修改第一批模块。
4. 跑测试。
5. 记录失败项。
6. 继续修改第二批模块。
7. 汇总风险。
8. 生成 PR 描述。

如果所有状态都只存在上下文里，一旦窗口被截断，或者进程重启，Agent 就会丢失任务进度。

所以 State Store 保存的不应该只是聊天记录，还应该包括结构化执行状态：

task_id
current_goal
completed_steps
pending_steps
changed_files
test_results
known_failures
approval_records
rollback_points

这里最关键的是两个工程词：幂等和原子。

幂等，意味着同一个状态写入重复执行，不应该造成不一致。

原子，意味着一次关键状态更新要么完整成功，要么完整失败，不能写一半。

如果一个 Agent 在“已经执行动作但还没记录状态”的瞬间崩溃，后续恢复会非常麻烦。

生产级 Agent 不能只考虑“下一步怎么做”，还要考虑“中断以后怎么继续”。

L：生命周期钩子，解决危险动作拦截问题

Lifecycle Hooks 可以理解成 Agent 执行过程中的拦截器。

它不一定改变模型输出，但可以在关键节点做治理：

1. 工具调用前做权限检查。
2. 文件修改前检查路径范围。
3. 外部请求前检查域名和凭据。
4. 高风险命令执行前要求人工确认。
5. 工具调用后记录审计日志。
6. 任务结束前检查证据是否齐全。

这层很重要，因为 Agent 的安全问题和普通聊天模型不一样。

普通模型的风险主要体现在输出内容上。Agent 的风险体现在动作上。

模型生成一句危险建议，和模型真的拿到 shell 权限执行危险命令，是两个级别的问题。

所以安全策略不能只写在 prompt 里。

Prompt 里的规则是软约束。Lifecycle Hooks 才能提供硬约束。

一个简单原则是：凡是可能改变外部世界的动作，都应该经过 Harness 层的策略判断，而不是完全交给模型自觉。

V：评估接口，解决不可观测问题

很多 Agent 项目最后都会遇到一个尴尬问题：

它到底为什么失败？

如果只有一段自然语言日志，或者一长串聊天记录，很难复盘。

Evaluation Interface 要做的不是简单打分，而是把执行轨迹结构化：

{
  "task_id": "fix-test-001",
  "steps": [
    {
      "type": "tool_call",
      "tool": "run_tests",
      "input": {"target": "tests/unit"},
      "output": {"status": "failed", "summary": "..."}
    },
    {
      "type": "file_edit",
      "path": "src/parser.ts",
      "summary": "adjust null handling"
    }
  ],
  "final_status": "success",
  "evidence": ["test_log", "git_diff"]
}

这样做有三个直接价值。

第一，可以复盘失败路径。到底是上下文缺失、工具误用、测试环境问题，还是模型判断错误。

第二，可以比较不同 Harness。否则我们测到的不是模型能力，而是“模型 + Harness + 环境”的混合性能。

第三，可以形成评测飞轮。失败样本进入分析，分析结果反过来改进工具、上下文、钩子和状态管理。

这里要区分 L 和 V。

L 是为了管住 Agent，V 是为了看清 Agent。

一个负责拦截，一个负责观测。两者都重要，但不能混在一起。

4. 这篇综述真正有用在哪里？

这篇综述最有价值的地方，不是提出了一个全新技术，而是把很多零散工程经验整理成了统一语言。

过去我们也会说“优化 Harness”，但这个说法太粗。

到底是优化执行循环，还是优化工具注册？是优化上下文，还是优化状态恢复？是补安全钩子，还是补评估轨迹？

如果没有组件化定义，很多讨论最后都会落回一句话：

这个 Agent 的工程做得还不够好。

这句话没错，但不指导行动。

过去讨论 Agent，经常按能力拆：

1. Planning
2. Tool Use
3. Memory
4. Reflection
5. Multi-Agent

这些都是能力模块。

Harness 的视角不一样，它关心这些能力模块如何被组织成可运行系统。

比如 Memory，如果只从模型能力看，问题是“怎么记忆”。放到 Harness 里，问题会变成：

1. 谁有权限写入记忆？
2. 写入内容是否需要校验？
3. 记忆能不能跨会话污染系统？
4. 检索结果如何注入上下文？
5. 删除、过期、审计怎么做？

Tool Use 也是一样。

只讲工具调用能力，关注的是模型能不能选对工具。放到 Harness 里，问题会变成：

1. 工具 schema 怎么设计？
2. 工具权限怎么收敛？
3. 工具返回怎么结构化？
4. 工具链组合会不会造成越权？
5. 调用证据怎么进入评估接口？

这就是“组件能力”和“系统基础设施”的差别。

有了 H = (E, T, C, S, L, V) 以后，优化方向会清楚很多。

比如一个工具调用失败问题，至少可能有四种解释：

1. T 的工具 schema 设计太宽，模型不知道怎么填参数。
2. C 没有把工具文档、业务上下文或历史错误传给模型。
3. E 的重试策略太粗，失败后只会重复同一个错误动作。
4. V 没有记录完整轨迹，导致后续复盘只能猜。

所以组件化不是为了把系统割裂，而是为了让优化更有的放矢。

5. 从 Prompt Engineering 到 Harness Engineering

如果把过去几年的 Agent 工程简单划分，可以看到一条路径。

第一阶段是 Prompt Engineering。

大家主要优化一段输入文本，研究如何让模型按某种格式思考、回答、调用工具。

第二阶段是 Context Engineering。

问题从“怎么写 prompt”变成“模型每一步应该看到什么”。RAG、长上下文、记忆压缩、上下文路由、任务摘要，都是这个阶段的典型工作。

第三阶段就是 Harness Engineering。

问题继续上升一层：

如何设计一个可控、可观测、可恢复、可评估的运行时，让 Agent 能在真实环境里稳定执行任务？

这不是否定 Prompt，也不是否定 Context。

相反，Prompt 和 Context 都变成了 Harness 的一部分。

Prompt 是策略表达的一部分。

Context 是信息调度的一部分。

Tool、State、Hook、Evaluation 则共同决定这个系统能不能进入生产环境。

6. 工程团队可以怎么用这张图？

如果你正在做 Agent 系统，我建议不要一上来就问“要不要换更强模型”，也不要笼统地说“优化 Harness”。

更有效的做法，是把 H = (E, T, C, S, L, V) 当成一张架构体检表。

它不是告诉你“系统里有哪些组件”，而是帮你把模糊的失败，拆成可操作的排查路径。

可以按下面这张表来用：

失败现象	优先检查	关键问题	优化方向
Agent 一直循环，停不下来	E + V	是否缺少终止条件，失败轨迹是否可见	设置最大步数、超时、重试上限，并记录每轮失败原因
工具经常选错或参数填错	T + C	工具语义是否清楚，上下文是否给到选择依据	收窄高频工具，强化 schema，把“什么时候不用”写进工具描述
生成结果看似合理，但不可执行	C + T	业务口径、环境约束和错误反馈是否进入下一轮	注入字段解释、权限范围、历史错误和结构化执行结果
任务中断后无法继续	S + E	状态是否只存在对话里	持久化目标、进度、中间产物、失败项和恢复点
安全规则只能靠模型自觉	L + T	危险动作有没有经过硬拦截	把权限、审批、脱敏、扫描量限制放到执行链路里
失败后只能靠猜	V + 全组件	是否记录了输入、动作、工具结果和最终证据	建结构化轨迹，把失败样本沉淀成评测数据

所以真正的使用方式不是“逐项打勾”，而是三件事：

1. 先看症状，不先换模型。 Agent 到底是失控、误用工具、忘上下文、状态丢失、安全失守，还是不可观测。
2. 再定位组件，不把 Harness 当成一句空话。 每类失败都要能落到 E、T、C、S、L、V 里的一个或几个组件。
3. 最后检查协同，不把单点优化当成系统治理。 工具调用失败可能同时依赖工具描述、上下文注入、执行重试和评估轨迹。

这也是为什么我更愿意把 H = (E, T, C, S, L, V) 称为优化地图，而不是组件清单。组件清单告诉你系统里有什么，优化地图告诉你出了问题应该先看哪里。

7. 落到业务系统里，Harness 应该怎么建？

最后看一个更接近业务系统的例子：企业数据分析 Agent。

它经常被理解成“自然语言生成 SQL”。但如果只从 Text2SQL 看，就会低估这件事的工程难度。

对于企业级数据分析 Agent 来说，真正难的不是让模型写出一条看起来像 SQL 的语句，而是让这条 SQL 在正确的数据上下文、正确的权限边界、正确的执行环境和正确的审计链路里被生成、执行、修正和复盘。

这恰好是 Harness 问题。

这里以数据库研发治理平台为例，看看 H = (E, T, C, S, L, V) 怎么落到业务系统里。

先给一个收敛后的任务边界：

维度	设计
输入	一个自然语言数据分析问题
输出	SQL、图表、解释和证据
工具	元数据查询、SQL 执行、样例 SQL 检索、图表生成
限制	只读数据库，不允许写入生产表
评估	SQL 是否可执行、结果是否符合口径、解释是否引用字段

然后把这个任务映射到 Harness。

Harness 组件	在数据分析 Agent 里的问题	平台可以沉淀的差异化
E 执行循环	问题提出后，SQL 如何生成、执行、报错修正、解释结果	把循环放进受治理的数据研发链路，而不是让 Agent 自由访问所有数据源
T 工具注册表	Agent 能调用哪些数据能力	元数据查询、SQL 执行、风险识别、权限校验、脱敏、工单、历史 SQL，都可以包装成 typed tools
C 上下文管理	模型生成 SQL 时应该看到什么	表结构、字段注释、指标口径、历史 SQL、权限范围、审核规则、执行错误
S 状态存储	多轮分析中，进度和中间结果如何保存	记录问题、SQL、执行结果、改写原因、触发规则和用户采纳情况
L 生命周期钩子	哪些动作必须被硬拦截	查询前鉴权、执行前 SQL 风险识别、敏感字段脱敏、扫描量限制、高风险审批
V 评估接口	如何判断 Agent 到底哪里做得不好	把生成、执行、修正、采纳、驳回沉淀成评测样本和优化闭环

这张表里最关键的是 T、C、L 三层。

T 决定 Agent 能做什么。普通 Agent 应用往往是临时接几个 API，但数据库研发治理平台本身就有数据库连接、元数据、SQL 执行、审批、审计这些能力。真正的 Harness 化，是把这些能力包装成边界清晰、参数可校验、返回稳定的工具。

C 决定 Agent 看见什么。数据分析 Agent 的上下文不是几张表的 DDL，而是字段含义、指标口径、历史 SQL、权限范围、审核规则和执行错误。模型负责生成 SQL，C 组件负责告诉模型：在这个企业里，什么 SQL 才是有业务含义、可执行、可治理的 SQL。这也是企业级数据分析 Agent 可以做得最厚的地方，也是核心差异化的体现。

L 决定 Agent 不能越过什么边界。很多系统会把安全规则写进 prompt，比如“不要查询敏感字段”“不要执行高风险 SQL”。但 prompt 只是软约束。企业数据库场景里，这些规则必须变成 Harness 层的硬约束：查询前鉴权、执行前审核、敏感字段脱敏、扫描量限制、高风险操作进入审批流。

做到这里，Agent 才开始像一个可治理的业务系统，而不是一个套了工具调用的聊天框。

所以，从数据库研发治理平台视角看，数据分析 Agent 的竞争力不只在模型能不能写 SQL，而在于平台能不能把已有的数据研发治理能力，系统性地组织成 Agent Harness。

真正的差异化落在 Harness 层：工具是受治理的，上下文是企业长期沉淀的，执行是有边界的，状态是可恢复的，动作是可审计的，结果是可评估的。

8. 这篇论文也有边界

需要强调的是，这篇综述目前是 preprint，不是已经完成同行评审的定论。

另外，Agent Harness 这个方向本身还很新，很多工业界最成熟的 Harness 都是内部系统，公开资料并不完整。

因此，论文里的系统分类和完整性矩阵，更多是基于公开文档、论文、博客和代码仓库做出的结构化整理。

读这篇论文时，可以保持两层判断。

第一层，可以接受它的框架价值。H = (E, T, C, S, L, V) 确实是一个很好的工程检查表。

第二层，不要把所有数字和横向比较当成最终事实。特别是涉及某个系统“最完整”“工业界天花板”这类判断，需要回到原始资料和实际场景验证。

换句话说，这篇综述适合拿来建立架构语言，不适合直接拿来做比较逻辑。

我们要吸取这里面分六个部分拆解优化的思维，同时又要意识到Agent Harness本身就是一个有机的整体，单纯从一个方面入手是做不好的。

9. 总结

Agent Harness 这个概念真正重要的地方，是把一个大家都在说、但边界一直有点模糊的词，变成了一套可以讨论、可以拆解、可以优化的组件框架。

模型能力仍然重要，但对于一个真正跑起来的 Agent 系统来说，只讨论模型是不够的。

一个生产级 Agent 至少要同时回答六个问题：

1. 它如何循环执行？
2. 它能调用哪些工具？
3. 它每一步能看到什么上下文？
4. 它的任务状态如何持久化？
5. 它的危险动作如何被拦截？
6. 它的执行轨迹如何被评估？

这六个问题对应的就是 H = (E, T, C, S, L, V)。

这个框架最大的实用价值，是让我们后续优化自己的 Agent 时，不再只说“效果不好”或者“Harness 需要加强”，而是可以更具体地判断：

1. 是 E 的执行循环需要收敛。
2. 是 T 的工具设计需要重新抽象。
3. 是 C 的上下文组织需要更精细。
4. 是 S 的状态恢复能力不够。
5. 是 L 的安全和策略拦截缺失。
6. 是 V 的轨迹记录和评估接口不完整。

但也要注意，这六个组件不是独立优化就完事了。

Agent 最后表现出来的可靠性，来自这些组件之间的协同。上下文会影响工具选择，工具结果会进入状态，状态会影响下一轮执行，生命周期钩子会改变动作空间，评估接口又会反过来指导下一轮优化。

所以，H = (E, T, C, S, L, V) 不是一个静态分类表，而是一张 Agent 工程优化地图。

这也是这篇综述最值得读的地方：它终于给 Agent Harness 这个被频繁使用、但一直不够清晰的概念，提供了一个相对完整的定义。

相关资源

1. Qianyu Meng et al., Agent Harness for Large Language Model Agents: A Survey, Preprints.org v3, posted 2026-04-28: https://www.preprints.org/manuscript/202604.0428
2. Sciety article activity page for v2, DOI 10.20944/preprints202604.0428.v2: https://sciety.org/articles/activity/10.20944/preprints202604.0428.v2
3. GloriaaaM / LLM-Agent-Harness-Survey dataset page: https://huggingface.co/datasets/GloriaaaM/LLM-Agent-Harness-Survey
4. Engineering.fyi mirror of Ryan Lopopolo, Harness engineering: leveraging Codex in an agent-first world: https://www.engineering.fyi/article/harness-engineering-leveraging-codex-in-an-agent-first-world