1. 从“能跑”到“跑得稳”Agent 稳定性问题的工程化破局思路做 Agent 开发的人大概都有过这种体验Demo 阶段一切丝滑一旦放到真实业务里跑上几百上千次各种稀奇古怪的失败就开始冒出来。同一个输入今天返回正常结果明天可能就卡在某个工具调用上死循环上一秒还在按预期规划步骤下一秒就自作主张跳过了关键环节。这种“薛定谔的稳定性”几乎是每个把 Agent 往生产环境推的团队都会撞上的墙。Harness Engineering 这个提法核心就是把 Agent 的稳定性问题从“调参玄学”拉回到工程可控的范畴。所谓 Harness原本指的是测试夹具、约束框架在这里我把它理解为围绕 Agent 构建的一整套运行时约束、观测、干预与恢复机制。它要解决的不是“让模型更聪明”而是“让系统在模型不够聪明、不够稳定的时候依然能给出可接受的结果”。这套东西适合谁看如果你正在把基于大模型的 Agent 从原型往线上推或者已经被各种偶发失败折腾得够呛那接下来的内容应该能帮你省下不少试错时间。我自己的体会是Agent 的稳定性问题八成以上不是模型能力问题而是工程问题。模型本身有随机性这是客观事实但我们可以通过外部的工程手段把这种随机性带来的影响控制在可接受范围内。Harness Engineering 就是干这个的。2. 拆解 Agent 不稳定的根源为什么“聪明”不等于“可靠”2.1 模型随机性与任务确定性的根本矛盾大模型的输出本质上是概率采样。同样的 prompt温度参数不为零时每次生成的 token 序列都可能不同。对于闲聊场景这种多样性是优点但对于需要精确执行的任务型 Agent这就是灾难的源头。一个订票 Agent这次可能正确地先查航班再选座位下次可能直接跳到支付环节因为它“觉得”用户已经选好了。这个矛盾没法从模型内部消除只能从外部约束。Harness 的第一层作用就是在模型输出和实际执行之间插入一个校验与修正层。比如强制要求 Agent 在调用任何写操作工具前必须先输出一个结构化的“执行计划”由 Harness 校验计划完整性后才放行后续调用。这相当于给模型加了一道“安检门”不让它直接冲到危险操作面前。2.2 工具调用的不确定性放大效应Agent 和普通 LLM 应用最大的区别在于它会调用外部工具。每一次工具调用都是一次网络请求、一次状态变更失败概率会随着调用链长度指数级放大。假设单次工具调用成功率是 99%一个需要连续调用 10 次工具的任务整体成功率就掉到 90% 左右如果调用 50 次成功率只剩 60% 出头。更麻烦的是工具调用失败后的处理逻辑往往很脆弱。模型看到报错信息后可能选择重试、可能换一个工具、也可能直接放弃并编造一个结果。Harness 需要在这里做的是统一工具调用的错误分类、重试策略和降级方案让模型不需要自己“思考”怎么处理错误而是由工程层兜底。2.3 上下文漂移与状态污染长对话或多步任务中上下文会不断累积。早期的一个小误差经过多轮传递后可能被放大成完全偏离目标的结果。比如 Agent 在第一轮误解了用户意图后面所有步骤都建立在这个错误理解上越走越偏。这种“上下文漂移”在长任务中特别常见。Harness 的应对思路是引入“状态快照”和“意图锚点”。每隔若干轮强制 Agent 重新确认当前状态与原始目标的对齐情况同时把关键状态如已完成的步骤、当前持有的数据从对话历史中抽离出来存到外部结构化存储里避免被后续对话污染。3. Harness 核心机制设计给 Agent 套上“工程缰绳”3.1 执行计划校验让 Agent 先“说清楚”再“动手”最有效的稳定性手段之一是强制 Agent 在行动前输出结构化计划。这个计划不是自然语言描述而是类似 JSON 的步骤列表每一步包含操作类型、目标工具、输入参数、预期输出、失败处理策略。Harness 拿到这个计划后做几件事检查步骤之间的依赖关系是否合理比如有没有在获取数据之前就尝试写入检查工具调用权限比如当前用户是否有权执行该操作检查参数完整性比如必填字段是否缺失检查计划长度是否超出限制防止无限循环只有全部通过才允许 Agent 开始执行。执行过程中每完成一步Harness 更新计划状态如果某一步失败按照预设的失败处理策略执行而不是让模型自由发挥。注意计划校验的粒度需要权衡。太粗起不到约束作用太细会让 Agent 变得僵化无法处理需要灵活调整的场景。我的经验是对写操作和外部副作用操作严格校验对读操作可以适当放宽。3.2 工具调用沙箱与幂等性保障工具调用是 Agent 最容易出问题的环节。Harness 需要为每个工具调用提供沙箱环境具体包括超时控制每个工具调用设置硬性超时超时后强制中断并返回标准错误重试策略区分可重试错误如网络抖动和不可重试错误如参数错误可重试错误按指数退避重试最多 N 次幂等性保障对于写操作要求工具本身支持幂等键或者由 Harness 在调用前检查是否已经执行过相同操作结果校验工具返回后校验返回结构是否符合预期 schema不符合则视为失败这些机制单独看都很基础但组合起来能挡掉大部分偶发失败。我见过太多团队在工具调用层裸奔出了问题才回头补代价是线上事故和用户信任流失。3.3 状态外置与上下文压缩前面提到上下文漂移问题Harness 的解法是把 Agent 的“记忆”从对话历史中剥离出来。具体做法是维护一个外部状态存储记录任务目标原始用户请求不可变已完成步骤列表含每步的输出摘要当前待执行步骤关键实体和变量如用户 ID、订单号、金额等每次模型需要决策时Harness 从外部状态构造一个精简的上下文注入 prompt而不是把全部对话历史塞进去。这样既控制了 token 消耗又避免了历史噪声干扰。对于超长任务还可以对已完成步骤做摘要压缩只保留关键信息。4. 实操落地从零搭建一个最小可用 Harness4.1 环境准备与基础依赖假设我们用 Python 来搭建这套东西核心依赖不多pip install pydantic jsonschema tenacity structlogpydantic用来定义计划、状态、工具输入输出的数据模型jsonschema用来校验工具返回结构tenacity提供重试装饰器省得自己写退避逻辑structlog做结构化日志方便后续排查问题不需要一上来就搞很重的框架先把核心链路跑通。我的建议是先用一个简单的命令行脚本模拟 Agent 循环把 Harness 的各个拦截点插进去验证逻辑正确后再接入真实的模型调用。4.2 定义计划与状态的数据结构先定义 Agent 执行计划的结构。这里用 Pydantic 模型from pydantic import BaseModel, Field from typing import List, Optional, Dict, Any from enum import Enum class StepStatus(str, Enum): PENDING pending RUNNING running SUCCESS success FAILED failed SKIPPED skipped class PlanStep(BaseModel): step_id: int action: str tool_name: str params: Dict[str, Any] expected_output: Optional[str] None on_failure: str abort # abort / retry / skip max_retries: int 2 status: StepStatus StepStatus.PENDING class ExecutionPlan(BaseModel): goal: str steps: List[PlanStep] current_step: int 0状态存储类似class AgentState(BaseModel): task_id: str original_goal: str plan: ExecutionPlan completed_steps: List[Dict[str, Any]] [] key_entities: Dict[str, Any] {} error_log: List[str] []这些结构看起来简单但它们是整个 Harness 的骨架。所有校验、重试、恢复逻辑都围绕这些数据结构展开。4.3 计划校验器的实现校验器接收模型输出的计划返回校验结果和修正建议def validate_plan(plan: ExecutionPlan, available_tools: dict) - tuple[bool, list[str]]: errors [] seen_step_ids set() for step in plan.steps: if step.step_id in seen_step_ids: errors.append(f重复的 step_id: {step.step_id}) seen_step_ids.add(step.step_id) if step.tool_name not in available_tools: errors.append(f未知工具: {step.tool_name}) continue tool_schema available_tools[step.tool_name][input_schema] try: jsonschema.validate(step.params, tool_schema) except jsonschema.ValidationError as e: errors.append(f步骤 {step.step_id} 参数校验失败: {e.message}) if len(plan.steps) 50: errors.append(计划步骤数超过上限 50) return len(errors) 0, errors校验失败时把错误信息返回给模型要求它重新生成计划。这里可以设置最大重试次数比如 3 次超过则终止任务并返回明确错误。4.4 工具调用执行器与重试逻辑执行器负责实际调用工具并处理超时、重试、结果校验from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type class ToolExecutionError(Exception): pass class RetryableError(ToolExecutionError): pass retry( stopstop_after_attempt(3), waitwait_exponential(multiplier1, min1, max10), retryretry_if_exception_type(RetryableError) ) def execute_tool(tool_name: str, params: dict, timeout: int 30): tool TOOL_REGISTRY[tool_name] try: result tool.call(params, timeouttimeout) except TimeoutError: raise RetryableError(f工具 {tool_name} 超时) except ConnectionError: raise RetryableError(f工具 {tool_name} 连接失败) # 校验返回结构 output_schema tool.output_schema try: jsonschema.validate(result, output_schema) except jsonschema.ValidationError as e: raise ToolExecutionError(f工具返回结构不符合预期: {e.message}) return result这里的关键是把错误分类做清楚。可重试错误走重试逻辑不可重试错误直接向上抛由计划层面的失败处理策略决定下一步。4.5 主循环与状态更新主循环把上面这些串起来def run_agent(task_id: str, user_input: str, max_turns: int 20): state AgentState( task_idtask_id, original_goaluser_input, planExecutionPlan(goaluser_input, steps[]) ) for turn in range(max_turns): # 1. 构造精简上下文 context build_context(state) # 2. 调用模型获取下一步动作或计划 model_output call_model(context) # 3. 如果是新计划校验 if model_output.get(type) plan: plan ExecutionPlan(**model_output[plan]) ok, errors validate_plan(plan, TOOL_REGISTRY) if not ok: state.error_log.extend(errors) continue # 让模型重新生成 state.plan plan # 4. 执行当前步骤 if state.plan.current_step len(state.plan.steps): step state.plan.steps[state.plan.current_step] try: result execute_tool(step.tool_name, step.params) step.status StepStatus.SUCCESS state.completed_steps.append({ step_id: step.step_id, result_summary: summarize(result) }) state.plan.current_step 1 except ToolExecutionError as e: step.status StepStatus.FAILED if step.on_failure abort: return {status: failed, error: str(e)} elif step.on_failure skip: state.plan.current_step 1 # retry 由 tenacity 处理 # 5. 检查是否完成 if state.plan.current_step len(state.plan.steps): return {status: success, state: state} return {status: max_turns_exceeded, state: state}这个循环虽然简化了很多细节但核心骨架是完整的。实际落地时还需要加上日志记录、指标上报、人工干预入口等。5. 常见问题与排查技巧实录5.1 模型不按格式输出计划怎么办这是最常见的问题。模型可能返回自然语言描述、可能返回不完整 JSON、可能字段名对不上。我的处理经验是分三层第一层在 prompt 里给出严格的输出格式示例并明确说明“只输出 JSON不要有其他内容”。第二层解析时做容错比如用正则提取 JSON 块或者用json_repair类库尝试修复。第三层如果还是失败把解析错误信息返回给模型要求重新生成最多重试 3 次。实测下来加上格式示例和重试机制后格式错误率能从 20% 降到 2% 以下。剩下的 2% 基本是模型能力边界需要换更强的模型或者简化计划结构。5.2 工具调用超时后状态不一致这是个隐蔽的坑。比如调用一个写操作工具请求发出去了但超时返回。实际上服务端可能已经执行成功了但 Agent 认为失败并重试导致重复写入。解法是要求所有写操作工具支持幂等键Harness 在调用前生成唯一键并记录重试时携带相同键服务端根据键去重。如果工具本身不支持幂等那就需要在 Harness 层做补偿检查超时后先查询目标状态确认是否已经变更再决定是否重试。这个逻辑因工具而异需要逐个适配。5.3 长任务中模型“忘记”原始目标前面提到的上下文漂移问题实际表现是模型在第 15 轮突然开始做一件和原始目标无关的事。排查时发现是因为对话历史太长原始目标被淹没在中间。解法就是状态外置。每次构造上下文时把原始目标放在 prompt 最前面并加上明确标记如“【原始目标不可更改】”。同时把已完成步骤压缩成摘要只保留关键结果。这样模型每轮看到的都是“目标 当前状态 待决策点”不会被历史噪声干扰。5.4 常见问题速查表问题现象可能原因排查方向解决手段计划校验频繁失败prompt 格式约束不足检查模型输出原始内容加强格式示例增加重试工具调用成功率低网络抖动或服务端限流查看错误类型分布分类重试加退避策略任务中途偏离目标上下文漂移检查上下文长度和内容状态外置目标锚定重复执行写操作超时后重试无幂等检查工具幂等性加幂等键补偿检查死循环无法终止计划步骤无上限检查计划长度设置最大步骤数和最大轮次提示这张表建议打印出来贴在工位上出问题时按行排查能省不少时间。6. 观测与迭代让 Harness 本身也能持续进化6.1 关键指标埋点Harness 跑起来之后需要观测它的效果。我一般关注这几个指标计划校验通过率反映模型输出格式的稳定性工具调用成功率按工具维度拆分定位薄弱环节任务端到端成功率最终业务指标平均重试次数反映系统抖动程度人工干预率需要人工介入的任务占比这些指标用结构化日志打出来接入现有的监控系统即可。关键是按 task_id 串联方便单任务回溯。6.2 失败案例的归因分析每次任务失败Harness 应该自动保存完整快照原始输入、每轮模型输出、工具调用记录、状态变更历史。定期抽样分析这些失败案例归类原因。常见类别包括模型理解错误、工具本身故障、计划设计缺陷、外部依赖超时等。归因之后针对高频原因做针对性改进。比如发现某工具超时率特别高就去优化那个工具的性能发现某类任务计划总是设计不合理就去调整 prompt 或增加 few-shot 示例。6.3 渐进式收紧约束Harness 的约束不是越严越好。初期可以放宽让 Agent 有足够自由度跑通流程随着对失败模式的理解加深逐步收紧关键环节的约束。比如一开始只校验写操作后来发现读操作也会出问题再把读操作纳入校验。这个渐进过程很重要。一上来就上全套约束很可能导致 Agent 什么都干不了反而打击团队信心。我的做法是先跑通再跑稳最后跑快。7. 一些踩坑之后的个人体会Harness Engineering 这套东西说到底是用工程手段弥补模型的不确定性。它不追求让 Agent 变得完美而是让它在不完美的情况下依然可用。我自己的体会是投入在 Harness 上的时间回报率远高于反复调 prompt 或换模型。模型会迭代但工程框架是积累下来的资产。另外一点Harness 的设计要跟着业务场景走。不同场景对稳定性的要求不同对失败的处理策略也不同。比如客服场景可以容忍偶尔答非所问但支付场景绝对不能容忍重复扣款。所以约束的松紧、重试的策略、降级的方案都需要根据具体业务来定没有一刀切的标准答案。最后分享一个小技巧在 Harness 里加一个“干跑模式”让 Agent 只生成计划不实际执行工具用来快速验证计划逻辑是否正确。这个模式在调试阶段特别有用能省下大量因为误操作导致的环境清理时间。