The Type接手一个跑了两年的老项目，再往上叠"AI Agent"需求，这题我熟。身边不少朋友以为 AI Agent 重构就是给系统接个大模型接口，让用户能聊天提问就完事了。我最初也这么想，直到真正动手做了一轮重构，才发现水面下的东西远比你想象的深：模型调用只是最外层，真正难的是把原来那套"人点按钮、代码执行"的逻辑，改造成"模型理解意图、动态调度工具、自行决策执行"的引擎化架构。
这篇文章是 AI Agent 项目重构系列的第二篇，前面聊过要不要重构、怎么评估老系统，这篇集中讲两件事：一是 AI 生成在整个重构里的真实作用，二是架构重建时怎么设计分层、拆模块、控边界。会涉及 Agent 与 LLM 的关系、DeepSeek 这类模型在架构中的位置、Skill/Memory/MCP 这些概念的具体落法，也会把我实操中踩过的坑和验证方法一并放出来。适合正在做老项目智能化改造的开发者，以及刚开始上手 Agent 架构、对"从哪下手"还比较模糊的人。
1. 重构前夜：老项目接入 AI 的三个幻觉
1.1 幻觉一：把 LLM 当成普普通通一个 API 来调
很多老项目的技术负责人对 AI 能力的第一直觉，就是"拿 Key、调接口、拿返回"。你问他重构方案，他描述出来的样子和调用一个短信服务没什么区别：业务系统发给大模型一段文本，模型回一段文本，完事。这个想法在纯问答场景里勉强成立，一旦涉及真实业务——查订单、改状态、审批流、多轮澄清——就会立刻崩掉。
因为 LLM 本身是无状态的。它每一次调用都"失忆"，不知道你上一轮说了什么，更不知道你数据库里订单状态已经流转到哪一步。老项目里那些理所当然的东西，事务、状态机、幂等性、权限校验，模型一概不理解。你把 LLM 当 API 调，等于让一个记忆力只有几秒钟的新员工直接处理核心业务，不炸才怪。
所以 AI Agent 重构里第一个要扭转的观念是：LLM 是系统里的一个"推理组件"，不是"万能接口"。它需要被编排、被管理、被约束。你要在它外面套一层又一层的东西，上下文记忆、工具定义、结果校验、失败兜底，这些才是 Agent 架构的核心工作。
1.2 幻觉二：Agent 就是写个循环反复调模型
比"当成 API"稍微进了一步的，是很多人把 Agent 理解成"循环调模型"。具体做法是写一个 while 循环，把用户问题丢给模型，解析模型返回的 JSON，发现里面有个 action 字段就去执行对应函数，然后再把结果塞回给模型，继续循环，直到模型说"任务完成"。逻辑上没错，但把它当全部架构来用，很快就会遇到失控问题。
典型症状是：模型在一个工具上反复尝试不换方案，或者两个工具之间来回调用停不下来，更麻烦的是它可能产生一个完全不符合业务约束的操作序列，比如先删了订单又去查这个订单。没有外部的状态约束、步骤上限、合法性校验，循环就成了脱缰野马。
Agent 的关键不在"循环"这两个字，而在"决策质量"。模型每一步都在做决策：当前信息够不够，需要调用哪个工具，工具返回结果怎么解读，下一步往哪走。这套决策要靠精心设计的 Prompt 策略、清晰完整的工具描述、结构化的输出协议来保证。把 Agent 等同于循环，等于只看懂了骨架，没看到肌肉和神经。
1.3 幻觉三：重构就是推翻重来
最容易劝退业务方的，是一上来就说"这系统不行，我们重写吧"。老项目最大的资产不是代码写得多优雅，而是里面沉淀了几年甚至十几年的业务规则、数据关系、异常处理逻辑。这些逻辑散落在各个服务里，是经过线上故障打磨出来的。全部推翻，相当于把积累也丢了。
AI Agent 重构的正确姿态是"外科手术式改造"。保住既有的业务服务和数据层，把 AI 能力作为新的编排层和交互层叠加在系统之上。老接口不用动，老库表不用动，甚至团队熟悉的业务代码也可以不动。你要重建的，是"承接用户意图、调度底层能力"的这一层。这也是为什么架构重建的重点从来不在底层存储，而在中间那一层控制逻辑上。
从这个角度说，AI Agent 重构更像是给一栋老房子装智能中控，而不是把房子拆了重盖。装中控要考虑的，是怎么在不破坏原有结构的前提下，让灯、空调、窗帘这些已经存在的设备被统一调度起来。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Agent 与 LLM、AI 模型的底层关系：以 DeepSeek 为例
2.1 三个概念的分工与边界
"Agent 和 LLM 和 AI 模型有什么区别"这个问题，我在好几场技术分享里都被问到过。我习惯用一个类比解释：AI 模型是发动机，LLM 是其中一种特定类型的发动机（烧"语言"这种燃料的），Agent 则是整辆车。
AI 模型是个大类，包含图像识别模型、语音合成模型、推荐模型、大语言模型等。LLM（大语言模型）指以 Transformer 架构为基础、在海量文本上预训练出来的模型，它的能力集中在理解和生成自然语言，也包括一些推理和代码能力。而 Agent 是一个完整的软件系统，它内部会调用 LLM 来做理解和决策，但它还包含记忆、工具调用、任务规划、执行反馈这些组件。你可以有一个不用 Agent 的 LLM 应用（比如纯粹的翻译工具），但一个不依赖 LLM 的 Agent 几乎不存在——至少在目前的范式下，LLM 是 Agent 的认知核心。
有了这个分层，处理很多问题就清楚了。比如你发现 Agent 回答质量差，先判断是哪个环节的问题：是模型的推理能力不够，还是工具描述没写清楚，还是记忆检索出了错。定位不到这一层，你只能像无头苍蝇一样反复改 Prompt，效果却微乎其微。
2.2 DeepSeek 在 Agent 里的真实位置
搜索引擎里很多人直接问"DeepSeek 属于哪个"，答案很明确：DeepSeek 是 LLM，是大语言模型这一层的产品。它不是一个 Agent 平台，也不是完整的 Agent 框架。你可以把 DeepSeek 的 API 接入你自己的 Agent 系统，让 Agent 的心智内核用 DeepSeek 来驱动；但 DeepSeek 本身不会替你做工具调用、记忆管理或任务编排。
这一点在实际选型时特别重要。有的人以为"用了 DeepSeek 就等于有了 Agent"，实际上只是有了一个很强的大脑，躯干和手脚还得自己搭。反过来，也有人对 Agent 框架寄予厚望，以为买了某个 Agent 平台就什么都不用管了，结果发现平台的模型能力一般，换个更强的 LLM 又涉及到整个系统怎么适配的问题。我的经验是：把模型层和 Agent 框架层解耦，模型可以随时替换，框架层保持稳定，这才是健康的架构关系。
在模型选型上，我重构时把 DeepSeek 这类开源/高性价比模型作为首选候选之一。原因不外乎成本可控、中文能力强，而且在 Agent 场景里，它的推理和工具调用能力已经足够支撑大多数业务任务。但注意，"足够"也是分场景的，复杂多跳推理任务还是要对比测试后再定，我在第六章会细讲评估方法。
2.3 为什么这个区别决定了你的架构
如果你能清楚区分 Agent、LLM 和 AI 模型这三个概念，架构上会少走很多弯路。反过来说，概念混淆几乎必然导致架构失衡。
常见的一种失衡是"模型过载"。把所有智能都寄托在模型上，觉得只要选一个最聪明的模型，Agent 就能处理一切。结果是 Prompt 越来越长、越来越复杂，模型偶尔犯个小错就没办法兜底，因为系统本身没有任何校验和补偿机制。另一种失衡是"框架过载"。搭了一大堆模块、流程、规则，结果模型的能力被层层约束住，本来一句话能解决的事，在系统里绕了七八个环节，延迟和成本都上去了。
健康的设计是让模型做它擅长的事——理解语义、拆解任务、决定调用哪个工具；让代码做它擅长的事——状态管理、权限校验、事务控制、结果校验。架构设计的本质，就是给这两者画好边界。边界清晰了，模型换哪个都不影响大局，业务逻辑也不会被模型的随机性带偏。
3. 架构重建：从"功能堆砌"到"引擎化设计"
3.1 原来的系统长什么样
我重构的那个老订单系统，结构非常典型：前端页面发起请求，经过一个 Controller 进入 Service 层，Service 里写满了几千行的业务逻辑，再往下是 DAO 访问数据库。用户想查订单，就点一个按钮，前端调一个接口，后端跑一段固定逻辑，返回结果。整个链路是刚性的，一个入口对应一段确定性的代码执行。
这种架构的优点是确定。同一个输入永远走同一条代码路径，出了错好排查，性能也可预测。缺点是不能应对开放性问题。用户说"帮我把上个月所有未发货的订单整理一下，催一下供应商，把结果整理成表格发我"，这种需求在传统架构里没法做，因为没有一个固定按钮叫"综合处理待发货订单"。要实现它，你得写一个专门的接口，把查订单、查供应商、生成表格、发送邮件这些步骤全都编排好。
AI Agent 架构要解决的，正是这种"非预设路径"的需求。它不再是"人点按钮、代码执行"，而是"人说目标、系统自主规划并调用工具完成目标"。这意味着中间必须有一层能承接开放意图、动态决策的"引擎"，而不是一堆写死的调用链。
3.2 新架构的五个核心模块
我重构后的架构，按职责拆成了五个模块，各模块之间尽量解耦。简洁起见我把它们列出来，再逐个说：
- 意图解析层：接收用户输入，识别任务类型、关键参数、约束条件，输出结构化的"任务描述"。
- 上下文管理层：负责短期对话记忆和长期业务记忆的存取，为模型提供必要的背景信息。
- 工具注册与调度层：维护一份工具清单，每个工具对应一个老系统的能力接口，负责按模型决策执行调用并返回结果。
- 生成引擎层：封装 LLM 调用，包含模型路由、Prompt 模板、结构化输出解析、结果校验。
- 评估与回滚层：对 Agent 的执行过程做监控、自评、人工兜底，异常时回滚或终止。
在这个结构里，意图解析层和生成引擎层都是"会用到模型"的地方，但职责完全不同。意图解析层的输出是给系统内部用的结构化指令，要求稳定、格式统一；生成引擎层的输出是面向任务执行的动作序列，要求贴合工具定义、可执行、可校验。把它们混在一起，是最常见的架构设计失误。
3.3 模块间的数据流怎么设计
模块拆完了，要解决的是数据怎么流动。老系统里数据流是直线：请求进来，一层层往下走，结果一层层往上返。Agent 架构里数据流是环形的：用户输入进来，经过意图解析，进入上下文管理，生成引擎决定调用什么工具，工具调度的结果再次返回给生成引擎，生成引擎结合新信息做下一步决策，循环往复，直到满足结束条件。
这个环形流转的设计里，最容易被忽略的是"状态快照"。传统接口是无状态的，或者通过 Session 简单维护登录态；Agent 的一次任务可能会持续多轮交互，涉及多个工具调用，中间任何一环出问题，都要能定位到是第几步、哪个工具、传了什么参数、返回了什么结果。我在架构里专门引入了一个"轨迹记录器"，把每一轮模型决策、工具调用、结果摘要全部落库，既方便排查问题，也方便回放分析。
另一个关键设计是"任务终止条件"。循环必须有出口，不能靠模型自觉。我加了三个硬性条件：最大轮数上限、目标完成判据、异常次数阈值。任何一条触发，Agent 都会停止并转入评估流程，而不是无限循环下去。没有这套控制机制，Agent 上线后你根本不敢放手让它干活。
4. AI 生成在重构中的角色：不只是代码生成
4.1 用 AI 生成重构代码的边界
说到"AI 生成"，很多人第一反应是用 Copilot 写代码。重构期间我确实大量用 AI 辅助生成代码，但用的方式比较克制：让 AI 做脚手架和样板代码，不碰核心业务逻辑的重写。
具体来说，我让 AI 生成了三类内容。第一类是接口转换层，把老系统内部的 Java Bean、DTO 转成 Agent 系统统一使用的 JSON Schema，这类转换规则明确、批量重复，非常适合 AI 生成。第二类是工具描述文档，把每个老接口的入参、出参、限制条件改写成模型能理解的 tool description，这个工作看似简单，其实非常耗时，AI 可以打底稿，我再人工校准。第三类是测试用例和 Mock 数据，把历史线上问题的复现场景生成出来，跑回归。
核心业务逻辑我没有让 AI 碰。原因是这些逻辑里太多隐性的边界条件和历史补丁，AI 生成的代码看着对，一跑到边界就翻车，而且排查成本比自己写还高。我的原则是：AI 负责生成"周边"，人负责迁移"核心"。
4.2 Agent 运行时的 AI 生成：Skill、Memory 与 MCP
除了写代码，Agent 系统运行时的"AI 生成"才是架构重建的核心亮点。这个概念和热搜里的 Skill、Memory、MCP 强相关。
先说 Skill。Skill 是给 Agent 封装好的一项特定能力，比如"查订单并汇总""生成催货函""提取表格数据"。它往往由一组 Prompt 模板 + 若干工具调用序列 + 输出格式定义组成。运行时，Agent 根据用户意图动态拼接对应的 Skill，生成执行逻辑。Skill 做得好的话，模型就不需要每次从零开始憋方案，而是套用成熟的"招式"，错误率会明显下降。
再说 Memory。Agent 的记忆分两层：会话内的短期记忆和跨会话的长期记忆。短期记忆就是多轮对话的历史，这好理解。长期记忆则需要把业务关键信息抽取出来，按结构化方式存储，下次相关任务时检索注入上下文。比如一个客户之前投诉过发货慢，下次这个客户再来问发货进度，Agent 能主动表示歉意并优先处理，这就靠 Memory 的能力。
最后是 MCP（Model Context Protocol）。它解决的是"工具接入标准化"问题。在没有 MCP 之前，每种外部系统都要写专门的适配代码，换个系统就要重写。MCP 定义了模型与工具之间的标准协议，让工具以统一的方式暴露给模型调用。重构中我把老系统的接口按 MCP 规范封装了一层，这样后面再接新的系统，只需要写对应 MCP Server 就行，Agent 主体逻辑完全不用动。
4.3 生成内容的质量控制
AI 生成最大的风险是不稳定。同一个输入，模型这次给你 JSON，下次给你 Markdown，再下次可能在 JSON 外面包一层解释性文字。所以质量控制不是可选项，是强制项。
我在生成引擎层加了四道关卡。第一道是"结构化输出约束"，在 Prompt 里明确要求输出格式，同时使用模型的 JSON Mode 或其他结构化输出能力，从源头减少格式漂移。第二道是"语法级校验"，拿到模型输出后先做格式解析，解析失败则自动重试一次，并附上错误信息让模型修正。第三道是"业务规则校验"，比如日期格式、金额范围、订单状态是否合法，这些是模型不知道的，必须用代码检查。第四道是"人工确认闸门"，对高影响操作（如删除、批量修改、对外发消息）强制要求人来确认，模型只有建议权，没有最终执行权。
这四道关卡的顺序是有讲究的。越靠前的关卡成本越低、自动化程度越高；越靠后的越严格，但需要人的介入也越多。把高成本的校验留给小部分高风险操作，整体的成本和效率才是可接受的。
5. 实操记录：一个订单处理 Agent 的重构过程
5.1 重构前的系统状况
我拿一个简化版的例子来讲实操，方便你直接套用。假设老系统是一个订单管理后台，两张核心表：订单表和供应商表。订单表有状态字段（待支付、已支付、待发货、已发货、已完成），供应商表维护了每个供应商的交货周期、联系方式。老后台提供了几个接口：查订单列表、查订单详情、修改订单状态、发邮件通知。
传统方式是客服每天手动查一遍待发货订单，给供应商发催货邮件，再更新一次备注。这个工作耗时不多但极其枯燥，而且容易漏。老板的需求是：做一个 AI 助手，让客服用自然语言就能完成这套流程，比如"帮我把这周还没发货的订单整理一下，给对应的供应商发个提醒"。
这个场景复杂度适中，非常适合作为 Agent 重构的入门案例。它既有数据库查询，又有外部动作（发邮件），还涉及多轮确认（发给哪些供应商、邮件怎么写），能完整覆盖前面讲到的所有核心模块。
5.2 逐步替换的六个步骤
我按六个步骤完成了改造，每一步都保持旧系统可运行：
第一步，盘清现有接口。把老系统所有和订单、供应商相关的接口、表结构、状态枚举整理成文档。这一步的重点是找到"领域边界"，确认哪些能力要暴露给 Agent，哪些必须留在内部。比如修改订单状态涉及并发和权限控制，必须留在老系统，不能直接让 Agent 操作数据库。
第二步，搭 LLM Gateway。统一封装模型调用，包括 Key 管理、超时重试、流式输出、模型路由。先不接任何 Agent 逻辑，只是让预留的接口能通。这个 Gateway 要支持多模型切换，因为后面要做模型对比测试。
第三步，封装工具层。把"查订单列表""查订单详情""改订单状态""发邮件"包装成 Agent 可调用的工具。每个工具包含：名称、功能描述、入参 Schema、出参 Schema、权限级别。这里最关键的是描述写得准确——模型靠描述理解什么时候该调用这个工具，描述模糊它就不敢调，或者乱调。
第四步，接入记忆和上下文管理。实现会话级历史记录，把用户订单查询历史、之前发过哪些催货邮件都纳入上下文。这样用户说"再催一次上周催过的那些"时，模型才能给出正确响应。
第五步，编写 Skill 工具包。针对"催发货"这个高频场景，写一个 Skill：先查待发货订单，再按供应商分组，生成催货邮件草稿，询问用户确认后才发送。这个 Skill 把一次性多步操作固化成流程模板，大幅降低模型自由发挥带来的不可控性。
第六步，搭建评估与回滚机制。设计一组典型测试场景，覆盖正常流程、缺参数流程、超预算流程、用户反悔流程。每次改动后跑一遍回归测试，线上出问题时能一键停用 Agent 回退到人工操作模式。
5.3 每一步的验证方法和结果
每一步验证的方法不同，没有统一公式，但思路是确定的：小步快跑，每层都单独测过再往下走。
第二步验证时，我只看一件事——Gateway 的可靠性。连续调用 100 次，统计响应时间、出错率、重试成功率。同时对比了 DeepSeek 和另一个商用模型的响应质量和成本，最终 DeepSeek 在中文场景下表现不错，而且 token 成本低不少，暂时定为默认模型。
第三步验证时，我拿典型问题去测试工具调用效果。比如"查一下所有已支付但还没发货的订单"，如果模型返回的 tool call 是查订单列表接口，入参准确，说明工具描述写明白了；如果模型调错接口，或者非要用模糊搜索，就回头改描述。
第四、五步验证时，我重点模拟多轮场景和异常场景。比如用户先说"查一下待发货订单"，再问"金额最大的那笔是什么时候下单的"，模型要能记住上一轮的结果；又比如用户说"把所有的都催一遍"但订单里有些供应商还没有联系方式，系统要让用户补充而不是直接跳过。
第六步验证是长期做的工作。上线第一周我每天人工抽查 20 条 Agent 执行记录，比对它的判断和操作是否符合业务预期，发现问题就补规则或者调整 Prompt。两周后准确率稳定了，才逐步放开更多操作权限。
6. 踩坑清单、性能调优与维护建议
6.1 重构过程中最容易翻车的三个坑
第一个坑是上下文无限膨胀。模型输入的 token 有限，而且上下文一长，注意力会分散，回答质量下降，成本也飙升。我见过有人把整个订单历史、全部商品目录都塞给模型，结果一次调用七八万 token，又贵又慢。解法是上下文裁剪和检索：只把当前任务必需的信息放进去，其他信息通过工具按需查询。
第二个坑是工具返回的结果不干净。老系统的接口返回往往有很复杂的嵌套结构，或者夹杂着模型不需要的字段。直接把这种结果原封不动喂给模型，不仅浪费 token，还会干扰模型判断。我在工具层做了一层"结果精简"，每个工具先把自己返回的字段挑一遍，只保留对后续决策有用的部分，再格式化成模型友好的一小段文本。
第三个坑是死循环和高危操作。模型在工具调用中可能进入死循环——同一个工具反复调用，参数稍微变动又调一次。我除了前面提到的最大轮数限制，还在工具层加了"频率限制"和"相似调用检测"，在五分钟内对同一个供应商连续发三次催货邮件这种事，会被系统拦截并转人工。高危操作方面，所有对外动作（发消息、改状态）都走人工确认闸门，这是底线，不可妥协。
6.2 延迟、成本与稳定性的综合调优
Agent 系统的性能和传统接口完全不是一个量级。传统接口一次调用几十毫秒，Agent 一次任务可能要调用模型好几轮，每轮一两秒，整体延迟很容易上到十几秒甚至几十秒。优化思路分三个方向。
延迟方向：第一，能并行就并行。多个独立查询同时发出，而不是串行排队。比如"查待发货订单"和"查供应商交货周期"互不依赖，可以同时查。第二，设置合理的超时阈值，某个工具调用超过 5 秒就快速失败，不让整个任务卡死。第三，对高频的同类请求加缓存，比如供应商交货周期这种变化不频繁的数据，缓存一小时完全没问题。
成本方向：模型分级策略非常有效。简单任务用参数较小的模型，复杂推理任务才使用大模型。我的做法是在 Gateway 层做路由：意图解析、工具调用这类结构化任务用轻量模型，多步推理、复杂汇总用强模型。粗略统计，这个策略能省下接近一半的 token 成本。
稳定性方向：所有模型输出都要做校验，任何一步校验失败要有降级路径——不是直接报错给用户，而是转人工或换个模型重试。生产环境中我做了"双模型兜底"，主模型超时或质量异常时，自动切到备用模型继续执行。这个切换对上层业务完全透明。
6.3 监控、评估与长期迭代方法
Agent 上线不代表重构结束，长期维护才是最花精力的地方。我建了三层监控体系：
第一层是执行日志追踪。每一轮模型决策、每一次工具调用、每一个结果摘要，全部记录下来。出问题的时候，按任务 ID 串起来回放，能快速定位到是哪一步决策错了。这就像给 Agent 装了行车记录仪，没有它，排查问题就只能靠猜。
第二层是质量评估集。我维护了一个人工标注的测试集，里面包含正常场景、边界场景、异常场景。每次修改 Prompt、调整工具描述、更换模型后，都要把整个测试集跑一遍，对比结果的变化。这个过程不能靠感觉，一定要有量化指标：任务完成率、工具调用准确率、无效轮次比例、用户投诉数。
第三层是线上抽检。抽样比例可以根据风险动态调整，初期抽检率高，稳定后逐步降低。抽检时不仅看结果对不对，还要看过程合不合理——结果对了但绕了远路，说明工具描述或 Skill 设计还有优化空间。
关于模型迭代，我的建议是不要频繁换模型，但一定要定期对比。LMM 的更新速度非常快，三个月前的评测结果可能就不适用了。每季度拿测试集跑一遍主流模型，把性价比最优的选出来，换模型在 Gateway 层只是一个配置项的事。架构稳定、模型可换，这才是重构后的 Agent 系统该有的形态。
回到开头那个问题——AI Agent 重构难不难？我的体会是，难不在模型调用，难在你想清楚边界、搭好骨架、控住流程。把业务留给代码，把理解交给模型，让两者各司其职，重构出来的系统才能稳稳当当地跑下去。