Deep Agents 稳定性的关键：Harness Engineering 工程体系实战拆解

先说结论：我最近大半年一直在折腾 Deep Agents，各种提示词技巧试了一圈、模型也从开源换到商用，最后发现真正让系统从“能跑demo”变成“能上线扛需求”的，不是模型本身，而是一层平时不太起眼、但极其关键的工程体系——Harness Engineering。这个词最近在圈子里热度很高，直译是“牵引控制工程”，往白了说，就是给 Deep Agent 套上一套完整的、可观测、可干预、可回滚的运行脚手架。

这篇文章我会从实际踩坑出发，把 Harness Engineering 的核心思路、落地步骤、常见问题全部拆开讲。适合正在做 Agent 应用的工程师、想进入这个方向的算法同学，以及被“模型能力很强但系统总崩”折磨过的项目负责人。看完之后，你至少能给自己现有的 Agent 系统画出改造路线图，而不是继续在 prompt 里打补丁。

1. 先搞清楚：Deep Agents 究竟卡在哪

1.1 从“单轮助手”到“Deep Agent”的复杂度跃迁

大多数人最开始做的 AI 应用，本质上是“单轮助手”：用户问一句，模型答一句，上下文就那几百字，错了重来，问题不大。可一旦做到 Deep Agent，情况完全变了。Deep Agent 的典型特征是：多步骤规划、多工具调用、长时间运行，模型要在整个过程中不断基于新信息修正自己的决策。

我举一个实际场景。一个客服工单 Agent，用户进来之后它要做的事情包括：理解用户意图、查订单、查库存、判断是否退款、生成工单、调用通知接口。听起来不复杂，但每一步都可能出错。比如调用查询接口返回了空数据，模型可能会“脑补”一个订单号继续往下走；又比如中间某一步报错，模型很可能带着错误的中间结果接着向下执行，最后生成一个完全错误的工单还给用户。

这就是 Deep Agent 最大的坑：错误会在链条中被放大，而不是被消除。单轮模型的错误是孤立的，Deep Agent 的错误是会传染的。上下文越长、步骤越多，出错的概率不是线性增加，而是指数级增加。这也是为什么很多人发现，Demo 阶段模型表现很好，一上生产就崩。

1.2 Harness Engineering 到底是做什么的

Harness 这个词，字面意思是“马具、挽具”，引申为“掌控和引导的工具”。在 AI 工程里，Harness Engineering 指的就是围绕 Agent 构建的一整套外部控制层，它不改变模型本身，但决定了模型在一个什么样的环境里思考、调用工具、输出结果。

我习惯把它比作配电箱里的电控柜：电器（模型）本身决定了能输出多大功率，但电控柜里的断路器等部件决定了什么时候切断、什么时候保护、什么时候允许电流经过。没有电控柜，电器也能转，但一有波动就烧掉了；有了电控柜，系统才能长期稳定运行。

放到 Agent 工程里，这个“电控柜”通常包含四层：

• 上下文编排层：负责管理“模型能看到什么”，包括历史消息、工具返回结果、任务描述的记忆与裁剪。
• 技能执行层：负责定义“模型能调用什么”，包括工具注册、参数校验、超时控制、幂等保护。
• 策略决策层：负责决定“下一步怎么走”，是继续思考、调用工具，还是直接结束，通常由一个运行循环来控制。
• 观察与护栏层：负责监控整个运行过程，包括日志记录、指标采集、预算控制、敏感操作拦截。

2. 整体设计思路：把 Agent 当系统工程来做

2.1 为什么不能靠“换更大模型”解决

我见过很多团队，Agent 一崩就把问题归咎于模型不够聪明，然后去换更大更贵的模型。这个思路有道理，但远远不够。模型能力就像发动机排量，排量大确实能跑更快，但如果没有变速箱、刹车和悬挂系统，你在弯道上照样翻车。

更深层的原因是，模型是概率系统，无论多强，都不可能保证 100% 按你的预期输出。而 Harness Engineering 要做的，就是用工程手段把那部分“概率不确定性”兜住。你可以让模型自由发挥，但在关键路径上给它装上约束、校验、重试机制。

举个我实测过的例子。同样一个数据抽取任务，用同一款模型，不加 Harness 时成功率大概 78%，加上 Harness 之后能做到 96% 左右。模型没变，变的只是外层控制逻辑：增加了输出格式校验、失败自动重试、结果合法性检查。这说明很多失败根本不是“模型笨”，而是缺少外围保障。

2.2 核心设计原则：显性化、可观测、可回滚

做 Harness 的早期，我走了不少弯路，最大的问题是想把控制逻辑全塞进一个大的 prompt 里。后来我总结出三个原则，现在基本成了我的设计底线。

第一是显性化。Agent 的每一步决策都必须能被代码显式地观察到，而不是隐藏在模型的黑盒里。比如说，模型认为“需要查库存”，这个判断必须输出为一个结构化的工具调用而不只是一段文字。这样系统才能判断它是否合理、是否超时、是否需要重试。

第二是可观测。每一次运行的完整轨迹，包括思考过程、工具调用、返回结果、耗时、token 消耗，都应该记录成结构化日志，而不是只留一个最终答案。没有观测数据，你根本无法定位到底是哪一步出了问题。后面我会详细讲怎么搭建这套观测体系。

第三是可回滚。这里不只是说代码版本能回滚，而是 Agent 的系统状态要能回滚。比如在调用数据库写操作之前，要先记录操作前快照；如果后续步骤失败，能够恢复到操作前状态。这一点在涉及支付、订单、权限修改等敏感操作时尤其重要。

2.3 轻量接入还是深度重构：怎么选

不少朋友会问，Harness 是不是一定要重写整个 Agent？不一定。根据项目阶段，我一般建议两种路径。

如果你的 Agent 已经是生产系统，或者正在快速迭代验证，那优先做“轻量接入”：在不改变模型和主流程的前提下，先加上输出校验、超时重试、日志追踪这三板斧。这部分改动量小，风险可控，收益往往立竿见影。

如果你还在搭建初期，或者现有系统已经因为复杂度过高而难以维护，那就值得做“深度重构”：把 Agent 的思维循环抽象成一个状态机，把工具调用、上下文管理、决策路由全部模块化。这样做的成本较高，但长期维护性和扩展性会好很多。我现在的项目就经历了从轻量接入到深度重构的过程，两者并不冲突，而是演进的先后顺序。

3. 核心细节解析与实操要点

3.1 上下文编排层：决定模型“视野”的边界

Deep Agent 的上下文管理，是最容易被低估、又最容易埋雷的部分。很多开发者直接把所有历史消息一股脑扔给模型，结果没几轮就把上下文窗口撑爆了，或者因为信息太杂导致模型忽略关键指令。

我的做法是把上下文分成五个区域：系统指令区、任务描述区、历史对话区、技能结果区、推理草稿区（scratchpad）。每个区域设定不同的保留策略。系统指令区每次都完整带上；任务描述区只放当前目标的简化版；历史对话区按时间和重要性截断；技能结果区只保留最近几次调用的返回，同时做摘要；推理草稿区则严格控制长度，防止模型在中间推理里绕圈子。

这里面有个关键技术点叫“上下文压缩”。压缩不是简单地把旧消息截断，而是要对旧内容做语义摘要。比如用户前面五轮都在改需求，最后确定了方案，那前五轮可以压缩成一行“用户需求经过多轮讨论，最终确认为……”。我一般会设置一个阈值：当历史 token 数超过总上下文的 40% 时，启动压缩。压缩时保留结构化信息，比如订单号、金额、日期，这些是业务逻辑的核心锚点，丢了就会出错。

3.2 技能执行层：工具调用必须有一道“安检门”

Deep Agent 的能力上限，很大程度上取决于它能调用的工具。但工具调用也是一把双刃剑，模型不是总有正确的判断力。我在生产环境里见过不少模型调用工具的错误方式：参数类型写错、必填字段漏掉、调用了一个不该调用的危险接口。

所以技能执行层至少要做四件事。

一是工具定义要结构化。给每个工具写清晰的 JSON Schema，明确参数类型、必填项、取值范围，让模型在生成调用时有一个强约束。很多框架的 function calling 已经支持，但不少人图省事只写描述不写 schema，结果模型自由发挥的空间就大了。

二是参数校验要在代码侧再做一遍，不要完全信任模型的输出。比如说“日期”字段，模型可能输出“明天”而不是具体日期，或者金额多了一个单位。这些要在进入真实 API 之前做转换和校验。

三是超时和重试机制。工具调用的超时不能只设一个全局超时，要按工具的类型分别设置。比如查询本地数据库可能 2 秒就够，但调用外部 HTTP 接口可能需要 10 秒。重试策略也要区分：只有幂等的工具才能安全重试，非幂等操作（比如创建订单）重试会导致重复数据处理，这种情况要加去重 ID。

四是敏感操作的二次确认。对于删除、写库、发送消息这类高风险工具，我建议加一道代码侧确认逻辑，比如要求模型必须明确输出一个确认标志，或者由更高权限的模块审批后才真正执行。

3.3 策略决策层：ReAct 和 Plan-then-Execute 怎么搭配

主流的 Agent 决策模式大致分两种：ReAct 和 Plan-then-Execute。ReAct 是边想边做，模型每步思考后可能立刻调用工具，然后根据结果调整下一步，适合探索性强、无法预先规划的任务。Plan-then-Execute 是先让模型生成一个完整计划，再逐步执行，适合流程明确、步骤固定的任务。

我的经验是，碰到复杂任务不要死守一种模式，而是让 Harness 根据任务类型动态选择。一个简单粗暴的规则是：如果任务描述里已经给出明确的操作流程，就直接走 Plan-then-Execute；如果任务本身模糊、需要不断试错和探索，就走 ReAct。更复杂的做法是让模型先判断任务类型再进行模式选择，但这又增加一层决策成本，初期不建议做。

在实际代码里，这个决策层通常是一个 while 循环，循环里根据模型输出走不同的分支。我在后面会给出一个精简实现，这里先强调一点：循环必须有最大步数限制，否则一定会在某个奇怪的任务上跑到天荒地老，Token 烧穿你的预算。

4. 实操过程与核心环节实现

4.1 最小闭环：给 Agent 套上一个“接线盒”

下面这段代码是我从实际项目里抽出来的一个最小可用的 Harness 核心骨架，用 Python 写的，去掉了业务细节，只保留授权逻辑。它的作用就是让你看到“显性化、可观测、可回滚”这三个原则具体是怎么落到代码里的。

from dataclasses import dataclass, field from typing import Any, Callable import json, time, uuid @dataclass class HarnessContext: task: str history: list = field(default_factory=list) scratchpad: list = field(default_factory=list) max_steps: int = 10 steps: int = 0 trace: list = field(default_factory=list) class HarnessRunner: def __init__(self, model_fn: Callable, tool_registry: dict): self.model_fn = model_fn self.tool_registry = tool_registry def _build_prompt(self, ctx: HarnessContext) -> str: # 实际项目中这里要做上下文压缩和分区 return f"任务：{ctx.task}\n\n历史：\n{self._format_history(ctx)}\n\n请输出下一步动作（think / call / finish）：" def _validate_action(self, action: dict) -> tuple[bool, str]: # 显性化：必须输出结构化动作 if "type" not in action: return False, "缺少动作类型" if action["type"] == "call": tool_name = action.get("tool_name", "") if tool_name not in self.tool_registry: return False, f"未注册的工具: {tool_name}" params = action.get("parameters", {}) schema = self.tool_registry[tool_name].get("schema", {}) # 简化：按 schema 校验必填字段 for req in schema.get("required", []): if req not in params: return False, f"缺少必填参数: {req}" return True, "ok" def run(self, ctx: HarnessContext) -> str: while ctx.steps < ctx.max_steps: ctx.steps += 1 prompt = self._build_prompt(ctx) raw = self.model_fn(prompt) action = json.loads(raw) # 要求模型输出 JSON 动作 ok, msg = self._validate_action(action) if not ok: ctx.scratchpad.append(f"动作校验失败：{msg}") ctx.trace.append({"step": ctx.steps, "event": "invalid", "detail": msg}) continue if action["type"] == "finish": return action.get("answer", "") if action["type"] == "think": ctx.scratchpad.append(action.get("thought", "")) ctx.trace.append({"step": ctx.steps, "event": "think", "text": action.get("thought", "")}) continue if action["type"] == "call": tool_fn = self.tool_registry[action["tool_name"]]["fn"] # 超时与重试：这里用简化写法 for attempt in range(3): try: result = tool_fn(**action["parameters"]) ctx.scratchpad.append(f"{action['tool_name']} => {result}") ctx.trace.append({"step": ctx.steps, "event": "tool", "tool": action["tool_name"], "params": action["parameters"], "result": result, "attempt": attempt + 1}) break except TimeoutError: if attempt == 2: ctx.scratchpad.append(f"工具 {action['tool_name']} 三次超时，放弃") ctx.trace.append({"step": ctx.steps, "event": "tool_timeout", "tool": action["tool_name"]}) continue return "达到最大步数，任务未完成"

这段代码最核心的地方在于，每一步模型输出都必须是一个结构化 JSON，而不是自由文本。这样 Harness 就能在进入真实执行之前做校验、记录和拦截。实际生产里我还会把 trace 直接打到日志系统，对接上监控面板。

4.2 评估体系的搭建：没有评估就没有改进

很多团队做 Agent 改进是“拍脑袋式”的：改一个 prompt，跑几个例子，感觉好一点就上线。这种方式的隐患是，你根本不知道改动是对整类任务有效，还是只对那几个样例有效。我强烈建议给 Agent 建一个离线评估集。

评估集不需要一开始就很大，先攒 50 到 100 条典型任务，覆盖正常流程、边界情况、需要多工具协作的复杂场景。每条任务除了输入之外，还要准备好“期望结果”和“关键约束”。关键约束很重要，比如“必须调用查询库存工具，且最终答案中不能出现虚构订单号”。

跑评估时，我和团队重点关注四个指标：

这个评估集能自动化跑最好。我现在的流程是每次改动 Harness 代码后，自动跑一遍回归评估，对比新旧指标。如果完成率下降，哪怕只有一个点，也要先停下来查为什么，不能贸然上线。

4.3 从单 Agent 到多 Agent：怎么用 Harness 做编排

任务复杂度上去以后，一个 Agent 很难扛下所有事情，这时候就需要多 Agent 协作。常见的方式有路由器 + 子 Agent、主 Agent 调度、流水线式传递等。Harness 在其中的作用不是替你做业务逻辑，而是保证每个 Agent 之间的上下文是隔离的、传递是显式的。

我的经验是，多 Agent 最容易出问题的地方是上下文串线。子 Agent A 的运行记录混进了子 Agent B 的上下文，导致 B 以为它已经知道了 A 的结论。解决方案有两个：一是给每个子 Agent 单独的 HarnessContext，互不共享；二是主 Agent 只传递结构化摘要，不让原始日志直接流入子 Agent 的上下文窗口。

多 Agent 的调度决策建议也放在 Harness 层，而不是让模型自己决定调用哪个子 Agent。你可以在工具注册表里把每个子 Agent 注册成一个“伪工具”，由主 Harness 统一调度和记录。这样既能复用单 Agent 的校验、超时、追踪机制，又能清楚地看到整个多 Agent 链路的完整轨迹。

5. 常见问题与排查技巧实录

5.1 上下文污染导致幻觉复现

有段时间，我的 Agent 总是把上一个任务里的订单号带到当前任务里来，导致查错订单。排查了很久才发现，问题出在上下文压缩策略上：压缩时把旧订单信息摘要进了历史，而当前任务的系统指令里没有明确“忽略历史订单信息”，模型就自作主张用上了。

后来我的解决办法是：在任务开始前，由 Harness 注入一条“当前任务状态”的系统信息，明确列出本次任务的订单号、用户 ID、目标等关键变量。同时，上下文压缩时禁止将旧任务的具体业务实体（订单号、金额、用户名）混入新的任务描述。简单说，动态事实要隔离，通用知识才共享。

5.2 工具调用陷入死循环和超时

另一个高频问题是，模型查到一个不理想的结果后，会反复调用同一个查询工具，试图“再试一次”直到拿到预期数据。这在 ReAct 模式里特别常见，浪费 token 不说，还会导致任务迟迟无法结束。

我的处理方式是双管齐下。一是在 Harness 里加“工具调用去重”：如果模型对同一个工具、相同参数连续调用超过两次，就拦截并提示模型换个策略。二是引入工具返回值摘要机制，把每次查询结果存成结构化缓存，如果后续步骤还需要同样的数据，直接取缓存，不重复调用真实接口。

5.3 评估数据过拟合与“刷分”陷阱

评估集攒到一定程度后，我发现某些任务通过率很高，但一上生产就原形毕露。原因是模型“记住”了评估集中的固定套路。比如评估集里所有查库存的订单号都以 2024 开头，模型遇到类似订单号时就直接套用历史结论，而不再认真调用工具。

针对这个问题，我做了两点改动：一是评估集要周期性更换，并加入“扰动项”，比如随机修改订单号、金额、日期，防止模型靠表面特征猜答案；二是关键约束的断言不能只看最终答案，还要校验过程中是否真的调用了应该调用的工具。也就是说，评估不仅要看“结果对不对”，还要看“过程对不对”。

5.4 问题速查表

6. 最后分享一点我的实际工程体会

我做了大半年 Deep Agents 之后，最深的感受是：模型能力的提升是缓慢的、线性的，而工程结构的改进往往是跳跃式、决定性的。Harness Engineering 的核心，不是把 Agent “关进笼子”限制它的能力，而是给它提供一个稳定、可控、能纠错的运行环境，让它敢在更复杂、更长链条的任务里放手干活。

如果你正被 Agent 的稳定性问题折磨，我的建议是从最小改动开始：先搭建工具调用的校验和超时重试，再补上结构化 trace，然后攒一个离线评估集。这三件事做完，你的 Agent 大概率会比现在至少稳一个档次。后续再逐步扩展上下文编排和多 Agent 编排，你会发现可维护性完全是另一个层级。