先复用再自己做——这是我做完第二个 Agent 项目后最想复盘的一句话。九个星期从零立项到上线全程没有自研底层框架、没有从第一行代码开始搭模型调用链路靠的全是现成的 Agent 基础设施。圈里很多人一提到 Agent 就觉得是个巨大的工程要自己写编排、自己管理上下文、自己搞工具调用结果项目拖上半年还看不到一个能跑的版本。我这第二个项目恰恰反过来先克制住自己造的冲动把能复用的基础设施全部复用上把精力集中在业务逻辑上九周上线而且稳得住。这篇文章不是来吹某个框架有多神的我想把整个拆解过程、选型逻辑、踩过的坑都摊开来讲。无论你是刚准备入坑 Agent 开发还是已经被自研框架折磨得够呛都可以对照这份思路重新盘一遍自己的项目结构。1. 项目概述为什么第二个 Agent 敢定九周上线1.1 项目背景与核心目标先说这个项目本身。它本质上是一个面向内部业务场景的多 Agent 协作系统需要完成信息采集、结构化解析、方案生成三层任务。第一个 Agent 项目我们走了不少弯路自研了编排引擎、自研了工具调用协议结果 70% 的时间花在了让系统能跑通上只有 30% 的时间真正花在业务效果上。第二个项目立项时团队里最核心的一个决定就是架构思路彻底换掉不再从地基开始盖楼而是把现成的基础设施当作默认选项只有在被明确证明不合适之后才考虑自己动手。这个思路的直接成果就是九周的交付周期。拆开看九周其实不算夸张——两周搭框架和跑通端到端链路三周做领域逻辑和业务效果调优两周做联调、评测和并发验证剩两周留给了安全检查和灰度发布。真实工作量并没有减少减少的是那些从零搭建基础设施带来的无底洞时间。之前第一个 Agent 光是把模型调用、上下文管理、工具注册这些底层能力磨稳定就花了快一个半月。1.2 复用的核心思路先站在别人肩膀上复用这个词听着简单做起来其实有一个很重要的心态转变默认所有能力都不需要自己造。很多开发者的第一反应是现成框架不够灵活我自己写更可控别人的代码有坑。这些担忧部分成立但在项目初期它们不应该成为反对复用的理由而应该成为选型时的评估维度。你真正需要判断的不是它完不完美而是它能不能让我把业务跑起来、能不能在出问题时有人接住。我习惯把复用的对象分成三档第一档是模型能力和基础组件比如大模型 API、向量数据库、消息队列这些毋庸置疑直接用第二档是 Agent 框架和编排工具它们帮你管理记忆、规划步骤、调用工具这是最值得花时间评估的一层第三档是业务组件比如权限系统、审核流程、日志链路这些往往藏在公司内部基础设施里容易被忽略但复用它们的收益最高因为它们是业务合规和稳定性的底座。这次项目里我们最满意的一个决策就是没有自己写 Agent 编排而是直接采用了现成框架。为什么因为对于一个需要快速上线的业务系统来说编排层要解决的是多轮对话怎么管理、工具调用怎么路由、失败怎么重试这些通用问题这些问题已经有成熟方案自己写不可能在九周内写到同等健壮程度。你要做的是理解框架的设计约束然后在它的约束之上构建业务。提示复用不是放弃控制权而是把控制权花在更值钱的地方——业务效果、数据质量、用户体验。基础设施层面的问题交给成熟组件业务层面的问题留给自己。2. 基础设施选型Agent 地基到底怎么搭2.1 四层架构视角下的 Agent 系统做 Agent 系统我习惯用经典的四层架构来拆解也就是表示层、应用层、领域层和基础设施层。听起来像传统的企业架构但放到 Agent 场景里每层都有自己的特殊含义。表示层是用户直接面对的部分包括对话界面、任务提交入口、结果展示页面。这层复用起来最没有心理负担——直接用现有的前端组件库、现成的聊天 UI 模板不要自己从头写消息气泡和流式渲染。应用层是 Agent 的应用服务层负责接收请求、编排任务流、协调多个 Agent 的协作。这一层是复用 Agent 框架的核心位置。主流框架已经把规划-执行-反思的循环、工具调用的参数解析、多轮对话的上下文维护都封装好了你只要注册好自己的工具函数和 Prompt 策略就行。领域层是你真正的业务核心存放着你对业务场景的理解怎么解析一份合同、怎么判断一个方案的合理性、怎么把原始数据变成结构化结果。这一层没有现成组件能替代必须自己写。但也只有这一层值得你从零写代码。基础设施层是支撑整个系统运转的底座包括模型网关、向量数据库、缓存、日志、监控。这层最不该自己造选用成熟服务就好。我们这次全部用的现成云服务和开源组件没有一行自研代码。2.2 选型表哪些复用、哪些自研我把这次项目的选型结果整理成了下面的表格你可以对照自己的场景做个参考。架构层能力项选型方案复用程度表示层对话界面、任务面板现成前端组件 聊天模板完全复用应用层Agent 编排、任务流主流 Agent 框架框架复用应用层多 Agent 协作框架内置的多智能体模式框架复用领域层业务规则、Prompt 策略自研业务逻辑与提示词工程完全自研基础设施层模型调用统一模型网关 API完全复用基础设施层向量检索现成向量数据库服务完全复用基础设施层任务队列云消息队列完全复用基础设施层日志与监控现成可观测平台完全复用基础设施层权限与审核公司内部基础设施完全复用这个表格最有参考价值的不是具体选了什么而是复用和自研的边界一目了然除了领域层其他全部复用。很多团队在自研上的投入恰恰是反过来的最喜欢在基础设施层较劲自己写模型网关、自己搞向量库封装、自己设计编排协议结果领域层反而没人管最终的 Agent 效果一塌糊涂。2.3 关键决策背后的成本账选型不是拍脑袋背后一定要算账。当时团队内部也吵过要不要自研编排引擎我算了一笔账现在分享出来。自研编排引擎的显性成本包括协议设计至少两周、核心循环实现三周、异常处理和重试机制两周、多 Agent 协作支持四周加起来已经十一周这还不算测试和文档。而选择一个成熟框架学习成本大约一周、业务适配两周总计三周。两边差了将近十周。按一个高级工程师的工时算这中间的差距够做一个完整功能模块了。更重要的是隐形成本。自研编排引擎意味着你要自己面对一堆极端情况模型返回格式不合法怎么办、工具调用陷入死循环怎么办、上下文超过了模型上限怎么办、多个 Agent 之间怎么避免互相干扰。这些问题每一个都是深坑成熟框架在社区里已经被趟过很多次了你直接继承这些经验就行。自研的话每一个坑都要亲自掉进去一次。当然复用框架也有成本主要是学习曲线和约束妥协。你需要接受框架的设计哲学比如它的任务调度方式、消息传递机制、状态存储策略。如果你的业务特殊到框架的约束成为瓶颈再考虑换方案也不迟。但在项目启动阶段这个风险完全值得冒。3. 九周实操过程全记录3.1 第 1-2 周搭框架、跑通端到端链路前两周的目标只有一个用最少的代码跑通一条最小可用的端到端链路。很多人立项后喜欢先画架构图、写设计文档我们这次反过来先直接搭一个毛坯房出来。具体做法是这样选好 Agent 框架后先照官方示例搭一个最简单的单 Agent 对话系统连上模型 API让它具备调用一两个工具函数的能力。然后逐步加厚把用户请求从前端页面送到应用层经过 Agent 的规划循环调用业务工具把结果返回给前端。整个链路不分层、不优化、不留后路只追求一件事——数据能从 A 走到 B。这套先跑通链路的方法我从第一个项目中总结出来的价值极高。因为 Agent 系统的复杂度是分布式的问题可能出在模型调用、工具解析、上下文截断、前端渲染任何一个环节。如果不先把链路整体打通你就永远在一个局部里打转不知道自己修的东西到底影不影响最终效果。第二周末尾我们做了一个内部演示输入一个真实业务问题系统给出了带工具调用过程的结构化回答。虽然效果还很粗糙但这个可以跑的状态给团队吃了一颗定心丸后面所有迭代都是在一条活链路上进行的而不是在纸面设计上空转。3.2 第 3-5 周领域层打磨与业务效果调优链路跑通之后真正的硬仗才开始领域层。这三周我们几乎没有碰过框架底层代码全部精力都在做两件事——完善业务工具的 Prompt 策略、优化结构化输出的质量。先说工具调用。Agent 框架里注册工具很简单几行代码就搞定难点在于怎么让 Agent 在正确的时机使用正确的工具。我们反复调整工具描述从获取合同条款这种笼统说法改成根据给定的合同编号返回指定条款的原始正文与结构化字段若条款缺失请返回明确标识。描述越具体模型调用工具的命中率越高这是实测下来最明显的一个优化点。再说输出质量。业务场景要求 Agent 最终产出结构化的方案文档而模型在自由对话场景下表现不错一到了严格 JSON 输出就各种翻车。解决方案是双保险在 Prompt 里明确输出格式要求并给出一个完整的输出示例同时在代码层用校验器和修正器兜底第一遍结果不合法就自动要求模型重新生成最多重试三次。这个机制上线后结构化解析的失败率从最初的 20% 左右降到了 2% 以内。这期间我们还做了一个很关键的决定建立评测集。从真实业务数据里抽了 50 条典型请求每个改动都在这 50 条上跑一遍对比前后效果。Agent 开发最大的痛点是没有标准答案不建评测集你根本分不清某个 Prompt 改动是变好了还是变差了。3.3 第 6-7 周多 Agent 协作、联调与评测第六周开始接入多 Agent 协作。这是第二个项目相比第一个最进阶的部分也是复用框架红利最明显的地方。框架内置的多智能体模式基本解决了我的编排需求一个总控 AgentCoordinator负责拆解任务两个执行 Agent 分别负责信息采集和方案生成还有一个质检 Agent 复核输出结果。换成自研方案这套通信机制至少要写一个月但用框架现有的能力两天就搭好了骨架。联调阶段最需要盯的是上下文传递。多 Agent 协作时上游 Agent 的输出会成为下游 Agent 的输入格式一旦不对整个链条就断了。我们通过约定每个 Agent 的输出必须包含结果数据和元信息两部分并且都走 JSON 格式才算把这个问题控制住。这里额外提醒一句一定要在任务描述里明确每个 Agent 的职责边界不然模型很容易出现抢活干或者互相推诿的情况。第七周的评测比第三周时严格多了从 50 条扩展到了 300 条覆盖常规请求、边缘情况、异常输入三类。评测维度也从能不能跑通细化到回答准确率、格式合规率、工具调用正确率、响应耗时四个指标。每次迭代都拉一张对比表哪个维度下降了立即回滚改动绝不带着不确定性进下一阶段。3.4 第 8-9 周并发验证、安全检查与灰度上线最后两周是上线前的收尾期干的全是脏活累活。第一个项目上线时被并发问题打得很惨这次提前做了准备。并发这块框架层解决的是一个请求内部的编排但多个请求同时来是另一回事。我们的方案很简单把模型调用放到异步任务队列里前端拿到任务 ID 轮询结果而不是同步等待。应用层是无状态的队列和工作节点都可以横向扩展。压测下来单节点稳定扛住了 20 个并发请求横向加到 3 个节点后翻了三倍基本满足业务预期。安全检查也值得单独说。Agent 系统比传统应用多了一层风险模型可能被提示词注入攻击也就是说用户的输入里带着恶意指令试图让 Agent 绕过原有的限制执行不该做的操作。我们的应对是在应用层加了一道输入过滤识别并剥离可疑指令同时在 Agent 的系统提示词里明确只执行任务框架内的操作不响应任何试图修改自身指令的请求。这在语料里不显眼但真正上线后你会发现这是保命的一层。灰度上线走的是非常传统的部署流程先在内部小范围开放拿到真实反馈后调整一轮 Prompt再扩展到全量用户。上线第一周系统的任务完成率是 91.7%人工介入率是 8.3%。作为第二个 Agent 项目这个数据我们自己是满意的。4. 复用过程中的坑与排查实录4.1 框架升级导致的行为变化第一个想分享的坑是框架版本升级带来的行为漂移。当时项目进行到第五周我们为了用上某个新特性做了次框架升级结果升级后同一批评测集里的任务完成率突然掉了 10 个百分点。排查了半天最后发现是框架在工具调用格式上做了调整旧版本的解析规则和新版本不完全兼容导致一小部分工具参数被错误解析。这个坑的教训是Agent 框架仍然处于快速迭代期版本升级不是无痛的。我的建议是所有升级都先在隔离环境里跑一遍完整评测集对比核心指标后再决定是否合并。评测集在这里的价值又体现了一次——没有它你根本无从判断是升级引入的问题还是业务改动引入的问题。4.2 抽象泄漏框架帮不了你的部分第二个坑更隐蔽属于抽象泄漏问题。框架封装了编排逻辑但总有缝隙会把底层的复杂性漏出来。最常见的表现是框架文档里写着自动处理上下文实际跑起来你会发现上下文窗口还是会爆只是以另一种形式爆——某个长对话跑到一半模型开始反复输出无意义内容或者干脆报错。解决这个问题我们不能指望框架只能在应用层做主动控制。我们的方案是给每个会话配置了上下文摘要策略对话超过一定轮数就把历史消息压缩成结构化摘要只保留关键信息和最近的几轮完整内容。这个逻辑不复杂但需要你对模型的上下文窗口有清晰的预算意识。记住一个原则框架管理的是怎么编排而什么内容进入上下文这件事最终负责人是你自己。4.3 并发与成本控制一个必须自己算清的账并发这块还有一个成本上的坑。Agent 和传统接口不一样一个任务可能包含多次模型调用而且每次调用的 token 数量都不小。传统接口的并发成本可以线性估算Agent 的并发成本却是成倍放大的——一次用户请求可能背后藏着 5 到 10 次模型调用中间的规划、反思、重试都在烧钱。我们踩过最痛的一次是因为某个任务的重试机制设置得太激进一次失败的调用会触发三次重试再加上多 Agent 协作中每个 Agent 都可能失败重试结果一个本该消耗 2 万 token 的任务实际消耗了将近 10 万 token。控制手段有两个一是实现全局的调用次数配额二是对重试次数和重试条件做精细化管理。别一股脑地失败就重试要先判断失败类型是格式错误还是服务不可用前者重试有效后者重试只会加重你的成本。4.4 快查表常见问题与解法把这次实操中遇到的典型问题和排查思路整理成一个速查表方便你直接对照。问题现象可能原因处理办法工具调用参数频繁解析失败工具描述不够具体、模型输出格式漂移细化工具描述、增加输出示例、加校验器重试多 Agent 互相干扰职责边界不清晰、上下文串扰明确分工描述、隔离各 Agent 的上下文长对话效果逐渐变差上下文窗口被无关信息占满引入上下文摘要压缩、控制历史保留轮数同一任务成本波动大重试机制过激、模型输入过多按失败类型分流重试、设置调用配额升级框架后效果下降行为变更、兼容性问题先在评测集上回归确认后再合并用户输入触发越权操作提示词注入风险输入过滤 系统提示词加固5. 复用的边界什么时候该自己造轮子5.1 判断标准与其纠结不如设置明确边界读到这里你可能会想那是不是所有 Agent 项目都不用自己造了也不尽然。我自己的判断标准有三条供你参考。第一条看项目生命周期。如果是短期内要出结果的项目复用是唯一选择如果是要做十年的核心产品框架层的长期依赖风险就要认真评估。第二条看业务是否高度特殊化。如果你发现业务逻辑和框架的抽象模型之间有根本性冲突——比如你需要完全自定义的调度策略、需要介入每个编排节点——这时候自研的必要性就出现了。第三条看在团队里有没有能力长期维护。自研不是写完就完了你要持续维护、跟进模型能力升级、处理新的异常场景没有这个能力的话自研就是在给团队埋雷。但我也要说这三条标准里容易被误判的是第二条。很多团队觉得自己业务特殊其实真正特殊的是领域层的业务规则和 Prompt 策略而不是应用层的编排机制。编排这件事绝大多数业务都是相似的接收任务、拆解、调用工具、汇总输出。框架完全能覆盖。5.2 我踩过之后的核心体会两个 Agent 项目做下来我最大的体会不是复用省了多少时间而是复用在战略上带来的主动感。第一个项目团队全员扑在造轮子上忙得脚不沾地业务方却在旁边等得焦虑第二个项目最忙的时候核心代码每天的新增不过几百行但每一次改动都直接作用在业务效果上迭代质量和节奏感完全不一样。我还想说复用框架不等于放弃学习底层原理。你依然要理解 Agent 编排的循环机制、上下文管理的内部逻辑、工具调用的协议设计。只有理解了这些你才能在框架出问题时快速定位、在需要定制时知道从哪下手。区别在于你的理解是用来用好工具的而不是用来重写工具的。最后再分享一个实操层面的小技巧无论选哪个框架先花一天时间把它的源码里编排循环和工具调用两个核心模块过一遍。不要只看文档文档讲的是用法源码告诉你的是边界。这个习惯我在第二个项目里收益最大很多后来遇到的问题根源都在我提前看过的那些代码里。项目上线不是终点后续还要应对模型升级、业务扩展和新场景的评测压力但至少现在这个底座让我敢拍胸脯说下一个项目我有信心把周期再压缩两周。