开头先讲个我最近的真实经历。团队内部有个 Agent demo跑得很欢能聊天、能查资料、能调用内部系统。但一放进生产环境立刻暴露问题对话轮次稍微长一点上下文就乱模型输出有时候直接截断工具调用的报错信息被原样丢给用户整个链路完全没有可观测性。代码在里面转得像是台装满杂物的洗衣机——能转但没人知道里面发生了什么。后面我把这套东西重构了一版核心思路就是题主提到的这句话把 Agent 框架拆开基于 PI 方案做一个生产级的 Harness。这里的 Harness 不是 CI/CD 里那个测试夹具而是在 Agent 场景下承上启下的执行装配层。PI 方案也不只是“Personal Intelligence”它更是一种架构取向——把规划Planner和解释执行Interpreter彻底分开。这篇文章不聊概念我把整个拆解过程、难点、踩坑点和优化策略写清楚给正在做 Agent 项目、尤其是从 demo 往生产环境推进的团队一个直接可参考的落地路径。1. Harness 到底是个什么东西先厘清边界再谈开发很多人把 Harness 和 Agent 本身混为一谈这是我见过最多、也最浪费时间的误解。Agent 是高层的“大脑嘴巴”负责理解意图、生成回复、决定下一步行动。而 Harness 是包在 Agent 外面的那层“骨骼血管神经”——它负责环境准备、上下文传递、工具注册、错误拦截、执行调度、日志追踪。没有 Harness 的 Agent 就像没有操作系统的计算机硬件再强也没法跑复杂任务。1.1 Agent 与 Harness 的本质差别我习惯用一个比较写实的类比Agent 是刚毕业的聪明实习生Harness 是围绕这个实习生建立的一套工作制度和管理流程。实习生专业能力很强但需要清晰的指令、需要有人帮他查资料、需要把任务拆成可执行的步骤、需要在出错的时候有人拦截重试、需要把做过的事情记录下来。Agent 负责任何单一节点上的“智能”Harness 负责让这些“智能”能稳定串联成一个可交付的完整流程。从代码层面看两者的边界更直观。Agent 的核心代码通常是 prompt 组装 LLM 调用 返回解析它关心的是“这一轮该怎么回应”。Harness 的核心代码则是循环调度器、状态管理器、工具注册表、错误处理链、追踪上下文。它关心的是“整个多轮任务怎么在一个稳定环境里跑完”。这个边界不清最典型的症状就是你会在 Agent 类里看到大量 handle_error、retry_logic、memory_dump 之类的代码。短期看着能用时间一长逻辑全缠在一起模型输出稍微变点格式整个模块就要推倒重来。1.2 开发生产级 Harness 的四个硬性指标拆开设计之前先定指标。生产级不是说代码写得花哨而是以下四个维度必须同时达标确定性同样的输入任务在模型输出质量波动的情况下系统最终的成功率和失败模式要基本可控。可观测性每一步计划生成、工具选择、工具执行、回复生成都必须能被追踪、被记录、被回放。容错性模型输出格式错误、工具超时、API 限流、上下文超长这些不应该让整个任务直接死掉。可扩展性加一个新工具、换一个底层模型、调整一个任务类型不能靠改核心代码来实现。这四个指标是评审 Harness 设计优劣的标尺。后面所有模块拆解本质上都是在为这四项服务。2. PI 方案的内部骨架Planner 与 Interpreter 的分工逻辑PI 不是什么新发明的名词但把它落到 Harness 设计上确实很实用。PI 方案把 Agent 的执行逻辑抽象成两层Planner规划层和 Interpreter解释执行层。我在生产环境重构时把原来的大 prompt 单体架构整个推翻就按这个分层重写。2.1 Planner 层把目标拆成可执行单元Planner 的职责只有一个拿到用户目标产出可执行计划。这个计划不能是一句空话必须是一串结构化的步骤。我见过很多失败的 Agent问题就出在 Planner 身上——它产出的计划太模糊。比如用户问“帮我分析上个月的销售数据并生成报告”模糊的计划是“分析数据生成报告”这种计划只能在 demo 里跑通因为 demo 的数据和逻辑都是预设好的。生产级计划必须明确到步骤1调用 sales_data_fetcher 获取上月数据步骤2调用 data_cleaner 去除异常值步骤3调用 report_generator 产出 Markdown 报告步骤4调用 notifier 把报告推送到指定群Planner 的输出必须是结构化格式JSON 或 YAML而不是自然语言。这样 Interpreter 才能稳定解析。2.2 Interpreter 层状态解释与原生工具绑定Interpreter 接收 Planner 输出的结构化计划逐条解释并执行。它有几个关键子任务子任务一工具调度。Interpreter 维护一张工具注册表将计划中的步骤名映射到实际的 Python 函数。这一步最讲究的就是工具绑定的稳定性。我在工具注册表里给每个工具设计了三个层级的信息功能描述给 Planner 看、入参出参 schema给 Interpreter 做校验、执行函数给代码调用。子任务二状态维护。每一步执行完Interpreter 要更新全局状态。这个状态包含已完成步骤列表、当前步骤的结果数据、剩余步骤、上下文积累。状态维护的重要性在于它是整个 Harness 可恢复性的基础。子任务三输出标准化。所有工具执行完无论返回什么格式Interpreter 都要把它转成统一的数据结构再喂给下一轮 LLM 调用。不然模型面对的数据格式杂乱推理质量必然下降。2.3 PI 方案与其他框架的取舍对比这里有个很关键的认知Agent 框架没有银弹。PI 方案的价值不在于比别的方案“更聪明”而在于它在工程上更好维护。我用一张表来说明几个方案的取舍方案主要优势主要劣势适用场景单体大 Prompt 方案搭建快、逻辑简单难维护、难调试、上下文浪费严重极简 DemoAgent 框架自动规划方案灵活性高、免手写流程黑盒调度、失败难复现、成本失控探索型任务PI 方案结构清晰、可控性强、易测试需要设计 Planner/Interpreter 协议、前期工作量稍大生产级任务流、工具密集型场景做生产级 Harness我个人强烈推荐 PI 方案。原因很直接可测试性。单体方案和全自动规划方案都很难对“计划生成”这个环节做单测因为你没法稳定控制模型的输出。PI 方案拆开后Planner 可以单独 mock 成固定输出做 Interpreter 的单测Interpreter 可以单独 mock 成工具执行结果做 Planner 的回归测试。这两者是本质区别。3. 生产级 Harness 落地的关键模块逐一拆解骨架定好了接下来是填肉。下面四个模块是我在实际重构中逐个踩坑踩出来的每一项都有真实的失败教训在里面。3.1 会话状态上下文管理第一版我直接用 Python dict 存储对话历史用户每发一条消息就 append 一条模型输出也 append 一条。看似没问题实际一跑就崩。问题出在“上下文爆长”上。多轮对话加工具调用一轮下来的 token 消耗比纯聊天大得多。工具返回的数据动辄几千字塞进消息历史里模型很快就被无关信息淹没。我的解决办法是“三级上下文结构”这也是 PI 方案拆开后的自然结果任务级上下文保存用户目标、Planner 的完整计划、当前步骤索引。这部分贯穿整个任务。步骤级上下文保存当前步骤的输入输出数据、工具执行的结果摘要。每步结束就替换不留冗余。全局记忆上下文保存跨任务的关键信息用户偏好、历史任务结论等。三级上下文的核心原则只有一个尽量少往模型 prompt 里塞原始数据塞经过提炼的摘要。这个思维转变帮我省了大量 token也让模型回复质量明显提升。3.2 记忆框架选型与分层记忆是 Agent 从“单轮问答工具”升级成“持续服务”的关键也是被讨论最多的部分。市面上的记忆方案很多向量数据库、Redis、SQLite、长期记忆、短期记忆、情景记忆……实际上不需要全上。我在生产环境做的是双层次记忆短期记忆任务进行中的上下文存内存或 RedisTTL 设置为 30 分钟。短期记忆的读写频率最高必须快不能引入太重的存储。长期记忆跨任务的关键信息摘要存向量库。每次任务结束后单独调一次 LLM 生成“本次任务的信息摘要”再向量化入库。这个“摘要入库”的步骤很多人会省省了的后果是长期记忆的召回质量极差。原始对话记录直接入库噪音太大而且存进去的信息未必是用户真正关心的。摘要化的过程相当于一个自动化的信息蒸馏。3.3 工具与 Skill 的接入机制工具接入是另一个容易翻车的地方。做 Harness 的人经常犯一个毛病把所有能想到的能力全做成工具往注册表里塞。结果 Planner 面对几十个工具的选择经常选错或犹豫既烧 token 又拉低准确率。我后来定了一条铁律工具按“场景包”注册而不是按“能力点”注册。什么叫场景包就是按用户使用场景把工具组合成一个 Skill。比如“周报生成”这个 Skill内部包含获取本周事件、整理格式、生成 Markdown、推送到群。对外暴露的时候只暴露一个接口。Planner 不用面对几十个细粒度工具只需要面对几个高内聚的 Skill。这个设计的好处不只是减少选择混乱更重要的是隔离变化。底层工具调整不影响 Planner工具体现给模型的功能描述和实际函数实现是两个独立版本可以分别优化。3.4 可观测性与 Tracing没有可观测性的 Agent 系统在生产环境里就是一个黑洞。用户报障说“机器人回得不对”你连它当时怎么想的都不知道。我在 Harness 里埋了一套结构化追踪日志每个关键节点都输出一条 JSON 日志用户原始输入Planner 输出的计划每步工具执行的结果摘要最终回复内容每步耗时和 token 消耗执行完成之后整个任务的所有追踪日志汇总成一个执行记录并落库。支持按任务 ID 查询随时回放。这套东西的调试价值极大。有一次模型突然在工具返回结果之后答非所问排查半天怀疑是 prompt 被污染最后靠回放日志发现是某次工具返回里包含了一段特殊字符串干扰了模型判断。如果没有追踪回放这种问题几乎无解。4. 从流水线到装配线执行引擎与编排策略Planner 和 Interpreter 是设计的核心但真正决定系统稳定性的是执行引擎怎么驱动这两个模块工作。执行引擎安排任务的方式直接描述系统的并发能力、失败恢复能力和资源消耗特征。4.1 同步编排与异步编排的取舍我第一版采用的是同步编排单线程依次执行计划中的每个步骤。好处是逻辑简单、状态一致性好、不需要考虑并发冲突。但单用户场景确实没问题多用户一压上来就崩了——准确说不是崩是体验急剧下降。一个用户的长任务跑着后面所有用户的请求都得排队等响应时间从秒级恶化到分钟级。后来我把执行引擎做成“事件驱动的异步编排”每个任务作为一个独立执行单元按事件流转触发下一步。计划生成完成触发工具执行工具执行完成触发状态更新状态更新完成触发下一步计划判断。核心是引入一个轻量级事件总线各环节通过发布订阅解耦。代价是复杂度上升收益是解决了并发问题。多用户的多个任务可以同时推进某个任务卡在慢工具上不会阻塞别的任务。4.2 重试、回退与熔断策略这一步是我在重构过程中投入时间最多的部分。AI 场景的错误处理比传统后端复杂得多因为错误来源不只有代码 bug还有模型输出的不确定性。重试策略工具调用失败超时、限流、网络错误直接重试重试次数上限 3 次退避采用指数退避间隔从 1 秒开始倍增。但模型 API 失败不能简单重试因为连续失败往往意味着 prompt 确实有问题继续重试只是浪费成本。回退策略当 Interpreter 执行工具失败且重试耗尽不能直接让任务死掉。我设计了一个降级策略把失败信息返回给 Planner让它重新规划换一条执行路径。Planner 重新规划出来的方案如果还是执行失败才宣告整个任务失败。熔断策略针对外部依赖系统的保护。比如某个数据源连续 5 次调用失败就把这个工具临时下线摘出注册表后续计划生成阶段不会再选中它。熔断持续 60 秒后自动恢复重新探测。4.3 并发与资源隔离多任务并发时有个隐蔽的坑资源竞争。最典型的例子是两个任务同时调用同一个外部系统触发了这个系统的限流导致双双失败。解决办法是给每一个外部依赖加上独立的信号量控制限制并发调用数设置为该系统允许并发上限的 70%。AI 模型 API 的并发控制更严格。我在 Harness 里实现了一个全局限流器按模型和模型部署类型区分每个维度独立限流。这个限流器兼顾两层API 服务商施加的硬限制以及预算控制模型按价格差异分别配额度。这些策略叠加起来的效果是系统不会因为某一个外部依赖的抖动而导致连锁崩溃。这是“生产级 Harness”在架构层面最核心的能力。5. 实测中的两个高频错误流式响应截断和执行终止有了上面的基础设计系统跑起来后会遇到各种实际问题。我挑两个出现频率最高、也最容易让新人懵的展开讲讲排查思路。这两个问题的名字就在标题的热搜词里说明大家普遍遇到很有代表性。5.1 malformed response 的完整排查链路现象是模型调用返回突然报错提示 response stream 格式异常没有产出有效响应。这种错误在流式输出场景下尤其频繁。第一步排查网络层。模型调用走的网络链路如果有不稳定的代理或中间层流式响应很容易被截断。这个问题在公网 API 调用时最常出现需要先排除网络因素确认是不是偶发的连接中断。第二步排查超时配置。很多模型 API 支持流式输出但客户端如果不及时接收数据部分实现场景下连接会被判定为超时。我从两个方向修一是增加 receive timeout 的配置二是启用自动重连机制。第三步排查返回体的解析逻辑。流式响应通常在结束时会有一个显式的结束标记。如果解析代码在生成结束标记时校验过于严格比如要求完整的 JSON 结构碰到模型输出被服务端截断的情况就会直接报 schema 错误。修复方式是加一个“宽松解析”模式解析失败时先保存原始响应到追踪日志然后用启发式规则尝试提取有用内容而不是立刻宣告失败。这套链路跑下来绝大多数流式响应问题都能定位。定位清楚之后要回到 Harness 设计层面做防御性改进。最有效的一个操作所有模型调用的输出都先过一层“响应规整器”把各种可能的格式问题在这个层统一处理Interpreter 永远只接收规整后的标准结构。5.2 execution terminated 的常见根因另一个高频错误是 Agent 执行在不明确的地方中途终止。这不是模型主动停止而是整个执行循环被异常打断。我排查过的根因有三类第一类是步骤状态更新崩溃。实现执行循环时我用一个共享变量记录当前步骤位置但没加锁。多任务并发时不同任务的循环体互相污染了状态变量导致步骤索引错乱触发异常终止。修复方式是每个任务独立的执行上下文对象彻底隔离不再有全局共享的可变状态。第二类是工具异常被暴力拦截。早期代码里工具执行包在 try-except 里但捕获异常后只是记录日志没有做任何处理循环直接退出。这种“静默终止”是最坑的用户只看到任务失败日志里却没有任何明确的失败原因。修复方式是把工具异常分成可重试、可降级、不可恢复三类分别走不同的后续链路。这个我之前在重试策略那一节讲过核心就是不要把所有异常一刀切。第三类是上下文长度触发保护机制。有些模型服务商在输入超长的时候会直接中断请求表现为任务终止。这类错误在排查日志里不太直观因为报错信息和上下文长度没有直接关联。我最后是给每次模型调用前的输入加了个 token 预估函数超阈值就自动触发上下文压缩把旧对话摘要化而不是硬着头皮继续调用。5.3 防御式编程处理 LLM 输出以上两类问题本质上是同一个大方向LLM 输出天然具有不确定性不能按传统编程的方式假设输出格式永远稳定。防御式编程在这一层极其重要。我给 Interpreter 加了一个“输出三重保险”第一重scheme 校验。模型输出先按声明格式校验不符合则尝试修复比如补缺失括号、修正类型。第二重语义降级。如果修复失败把模型原始输出作为纯文本交给下一个环节的专门解析器尝试提取关键信息而不是直接丢弃。第三重兜底回复。如果上面的全部失败直接向用户反馈系统暂时无法处理该请求并附带一个更简化的重新提问建议。这样即便模型完全失控用户感知到的也只是“这次没答好”而不是“系统异常”。这套保险机制叠加下来生产环境的可用性从 90% 出头提升到接近 99%。代价是代码量增加不少但这个投入完全值得。6. 测试那些容易被忽视的事用 pytest 给 Agent 系统上强度Harness 写完之后测试环节非常关键。但 Agent 系统的测试和普通后端测试有本质差异——不确定性因素太多不能按老思路测。6.1 测试的核心分层我按三个层次组织测试单元层针对各个独立模块的测试。Planner 解析工具 Schema 测、Interpreter 状态更新测、上下文压缩测、工具注册表测。这一层最容易写也最容易被跳过但覆盖了大部分纯逻辑。集成层针对模块间协作的测试。Planner 输出交给 Interpreter 的全流程测试工具执行结果喂给模型库再取回的标准链路测试。这一层要重点 mock 掉模型调用保证测试的确定性。回归层针对已知问题场景的保护性测试。比如上文说的流式截断、上下文超长都做成固定用例每次代码改动后跑一遍防止旧问题复发。6.2 模拟 LLM 输出集成层测试的核心技术点是用固定 mock 替代真实模型调用。我实现了一个 MockLLMClient支持从文件读预设响应按调用顺序返回。这样测试完全可复现不依赖真实模型 API。mock 的数据来源有三个渠道一是录制真实生产环境的模型响应。通过 Harness 的追踪日志系统把之前调用的真实响应保存成配置文件作为回归测试的基准数据。二是手工构造异常 case。比如故意造一个格式错误、空输出、超长输出的响应塞给 Interpreter验证三层保险机制是否正常触发。三是边界数据来源组合。构造一个完整普通过程的响应序列加上中途工具调用失败、降级路径重规划验证整个任务链路的容错表现。这套 mock 体系建好之后Agent 系统的测试效率有了质的提升。原来一次模型调用测试等 10 秒起步现在毫秒级完成而且不会因为模型响应波动导致测试偶发失败。6.3 整体回归的经验很多 Agent 项目会忽略一个事情系统重构之后原来能跑通的场景可能悄悄退化了。模型 prompt 改一行、工具描述改一句、上下文结构改一个字段都可能影响整体行为。我的做法是建一个“黄金用例集”。把之前所有线上处理成功的历史任务录制成场景用例每次大版本更新后全部跑一遍。这个用例集目前已经有几百个场景跑一次大概十几分钟。虽然耗时但每次发布前跑完心里确实有底。效果很直接线上出的 P0 问题绝大部分都是黄金用例集跑完后还漏掉的新场景而不是回归问题被改回来。7. 一个值得玩味的跨学科类比PI 参数整定与 Agent 控制这个章节的标题可能会让人意外但恰恰是我在这个项目里收获最启发性的一个角度。控制论里的 PI 控制器比例积分控制和 Agent 里的 Harness 设计虽然来自完全不同的领域内在逻辑惊人相似。控制系统的 PI 控制器有两个核心参数比例系数 P 和积分系数 I。P 决定系统对当前偏差的响应速度I 决定系统对历史累积误差的消除能力。P 太大系统震荡I 太大系统超调。只有把两个参数匹配好系统才能稳定收敛。映射到 Agent 系统里这个思路非常有意思。P 相当于 Harness 对“当前轮次状态”的响应强度。P 太弱模型遇到小问题不会纠正沿着错误路径一路跑到底。P 太强模型每一轮都过度反应稍微有点偏差就重新规划任务震荡不已。I 相当于 Harness 对“任务历史信息”的利用深度。I 太弱系统记不住上下文教训同样的错误会在多轮对话里反复出现。I 太强旧信息过度主导新信息反而被淹没。我在调 Harness 参数的时候就走过这个弯路。刚开始把 Planner 的重规划触发条件调得过敏感稍微检测到工具输出不符合预期就重新规划。结果系统像台疯狂摆动的钟摆全程在执行“规划-折腾-重规划”的循环效率极低。那段时间我天天对着输出日志叹气直到某次和做控制系统的朋友聊天他一句话点醒我“你这是临界震荡了P 太大了啊。”后来我把重规划触发条件调得更严格只有当连续两个工具执行都偏离计划时才触发重规划系统才稳定下来。这不就是 PI 控制器的 P 参数整定吗。这个类比给了我一个重要的方法论启发Harness 的本质是一个对不确定系统做稳定控制的控制器。我们有意识地按照“比例-积分-微分”的思路去设计 Harness 的各个反应机制。比例对应单轮响应积分对应跨轮状态累积微分对应趋势预判比如预计后续步骤可能超时提前告警。这套思路在后续迭代里成了一个很好的设计参照系。而且从热搜词里也能看到很多人同时关注“电压电流双闭环pi控制”和“pi agent”这两个词看似毫无关联背后其实共享着同一种系统思维你要在一个充满扰动和不确定性的环境里让一套系统稳定地逼近目标。控制论解决这个问题已经上百年了Agent 框架领域完全可以借鉴它成熟的设计思路。8. 最后聊聊开发节奏与团队配合技术细节聊到这里最后想聊一点方法论层面的东西。一个 Harness 从零到生产级研发节奏怎么把握团队配合怎么安排这决定了项目是按期落地还是无限延期。我经历的失败版本是“一口气憋大招”。架构设计想的无比宏大各种先进方案全面引入代码写了一个多月才看到第一版可运行的系统。结果一跑全是问题根本没法定位是哪一层的锅——因为太多新东西同时引入出错时完全无法归因。重构时我换了策略先跑通一条最小闭环再逐步替换薄弱环节。第一版 Harness 只实现了最简单的同步执行链路一个工具的调用、一个简单的状态管理、最基础的日志。先把这条路走通然后依次加入异步编排、重试机制、上下文压缩、追踪系统。每次只改一个变量出了问题立刻能定位到具体模块。这个策略在团队协作上也很有效。模块解耦清晰的情况下可以让不同的同事并行推进不同模块的开发一个人做工具接入规范一个人做执行引擎一个人做测试框架。只要接口定义得够清晰Planner 输出格式、Interpreter 事件约定互相之间的耦合就能控制在合理范围内。接口定义是整个项目里最重要也最需要提前投入的环节。具体地说要把 Planner 和 Interpreter 之间的协议当作一个“API 合同”来对待Planner 输出的 JSON 格式、每个字段的含义、可接受的值范围全都写清楚。这听起来很简单但真做的时候很容易被遗漏。我吃过最大的亏就是接口定义含糊大家各写各的联调时才意识到两边对“步骤状态”的理解根本不一致返工成本极高。工具接入规范也一定要提前定好。工具函数的命名规则、入参出参的 schema 标准、错误码定义这些看起来是细枝末节实则直接影响工具的接入效率。规范清晰的话新工具接入可能只需要半小时规范混乱的话一个工具接入能拖一整天。最后说一个团队认知层面的坑不要让所有事情都停留在“聊天记录”里。Harness 的设计文档、模块说明、接口定义、测试用例都必须是持续维护的正式文档。Agent 项目迭代速度极快两三个星期之后当时写的代码可能连自己都看不懂。文档是让这个系统可以被长期维护的唯一保障别嫌写文档麻烦你以后会感谢当时的自己。这篇从 Harness 边界讲到 PI 方案拆解再到执行引擎、错误排查、测试策略、跨学科启示和团队配合基本涵盖了把 Agent demo 推向生产级所需的主要工程环节。这套设计不一定适合所有团队但核心思路值得参考框架拆开边界划清控制收敛测试兜底。希望这段踩坑经历能给正在路上的人一些实实在在的帮助。
基于PI方案的生产级Agent Harness设计：从Demo到稳定落地
开头先讲个我最近的真实经历。团队内部有个 Agent demo跑得很欢能聊天、能查资料、能调用内部系统。但一放进生产环境立刻暴露问题对话轮次稍微长一点上下文就乱模型输出有时候直接截断工具调用的报错信息被原样丢给用户整个链路完全没有可观测性。代码在里面转得像是台装满杂物的洗衣机——能转但没人知道里面发生了什么。后面我把这套东西重构了一版核心思路就是题主提到的这句话把 Agent 框架拆开基于 PI 方案做一个生产级的 Harness。这里的 Harness 不是 CI/CD 里那个测试夹具而是在 Agent 场景下承上启下的执行装配层。PI 方案也不只是“Personal Intelligence”它更是一种架构取向——把规划Planner和解释执行Interpreter彻底分开。这篇文章不聊概念我把整个拆解过程、难点、踩坑点和优化策略写清楚给正在做 Agent 项目、尤其是从 demo 往生产环境推进的团队一个直接可参考的落地路径。1. Harness 到底是个什么东西先厘清边界再谈开发很多人把 Harness 和 Agent 本身混为一谈这是我见过最多、也最浪费时间的误解。Agent 是高层的“大脑嘴巴”负责理解意图、生成回复、决定下一步行动。而 Harness 是包在 Agent 外面的那层“骨骼血管神经”——它负责环境准备、上下文传递、工具注册、错误拦截、执行调度、日志追踪。没有 Harness 的 Agent 就像没有操作系统的计算机硬件再强也没法跑复杂任务。1.1 Agent 与 Harness 的本质差别我习惯用一个比较写实的类比Agent 是刚毕业的聪明实习生Harness 是围绕这个实习生建立的一套工作制度和管理流程。实习生专业能力很强但需要清晰的指令、需要有人帮他查资料、需要把任务拆成可执行的步骤、需要在出错的时候有人拦截重试、需要把做过的事情记录下来。Agent 负责任何单一节点上的“智能”Harness 负责让这些“智能”能稳定串联成一个可交付的完整流程。从代码层面看两者的边界更直观。Agent 的核心代码通常是 prompt 组装 LLM 调用 返回解析它关心的是“这一轮该怎么回应”。Harness 的核心代码则是循环调度器、状态管理器、工具注册表、错误处理链、追踪上下文。它关心的是“整个多轮任务怎么在一个稳定环境里跑完”。这个边界不清最典型的症状就是你会在 Agent 类里看到大量 handle_error、retry_logic、memory_dump 之类的代码。短期看着能用时间一长逻辑全缠在一起模型输出稍微变点格式整个模块就要推倒重来。1.2 开发生产级 Harness 的四个硬性指标拆开设计之前先定指标。生产级不是说代码写得花哨而是以下四个维度必须同时达标确定性同样的输入任务在模型输出质量波动的情况下系统最终的成功率和失败模式要基本可控。可观测性每一步计划生成、工具选择、工具执行、回复生成都必须能被追踪、被记录、被回放。容错性模型输出格式错误、工具超时、API 限流、上下文超长这些不应该让整个任务直接死掉。可扩展性加一个新工具、换一个底层模型、调整一个任务类型不能靠改核心代码来实现。这四个指标是评审 Harness 设计优劣的标尺。后面所有模块拆解本质上都是在为这四项服务。2. PI 方案的内部骨架Planner 与 Interpreter 的分工逻辑PI 不是什么新发明的名词但把它落到 Harness 设计上确实很实用。PI 方案把 Agent 的执行逻辑抽象成两层Planner规划层和 Interpreter解释执行层。我在生产环境重构时把原来的大 prompt 单体架构整个推翻就按这个分层重写。2.1 Planner 层把目标拆成可执行单元Planner 的职责只有一个拿到用户目标产出可执行计划。这个计划不能是一句空话必须是一串结构化的步骤。我见过很多失败的 Agent问题就出在 Planner 身上——它产出的计划太模糊。比如用户问“帮我分析上个月的销售数据并生成报告”模糊的计划是“分析数据生成报告”这种计划只能在 demo 里跑通因为 demo 的数据和逻辑都是预设好的。生产级计划必须明确到步骤1调用 sales_data_fetcher 获取上月数据步骤2调用 data_cleaner 去除异常值步骤3调用 report_generator 产出 Markdown 报告步骤4调用 notifier 把报告推送到指定群Planner 的输出必须是结构化格式JSON 或 YAML而不是自然语言。这样 Interpreter 才能稳定解析。2.2 Interpreter 层状态解释与原生工具绑定Interpreter 接收 Planner 输出的结构化计划逐条解释并执行。它有几个关键子任务子任务一工具调度。Interpreter 维护一张工具注册表将计划中的步骤名映射到实际的 Python 函数。这一步最讲究的就是工具绑定的稳定性。我在工具注册表里给每个工具设计了三个层级的信息功能描述给 Planner 看、入参出参 schema给 Interpreter 做校验、执行函数给代码调用。子任务二状态维护。每一步执行完Interpreter 要更新全局状态。这个状态包含已完成步骤列表、当前步骤的结果数据、剩余步骤、上下文积累。状态维护的重要性在于它是整个 Harness 可恢复性的基础。子任务三输出标准化。所有工具执行完无论返回什么格式Interpreter 都要把它转成统一的数据结构再喂给下一轮 LLM 调用。不然模型面对的数据格式杂乱推理质量必然下降。2.3 PI 方案与其他框架的取舍对比这里有个很关键的认知Agent 框架没有银弹。PI 方案的价值不在于比别的方案“更聪明”而在于它在工程上更好维护。我用一张表来说明几个方案的取舍方案主要优势主要劣势适用场景单体大 Prompt 方案搭建快、逻辑简单难维护、难调试、上下文浪费严重极简 DemoAgent 框架自动规划方案灵活性高、免手写流程黑盒调度、失败难复现、成本失控探索型任务PI 方案结构清晰、可控性强、易测试需要设计 Planner/Interpreter 协议、前期工作量稍大生产级任务流、工具密集型场景做生产级 Harness我个人强烈推荐 PI 方案。原因很直接可测试性。单体方案和全自动规划方案都很难对“计划生成”这个环节做单测因为你没法稳定控制模型的输出。PI 方案拆开后Planner 可以单独 mock 成固定输出做 Interpreter 的单测Interpreter 可以单独 mock 成工具执行结果做 Planner 的回归测试。这两者是本质区别。3. 生产级 Harness 落地的关键模块逐一拆解骨架定好了接下来是填肉。下面四个模块是我在实际重构中逐个踩坑踩出来的每一项都有真实的失败教训在里面。3.1 会话状态上下文管理第一版我直接用 Python dict 存储对话历史用户每发一条消息就 append 一条模型输出也 append 一条。看似没问题实际一跑就崩。问题出在“上下文爆长”上。多轮对话加工具调用一轮下来的 token 消耗比纯聊天大得多。工具返回的数据动辄几千字塞进消息历史里模型很快就被无关信息淹没。我的解决办法是“三级上下文结构”这也是 PI 方案拆开后的自然结果任务级上下文保存用户目标、Planner 的完整计划、当前步骤索引。这部分贯穿整个任务。步骤级上下文保存当前步骤的输入输出数据、工具执行的结果摘要。每步结束就替换不留冗余。全局记忆上下文保存跨任务的关键信息用户偏好、历史任务结论等。三级上下文的核心原则只有一个尽量少往模型 prompt 里塞原始数据塞经过提炼的摘要。这个思维转变帮我省了大量 token也让模型回复质量明显提升。3.2 记忆框架选型与分层记忆是 Agent 从“单轮问答工具”升级成“持续服务”的关键也是被讨论最多的部分。市面上的记忆方案很多向量数据库、Redis、SQLite、长期记忆、短期记忆、情景记忆……实际上不需要全上。我在生产环境做的是双层次记忆短期记忆任务进行中的上下文存内存或 RedisTTL 设置为 30 分钟。短期记忆的读写频率最高必须快不能引入太重的存储。长期记忆跨任务的关键信息摘要存向量库。每次任务结束后单独调一次 LLM 生成“本次任务的信息摘要”再向量化入库。这个“摘要入库”的步骤很多人会省省了的后果是长期记忆的召回质量极差。原始对话记录直接入库噪音太大而且存进去的信息未必是用户真正关心的。摘要化的过程相当于一个自动化的信息蒸馏。3.3 工具与 Skill 的接入机制工具接入是另一个容易翻车的地方。做 Harness 的人经常犯一个毛病把所有能想到的能力全做成工具往注册表里塞。结果 Planner 面对几十个工具的选择经常选错或犹豫既烧 token 又拉低准确率。我后来定了一条铁律工具按“场景包”注册而不是按“能力点”注册。什么叫场景包就是按用户使用场景把工具组合成一个 Skill。比如“周报生成”这个 Skill内部包含获取本周事件、整理格式、生成 Markdown、推送到群。对外暴露的时候只暴露一个接口。Planner 不用面对几十个细粒度工具只需要面对几个高内聚的 Skill。这个设计的好处不只是减少选择混乱更重要的是隔离变化。底层工具调整不影响 Planner工具体现给模型的功能描述和实际函数实现是两个独立版本可以分别优化。3.4 可观测性与 Tracing没有可观测性的 Agent 系统在生产环境里就是一个黑洞。用户报障说“机器人回得不对”你连它当时怎么想的都不知道。我在 Harness 里埋了一套结构化追踪日志每个关键节点都输出一条 JSON 日志用户原始输入Planner 输出的计划每步工具执行的结果摘要最终回复内容每步耗时和 token 消耗执行完成之后整个任务的所有追踪日志汇总成一个执行记录并落库。支持按任务 ID 查询随时回放。这套东西的调试价值极大。有一次模型突然在工具返回结果之后答非所问排查半天怀疑是 prompt 被污染最后靠回放日志发现是某次工具返回里包含了一段特殊字符串干扰了模型判断。如果没有追踪回放这种问题几乎无解。4. 从流水线到装配线执行引擎与编排策略Planner 和 Interpreter 是设计的核心但真正决定系统稳定性的是执行引擎怎么驱动这两个模块工作。执行引擎安排任务的方式直接描述系统的并发能力、失败恢复能力和资源消耗特征。4.1 同步编排与异步编排的取舍我第一版采用的是同步编排单线程依次执行计划中的每个步骤。好处是逻辑简单、状态一致性好、不需要考虑并发冲突。但单用户场景确实没问题多用户一压上来就崩了——准确说不是崩是体验急剧下降。一个用户的长任务跑着后面所有用户的请求都得排队等响应时间从秒级恶化到分钟级。后来我把执行引擎做成“事件驱动的异步编排”每个任务作为一个独立执行单元按事件流转触发下一步。计划生成完成触发工具执行工具执行完成触发状态更新状态更新完成触发下一步计划判断。核心是引入一个轻量级事件总线各环节通过发布订阅解耦。代价是复杂度上升收益是解决了并发问题。多用户的多个任务可以同时推进某个任务卡在慢工具上不会阻塞别的任务。4.2 重试、回退与熔断策略这一步是我在重构过程中投入时间最多的部分。AI 场景的错误处理比传统后端复杂得多因为错误来源不只有代码 bug还有模型输出的不确定性。重试策略工具调用失败超时、限流、网络错误直接重试重试次数上限 3 次退避采用指数退避间隔从 1 秒开始倍增。但模型 API 失败不能简单重试因为连续失败往往意味着 prompt 确实有问题继续重试只是浪费成本。回退策略当 Interpreter 执行工具失败且重试耗尽不能直接让任务死掉。我设计了一个降级策略把失败信息返回给 Planner让它重新规划换一条执行路径。Planner 重新规划出来的方案如果还是执行失败才宣告整个任务失败。熔断策略针对外部依赖系统的保护。比如某个数据源连续 5 次调用失败就把这个工具临时下线摘出注册表后续计划生成阶段不会再选中它。熔断持续 60 秒后自动恢复重新探测。4.3 并发与资源隔离多任务并发时有个隐蔽的坑资源竞争。最典型的例子是两个任务同时调用同一个外部系统触发了这个系统的限流导致双双失败。解决办法是给每一个外部依赖加上独立的信号量控制限制并发调用数设置为该系统允许并发上限的 70%。AI 模型 API 的并发控制更严格。我在 Harness 里实现了一个全局限流器按模型和模型部署类型区分每个维度独立限流。这个限流器兼顾两层API 服务商施加的硬限制以及预算控制模型按价格差异分别配额度。这些策略叠加起来的效果是系统不会因为某一个外部依赖的抖动而导致连锁崩溃。这是“生产级 Harness”在架构层面最核心的能力。5. 实测中的两个高频错误流式响应截断和执行终止有了上面的基础设计系统跑起来后会遇到各种实际问题。我挑两个出现频率最高、也最容易让新人懵的展开讲讲排查思路。这两个问题的名字就在标题的热搜词里说明大家普遍遇到很有代表性。5.1 malformed response 的完整排查链路现象是模型调用返回突然报错提示 response stream 格式异常没有产出有效响应。这种错误在流式输出场景下尤其频繁。第一步排查网络层。模型调用走的网络链路如果有不稳定的代理或中间层流式响应很容易被截断。这个问题在公网 API 调用时最常出现需要先排除网络因素确认是不是偶发的连接中断。第二步排查超时配置。很多模型 API 支持流式输出但客户端如果不及时接收数据部分实现场景下连接会被判定为超时。我从两个方向修一是增加 receive timeout 的配置二是启用自动重连机制。第三步排查返回体的解析逻辑。流式响应通常在结束时会有一个显式的结束标记。如果解析代码在生成结束标记时校验过于严格比如要求完整的 JSON 结构碰到模型输出被服务端截断的情况就会直接报 schema 错误。修复方式是加一个“宽松解析”模式解析失败时先保存原始响应到追踪日志然后用启发式规则尝试提取有用内容而不是立刻宣告失败。这套链路跑下来绝大多数流式响应问题都能定位。定位清楚之后要回到 Harness 设计层面做防御性改进。最有效的一个操作所有模型调用的输出都先过一层“响应规整器”把各种可能的格式问题在这个层统一处理Interpreter 永远只接收规整后的标准结构。5.2 execution terminated 的常见根因另一个高频错误是 Agent 执行在不明确的地方中途终止。这不是模型主动停止而是整个执行循环被异常打断。我排查过的根因有三类第一类是步骤状态更新崩溃。实现执行循环时我用一个共享变量记录当前步骤位置但没加锁。多任务并发时不同任务的循环体互相污染了状态变量导致步骤索引错乱触发异常终止。修复方式是每个任务独立的执行上下文对象彻底隔离不再有全局共享的可变状态。第二类是工具异常被暴力拦截。早期代码里工具执行包在 try-except 里但捕获异常后只是记录日志没有做任何处理循环直接退出。这种“静默终止”是最坑的用户只看到任务失败日志里却没有任何明确的失败原因。修复方式是把工具异常分成可重试、可降级、不可恢复三类分别走不同的后续链路。这个我之前在重试策略那一节讲过核心就是不要把所有异常一刀切。第三类是上下文长度触发保护机制。有些模型服务商在输入超长的时候会直接中断请求表现为任务终止。这类错误在排查日志里不太直观因为报错信息和上下文长度没有直接关联。我最后是给每次模型调用前的输入加了个 token 预估函数超阈值就自动触发上下文压缩把旧对话摘要化而不是硬着头皮继续调用。5.3 防御式编程处理 LLM 输出以上两类问题本质上是同一个大方向LLM 输出天然具有不确定性不能按传统编程的方式假设输出格式永远稳定。防御式编程在这一层极其重要。我给 Interpreter 加了一个“输出三重保险”第一重scheme 校验。模型输出先按声明格式校验不符合则尝试修复比如补缺失括号、修正类型。第二重语义降级。如果修复失败把模型原始输出作为纯文本交给下一个环节的专门解析器尝试提取关键信息而不是直接丢弃。第三重兜底回复。如果上面的全部失败直接向用户反馈系统暂时无法处理该请求并附带一个更简化的重新提问建议。这样即便模型完全失控用户感知到的也只是“这次没答好”而不是“系统异常”。这套保险机制叠加下来生产环境的可用性从 90% 出头提升到接近 99%。代价是代码量增加不少但这个投入完全值得。6. 测试那些容易被忽视的事用 pytest 给 Agent 系统上强度Harness 写完之后测试环节非常关键。但 Agent 系统的测试和普通后端测试有本质差异——不确定性因素太多不能按老思路测。6.1 测试的核心分层我按三个层次组织测试单元层针对各个独立模块的测试。Planner 解析工具 Schema 测、Interpreter 状态更新测、上下文压缩测、工具注册表测。这一层最容易写也最容易被跳过但覆盖了大部分纯逻辑。集成层针对模块间协作的测试。Planner 输出交给 Interpreter 的全流程测试工具执行结果喂给模型库再取回的标准链路测试。这一层要重点 mock 掉模型调用保证测试的确定性。回归层针对已知问题场景的保护性测试。比如上文说的流式截断、上下文超长都做成固定用例每次代码改动后跑一遍防止旧问题复发。6.2 模拟 LLM 输出集成层测试的核心技术点是用固定 mock 替代真实模型调用。我实现了一个 MockLLMClient支持从文件读预设响应按调用顺序返回。这样测试完全可复现不依赖真实模型 API。mock 的数据来源有三个渠道一是录制真实生产环境的模型响应。通过 Harness 的追踪日志系统把之前调用的真实响应保存成配置文件作为回归测试的基准数据。二是手工构造异常 case。比如故意造一个格式错误、空输出、超长输出的响应塞给 Interpreter验证三层保险机制是否正常触发。三是边界数据来源组合。构造一个完整普通过程的响应序列加上中途工具调用失败、降级路径重规划验证整个任务链路的容错表现。这套 mock 体系建好之后Agent 系统的测试效率有了质的提升。原来一次模型调用测试等 10 秒起步现在毫秒级完成而且不会因为模型响应波动导致测试偶发失败。6.3 整体回归的经验很多 Agent 项目会忽略一个事情系统重构之后原来能跑通的场景可能悄悄退化了。模型 prompt 改一行、工具描述改一句、上下文结构改一个字段都可能影响整体行为。我的做法是建一个“黄金用例集”。把之前所有线上处理成功的历史任务录制成场景用例每次大版本更新后全部跑一遍。这个用例集目前已经有几百个场景跑一次大概十几分钟。虽然耗时但每次发布前跑完心里确实有底。效果很直接线上出的 P0 问题绝大部分都是黄金用例集跑完后还漏掉的新场景而不是回归问题被改回来。7. 一个值得玩味的跨学科类比PI 参数整定与 Agent 控制这个章节的标题可能会让人意外但恰恰是我在这个项目里收获最启发性的一个角度。控制论里的 PI 控制器比例积分控制和 Agent 里的 Harness 设计虽然来自完全不同的领域内在逻辑惊人相似。控制系统的 PI 控制器有两个核心参数比例系数 P 和积分系数 I。P 决定系统对当前偏差的响应速度I 决定系统对历史累积误差的消除能力。P 太大系统震荡I 太大系统超调。只有把两个参数匹配好系统才能稳定收敛。映射到 Agent 系统里这个思路非常有意思。P 相当于 Harness 对“当前轮次状态”的响应强度。P 太弱模型遇到小问题不会纠正沿着错误路径一路跑到底。P 太强模型每一轮都过度反应稍微有点偏差就重新规划任务震荡不已。I 相当于 Harness 对“任务历史信息”的利用深度。I 太弱系统记不住上下文教训同样的错误会在多轮对话里反复出现。I 太强旧信息过度主导新信息反而被淹没。我在调 Harness 参数的时候就走过这个弯路。刚开始把 Planner 的重规划触发条件调得过敏感稍微检测到工具输出不符合预期就重新规划。结果系统像台疯狂摆动的钟摆全程在执行“规划-折腾-重规划”的循环效率极低。那段时间我天天对着输出日志叹气直到某次和做控制系统的朋友聊天他一句话点醒我“你这是临界震荡了P 太大了啊。”后来我把重规划触发条件调得更严格只有当连续两个工具执行都偏离计划时才触发重规划系统才稳定下来。这不就是 PI 控制器的 P 参数整定吗。这个类比给了我一个重要的方法论启发Harness 的本质是一个对不确定系统做稳定控制的控制器。我们有意识地按照“比例-积分-微分”的思路去设计 Harness 的各个反应机制。比例对应单轮响应积分对应跨轮状态累积微分对应趋势预判比如预计后续步骤可能超时提前告警。这套思路在后续迭代里成了一个很好的设计参照系。而且从热搜词里也能看到很多人同时关注“电压电流双闭环pi控制”和“pi agent”这两个词看似毫无关联背后其实共享着同一种系统思维你要在一个充满扰动和不确定性的环境里让一套系统稳定地逼近目标。控制论解决这个问题已经上百年了Agent 框架领域完全可以借鉴它成熟的设计思路。8. 最后聊聊开发节奏与团队配合技术细节聊到这里最后想聊一点方法论层面的东西。一个 Harness 从零到生产级研发节奏怎么把握团队配合怎么安排这决定了项目是按期落地还是无限延期。我经历的失败版本是“一口气憋大招”。架构设计想的无比宏大各种先进方案全面引入代码写了一个多月才看到第一版可运行的系统。结果一跑全是问题根本没法定位是哪一层的锅——因为太多新东西同时引入出错时完全无法归因。重构时我换了策略先跑通一条最小闭环再逐步替换薄弱环节。第一版 Harness 只实现了最简单的同步执行链路一个工具的调用、一个简单的状态管理、最基础的日志。先把这条路走通然后依次加入异步编排、重试机制、上下文压缩、追踪系统。每次只改一个变量出了问题立刻能定位到具体模块。这个策略在团队协作上也很有效。模块解耦清晰的情况下可以让不同的同事并行推进不同模块的开发一个人做工具接入规范一个人做执行引擎一个人做测试框架。只要接口定义得够清晰Planner 输出格式、Interpreter 事件约定互相之间的耦合就能控制在合理范围内。接口定义是整个项目里最重要也最需要提前投入的环节。具体地说要把 Planner 和 Interpreter 之间的协议当作一个“API 合同”来对待Planner 输出的 JSON 格式、每个字段的含义、可接受的值范围全都写清楚。这听起来很简单但真做的时候很容易被遗漏。我吃过最大的亏就是接口定义含糊大家各写各的联调时才意识到两边对“步骤状态”的理解根本不一致返工成本极高。工具接入规范也一定要提前定好。工具函数的命名规则、入参出参的 schema 标准、错误码定义这些看起来是细枝末节实则直接影响工具的接入效率。规范清晰的话新工具接入可能只需要半小时规范混乱的话一个工具接入能拖一整天。最后说一个团队认知层面的坑不要让所有事情都停留在“聊天记录”里。Harness 的设计文档、模块说明、接口定义、测试用例都必须是持续维护的正式文档。Agent 项目迭代速度极快两三个星期之后当时写的代码可能连自己都看不懂。文档是让这个系统可以被长期维护的唯一保障别嫌写文档麻烦你以后会感谢当时的自己。这篇从 Harness 边界讲到 PI 方案拆解再到执行引擎、错误排查、测试策略、跨学科启示和团队配合基本涵盖了把 Agent demo 推向生产级所需的主要工程环节。这套设计不一定适合所有团队但核心思路值得参考框架拆开边界划清控制收敛测试兜底。希望这段踩坑经历能给正在路上的人一些实实在在的帮助。
