Harness工程实战：从线上事故到长时运行Agent的稳定性设计

1. 从一次线上事故说起为什么 Harness 工程值得单独拎出来讲去年冬天我们团队负责的一个自动化代码审查 Agent 在灰度环境跑得好好的一上生产就翻车了。表现很诡异前 20 分钟一切正常第 21 分钟开始Agent 开始重复执行同一个文件读取操作像卡带一样循环了 47 次最后把上下文窗口撑爆整个任务链断裂。事后复盘问题不在模型本身也不在提示词而在于我们压根没有为 Agent 设计一套完整的“运行骨架”——也就是今天要聊的Harness 工程。这个词最近在 Agent 开发圈子里被反复提及但很多人对它的理解还停留在“不就是个执行器吗”。实际上Harness 工程涵盖的范围远比一个 while 循环大得多它要管 Agent 怎么循环、上下文怎么组织、沙箱怎么隔离、结果怎么验证、长时运行怎么保持稳定。你可以把模型想象成一台性能强悍但脾气不定的发动机Harness 就是那套底盘、变速箱、冷却系统和仪表盘——没有它发动机再猛也上不了路。这篇文章适合三类人看正在做 Agent 应用但总被稳定性问题折磨的开发者、想从“调提示词”进阶到“做系统工程”的 AI 工程师、以及需要评估 Agent 方案可行性的技术负责人。我会从整体设计思路讲到每个核心模块的实操细节把踩过的坑和验证过的方案都摊开来说。全文基于我们团队在多个模拟项目中的实践总结涉及具体参数和代码的地方都会给出可复现的参考。2. Harness 工程的整体设计与核心思路拆解2.1 什么是 Harness它和普通 Agent 框架的区别在哪先把这个概念钉死。Harness 在英文里是“马具、挽具”的意思套在马身上用来控制方向、传递力量。放到 Agent 语境里它指的是包裹在模型外层的一整套运行时基础设施负责把模型的单次推理能力转化为可控制、可观测、可恢复的持续任务执行能力。很多人会把它和 LangChain、AutoGPT 这类框架混为一谈。区别在于框架提供的是“能力组件”比如工具调用、记忆存储、链式编排而 Harness 关注的是“运行契约”也就是 Agent 在真实环境中跑起来之后怎么保证它不跑偏、不卡死、不失控。举个具体例子框架能让你轻松定义一个“读取文件”的工具但 Harness 要解决的是这个工具被连续调用 50 次时怎么熔断读取失败时重试几次重试间隔怎么设计这些才是生产环境真正要命的问题。我们内部有个粗线条的划分标准如果一个 Agent 任务在 5 分钟内、10 步以内能完成框架层面的能力基本够用一旦任务时长超过 30 分钟、步骤超过 50 步、涉及外部环境交互就必须认真设计 Harness。这个阈值不是拍脑袋来的而是根据上下文窗口消耗速率和错误累积概率算出来的——后面会详细展开。2.2 为什么“循环”只是冰山一角五个核心模块的协作关系一个完整的 Harness 至少包含五个模块它们之间的关系不是简单的串联而是相互制约的闭环。Agent 循环是心脏负责驱动“推理-行动-观察”这个基本节拍。但循环本身不产生智能它只是节奏控制器。上下文管理是记忆系统决定每一轮循环里模型能看到什么、看不到什么。沙箱环境是手脚提供文件操作、命令执行、网络请求等实际能力同时承担隔离和安全职责。验证机制是免疫系统在每一步行动后检查结果是否符合预期决定继续、重试还是中止。长时运行保障是耐力系统处理超时、断连、状态持久化和恢复。这五个模块的协作有个关键原则循环的每一步都必须经过验证才能进入下一步验证的结果必须反馈到上下文管理中上下文的膨胀必须触发压缩或截断策略而所有状态变更必须能被长时运行模块持久化。缺了任何一环Agent 在长任务中都会出问题。我们早期做过一个实验只做循环和沙箱不做验证和上下文压缩结果 Agent 在第 38 步开始出现“幻觉累积”——前面读错了一个配置项后面所有推理都建立在错误前提上最终输出了一份完全不可用的报告。2.3 方案选型为什么我们最终放弃了“全自主”路线市面上关于 Agent 的设计哲学大致分两派一派追求“全自主”给模型最大的自由度让它自己规划、自己纠错另一派主张“强约束”把任务拆成固定流程模型只在关键节点做决策。我们两种都试过最后选了中间路线宏观流程强约束微观步骤给自主。全自主路线的问题在于错误传播不可控。模型在长任务中一旦进入错误状态很难靠自己跳出来因为它看到的上下文已经被自己的错误输出污染了。我们实测过一个全自主的代码重构 Agent在 200 步左右的任务中有 60% 的概率会在某个点开始“自我说服”把明显错误的方案论证成正确的。强约束路线则走向另一个极端流程太死遇到预期外的情况就卡住需要人工介入的频率太高失去了自动化的意义。最终方案是用状态机定义任务的宏观阶段比如“探索-规划-执行-验证-收尾”每个阶段内部允许模型自由决策但阶段之间的跃迁必须满足预设条件。这样既保留了灵活性又给错误传播设了防火墙。这个设计决策直接影响了后面所有模块的实现方式。3. 核心模块深度解析与实操要点3.1 Agent 循环不只是 while True而是带状态的心跳Agent 循环最朴素的写法就是一个 while 循环不断调用模型、执行工具、把结果塞回上下文。但生产级的循环需要处理至少四种状态正常推进、等待外部输入、重试中、终止。每种状态对应不同的循环行为。我们用的循环骨架大致是这样的逻辑每轮开始先检查终止条件步数上限、时间上限、任务完成标志然后从上下文管理器获取当前轮次的输入调用模型推理解析输出中的行动指令交给沙箱执行执行结果经过验证器检查后写回上下文最后更新循环状态。这个顺序不能乱尤其是验证必须在写回之前否则错误结果会污染上下文。这里有个容易忽略的细节循环的步数上限不能设成固定值。我们最初设了 100 步硬上限结果发现有些复杂任务确实需要 150 步以上而有些简单任务 20 步就该结束却因为模型“恋战”拖到 80 步。后来改成动态上限根据任务类型给一个基准值再根据当前已消耗的上下文比例动态调整。具体公式是max_steps base_steps * (1 context_used_ratio)其中context_used_ratio是已用上下文占窗口的比例。这样上下文用得越多允许的步数反而越多因为说明任务确实复杂。注意循环中一定要有“无进展检测”。如果连续 N 轮的行动和观察结果高度相似可以用简单的文本相似度判断说明 Agent 卡住了必须强制中断或切换策略。我们设的 N 是 3实测能拦住大部分死循环。3.2 上下文管理在有限窗口里做无限任务的取舍艺术上下文管理是 Harness 工程里最考验工程判断力的部分。模型的上下文窗口就那么大但长任务产生的信息量可能是窗口的几十倍。怎么取舍直接决定 Agent 的“记忆力”和“判断力”。我们的策略是分层管理系统提示层永远保留包含角色定义、核心规则、当前任务目标近期交互层保留最近 K 轮完整的推理-行动-观察记录K 根据任务类型在 5 到 15 之间调整摘要层存放更早历史的压缩摘要由模型自己生成但生成时机和压缩比例由 Harness 控制外部存储层存放完整的原始记录需要时通过检索工具按需拉取。压缩时机的选择很关键。我们试过两种方案一种是固定轮次压缩比如每 10 轮压缩一次另一种是阈值触发当上下文使用率达到 70% 时启动压缩。实测下来阈值触发更合理因为不同任务的上下文消耗速率差异很大。压缩比例也有讲究压缩太狠会丢失关键细节压缩太松起不到释放空间的作用。我们的经验值是每次压缩把目标区域压缩到原长度的 20% 到 30%同时保留所有“决策点”信息——也就是 Agent 做出关键选择的那些轮次这些轮次的记录不参与压缩。还有个实操技巧给上下文打标签。每一条写入上下文的信息都标注类型事实、推理、行动结果、错误信息和重要性等级。压缩时优先丢弃低重要性的推理过程保留事实和错误信息。这个标签机制让压缩后的上下文质量明显提升Agent 在压缩后“失忆”的情况减少了大概七成。3.3 沙箱环境隔离不是目的可控才是沙箱的核心诉求有两个安全隔离和能力供给。安全隔离好理解不能让 Agent 随便操作宿主机。能力供给则经常被低估——沙箱里提供什么工具、工具的粒度怎么设计直接影响 Agent 的执行效率和错误率。我们最初给沙箱配了一套“万能工具”一个能执行任意 shell 命令的接口。结果 Agent 经常写出又长又复杂的命令出错后很难定位是命令本身的问题还是环境的问题。后来改成“细粒度工具集”读文件、写文件、列目录、搜索内容、执行预定义脚本每个工具职责单一参数明确。这样虽然工具数量多了但每个工具的行为可预测验证器也容易判断执行结果是否正常。沙箱的生命周期管理也有讲究。我们采用“任务级沙箱”每个任务启动时创建一个干净的沙箱实例任务结束后销毁。这样避免了任务间的状态污染。但创建沙箱有开销对于高频短任务不划算。所以又加了一层“沙箱池”预热一批沙箱实例任务来了直接分配用完重置后放回池子。重置操作包括清空工作目录、恢复环境变量、重置网络访问策略。实测下来沙箱池能把任务启动延迟从 3 秒降到 200 毫秒左右。提示沙箱内的文件操作一定要做路径规范化。我们遇到过 Agent 用相对路径../../etc/passwd试图越界访问的情况虽然沙箱本身有隔离但路径检查能提前拦截这类异常行为减少无效尝试。3.4 验证机制让 Agent 学会“停下来想一想”验证机制是 Harness 里最容易被做薄的部分。很多实现只在任务结束时验证最终结果中间步骤完全不检查。这在短任务里问题不大长任务里就是灾难——错误像滚雪球一样越滚越大。我们的验证分三层格式验证检查模型输出是否符合预期结构比如 JSON 能不能解析、必填字段在不在语义验证检查行动结果是否符合任务逻辑比如读文件操作返回了内容而不是错误码进度验证检查当前状态是否在向目标靠近比如距离完成还有多少步、关键里程碑是否达成。格式验证和语义验证是确定性的用规则就能实现。进度验证则需要一些启发式判断。我们的做法是让模型在每轮输出时附带一个“进度自评”用 0 到 100 表示任务完成度。Harness 记录这个自评值的变化曲线如果连续多轮自评值不增反降或者增长极其缓慢就触发预警。这个信号不一定准确但作为辅助判断很有价值。验证失败时的处理策略也要分层。格式错误直接重试把错误信息反馈给模型让它修正。语义错误先重试一次再失败就切换工具或换一种实现方式。进度停滞则触发“策略重规划”把当前状态和已完成的部分总结一下让模型重新规划剩余步骤。这套分层处理机制把我们的任务成功率从 62% 提升到了 89%。3.5 长时运行保障断点续跑与状态持久化长时运行的核心问题是任务跑到一半进程挂了、机器重启了、网络断了怎么办答案只有一个状态持久化 断点续跑。状态持久化不是简单地把上下文存下来就完事。需要持久化的包括当前循环轮次、上下文快照、沙箱工作目录状态、已完成步骤的清单、验证器的历史记录。这些状态要能原子性地写入存储并且在恢复时能完整重建运行环境。我们用的是“检查点”机制每完成一个宏观阶段比如“探索”阶段结束进入“规划”阶段就写一个检查点。检查点包含重建运行所需的最小状态集。恢复时从最近的检查点加载重放检查点之后的步骤日志来恢复到中断点。这里有个细节重放不能真的重新执行工具调用而是从日志中读取当时的执行结果。所以日志必须记录每一步的完整输入输出。断点续跑还有个隐蔽的坑外部副作用。如果 Agent 在中断前已经修改了外部系统比如发了一封邮件、提交了一个表单恢复后不能重复执行这些操作。我们的解法是给每个有副作用的操作分配一个幂等键执行前先检查这个键是否已经执行过。这个机制在模拟项目中救过我们好几次避免了重复提交导致的脏数据。4. 完整实操流程从零搭建一个可运行的 Harness4.1 环境准备与基础依赖先列一下我们用的技术栈都是常见组件不涉及任何特殊工具。运行时用 Python 3.11异步框架用 asyncio状态存储用 SQLite轻量场景或 PostgreSQL生产场景沙箱用容器化方案日志用结构化日志库。模型接口走标准的 HTTP 调用不绑定特定供应商。目录结构大致这样组织harness/core放循环和状态机harness/context放上下文管理harness/sandbox放沙箱接口和实现harness/validator放验证器harness/persistence放持久化harness/tools放工具定义。每个模块之间通过明确的接口通信方便单独测试和替换。初始化配置里几个关键参数max_context_tokens根据模型窗口设留 20% 余量给输出compression_threshold设 0.7max_steps_base按任务类型设代码类任务 80文本类任务 40checkpoint_interval按阶段设不按固定步数。这些参数没有绝对最优值需要根据实际任务分布调优。4.2 循环控制器的实现细节循环控制器是整个 Harness 的调度中心。它的主循环逻辑用伪代码表示大概是这样async def run_loop(task, context, sandbox, validator, persistence): state LoopState.RUNNING step 0 while state LoopState.RUNNING: step 1 if should_terminate(step, context, task): state LoopState.TERMINATED break model_input context.build_input() model_output await call_model(model_input) action parse_action(model_output) if action is None: context.add_error(无法解析行动指令) continue result await sandbox.execute(action) validation validator.check(action, result, context) if validation.passed: context.add_observation(result) context.update_progress(model_output.progress) else: handle_validation_failure(validation, context) if should_checkpoint(step, context): persistence.save_checkpoint(build_checkpoint(state, context, sandbox)) return state这段逻辑里should_terminate综合判断步数、时间、完成标志和进度停滞。handle_validation_failure根据失败类型决定重试、换策略还是中止。should_checkpoint按阶段跃迁触发。每个函数的具体实现根据任务类型有差异但骨架是通用的。4.3 上下文压缩的具体操作压缩操作在上下文使用率达到阈值时触发。具体步骤先标记出所有“决策点”轮次Agent 做出关键选择的轮次比如选择工具、确定参数、判断完成这些轮次不压缩。然后把剩余轮次按时间倒序排列保留最近 K 轮完整记录。更早的记录按类型分组事实类信息合并成摘要推理类信息只保留结论错误信息保留错误码和简要描述。最后让模型对合并后的内容生成一段连贯的摘要文本替换原始记录。压缩后的上下文结构变成系统提示 决策点记录 近期完整记录 历史摘要。这个结构在多次压缩后依然保持稳定不会出现“摘要的摘要”导致信息严重失真。我们实测过连续压缩 8 次后的上下文质量关键信息的保留率在 85% 以上。4.4 沙箱工具集的定义与实现工具定义用 JSON Schema 描述参数实现层做具体的操作。以文件读取工具为例参数包括path必填字符串、encoding可选默认 utf-8、max_bytes可选默认 1MB。实现时先做路径规范化检查是否在允许的工作目录内然后读取文件超过大小限制就截断并返回截断标志。工具执行结果统一格式{success: bool, data: any, error: str, metadata: dict}。metadata里放执行耗时、资源消耗等信息供验证器和监控使用。这个统一格式让验证器可以用同一套逻辑处理所有工具的结果。4.5 验证器的规则配置验证器分三层每层的规则用配置驱动。格式验证的规则比如“输出必须是合法 JSON”“必须包含 action 字段”。语义验证的规则比如“读文件操作 success 为 true 时 data 不能为空”“写文件操作后文件大小应大于 0”。进度验证的规则比如“连续 3 轮 progress 增量小于 5 则触发预警”。规则配置支持热更新不用重启 Harness 就能调整验证策略。这在调试阶段特别有用发现某个规则误报率高直接改配置就行。4.6 持久化与恢复的实操检查点写入用事务保证原子性。检查点内容序列化成 JSON包含循环状态、上下文快照、沙箱工作目录的文件清单和校验和、已完成步骤的 ID 列表。恢复时先加载检查点重建上下文和沙箱环境然后从步骤日志中读取检查点之后的记录按顺序重放只读结果不重新执行。步骤日志用追加写的方式每条记录包含步骤 ID、时间戳、行动指令、执行结果、验证结论。日志文件按任务 ID 分片方便检索和清理。5. 常见问题与排查技巧实录5.1 循环卡死与无效重试的排查症状Agent 反复执行同一个操作上下文里堆满了相同的错误信息。排查思路先看错误信息是否完全一致。如果完全一致说明 Agent 没有从错误中学习可能是上下文里缺少“这个操作已经失败过”的明确提示。解法是在验证失败时除了写入错误信息还要写入一条“禁止重复此操作”的指令。如果不完全一致但高度相似说明 Agent 在微调参数但方向错误需要触发策略重规划。避坑技巧给每个工具调用生成一个指纹工具名 参数哈希在上下文里维护一个“已尝试指纹”集合。当 Agent 尝试一个已存在的指纹时直接拦截并提示“此操作已尝试过结果如下”避免无效重试。5.2 上下文溢出与信息丢失的平衡症状压缩后 Agent 突然“忘记”了之前的关键信息开始重复已完成的工作。排查思路检查压缩时是否误删了决策点记录。决策点识别逻辑可能漏判了一些关键轮次。另一个可能是摘要生成质量太差丢失了关键细节。避坑技巧压缩后加一步“一致性检查”让模型回答几个关于任务状态的问题比如“当前完成了哪些步骤”“下一步计划是什么”如果回答与压缩前矛盾说明压缩过度需要回滚并调整压缩比例。5.3 沙箱环境不一致导致的诡异错误症状同样的操作在本地测试正常在沙箱里报错。排查思路对比本地和沙箱的环境差异重点检查工作目录、环境变量、依赖版本、文件权限。沙箱重置不彻底是常见原因上一个任务留下的文件可能影响当前任务。避坑技巧沙箱重置时做一次“干净度检查”列出工作目录所有文件与初始状态对比多出来的文件全部删除。环境变量恢复成基线快照。这个检查耗时不多但能拦住大部分环境不一致问题。5.4 长时运行中的内存泄漏与资源耗尽症状任务运行几小时后进程内存持续增长最终被系统杀掉。排查思路检查上下文管理是否及时释放了不再需要的对象。日志和检查点数据是否无限累积。沙箱池是否有实例泄漏借出后没归还。避坑技巧给所有资源加计数器定期打印资源使用快照。上下文对象用弱引用持有避免循环引用。日志文件按大小滚动检查点只保留最近 N 个。沙箱实例加超时自动回收。5.5 验证器误报与漏报的调优症状验证器频繁拦截正常操作或者放过了明显错误的结果。排查思路收集误报和漏报的案例分析规则哪里过严或过松。格式验证的误报通常是 Schema 定义太死语义验证的漏报通常是规则覆盖不全。避坑技巧验证器加一个“影子模式”新规则先只记录不拦截观察一段时间后再决定是否启用。这个模式让我们在调整验证规则时有了数据支撑避免了拍脑袋改规则导致的连锁问题。问题类型典型症状首选排查方向快速缓解措施循环卡死重复相同操作检查错误反馈是否明确加指纹拦截上下文溢出压缩后失忆检查决策点保留情况回滚压缩调比例沙箱不一致本地正常沙箱报错对比环境差异加强重置检查资源泄漏内存持续增长检查对象释放和池管理加资源计数器和超时回收验证误报正常操作被拦截检查规则严格度启用影子模式观察6. 长时运行场景下的进阶优化6.1 任务分解与子任务编排超过一定规模的任务单靠一个循环跑到底效率很低。我们的做法是在 Harness 上层加一个“任务编排器”把大任务拆成子任务每个子任务独立运行一个 Harness 实例子任务之间通过消息队列传递结果。这样单个子任务失败不影响整体重试成本也低。拆分粒度是个经验活。太粗起不到隔离作用太细增加编排开销。我们的参考标准是每个子任务能在 10 到 30 分钟内完成步骤数在 30 到 80 之间。这个范围是根据上下文消耗速率和错误恢复成本综合定的。6.2 跨会话的状态继承有些任务需要跨会话保持状态比如一个持续多天的数据收集任务。我们的方案是把持久化层做成独立的服务Harness 实例启动时从服务加载状态运行中定期同步结束时写回。状态服务用版本号做并发控制避免多个实例同时修改同一任务状态。6.3 监控与告警体系生产环境的 Harness 必须有监控。我们采集的指标包括每轮循环耗时、上下文使用率、验证通过率、工具调用成功率、检查点写入延迟。这些指标按任务 ID 和时间维度聚合异常时触发告警。告警阈值不是固定的而是根据历史数据的百分位数动态调整避免误报。这套监控体系帮我们提前发现了多次潜在故障比如上下文使用率异常攀升往往预示着 Agent 陷入了低效循环验证通过率骤降通常意味着任务环境发生了变化。7. 我个人在实际操作中的几点体会做 Harness 工程这一年多最大的感受是Agent 的智能程度取决于模型但 Agent 的可靠程度完全取决于 Harness。我们花在调提示词上的时间可能只占两成剩下八成都在打磨循环、上下文、沙箱、验证和持久化这些“脏活累活”上。但正是这些脏活累活决定了 Agent 能不能从 demo 走向生产。另一个体会是不要追求一步到位。我们最初的 Harness 只有循环和沙箱验证和持久化都是后来遇到问题才补上的。每个模块都是在真实故障的驱动下逐步完善的。如果你刚开始做建议先把循环和上下文管理做扎实这两个是基础中的基础其他模块可以边跑边加。最后分享一个小技巧给 Harness 加一个“回放模式”。把任务执行过程中的所有输入输出记录下来需要调试时用回放模式重新跑一遍但模型调用和工具执行都走录制的数据。这个模式让我们能在不消耗模型额度的前提下复现问题调试效率提升非常明显。这个功能实现起来不复杂但在排查偶发问题时价值巨大。