1. Demo 和生产的差距为什么一个能跑的 Agent 无法直接上线1.1 Demo 的本质是让看的人信服生产的本质是不让看的人失望我最早接触 Agent 项目时团队先在内部环境搭了一个很漂亮的 Demo让大模型去查订单、算库存、生成日报现场演示给业务方看效果相当惊艳。产品负责人当场拍板说这个要尽快接进现在的系统里。那一刻我心里就开始打鼓——因为我知道演示环境和真实业务之间差着一整条生产线。Demo 阶段有个潜规则你下意识会挑稳定的输入去测会等模型状态好的时候去展示会让工具接口保持通畅也不会有人在同一秒并发调用十几个 Agent 实例。这些条件在演示环境里是默认成立的但到了生产环境每一条都变成了需要专门设计的变量。说白了Demo 是在证明这件事理论上可以做到生产是在回答这件事在没人盯着的深夜能不能自己扛住。这两种目标对系统架构的要求完全不同。1.2 生产环境对 Agent 提出的七个额外要求我在把 Agent 从 Demo 推到生产的过程中逐步总结出七个绕不开的硬性要求输入无规律线上的用户不会按你预设的句式提问可能一句话带了三个实体可能一次提问跨了五个业务系统甚至可能提一个跟当前上下文毫无关系的问题。并发与资源争抢演示时是单用户、单请求生产环境是同一个模型服务被多个业务方共享谁先谁后、谁超时、谁占了多少 token都必须有明确的调度策略。异常必须可控工具接口可能宕机、返回超时、数据格式变了、鉴权过期Agent 每一个步骤都可能踩到异常系统不能因为一次失败就把整个会话搞崩。安全和权限不能含糊线上 Agent 要访问真实业务数据哪些库能查、哪些操作能执行、操作前后要不要留痕这些在 Demo 里几乎没人管生产环境则是红线。可观测性Demo 出了问题你反正就在旁边直接看控制台就行。生产环境用户报Agent 回答错了你至少得能查出来是模型理解错了、工具调用错了还是数据本身错了。成本边界大模型调用是按 token 计费的生产环境的调用量一上来如果没有预算和上限控制月底账单会让你怀疑人生。模型升级与回滚生产环境不能随便换模型版本升级前要验证、升级后要能快速回退否则一次模型端的小改动可能让全链路表现大变。这七点每一项都不是大模型本身能解决的需要 Agent 外部的宿主框架去承接。这个框架就是我们说的 Agent Harness。2. Agent Harness 到底解决了什么把会想变成能办事2.1 先理清概念Agent 是大脑Harness 是躯干很多刚接触 Agent 开发的人会把 Agent 和 Agent Harness 混为一谈我自己早期也绕了好一阵。这里先给个最简单的区分:Agent 是那个会思考的部分它负责理解用户意图、拆解任务、决定下一步调用什么工具。你可以把它理解成大脑。Agent Harness 是承载 Agent 运行的那个躯干和神经系统它负责把 Agent 的决策真正落地到具体工具调用上包括工具注册、参数校验、权限检查、上下文管理、错误恢复、日志追踪、并发控制等等。打个比方Agent 像一个刚入职的专家他知道处理这个问题应该先查库存再下单Harness 则是公司里那套已经跑通的流程系统——帮他申请权限、调用接口、记录每一步操作、在接口挂了的时候告诉他该重试还是该上报。没有 Harness 的 Agent就像直接把一个专家扔进没有任何管理制度的公司他有能力但发挥不出来。2.2 关键理解Harness 发起工具调用而不是把自己变成工具我见过不少团队在架构设计时走偏最典型的就是把 Harness 本身设计成一个万能工具让模型通过一个大而全的 tool 接口去调用所有能力。这个思路跑一段时间就会发现很别扭。正确的理解应该是Agent Harness 是发起工具调用的执行者而不是被调用的工具本身。区别在哪里如果 Harness 是工具那 Agent 每次想用能力都得先描述一番要调用什么相当于大脑和肢体之间隔了一个传话的人效率低错误率还高。如果 Harness 是执行者那 Agent 只需要给出决策意图Harness 负责把意图翻译成精确的工具调用、参数注入、结果回传。这就像一个执行力很强的副手你告诉他去确认一下订单能发哪些地区他直接调仓储系统查完给你结论而不是反过来问你要调哪个接口、参数填什么。在工具数量多、调用链复杂的生产系统里这种执行者模式几乎是必须的。否则每个工具的参数格式、鉴权方式、返回结构都要让大模型去理解和拼装token 消耗大出错概率也会指数级上升。2.3 Harness 与 Demo 脚本的本质区别有人可能会问一个简单的 Demo 脚本不也能调用工具吗是的Demo 脚本和 Harness 表面上都在做调用工具这件事但两者的设计逻辑完全不同。对比维度Demo 脚本Agent Harness调用方式写死的顺序调用根据 Agent 决策动态路由输入容忍度假设输入符合预期需要兜底处理各种异常输入上下文管理通常只保留最近一轮支持多轮、跨会话持久化权限控制一般没有每个工具可配置独立权限可观测性靠 print 和断点全链路日志、追踪、指标并发能力单实例单请求支持多实例、并发调度错误恢复直接崩溃或报错重试、回退、降级策略模型绑定针对特定模型硬编码可切换模型、可灰度测试这张表列出来之后你会发现 Demo 脚本解决的是今天演示能跑通Harness 解决的是未来半年业务增长之后依然能跑通。两者之间不是一层简单的封装关系而是架构思维的整体转换。3. 把一个 Agent Harness 从 Demo 改造成生产级逐步实操接下来聊聊我实际改造走过的四步每一步都对应上面的一个核心差距。3.1 第一步把硬编码工具调用改成注册式的工具路由Demo 阶段最常见的写法是if intent query_order: result order_api.query(order_id) return format(result)这种代码在演示时完全没问题但一旦工具数量超过五个分支就会变得很难维护而且 Agent 的意图识别不可能每次 100% 准确一旦识别偏了硬编码分支就无能为力。我改造成了注册 路由的模式tool_register( namequery_order, description根据订单号查询订单基本信息, params_schema{ order_id: {type: string, required: True} }, permissionorder:read, timeout_ms3000 ) def query_order(order_id: str) - dict: return order_api.query(order_id)Harness 启动的时候扫描所有注册好的工具构建一份工具清单Agent 在决策时看到的是这个清单而不是散落在代码里的 if else。工具多了以后这种注册式的管理能极大降低维护成本新增一个工具只需要写一个函数加一个装饰器。关键点在于Harness 要根据 Agent 的决策从清单里挑出正确的工具校验参数注入上下文然后执行并回传结果。这个路由过程才是 Harness 的核心价值。3.2 第二步上下文与记忆的持久化设计Demo 阶段上下文一般就是一个内存里的队列对话结束就没了。生产环境不行用户可能隔一天继续上一次的会话业务系统可能要求关键信息跨步骤传递。我的做法是引入一个独立的上下文存储层包含三个部分短期上下文当前会话内的对话和历史工具调用记录存在内存或 Redis设过期时间。长期记忆用户偏好、历史结论、重要业务实体存数据库按用户和会话维度组织。工作记忆当前任务执行过程中的中间状态比如已经查到订单号、已经确认库存充足这些信息在后续多步调用中要能随时取用。这里有一个经常被忽略的细节上下文不是越长越好。把几千轮的历史全塞给模型token 费用高模型还容易在无关信息里迷失。我给上下文做了摘要压缩——当会话超过一定长度Harness 会把早期内容总结成结构化摘要只把摘要和最近几轮原始记录一起发给模型。3.3 第三步给每个工具加约束、超时与兜底生产环境下工具调用失败的频率比 Demo 阶段高出一个数量级。网络抖动、服务重启、数据不一致、鉴权过期各种情况都会遇到。所以我在工具注册层统一加了几个机制:超时控制。每个工具注册的时候都配一个timeout_msHarness 用异步方式调用超时直接返回特定错误码不让模型一直等。重试策略。针对网络类错误连接超时、5xx默认重试两次间隔递增针对业务性错误比如查无数据、参数非法不重试直接返回问题描述。结果规范化。不管工具底层返回什么格式Harness 统一包装成{status, data, error}的结构再丢给模型。这样模型拿到的是一个稳定契约不会因为某个接口返回了一个奇怪的嵌套结构就理解错。兜底话术。如果某个工具一直失败Harness 会向模型明确传递该功能当前不可用的信号并提供替代建议。比如查询订单超时就提示模型告知用户系统暂时无法查询请稍后再试而不是让模型自由发挥编一个答案。这一步做完之后Agent 在生产环境里的稳定性会有非常明显的提升——至少不会再因为一个小接口报错就导致整个回答脱轨。3.4 第四步加可观测性把黑盒变成白盒线上 Agent 出问题之后最痛苦的事就是你不知道模型到底怎么想的。它为什么调这个工具为什么拒绝回答为什么绕了两步才回来为了回答这些问题我在 Harness 里加了两层可观测能力。第一层是结构化日志。Agent 的每一步决策、每一次工具调用、每个 token 消耗都以 JSON 格式落日志带上 trace_id 和 session_id。出问题的时候我通过 trace_id 可以拉出整条链路用户输入 → 模型理解 → 工具调用 → 结果回传 → 最终回复。第二层是决策回放。Harness 把每次发给模型的 prompt包含系统提示词、上下文、工具清单和模型的原始返回都存下来。这样线上出了模型答非所问的问题时我能完整复现当时模型的输入和输出直接定位是提示词写得不清晰、上下文被截断了还是工具描述太含糊导致模型误选。这两层加上之后生产环境就从一个黑盒变成了可审讯的白盒排查问题的效率提升了不止一个量级。4. 生产改造时我踩过的四个坑附完整排查链路实操过程中我至少踩了四五个不小的坑这里挑四个最典型的把排查思路也一并写出来方便你对照。4.1 坑一Agent 连续调用工具之后上下文直接爆掉现象上线几天后用户反馈Agent 越聊越笨复杂的对话经常回答一半就断掉。查看日志发现模型请求报了一个 token 超限的错误。排查链路先确认是不是模型输入长度上限被触发。查了一次请求里发送的 token 数发现确实接近上限。追下去看是什么占满了上下文。发现每次工具调用的完整结果都被原样塞进下一轮请求有些接口返回几百行 JSON连续几轮调用下来上下文就爆了。定位到根因是没有对工具结果做裁剪尤其是一些查询类接口把不必要的大字段全返回给了模型。解决方案给工具返回加大小限制超过阈值的字段自动截断或摘要。区分工具执行的结果和发送给模型的内容前者完整存日志后者精简化。加入前面提到的上下文摘要压缩机制长会话早期内容定期转成摘要。这个坑后来再也没出现过但每次想起都觉得后怕——如果上线前就做好上下文容量设计就不用经历那几天用户投诉的窘境。4.2 坑二工具返回异常Agent 反而开始一本正经地胡说现象某个晚上仓储服务临时升级查询库存的接口连续报错。Agent 在无法获取真实库存的情况下居然直接回复用户目前库房有货预计明天可以发出而实际库存是零。排查链路拉出 trace_id看到工具调用返回的确实是错误状态以及 Harness 包装好的错误提示。查看发模型的最终 prompt发现 Harness 把库存服务暂时不可用的错误信息加到了很靠后的位置而系统提示词里又没有约定工具不可用时必须明确告知用户的原则。定位到根因是两层原因叠加一是错误信息在 prompt 里的地位太弱模型优先关注了用户问题二是系统提示词缺少对工具不可用场景的强制约束。解决方案工具异常时Harness 主动把错误信号提升为高优先级输入并在系统提示词里明确加一条当工具无法提供真实数据时必须向用户说明暂时无法获取信息禁止凭猜测作答。针对金融、库存、订单这类结果直接影响用户操作的场景还可以加一层后置过滤规则——如果工具异常且模型回答中涉及具体数值Harness 直接拦截并要求重答。这个坑给我的教训是大模型默认会顺着用户的问题编如果没有显式的安全绳它在信息不足时也会表现得像是胸有成竹。4.3 坑三多实例并发跑共享状态互相打架现象把 Agent 服务从单实例扩到多实例之后突然出现会话串号——用户 A 查到的订单跑到用户 B 的对话里了。排查链路第一时间怀疑是 session 管理的问题查了所有上下文读写逻辑都是按 session_id 隔离的看起来没问题。继续往下追发现工具层调用了一个内存缓存缓存 key 只包含工具名和参数没有带上 session_id。两个用户如果查同一个订单号命中的是同一份缓存。再往下查发现缓存里存的是上一个用户请求的完整业务对象包括对方手机号、地址这些敏感信息于是 B 用户在后续对话中通过日志接口间接读到了 A 的数据。解决方案缓存 key 强制加入 session_id 和 user_id。敏感业务数据默认不进共享缓存只做短生命周期的本地缓存。在上线规范里加了一条多实例部署时上下文相关的一切存储必须经过 Redis 或数据库统一管理禁止散落在各实例内存。这个坑属于典型的单机验证通过分布式就现原形也再次印证了生产环境必须在一开始就考虑并发隔离。4.4 坑四线上出问题调用链路无从查起现象业务方反馈某天下午 Agent 的某类问题回答质量直线下降但我们翻遍日志也不知道为什么。排查链路最初日志里只有应用层面打的标准业务日志完全没有模型调用层的记录。只知道答得不好但不知道为什么答得不好。补齐了模型调用日志之后发现那段时间用户输入的问题大多涉及一个新上线的营销活动而工具清单里根本没有对应的活动查询工具。进一步分析模型原始返回发现模型其实试图用已有工具拼凑答案但由于缺少正确的工具就退而求其次给了一段泛泛而谈的话术。解决方案给所有模型调用加上完整日志包括 prompt 版本、模型版本、token 量、响应内容。一旦发现某类问题回答质量下降先看工具覆盖度—是不是业务变了但 Agent 的工具没有跟着更新。建立一个工具覆盖度看板定期对比用户问题的意图分布和现有工具清单找出缺口。这个坑最大的价值在于让我意识到Agent 的生产问题很多时候不是模型不够聪明而是工具跟不上业务变化。Harness 如果只负责调用而不负责工具和业务的匹配感照样会翻车。5. 上线之后的事灰度、审计和成本这三件事逃不掉5.1 灰度发布和快速回滚Agent 系统的灰度比普通服务更难做因为它有两个独立的变量一个是模型行为模型版本、提示词一个是工具行为接口变更、权限配置。这两个变量一变整体输出就可能大变。我的做法是把灰度拆成两层按流量比例灰度先切 5% 的请求到新配置观察指标无异常再逐步上调。按用户维度灰度优先让内部测试账号和历史低敏用户使用新链路等稳定了再放开通用流量。回滚也一样要能分别做。如果模型版本导致回答质量下降可以直接把模型版本回退如果工具注册出了问题就单独回滚工具版本。Harness 在设计时就要支持模型、工具、提示词三者的版本独立管理否则上线后你会发现一个配置错了只能整体回滚牵连面特别大。5.2 工具级权限与操作审计Demo 阶段工具调用就是直接请求接口没人关心权限。生产环境完全不行Agent 本质上是在代表用户操作业务系统权限控制不严会出大事。我在 Harness 里加了这么几层工具级权限每个工具都配置允许访问的角色和用户范围。普通用户角色调不了删除订单这类高权限工具。参数级校验即便工具被调用Harness 也要校验参数是否越权。比如用户 A 只能查自己的订单传入别人的订单号就直接拦下来。操作审计记录每一次工具调用包括调用者、会话、参数、返回状态、耗时。审计日志至少保留 180 天方便安全团队复查。有一次我们内部安全审计需要回答上周哪些用户通过 Agent 改过发货地址我直接拉审计日志筛选出来十分钟就把材料交上去了。如果没有这层设计这种审计需求几乎无从下手。5.3 成本与性能的平衡大模型调用的成本在生产环境是会让你心惊肉跳的。一次复杂的多步任务光模型推理就要消耗几万 token一天跑上几万次请求账单数字相当可观。我的经验是几个方向并行用便宜模型做分类路由。一些简单的意图识别、实体提取不需要每次都请最强模型出手先用小模型判断该走哪条链路再决定用哪个模型。启用缓存。对完全相同的用户输入直接返回历史答案不走模型。对相似问题也可以做语义缓存命中率高的场景能省下一大笔钱。限制每轮的最大 token 数。Harness 在请求模型时设置max_tokens上限防止模型偶尔话痨一次性输出过长。定期统计工具调用成本。按工具、按业务场景做成本归因找出最烧钱的场景再针对性优化。成本这块我见过太多团队上线之后才开始关注结果被账单追着跑。最好是架构阶段就把成本指标接入 Harness 的监控面板每天看心里有数。还有一个关于性能的点工具调用结果的返回时效会直接影响用户体验。Harness 的调度要尽量并行化无依赖的工具调用而不是串行挨个等。比如 Agent 要同时查库存和查物流时效这两个工具没有任何依赖关系就丢到并发池里同时执行能省下至少一半的等待时间。6. 一点实操体会写到这里其实我最想表达的一个观点是Agent Harness 不是锦上添花的中间层而是 Agent 真正进入生产系统的必备件。Demo 阶段你可以把模型当主角让所有代码围着模型转一旦到了生产情况就反过来了——模型变成了整个系统里的一个环节而 Harness 才是那个保证每个环节有序运转的调度中枢。从我自己的经历看最顺的推进路径是先想清楚Agent 在业务里到底承担什么角色、能访问什么资源、失败时应该怎么表现再去选实现方案。技术上注册式工具路由、持久化上下文、工具超时兜底、结构化可观测、工具级权限这五件事是生产级 Harness 的底线缺任何一件都可能让你在后面某个深夜付出代价。如果你现在正处在Demo 跑通了但不知道下一步怎么走的阶段我的建议很简单先把上面这四个坑对应的能力补上再谈上线。等你把补丁打上跑一段时间你会明显感觉到Agent 真正接进项目靠的不是模型有多聪明而是它脚下那个架子搭得够不够稳。最后分享一个小技巧做 Agent 生产化改造时请务必保留一份线上真实会话的脱敏数据集定期拿它去做回归测试。模型会升级工具会变更业务会调整只有靠这套回归集你才能在每次改动之后用最短的时间确认这事到底有没有被我改坏。根据我个人经验这笔前期的数据投入能给你省下日后大量排障时间。
