Agent项目复用现成设施：从自研深坑到九周上线

去年我们立项第二个 Agent 项目时我直接跟老板说这次先复用再自己做底层基础设施能不写就不写。第一个项目把我们坑惨了——当时整个团队追求全自研从 Prompt 模板到工具协议、从状态机到重试策略全都要自己磨八周过去交付物连内部试用都勉强大量时间耗在模型偶尔输出畸形 JSON、工具调用频繁超时这类基础问题上。第二个项目启动时我们换了一套打法模型接口直接用现成的Harness 拿社区成熟的来改Skills 能挂现成技能就挂现成技能自研只集中在业务逻辑和内部系统适配层。结果就是标题写的九周上线而且是灰度环境里真跑业务流量的那种上线。这篇文章是把那次复用的全过程摊开来讲包括每一层到底复用了什么、为什么这么选、中途踩了哪些坑以及如果你也要做第二个 Agent哪些地方可以直接参考。1. 为什么第二个 Agent反而不该急着继续自研很多人有个错觉项目做得越多自研比例应该越高。但至少对 Agent 项目我的经验完全相反。第一个自研是为了摸清边界第二个应该赶紧复用因为你的业务壁垒根本不在那些基础设施上。这不是姿态问题而是时间账。1.1 第一个 Agent 留下的三笔重复发明的债第一笔债是工具协议。当时我们觉得现成的工具调用方式不优雅自己定义了一套类似 JSON-RPC 风格的协议结果模型经常输出结构不规范的参数我们硬写了三周解析器去兜底。后来才发现现成生态里模型原生的函数调用机制已经非常成熟对结构化参数的支持比我们自己设计得更好根本不需要发明新协议。第二笔债是重写偏好。团队遇到一个组件不顺手第一反应不是去查社区里有没有更好用的而是我们自己写一个更强的。结果新组件带来新坑修完新坑又发现缺功能循环往复。后来我们定了一条规矩遇到问题先花半小时调研生态里最活跃的替代品而不是花半小时写第一行代码。第三笔债是可观测性缺位。第一个项目上线后没有 trace、没有 token 成本统计出 bug 全靠肉眼翻日志。排查一个某个用户的任务为什么卡住的问题要翻三个服务最后发现是第三方接口静默超时。这些能力在现成的 Agent 基础设施里几乎都是标配但我们一开始根本没考虑。这三笔债让第一个项目至少多花了五周而且没换来任何用户可见的价值。1.2 先想清楚你的壁垒到底在哪一层复盘之后我们问了自己一个问题这个 Agent 产品的护城河是什么答案是业务数据、内部流程和对垂直场景的理解绝不是我们自己写了一套 Prompt 框架。所以我后来一直用三个问题来判断每一层该复用还是自研这一层是否直接服务最终用户价值开源或商业方案是否已经足够成熟如果底层将来升级替换成本高不高三个答案里只要有一个是否就老老实实复用。尤其是第二问很多人会高估自研方案的成熟度——自己写的东西跑通三个 case 就觉得够用但上线后要面对的并发、异常、可观测性问题开源项目早就替你踩完了。1.3 这套打法适合谁不适合谁先复用再自作不是普适真理。适合的场景很明确业务价值还没验证、团队规模小、交付时限硬、成本敏感。第二个 Agent 恰好全中——我们不是要做研究型项目而是要快速验证一个业务假设。反过来如果你创业卖的就是 Agent 底层引擎或者你需要从模型行为层做深度改造又或者数据主权有极端要求那该花的自研时间一分都省不掉。想清楚自己属于哪类团队比选什么框架重要得多。2. Agent Harness这是整辆车的底盘别自己拿钢管焊很多人把 LangChain、Dify 当成 Agent 开发的全部这个理解不完整。真正撑起生产级 Agent 的是一个叫 Harness 的运行时外壳——它把 LLM、工具、记忆、安全边界绑在一起管着 Agent 从启动到退出的整个生命周期。为什么说复用基础设施首先得选好 Harness因为没有它后面所有复用都没有稳定的挂载点。2.1 Harness 到底管什么Harness 的核心职责可以拆成四块生命周期管理Agent 从接收到任务到规划、调用工具、等待用户确认、完成、异常退出这个状态机如果自己写要处理的边界情况远比你想象的多——并发任务、超时恢复、幂等重入。循环控制模型在复杂任务里偶尔会陷入死循环Harness 要用最大步数、最大 token、单步超时这些硬护栏兜底。工具注入与 Schema 校验所有工具统一注册模型返回的调用参数先过一层校验再真正执行避免脏参数直接打到业务接口上。可观测性每个环节的 trace、token 消耗、工具调用记录都应该是开箱即用的能力。用个生活化类比编排框架像导航软件告诉你路线怎么走Harness 更像发动机管理系统管的是每一个动作能不能稳定发生。你可以换路线但发动机一定不能熄火。2.2 Harness 和编排框架是两回事这是最容易混淆的地方。编排框架关心任务如何拆解和流转——哪个子任务先做、依赖关系是什么、怎么并行Harness 关心的是 Agent 这个进程本身如何被启动、被监控、被安全地暂停和恢复。第一个项目我们就是栽在这——把编排当成了全部忽略了运行壳结果一上线就发现超时没有统一处理、工具调用没有熔断、并发一高就乱。后来看业界关于 Agent Harness 的深度拆解文章才意识到生产级 Agent 真正难的部分全在那些看起来不起眼的运行时细节里。2.3 落地选型时我们只盯四个指标当时我们挑 Harness 时列了一张清单只看四个维度社区活跃度最近一个月有没有持续提交有多少公司在生产环境里用。生命周期状态机是否完整是不是覆盖了中断、恢复、失败转移这类非理想路径。扩展点是否够能否接入内部系统认证、能否把自有 trace 接到统一监控。开源协议和文档质量协议是否友好、文档能不能让新人在两天内跑通。选型这件事我建议不要拍脑袋。我们第一周没急着写代码花了两天把选型文档写出来把候选方案的优缺点列清楚再动手。这看似浪费的两天后来省掉了至少两周返工——因为方案一旦定下来后面所有适配工作都沿着这个边界走。3. Skills 机制把能力做成即插即用的模块如果说 Harness 是底盘那 Skills 约等于给 Agent 装上了一排即插即用的功能模组。第二个 Agent 能九周上线Skills 的功劳至少占三成。它解决的问题是不再需要把每个能力硬编码进主流程而是以说明书 工具 验收用例的形式注册给模型模型读懂了说明自己就能决定什么时候调用。3.1 一个 Skill 的四个组成部分我理解 Skill 的方式是把它想成新员工工位抽屉里的工具说明书。Agent 需要一个技能时会先看到一张描述卡上面写着这个技能解决什么问题、什么条件下该用、参数长什么样、大概会产生多少开销。具体拆开一个 Skill 就是四样东西的组合触发说明用自然语言写清楚什么时候该用这个技能这是模型做决策的主要依据。参数 Schema一段 JSON Schema约束输入的字段、类型和取值范围。执行函数真正去调用某个工具或 API 的那段代码。验收用例一组输入输出样例用来做回归测试防止后面改动破坏了原有能力。关于 Agent Skills行业里有一篇讲得很透的原理解析核心观点是 Skill 的形态应该以自然语言描述为主、以代码为辅。我们实践下来完全赞同——模型是靠阅读理解来触发技能的说明文字的质量直接决定调用准确率。3.2 我们直接复用了三套现成技能第一个是网页保存成 Markdown。以前我们得自己写爬虫加 HTML 解析器现在社区里成熟的 Skill 直接挂载适配了一下内部存储就上线了。第二个是表格解析Excel、CSV 这类文件的读取和结构化处理现成工具包直接接入。第三个是本地文件检索在指定目录里按语义找文件还自带了权限边界检查。这三套技能如果全部从零开始每套至少一周加起来三周打底。但因为我们选了有现成 Skills 生态的 Harness这三块基本是适配 测试的活一周内全部搞定。这让我深刻意识到能力模块层也是基础设施而且是最容易被低估的一类。3.3 写新 Skill 时也别从零开始团队里第一次写自家 Skill 的同事上来就想把执行函数设计得无比通用。我直接把他按住让他从仓库里复制一份结构最接近的现成 Skill只改三样东西触发说明、参数 Schema、内部调用逻辑。结果他一天半就把新 Skill 合入了主干而通用方案讨论了三天还没定稿。这段经历给我的经验是Skill 的迭代重点应该放在说明文字上而不是代码结构。我们后来每次发版改得最多的都是触发说明——比如最初写当用户要求整理网页时使用后来发现模型也会在用户只是问网页里某句话时触发于是补了一条反面约束当用户只是询问网页内容时不要使用直接回答即可。正面例子加反面例子模型的理解一下就准了。4. 模型层和记忆层我们到底复用了什么模型层我们干了一件让不少人意外的事——除了砍掉领域微调的计划其余几乎全部走现成 API 配置路线。不做微调的理由很直白九周交付的项目既没有时间也没有足够数据做一次靠谱的微调而现成模型的能力已经足够覆盖我们的业务场景差的那点领域感用提示词和 Skill 说明就补上了。4.1 函数调用复用平台自带的手第一层复用是模型平台自带的函数调用Function Calling机制。模型在需要调用工具时会直接输出规范化的工具调用参数我们再把这些参数转发给对应 Skill 的执行函数。这套机制比当年自己解析自然语言输出不知道高到哪里去了——省掉了解析器、兜底对话逻辑、错配处理这些所有脏活。实际体验下来函数调用最舒服的一点是参数校验前置。模型输出的工具调用参数本身就是结构化 JSON我们在 Harness 层做一层 Schema 校验不合法就直接让模型重新生成而不是像以前那样等执行阶段才发现参数错了。这让工具调用成功率肉眼可见地上升至少稳定在百分之九十八以上。4.2 记忆三层方案全用成熟存储记忆是 Agent 体验的关键但我们没有发明任何新东西直接按三层模型搭短期记忆放在上下文窗口里靠提示词压缩和摘要控制 token 增长。工作记忆用 Redis 存会话中间状态比如当前执行到哪一步、哪些结果还没写入。长期记忆向量数据库存历史事实和用户偏好。特别说一下长期记忆的选型。我们量化数据量后发现历史事实大概几十万条量级完全不需要独立部署一套大规模向量引擎。最后选了 PostgreSQL 加 PGVector 插件直接复用团队已经在运维的数据库实例省掉了一个全新组件的部署、监控和备份成本。这条建议送给大多数中小团队——别一听 RAG 就上一个新数据库先看看你现有的存储能不能顶上。4.3 记忆和上下文相关的三个坑有些坑是跑起来之后才显形的。第一个是不该把记忆全量塞进上下文——不是钱的问题是效果问题。上下文超过一定长度模型的注意力会被稀释反而忽略当前用户真正想要的东西。所以我们做了两级摘要用户离开对话超过一段时间就把中期细节压缩成长线记忆。第二个坑是向量召回不加阈值。刚开始召回时旧记忆里一些无关片段会经常蹦出来干扰回答后来加了相关度阈值和时间衰减权重情况立刻好转。第三个坑是换模型要跑回归——提示词和 Skill 说明在不同模型上的理解能力不太一样换基座模型不能只看离线指标一定得拿真实用例集过一遍再切换。5. 编排框架四选一AI 助手开发到底该站哪个队写到这里肯定有人会问现在不是有 LangChain、Dify、CrewAI 这些现成框架吗为什么还要自己盘一套 Harness答案是这些框架本身就是一种基础设施复用我们当然用了只是把每个工具放在最合适的位置上。毕竟框架不是万能药重点是拿它解什么题。5.1 四个方向的复用价值对照我把当时认真考虑过的路线列了一张表方便后面的团队直接参考路线核心定位主要复用什么需要注意什么LangChain全链路组件库工具封装、链式调用、各种连接器抽象层多学习曲线陡版本演进快LangGraph状态图编排状态流转、断点恢复、人机协作节点需要先理解图模型心智负担偏高Dify可视化 AI 应用平台工程化面板、RAG 管道、调试界面深度定制时可能受平台边界限制CrewAI多 Agent 角色协作角色分工、任务委派、团队协作模式生产级的监控和容量能力需要自己补5.2 我们的判断标准能力密度与逃逸成本挑框架不能只看 Star 数我们当时给自己定了两个判断标准。第一个叫基础设施能力密度这个组件能帮我少写多少代码它是否默认提供了重试、缓存、可观测性、批量调度这些生产必需的东西密度越高复用价值越大。第二个叫逃逸成本如果它将来不合适抽离方案的代价高不高有些框架深度绑定你所有业务代码都长在它的抽象上一旦版本大升级就是二次开发有些框架只做薄薄一层抽离时基本无痛。我们的倾向是宁可自己多写一百行胶水代码也不要被一个巨型抽象绑死。5.3 我们的最终组装方式验证环境我们用了 Dify——它可以让业务方在一周内就看到交互效果可视化流程和调试面板极大降低了沟通成本需求对齐阶段特别管用。但生产环境我们没把 Dify 直接搬上去而是用自选 Harness 加轻量胶水代码内部工具适配器直接注入LangChain 只是作为设计参考借鉴了少数几个模式。这个组合的好处是验证阶段享受了 Dify 的开箱即用生产阶段避开了平台绑定真正把现成的东西和自己的差异化之间划出了一条清晰边界。说白了Dify 帮我们把业务方喂饱Harness 帮我们把服务器扛住两者各司其职。6. 九周上线时间线我们每周具体在干嘛这一章把时间线完全摊开。九周听着玄拆开其实就是两周收口、两周搭壳、两周接能力、两周调质量、一周交付。每一步都有具体的交付物而不是泛泛的推进中。6.1 第 1-2 周接口与边界只做四件事第一周我们没有写任何业务代码全部精力花在四件事上定义工具调用的 JSON Schema、确定模型适配层的接口、建好数据库表结构、画清楚生命周期状态机。这段看起来不写代码的工作其实最省后面时间——因为所有复用组件都要挂在这些边界上边界不稳后面全得返工。踩过一个坑一开始想做一套万能工具协议想支持未来所有可能的工具被同事一盆冷水泼醒——我们连未来有哪些工具都不知道怎么定义通用协议最后老老实实先只支持三个高频工具其他工具等需求明确了再加。这个砍边界的决定让第一周顺利收口。6.2 第 3-4 周Harness 骨架搭起来这两周把选好的 Harness 跑通接入内部系统认证和第一批工具适配器。因为 Harness 是现成的我们主要工作是配置和适配而不是从零写状态机。第三周结束时就跑通了一个最简单的问答 单工具调用链路。这里的教训是别贪全。我们一开始想让所有内部工具一次性接入结果集成测试直接炸锅——十几个工具各有各的鉴权方式、返回格式、超时时间根本不是一个星期能磨完的。后来改成按业务优先级分批接入每批一个小迭代节奏立刻顺了。6.3 第 5-6 周Skills 与工具接通主干能力这两周是复制模板写 Skill、做端到端调试的高峰期。我们复用了三套现成 Skill又自己写了两个内部专用的前面说的复制最近结构再改的方法就是这时候定下来的。每个 Skill 合入前都要跑验收用例保证改动不会破坏已有能力。这个阶段最大的坑是工具返回结果太大。有一次某个内部接口返回了几百行 JSON直接吃掉了上万 token一次任务还没开始就把上下文预算耗完了。后来我们统一给工具输出加了字段裁剪、分页返回和摘要处理三道工序token 消耗立刻降下来模型也能更精准地找到自己需要的信息。6.4 第 7-8 周记忆与评测把质量焊死向量库接入是在第七周完成的毕竟选了 PGVector部署和配置都很轻。真正花时间的是搭建评测体系。我们整理了一批业务场景用例把任务完成率当成唯一指标的毛病也改了增加到四个维度工具调用成功率、平均步数、token 成本、幻觉率。评测集要特别说一句70% 以上的用例设计成怪问题、反问题、模糊需求。正常的 happy path 谁都跑得通真正的质量差异全在边界场景里。比如用户中途反悔、用户给了互相矛盾的要求、用户要求调用一个权限外的工具这些才是评测的重点。6.5 第 9 周灰度上线以及一点反思第九周做的事比较收敛小范围灰度、可回滚方案、盯着 trace 看真实用户的行为模式。灰度期间果然发现一个场景化问题——真实用户并不会像测试集那样规规矩矩说话口语化表达和少字段的诉求比预想得多但因为 Skill 触发说明写得足够清楚模型大多数时候都能正确引导用户补充信息。回头看这九周如果要我总结一个最大的教训那就是第一周如果不坚持砍掉自研工具协议的执念后面根本不用这么顺。很多时间看起来是省在了 Skills、省在了 Harness其实最根本的是省在了想清楚哪里该踩在别人的肩膀上。两个 Agent 项目走完我最大的感受是决定一个 Agent 项目多少周能交付的往往不是模型效果本身而是你愿意在多大程度上复用现成基础设施。第一次我们年轻气盛什么都想自己造输得很惨第二次我们学会了站在巨人肩膀上赢得很踏实。最后分享一个内部小原则每次想自己造轮子之前先问一句——如果这个组件是开源的作为维护者我会不会在评审时拒绝它如果答案是会那就老实复用吧。把省下来的精力留给真正只属于你产品的那个差异点。