Agent Harness 集成决策模型的工程实践：从不可控到可审查-北京尧图网络

做 Agent 相关项目的时间越长我越觉得“执行框架Harness”和“决策模型Decision Model”是两件经常被混为一谈的事。去年我做一个偏向业务落地的 Agent 时框架倒是跑得很顺上下文管理、工具调用、记忆缓存全都有现成方案可一旦开放了十几个工具模型就开始自由发挥一会儿重复查同一个接口一会儿跳过必要步骤直接给结论。后来我把“让模型自己决定下一步”改成“由 harness 内嵌一套显式决策模型来接管”情况才慢慢好转。这篇算是把这段集成经验整理一遍适合正在把 Agent 从 Demo 推向生产环境、却觉得“模型行为不可控”的开发者。内容不绕弯子也不逐行分析某个开源框架源码只讲集成思路、落地细节和踩过的坑。你不需要懂太多算法只要写过一点 Agent 代码能理解工具调用和对话循环就能跟得上。1. 为什么说 Agent Harness 缺的不是执行力而是决策力1.1 Harness 管的是“跑起来”Decision Model 管的是“下一步”先说清楚这两个词在我这里的定义。Agent Harness也就是执行框架它负责的是那些“力工活”接收用户输入、组装上下文、维护对话历史、注册和调度工具、把工具结果写回状态、控制 token 长度、处理多轮记忆。它像一个外骨骼让模型能够“伸手”去调用外部系统。但“下一步到底该干什么”在大多数框架里其实是交给模型自己临场发挥的。模型看着一堆工具描述凭感觉挑一个调用挑错了就换个工具再来一次。这个过程叫决策而框架本身并不承担决策责任它只负责执行决策产生的结果。Decision Model 就是把“下一步做什么”这件事从模型的潜意识里拿出来变成一个显式、可审查、可替换的模块。它可以是一段规则、一个状态机、一份计划清单也可以是规则和 LLM 的混合体。集成到 harness 里之后模型不再是唯一的脑harness 本身开始有脑。1.2 显式决策模型解决的三个根子问题我把“没有显式决策”的 Agent 遇到的核心问题归纳成三类。第一是不可复现。同一个用户问题同一批工具模型这次可能先查订单再查物流下次可能先查物流再查订单甚至第三次直接跳过订单查询去猜结果。所有的工具调用“轨迹”完全随机。做测试的人最烦这个bug 报过来复现不了因为决策路径本身是漂移的。第二是不可审查。项目上线之后出了个错误结论你想查清楚 Agent 为什么走错了。打开日志只有一句“调用了某工具”没有“为什么调用”的记录。因为决策依据在模型的隐状态里你根本捞不出来。这种 Agent 没法做责任追溯在业务方眼里等于黑箱。第三是不可干预。业务方说“退款金额超过一千元必须人工确认”你说好然后你打开了代码发现根本不知道在哪里加这个逻辑。加在工具调用前模型不保证遵守。加在工具调用后又太晚了。没有决策层你没有一个明确的“关卡”去拦截或放行。显式决策模型把这三件事一起解决了决策有依据、有记录、有拦截点。这也是我认为它值得被集成进 harness 的最大理由。1.3 常见的决策模型有哪些形态自由提示式直接把指令写进 System Prompt让模型自行决定每一步。实现成本最低但稳定性最差。约束式用工具调用 Schema、Few-shot 示例、甚至 JSON 模式限制决策输出格式。比纯提示可靠一点但模型该跑偏还是会跑偏。预编排式提前定义好流程、DAG 或状态机模型只能在预设节点里做局部选择。可控性最高灵活性最低。混合式先走规则分流再把模糊情况交给 LLM 决策。兼顾可控与灵活是我实际落地时最常用的一种。这几种形态不是互斥的一个复杂业务里完全可以共存。比如全局用状态机控流程流程内某个节点用 LLM 做内容抽取抽取结果再套一层规则阈值校验。集成 Decision Model 进 harness本质就是把这些形态放到一个统一的可插拔框架里。2. 一个能装决策模型的 Harness 应该怎么搭2.1 先分清楚三层工具注册、决策策略、执行循环很多现成框架会把这三层揉在一起看起来方便其实给集成决策模型留的口子特别小。我自己的习惯是把 harness 拆成三个独立部分工具注册层只管“有什么工具可用”每个工具都要有名字、描述、参数 Schema、以及真实的处理函数。决策策略层负责“选哪个工具、要不要选、何时终止”。执行循环层负责“把决策变成动作再把动作结果写回状态”。这个拆法的好处是每一层都能独立测试。工具层写单元测试决策层做决策回放测试执行循环做集成测试。你不需要为了验证一个决策逻辑去启动整套 Agent。# 工具注册层的最小设计 dataclass class ToolSpec: name: str description: str parameters: dict handler: Callable # 执行状态决策层与执行层通过它通信 dataclass class AgentState: user_input: str history: list observations: dict steps: list done: bool False有人可能会觉得多包这么一层很麻烦。但生产环境里工具数量超过十个之后这层“壳”带来的收益远大于成本。它让工具发现、参数校验、权限控制都有了统一地盘否则你只能在各个调用点四处打补丁。2.2 决策接口这么设计才能让模型“随时可换”决策模型是整个 harness 里最核心的插槽。接口设计得好后续换策略、加规则、做 A/B 对比都很轻松设计得差哪怕只是让决策逻辑多一个分支都要动主循环代码。我习惯用一个统一的决策动作返回值包含动作类型、目标工具、参数、以及决策理由。dataclass class Decision: action: str # call_tool / ask_user / finish / replan tool_name: str reason: str 然后定义决策策略接口class DecisionPolicy(ABC): abstractmethod def decide(self, state: AgentState) - Decision: ...所有具体策略都实现这个接口。LLM 自由决策是一种策略规则分流是一种策略状态机也是一种策略。你在 harness 里只需要依赖这个接口完全不关心背后是模型在选还是代码在选。这里的 key point 是决策返回值里一定带上reason字段。别小看这个字段它是后面决策日志、错误分析、甚至用户解释机制的原材料。没有 reason你做的就不是可解释决策仍然是个黑箱。2.3 主循环的核心逻辑与决策状态回传决策模型集成进 harness 之后主循环会变得非常朴素。逻辑只有一个原则harness 不决定“做什么”只负责“做了之后记录结果”。def run(harness, policy, user_input): state harness.init_state(user_input) while not state.done: decision policy.decide(state) if decision.action call_tool: result harness.execute_tool( decision.tool_name, decision.args ) state.observations[decision.tool_name] result state.history.append((tool_call, decision, result)) elif decision.action ask_user: user_reply harness.request_user_input(decision.reason) state.history.append((user_reply, user_reply)) elif decision.action finish: state.done True return state只要坚持这种写法决策策略的回传信息就会自动进入state.history变成后续决策的依据。你可以在不改变主循环的前提下分别实现对同一批历史数据做不同决策策略的离线对比。实际操作中我给每个策略都加了一个版本号字段。决策日志里会记录当前策略是 v1.3 还是 v2.0。这样当线上决策效果变化时你能立刻定位是策略更新造成的还是外部数据变化造成的。这个习惯帮我排查过好几次莫名其妙的线上波动。3. 三个真实场景三套决策模型落地对比3.1 工具一多就乱调用规则分流加 LLM 兜底场景是我早期做客服 Agent 时的日常。工具清单里有订单查询、退款申请、物流跟踪、优惠券计算、发票申请等二十多个接口模型经常犯的毛病是“用户问的是退款进度它先去调了优惠券接口”。原因也简单工具描述越长越多模型对意图和工具之间的映射就开始模糊。我当时没有选择把所有决策都交给 LLM 反复推理因为每次推理都花钱花时间。我加了一道规则分流层先做一个轻量意图匹配把用户输入和工具描述做一次相似度计算同时配合关键词规则筛出候选工具集。如果候选工具只有一个且置信度高于阈值直接调用不走 LLM。如果候选工具多于一个才把候选集交给 LLM 决策。如果所有候选置信度都低于阈值决策结果直接是ask_user让用户澄清意图而不是盲目猜测。这个改动上线后工具误调用率直接下降了一个量级。而且很多高频简单问题根本不需要大模型参与决策响应延迟从秒级降到百毫秒级。规则层不是来替代 LLM 的是来帮 LLM 挡掉那些它不该做的低难度决策的。3.2 多步任务记不住进度计划执行模型接管第二个场景是用户让 Agent 做多步比较比如“对比这三款设备的参数并给出哪款更适合办公的建议”。自由决策模式下模型经常查完设备 A 就忘了还差设备 B、C或者查完参数之后直接开始编结论完全无视上下文里已经存在的工具返回结果。这个问题靠加 Prompt 很难根治因为模型的注意力会被长上下文稀释。我换成了 Plan-and-Execute 式决策模型首轮决策让 LLM 生成一份结构化计划harness 保存计划并逐条执行执行过程中不再让模型自由选择下一步。[ { step: 1, tool: product_detail, query: 设备A 参数 }, { step: 2, tool: product_detail, query: 设备B 参数 }, { step: 3, tool: product_detail, query: 设备C 参数 }, { step: 4, tool: comparison_report, context: 前三步结果 } ]计划执行的好处是每一步工具调用都严格对应计划如果某一步失败harness 会带着失败状态回到一个“重规划”决策点让 LLM 只针对失败步骤做修正而不是推翻全局。这样既不牺牲灵活性又让大部分路径可以被预测和测试。实测同一批任务改用计划执行后任务完成率明显提升token 消耗反而下降了。原因很朴素模型不需要每一步都重新阅读全部历史再决定下一步计划已经在上下文里铺好了执行过程更像“按清单做动作”。3.3 流程不能出错状态机把决策范围框死第三个场景是流程强约束业务。比如退款审批、数据订正这类操作合规要求决策动作必须按固定顺序走任何一步都不能跳过。这种情况下我根本不想让模型有“自由发挥”的空间而是用一个状态机决策模型。状态被定义成固定枚举received、verifying、confirming、executing、completed。在每个状态内模型只能从预先定义好的动作集合里选择。比如verifying状态下模型可以决定“资料是否齐全”动作只有proceed、reject、request_more_info三种不存在第四个选项。同时 harness 层做状态转移校验状态只能按定义好的方向流转任何非法跳转都会被拒绝并报错。这样模型再聪明也没有办法绕过“人工确认”这个强制节点。维度自由决策规则分流计划执行状态机可预测性低中较高高灵活性高中中低实现成本低中中较高适合场景开放问答工具多而杂多步任务强合规流程这张表基本就是我选型时的判断依据。没有哪一种在所有维度上都赢关键看业务当下更缺什么缺灵活性就上自由决策缺稳定性就上状态机。4. 集成过程中那些绕不开的坑4.1 决策空转模型在同一个工具上反复打转集成决策模型之后我最先遇到的坑不是模型不会选工具而是它会在同一个工具上反复打转。比如查询订单接口返回了系统繁忙模型马上再调一次同一个接口还是繁忙再调一次。整个过程看起来像在努力解决问题实际上是在空转。问题出在决策策略没有“记住”自己刚刚做过什么。解决方案是在 harness 里加一个工具调用指纹把“工具名加参数摘要”计算成一段哈希连续出现两次及以上相同指纹时强制策略进入收尾分支不再允许继续尝试相同调用。current_fp fingerprint(tool_name, decision.args) if current_fp state.last_fingerprint: state.repeated_calls 1 else: state.repeated_calls 0 state.last_fingerprint current_fp if state.repeated_calls 3: return Decision(actionask_user, reason工具连续多次返回相同异常需要人工介入)这个逻辑看起来很笨但它非常有效而且能被测试覆盖。决策模型再聪明也需要外部机制兜底因为它天然地“不擅长承认自己做不到”。4.2 工具超时后决策模型还在装没事另一个高频坑是工具执行超时。外部接口在指定时间没返回harness 直接把异常抛给了决策层。很多模型面对异常的第一步反应是换一个相似工具试试而不是回到用户侧确认。如果刚好那个相似工具也需要访问同一个下游系统结果就是连环超时。我后来规定工具执行结果必须带一个明确的状态码不能只给一句“成功了”或“报错了”。决策策略拿到状态码之后先做一次状态判断再做动作选择。状态码含义SUCCESS工具正常返回TOOL_ERROR工具逻辑内部错误TIMEOUT执行超时RATE_LIMIT触发限流NEED_PERMISSION需要用户授权或人工审批状态码里我最重视RATE_LIMIT和NEED_PERMISSION这两个。很多线上故障都是因为决策模型不知道“当前动作被限流了”和“当前动作需要人工审批”于是反复尝试无意义的重试。把这些状态回传到决策层模型才有机会做出正确判断。4.3 上下文快满时决策质量断崖式下跌上下文窗口紧张带来的决策质量恶化比想象中来得更早。工具一多每轮还要带着历史工具返回结果到第五六轮时可用 token 就开始紧张了。这时候模型的表现不是“变笨”而是“变得保守”或者“变得激进”有时候干脆不调用工具直接凭印象回答。我给 harness 加了一个上下文预检机制在每次决策前估算剩余 token 量低于阈值时自动切换决策模式。一种模式是把长工具结果压缩成摘要再参与决策另一种是提前结束自由探索把未完成事项转成交给用户确认的清单。压缩摘要这一步要谨慎不要把关键字段丢掉。我踩过一次坑压缩后摘要丢失了用户订单号导致后续决策引用了一个不存在的订单号整个流程走歪。后来我的摘要在压缩的同时保留所有实体字段和数字字段宁可摘要长一点也不能丢关键信息。5. 把决策过程变成可观测、可评估的资产5.1 决策日志怎么记才不白记集成决策模型之后的另一大好处是决策日志不再是“模型输出了什么”而是“模型为什么这么选”。我用的决策日志是 JSON Lines 格式每条决策一行至少包含以下字段{ turn: 12, context_tokens: 8210, candidates: [order_query, refund, coupon], decision: call_tool:order_query, reason: 用户问题包含订单号优先匹配订单状态查询, result_status: SUCCESS, latency_ms: 312, policy_version: rulesllm-v3 }记录的时候要克制没必要把完整上下文和工具返回结果全部塞进去那会让日志文件变得非常庞大。重点记录决策输入的关键摘要、决策输出、以及决策理由。完整上下文可以单独存一份按 trace_id 关联的明细需要排查时再拉出来回放。有了这份日志你就可以对历史决策做离线评估把某一天的日志重新喂给新的决策策略看它是否会在同样的场景做出更好的选择。这个过程不需要线上改动就能提前预估策略变更的影响范围。5.2 衡量决策模型效果的四个指标评估一个决策模型好不好不要只看“任务成功率”那是结果指标太粗了。我日常跟踪四个相对细的指标决策有效率所有工具调用里真正对推进任务有帮助的占比。如果频繁出现“调用工具后结果没用上”说明决策层对候选工具的理解不够。平均决策延迟从发起决策请求到拿到决策结果的时间。纯 LLM 决策通常会比规则决策慢一个数量级这也是我建议规则优先的原因之一。策略漂移率相同输入和状态下多次决策结果不一致的概率。这个指标高说明策略里随机性太强测试和审核都会很痛苦。人工兜底率最终需要用户澄清或人工介入的任务占比。这个指标最能反映决策层对“自己能力边界”的认知不是越低越好而是应该稳定在合理区间。这四个指标定期画趋势线能很快看出哪次策略调整真正产生了收益哪次只是自我感觉良好。有一次我把计划执行模型的提示词调得更详细任务成功率没变化但平均决策延迟涨了 30%全靠指标曲线才定位出来。5.3 我的落地顺序建议先规则再模型后混合如果你现在正打算给现有 Agent 集成决策模型我强烈建议不要一步到位上大而全的框架。我自己的落地顺序是这样的第一阶段先做决策日志埋点。不改变现有行为只是把每次“为什么选这个工具”记录下来哪怕是事后根据上下文补写 reason。没有数据后面所有优化都是拍脑袋。第二阶段把最高频、最容易出错的 3 到 5 个场景改成规则决策。比如意图匹配命中就给固定工具映射命中不了才走原逻辑。这一阶段就能明显感受到可控性提升。第三阶段针对低置信度场景引入 LLM 决策并套上版本号。接着用第一阶段的日志做离线对比确认新策略确实更优后再灰度上线。第四阶段才考虑把状态机、计划执行这些重型模型引入关键流程。到这一步时整个 harness 的决策插槽已经被验证过是稳定的再往里加复杂策略风险就小很多。整个过程中最容易被忽略但最值得投入的是维护一套“决策回放测试集”。把线上出错的高价值案例沉淀下来每次改策略先跑一遍回放确认老问题不再犯、新问题没引入。这套测试集比任何架构设计都更能帮你稳住线上质量。集成决策模型这事本质上不是给 Agent 装一个更聪明的脑子而是给团队装一个能评审、能修正、能测试的决策机制。模型的能力会迭代工具的接口会变但只要决策层和 harness 之间的这个插槽还在后续所有优化都有落脚点。我个人实际操作下来的体会是花了最多时间的部分不是写策略而是把决策动作、决策理由、执行状态这三者的数据流理顺。理顺之后不管是接新工具还是调决策策略都会变得很顺。你甚至可以把这套插槽延伸到多 Agent 协作场景——当多个 Agent 需要互相让渡控制权时这个决策模型就会自然升级成“协作层决策”当前这套集成思路可以原封不动地复用过去。

Agent Harness 集成决策模型的工程实践：从不可控到可审查

相关推荐

AI短剧翻车视频为何比正片还火：一套驯服AI的内容创作方法论

Vue+Node高校计算机课程评教系统开发实践

ViTPose/MMPose 人体姿态估计 FP16 混合精度训练实战：ResNet-50 COCO 256x192 动态损失缩放配置全解析

更多资讯

PS5通用优化方案：截图、串流、存储与网络设置全指南

基于MATLAB矩量法的电磁散射RCS计算与三维扩展

WordPress高并发架构实战：LNMP环境与三层缓存策略解析

SDD驱动的AI工程开发：用契约重构编程思维

KUKA机器人EtherNet/IP直连工业相机：配置、坐标映射与避坑指南

ffdec-18.5.0深度指南：SWF反编译、AS3反混淆与Flash遗产抢救

今日更新

小波包能量谱原理与MATLAB实现：从频带分解到故障特征提取

基于LSTM的网易云音乐评论情感分析：数据清洗与模型调优实战

Alpha-Beta剪枝与极大极小值算法：博弈树搜索原理与实战优化

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？