1. 为什么“换一套 Harness”能顶两代模型先把结论摆在前面在 Agent 开发这条线上Harness 的工程成熟度往往比模型本身的代际提升更能决定最终效果。我最近半年在几个 Agent 项目里反复验证过这件事——同一个模型换一套更合理的 Harness任务成功率能从“勉强能用”跳到“可以交付”而把模型从上一代换成最新一代提升幅度反而没那么夸张。这里说的 Harness不是某个具体产品而是包裹在模型外面的那一整套工程骨架上下文怎么组织、工具怎么暴露、ReAct 循环怎么跑、错误怎么兜、结果怎么校验。模型是发动机Harness 是底盘、变速箱和方向盘。发动机再强底盘散架车照样开不动。热词里反复出现的Harness、Agent、Context、Tool、ReAct其实正好对应 Harness 的五个核心模块。很多人把注意力全放在“用哪个模型”上却忽略了这五个模块才是真正决定 Agent 能不能干活的东西。这篇就按我自己的实操经验把这套骨架拆开讲清楚包括每一步为什么这么设计、参数怎么定、坑在哪里。适合谁看正在做 Agent 开发、被“模型很强但 Agent 很蠢”困扰的人想从零搭一个能跑通任务的 Agent 的人以及已经有一套 Harness 但总觉得哪里不对劲、想系统性优化的人。不需要你是模型训练专家但最好写过一点调用 API 的代码这样后面的配置和步骤你能直接抄。2. Harness 到底是什么把模型从“聊天”变成“干活”2.1 一句话区分 Harness 和 Agent热词里有个高频问题“harness 和 agent 区别”。我用一句话说清楚Agent 是角色Harness 是这个角色赖以工作的整套工具和环境。Agent 是“谁在干活”——它决定了目标、决策风格、要不要调用工具。Harness 是“怎么干活”——它决定了模型看到什么上下文、能调用哪些工具、调用结果怎么回填、循环什么时候停。打个比方Agent 是司机Harness 是车。你光换个更聪明的司机换模型但车没有方向盘助力、刹车还失灵Harness 烂司机再牛也开不好。反过来车调校得好一个普通司机也能开得又稳又快。这就是“换一套 Harness 比换两代模型还管用”的底层逻辑。2.2 Harness 的五个核心模块结合热词我把 Harness 拆成五块后面每一块都会单独展开模块作用对应热词Context 管理决定模型每一步看到什么信息ContextTool 层决定模型能调用什么、怎么调ToolReAct 循环决定“思考-行动-观察”怎么转ReAct错误与重试决定出错后怎么兜底api error、execution terminated结果校验决定输出能不能直接用skill、harness engineering这五块里Context 管理和 Tool 层是投入产出比最高的两块。我实测下来光把这两块做扎实任务成功率就能提升一大截比换模型划算得多。2.3 为什么模型代际提升的边际收益在下降现在主流模型的原始能力都已经过了“能不能理解指令”这条线。热词里那个maximum context length is 1048576 tokens的报错说明上下文窗口已经大到离谱但窗口大不等于用得好——塞进去一堆无关信息模型反而更容易跑偏。模型代际提升主要提升的是“单步推理质量”但 Agent 任务失败绝大多数不是单步推理不行而是上下文里缺了关键信息、工具返回格式模型看不懂、循环卡死在某一步、错误没兜住直接崩。这些问题换模型解决不了只有改 Harness 才能解决。3. Context 管理决定 Agent 智商的上限3.1 上下文不是越多越好新手最容易犯的错就是把所有历史对话、所有工具返回、所有文档一股脑塞进上下文。结果就是热词里那个经典报错maximum context length超了或者虽然没超但模型开始“失忆”——前面说过的关键约束后面就忘了。Context 管理的核心原则是每一步只给模型它这一步真正需要的信息。这跟人干活一样你不需要把整个项目所有文档摊在桌上才能写一行代码你只需要当前这个函数相关的上下文。3.2 三层上下文结构我一般把上下文分成三层来组织系统层System角色设定、全局约束、输出格式要求。这部分固定不变放在最前面利用模型对开头内容的注意力优势。任务层Task当前任务的目标、已完成的步骤摘要、当前待解决的问题。这部分随循环推进动态更新。即时层Immediate最近一次工具调用的原始返回、当前这一步的具体指令。这部分最“新鲜”放在最靠近生成位置的地方。这样分层的好处是系统层的约束不会被淹没任务层保持精简即时层的细节又足够具体。实测下来同样的模型用这种结构比“平铺所有历史”的任务成功率明显更高。3.3 上下文压缩的实操参数当任务步骤变多历史会膨胀。这时候需要压缩。我的做法是保留最近 N 轮原始对话N 一般取 3 到 5。太少会丢上下文太多会挤占空间。更早的历史做摘要用一次单独的模型调用把“已完成步骤 关键结论”压成一段话。工具返回做截断超过一定长度的返回只保留头部和尾部中间用省略标记。具体阈值我一般这么定如果模型上下文窗口是 128K我会把系统层控制在 2K 以内任务层摘要控制在 4K 以内即时层原始内容控制在 8K 以内剩下的留给模型生成和缓冲。这样即使任务跑几十步也不会撑爆。注意压缩摘要这一步本身也会消耗 token 和时间不要每一步都做。我的经验是每 5 到 8 步做一次摘要或者当上下文占用超过窗口的 60% 时触发。3.4 一个容易忽略的点上下文里的“噪音”热词里有个deepseek messages tool calls need immediate results这其实是在说工具调用结果必须及时回填。但回填的时候很多人把工具返回的原始 JSON 整个塞进去里面一堆模型根本不需要的字段比如时间戳、内部 ID、调试信息。这些就是噪音。我的做法是工具返回后先用一个轻量的格式化函数把结果清洗成模型友好的形式只保留它决策需要的信息。这一步看起来小但对模型理解结果帮助很大。比如一个搜索工具返回 20 条结果我只保留标题、摘要和链接把其他元数据全砍掉。4. Tool 层设计让模型“会用”比“有得用”更重要4.1 工具不是越多越好很多人一上来就给 Agent 挂几十个工具觉得能力越全越好。实际结果是模型选择困难经常调错工具或者该调工具的时候不调。热词里tool和agent总是成对出现但工具的质量远比数量重要。我的原则是每个工具都要有清晰的“什么时候用”和“什么时候不用”的说明。工具描述里不能只写“这个工具能搜索”要写“当需要查找实时信息、且本地知识库没有答案时使用如果问题涉及计算不要用这个工具”。4.2 工具描述的写法工具描述是模型决定调不调、怎么调的唯一依据。我总结了一个模板功能一句话这个工具做什么。使用场景什么情况下该用。不使用场景什么情况下不该用这条最容易被忽略但极其重要。参数说明每个参数的类型、含义、是否必填、示例值。返回说明返回什么格式模型该怎么解读。举个例子一个查询天气的工具描述里要明确写“当用户询问某地当前或未来天气时使用如果用户只是闲聊提到天气不要调用”。这样能大幅减少误调用。4.3 工具返回格式的统一热词里deepseek messages tool calls need immediate results反映了一个真实痛点工具调用后结果必须立刻、以模型能懂的格式回填。如果返回格式五花八门模型每次都要重新理解效率极低。我的做法是所有工具返回统一成一种结构比如{ status: success, summary: 一句话说明结果, data: 模型需要的主体内容, hint: 给模型的下一步建议可选 }这样模型看到任何工具返回都知道先看 status 判断成败再看 summary 快速理解需要细节再看 data。统一格式带来的稳定性提升比换模型明显得多。4.4 工具调用的参数校验模型生成的参数经常有格式问题比如该传数字传了字符串、该传数组传了单个值。如果直接拿去做实际调用就会报错。我的做法是在 Harness 里加一层参数校验和自动修复类型不对就尝试转换缺必填参数就返回明确错误让模型重试而不是直接崩掉。这一层看起来是“防御性编程”但它把大量本会导致任务失败的小错误挡在了外面。实测下来加了参数校验后工具调用的成功率提升非常明显。5. ReAct 循环让“思考-行动”转得又稳又准5.1 ReAct 的本质ReAct 就是 Reasoning Acting模型先想Reasoning再决定要不要行动Acting行动后观察结果Observation然后继续想。热词里react和agent高频共现说明这是 Agent 的核心循环。但很多人把 ReAct 理解成“让模型输出 Thought/Action/Observation 三个字段”这只是形式。ReAct 的本质是给模型一个结构化的决策节奏防止它一上来就瞎调工具或者想半天不行动。5.2 循环终止条件ReAct 最容易出的问题是死循环模型反复调同一个工具或者一直在“想”不行动。热词里agent execution terminated due to error很多时候就是循环没兜住导致的。我一般设三重终止条件任务完成信号模型明确输出最终答案且通过结果校验。步数上限一般设 15 到 25 步超过就强制收尾让模型基于已有信息给最佳答案。重复检测如果连续 3 步调同一个工具且参数高度相似判定为卡住强制换策略或终止。这三重条件里重复检测最容易被忽略但最有用。我踩过的坑就是模型在一个工具上反复试每次都差一点点结果烧了一堆 token 还是没结果。加了重复检测后这种情况基本绝迹。5.3 每步的提示词结构ReAct 每一步的提示词我固定成这个结构当前任务目标重申防止跑偏已完成步骤摘要上一步的观察结果当前可用工具列表输出格式要求Thought / Action / Final Answer关键是每一步都重申目标。模型在长循环里很容易忘记最初要干什么重申一次成本很低但能显著减少跑偏。5.4 思考与行动的节奏控制有些任务适合“多想少动”有些适合“快动快试”。我一般根据任务类型调两个参数思考深度复杂推理任务要求模型在 Action 前写更详细的 Thought简单任务允许直接 Action。行动频率探索型任务鼓励多调工具确定型任务鼓励少调、精调。这两个参数没有标准值我的经验是先用默认值跑几个 case看模型是“想太多不行动”还是“乱行动不想”再针对性调整。6. 错误处理与重试决定 Agent 能不能“扛住”6.1 错误分类Agent 跑起来会遇到各种错误热词里就有api error: 400、execution terminated due to error、context相关报错。我把错误分成三类错误类型例子处理策略可重试错误网络超时、限流退避重试可修复错误参数格式错、工具返回异常回填错误让模型修正致命错误上下文超限、认证失败终止并报告分类的意义在于不是所有错误都该重试也不是所有错误都该终止。把可修复错误直接终止是很多 Harness 的通病白白浪费了模型自我修正的能力。6.2 退避重试的参数对于可重试错误我用指数退避第一次等 1 秒第二次 2 秒第三次 4 秒最多重试 3 次。超过就归为致命错误。这个参数不是拍脑袋是因为大部分临时性错误在几秒内会恢复等太久浪费用户时间等太短又没效果。6.3 把错误变成模型的输入这是我最想强调的一点可修复错误不要吞掉要回填给模型。比如工具返回“参数 x 必须是数字”就把这句话原样放进 Observation模型下一步大概率会修正。这比 Harness 自己硬修要灵活得多因为模型比任何规则都更懂当前语境。热词里deepseek messages tool calls need immediate results说的就是这个——工具调用的结果包括错误结果必须立刻、完整地回填模型才能继续。6.4 上下文超限的兜底maximum context length这个报错太常见了。我的兜底策略是一旦检测到接近上限立刻触发上下文压缩把早期历史摘要化只保留最近几轮原始内容。如果压缩后还是超就丢弃最早的工具返回细节只留摘要。这个兜底能让长任务不至于因为超限直接崩掉。7. 结果校验让输出“能直接用”7.1 为什么需要校验模型输出的最终答案经常有格式问题、缺字段、或者答非所问。如果直接返回给用户或下游系统就会出问题。热词里skill、harness engineering这些词其实都指向“让 Agent 输出可控、可用”。7.2 校验的三个层次格式校验输出是否符合要求的格式JSON、Markdown、特定字段。完整性校验必填内容是否都有。合理性校验内容是否和任务相关有没有明显矛盾。格式和完整性校验可以用代码做快且稳。合理性校验一般需要再调一次模型或者用规则做粗筛。我的做法是格式和完整性必须过合理性做抽样检查不过就触发一次重生成。7.3 校验失败后的处理校验失败不要直接报错给用户而是把失败原因回填给模型让它重生成。比如“输出缺少 summary 字段”模型看到后基本都能补上。重生成最多 2 次还不行就返回带标记的结果让下游知道这个输出需要人工确认。8. 常见问题与排查速查表8.1 高频问题速查现象可能原因排查方向模型不调工具工具描述不清、场景没写检查工具描述的使用/不使用场景反复调同一工具循环无重复检测加重复检测和步数上限上下文超限历史未压缩加分层上下文和摘要工具调用报错参数格式问题加参数校验和自动修复输出格式乱缺格式约束系统层加输出格式要求任务跑偏目标未重申每步提示词重申目标8.2 我的独家避坑经验第一个坑别在系统提示里写太多规则。规则越多模型越容易顾此失彼。我的做法是把规则分层核心约束放系统层具体规则放对应步骤的提示里。第二个坑工具返回别塞原始 JSON。清洗成模型友好的格式这一步的投入产出比极高。第三个坑别指望模型自己记住目标。长循环里每步重申目标成本低、效果好。第四个坑错误别吞。可修复错误回填给模型让它自己修比 Harness 硬修灵活。第五个坑步数上限一定要设。没有上限的循环迟早会烧光你的预算。8.3 性能与成本的平衡Harness 做得好token 消耗反而可能下降因为上下文精简了、循环少了、重试少了。我实测过一个任务优化 Harness 后同样的模型token 消耗降了大概三成任务成功率还升了。所以“把 Harness 做扎实”不是增加成本而是降本增效。9. 从零搭一套 Harness 的实操顺序9.1 第一步定义任务和成功标准先别写代码先想清楚这个 Agent 要完成什么任务什么样的输出算成功。成功标准要可校验比如“输出包含 A、B、C 三个字段且格式为 JSON”。这一步决定了后面所有设计。9.2 第二步设计工具集根据任务需要列出最小工具集。每个工具按前面说的模板写描述。工具宁少勿多能合并的合并。9.3 第三步搭上下文结构按系统层、任务层、即时层三层组织。先写死结构跑通后再加压缩逻辑。9.4 第四步实现 ReAct 循环先实现最简版本想-调-观察-再想。加上步数上限和重复检测。跑几个 case 看效果。9.5 第五步加错误处理和校验把可修复错误回填加退避重试加结果校验。这一步是让 Agent 从“能跑”到“能交付”的关键。9.6 第六步迭代优化拿真实任务跑记录失败 case分析是 Context、Tool、循环还是校验的问题针对性改。我一般迭代 3 到 5 轮效果就稳定了。10. 我个人的几点体会做 Agent 这半年最大的感受就是模型是变量Harness 是常量。模型会一直更新但一套好的 Harness 能让你在每次模型更新时都吃到红利而不是每次都要重新调。另外别迷信“最新模型解决一切”。我见过太多项目模型换了一茬又一茬Harness 还是那套烂骨架结果就是一直“差一点”。把 Context 管好、Tool 描述写清、循环兜住、错误回填、结果校验这五件事做到位用中等模型也能跑出能交付的效果。最后分享一个小技巧每次任务失败先别急着怪模型先看 Harness 的日志。十有八九问题出在上下文缺了信息、工具描述有歧义、或者错误被吞了。把这几处修好你会发现模型其实比你想的聪明得多。