结论先行:Agent Harness(智能体运行时)是模型之外的全部工程——上下文装配、工具执行循环、权限与沙箱、状态管理、可观测性。同一个模型,配不同的 harness,产出质量可以差出一个量级。对后端工程师来说这是个熟悉的故事:模型是发动机,harness 才是整车,用户买的是车不是发动机。
Harness 到底包含什么
拆开任何一个成熟的 Agent 产品(Claude Code、Cursor、各家内部平台),harness 大致由五部分组成:
- 上下文装配:system prompt、项目说明书(AGENTS.md)、记忆检索结果、历史消息裁剪,每轮请求前动态拼装。模型自己不知道你的项目长什么样,是 harness 把这些信息喂进去的。装配策略决定了模型的"视野":塞什么、塞多少、按什么顺序塞,每一步都有讲究——前缀是否逐字节稳定关系到 prompt 缓存命中,内容相关度关系到模型注意力的分配,该外置的放磁盘还是该塞窗口,是每个 harness 都要回答的问题。
- 工具执行循环:核心是一个 while 循环——模型返回工具调用就执行,把结果拼回上下文再请求,直到模型给出最终回答。循环里的重试、超时、输出截断都是 harness 的活。这个循环的健壮性直接决定长任务成功率:一次工具执行抛异常没有被捕获,整个任务就地中断;一次下游工具慢了没有超时,用户面对的是无限转圈。
- 权限与沙箱:哪些命令能直接跑、哪些要人工确认、哪些在隔离环境里跑。这是 Agent 能不能被放进生产流程的前提——没有权限层的 Agent 只能跑在开发者本机的注视下,进不了 CI,更进不了生产。
- 状态管理:会话恢复、任务清单、跨轮次记忆。没有持久化的 Agent 每次都是失忆的新员工——会话一断,前面探索过的所有结论全部作废,同样的 token 再花一遍。
- 可观测性:每次 LLM 调用的 token 消耗、每次工具调用的输入输出,落盘可回放。出了问题靠它归因,月底成本靠它解释,权限规则演进靠它提供证据。
这五部分没有一样涉及模型权重本身,但每一项做得深浅都直接体现在产出质量上。工程上有个朴素的观察:Agent 项目的失败复盘里,归因到"模型不够聪明"的比例远低于归因到这五件事没做好的比例。
一个最小 Harness 的骨架
去掉所有产品化包装,核心循环其实很短。先看错误写法——网上大量教程级的 Agent 代码长这样:
# 错误写法:裸循环,三处裸奔
messages = [system_prompt, user_task]
while True:
resp = llm.chat(messages, tools=TOOL_SCHEMAS)
if resp.stop_reason != "tool_use":
break
for call in resp.tool_calls:
result = execute_tool(call) # 没有权限闸门:rm -rf 会被直接执行
messages.append(tool_result(
call.id, result # 没有截断:一次 cat 大文件撑爆上下文
))
# 没有压缩策略:长任务逼近窗口上限后必然报错退出
生产可用的版本,每个环节都要有 harness 的手笔:
# 正确写法:权限、截断、压缩三道闸门齐全
messages = [system_prompt, user_task]
while True:
resp = llm.chat(messages, tools=TOOL_SCHEMAS)
if resp.stop_reason != "tool_use":
break # 模型给出最终回答
for call in resp.tool_calls:
check_permission(call) # harness:权限闸门,不通过则拒绝并把原因反馈给模型
result = execute_tool(call) # harness:超时控制、异常捕获、重试都在这一层
messages.append(tool_result(
call.id, truncate(result, MAX_TOKENS) # harness:输出截断
))
if token_count(messages) > LIMIT: # harness:上下文压缩
messages = compact(messages)
十几行代码,但这几行里藏了三个最容易出事故的点:权限没有闸门,Agent 会 rm -rf;工具输出不截断,一次 cat 大文件就撑爆上下文;没有压缩策略,长任务跑到一半必挂。
harness 的行为策略通常收在一组配置里,让策略可 review、可版本化,而不是散落在代码各处:
# harness 核心配置(示意)
permissions:
default: ask # 默认要人工确认
allow: ["Read", "Grep", "Glob"] # 只读工具免确认
deny: ["Bash(rm:*)", "Bash(curl:*)"] # 危险命令直接拒绝
context:
max_tokens: 200000
tool_output_limit: 10000 # 单次工具输出截断阈值(字符)
compact_threshold: 0.85 # 占用超 85% 触发压缩
observability:
trace_dir: ~/.agent/traces # 全量事件落盘目录
redact: [".env*", "*token*", "*secret*"] # 落盘前脱敏规则
为什么 Harness 比换模型更重要
实践中常见的情况是:团队发现 Agent 不好用,第一反应是换更强的模型,换了之后提升有限。因为大多数失败不是模型能力问题,而是工程问题:
- 工具描述写得烂,模型选错工具,再强的模型也白搭;
- 上下文塞满无关内容,模型注意力被稀释,关键约束反而看不见;
- 没有校验闭环,模型说"测试跑过了",harness 不验证,错误一路传递到提交。
这些都在 harness 层修,不动模型一行参数。反过来,模型升级带来的收益,也要靠 harness 把能力"接住"——更强的长上下文意味着你可以塞更多项目说明进去,更好的工具调用意味着你可以设计更粗粒度的工具;模型没换而 harness 退化(比如缓存前缀被动态字段污染),体验反而会倒退。
一个实用的归因顺序:任务失败后先回放 trace,依次问三个问题——模型当时看到了什么(上下文装配问题)、它想调的工具描述清不清楚(工具设计问题)、harness 有没有把结果如实带回(执行层问题)。三个都排除了,才轮到"换个模型试试"。
给后端工程师的三个判断
一是把 harness 当成一个普通的分布式系统来设计:工具是下游服务,模型是不可靠依赖(会超时、会返回垃圾),上下文是有限资源的缓存。你不会把下游服务的响应原文不裁剪地塞进下一份请求,也不会给一个内部工具开 root 权限——同样的纪律原样适用于 harness。
二是不迷恋端到端 Demo,生产可用的关键是失败路径:重试、降级、审计。Demo 里模型一口气跑通六十轮很惊艳,生产里第一周你就会遇到工具超时、输出超限、权限拒绝这三件事,它们的表现形式决定用户对你的平台是信任还是弃用。
三是评估 Agent 产品时别只看模型名字,看它的权限模型、上下文策略和可观测性做得深不深——这才是工程壁垒所在。模型是商品,harness 是资产;模型的差距会随代际更替抹平,harness 的差距会随团队沉淀拉大。
五个组件的失效后果
| 组件 | 职责 | 失效后果 | 成熟度信号 |
|---|---|---|---|
| 上下文装配 | 每轮动态拼装输入 | 模型"看不见"关键约束,答非所问 | 前缀稳定、内容按相关度取舍 |
| 工具执行循环 | 调用-执行-回填 | 一次异常中断整个任务 | 超时/重试/异常兜底齐全 |
| 权限与沙箱 | 危险操作分级管控 | 误删文件、数据外泄 | allow/deny 规则化、有审计 |
| 状态管理 | 会话与任务持久化 | 断线即失忆,成本翻倍 | 任务清单落盘、跨会话可恢复 |
| 可观测性 | 全量事件记录 | 失败只能靠猜,成本说不清 | trace 可回放、成本可归因到步 |
实战场景
一个真实感很强的场景:同一个模型,团队两套内部 Agent 平台并行跑了两个月(以下为定性观察,不构成 benchmark 结论)。A 平台的工具输出从不截断,探索类任务平均进行到十几轮就逼近窗口上限,任务半途夭折是常态;B 平台做了截断加压缩,同样的任务能稳定跑完。复盘时双方都先申请了升级模型配额,最后定位下来差异最大的三个点全在 harness:B 的工具描述里写了"优先用 Grep 定位、再分段 Read",单任务的平均读取量明显低于 A;B 挂了 PreToolUse 钩子挡住 mapper 目录写入,期间省掉了好几次人工回滚;B 的 trace 按任务落盘,出问题十分钟内能定位到具体哪一轮上下文开始跑偏,A 只能靠当事人回忆。模型一行没换,体验差出一截——这就是 harness 的分量。
检查清单
- 工具执行循环有异常捕获与超时控制,单次工具失败不中断整个任务
- 所有工具输出进入上下文前经过截断,阈值可配置
- 权限规则用 allow/deny 声明式管理,deny 覆盖 rm、curl 等危险命令
- 上下文占用逼近阈值时有压缩或外置策略,长任务能跑完
- 任务清单与关键状态落盘,会话中断后可恢复
- 每次 LLM 调用与工具调用有 trace 落盘,含 token 与成本字段
- 评估 harness 时考察权限模型、上下文策略、可观测性,而不是只看接了哪个模型