1. 棕地 Agent 工程到底难在哪从“能跑”到“敢改”的鸿沟接手一个跑了七八年的老系统老板突然说“给它加个 AI Agent 吧”这大概是当下不少资深工程师最真实的处境。新项目从零搭 Agent 框架网上教程一抓一大把LangChain、LangGraph、各种主流架构的 Demo 半天就能跑通。可一旦把场景换成那种几十万行、没人敢动、注释停留在三年前、原作者已经离职的遗留代码库事情就完全变了味道。棕地 Agent 工程这个词说的就是这种在已有系统上做增量智能化的活儿——不是推倒重来而是在活着的、还在产生业务价值的系统上动手术。我先把结论摆在前面在遗留代码库里做 AI Agent最大的敌人从来不是模型能力不够而是你对这套老系统的理解程度不够。很多人一上来就想着“我要接个大模型进去”结果连这个系统里哪个模块负责什么、数据怎么流转、哪些接口是历史包袱都还没搞清楚最后做出来的 Agent 要么是个花架子要么一上线就把生产环境搞出问题。棕地工程的核心矛盾在于遗留系统本身是脆弱的、隐性的、充满历史妥协的而 AI Agent 是概率性的、需要试错的、行为不完全可预测的。把这两个东西捏在一起难度不是加法是乘法。那为什么还要做因为绝大多数企业真正的业务价值都沉淀在这些老系统里。你不可能让一家做了二十年 ERP 的公司把系统推倒重来去拥抱 AI那不现实。真正有价值的场景恰恰是在这些老系统上长出智能能力——比如让 Agent 自动处理那些重复的工单分类、自动生成报表解读、自动在多个老系统之间做数据搬运和校验。这些活儿人来做又慢又容易出错Agent 来做刚好合适。所以棕地 Agent 工程不是一个可选项而是大部分传统企业落地 AI 的必经之路。这篇文章我想聊的不是“怎么搭一个 Agent”而是“怎么在一个你不敢乱动的老系统里安全地、可控地、可回滚地把 Agent 嵌进去”。我会结合自己在几个遗留系统上做 Agent 改造的实际经验把那些反直觉的、跟常规教程完全相反的法则讲清楚。如果你手上正好有一个老系统要加 AI 能力或者你是个架构师正在评估这件事的可行性那接下来的内容应该能帮你少走不少弯路。适合有一定工程基础、对 AI Agent 有基本认知、但还没在真实遗留系统上踩过坑的读者。2. 法则一先给老系统做“特征测试”再谈 Agent 接入2.1 为什么特征测试是棕地 Agent 的第一道门槛在绿地项目里你写代码之前系统是空的行为完全由你定义。但在棕地项目里系统已经有一套运行了多年的行为逻辑这套逻辑可能连文档都没有全靠代码本身和运维经验在维持。这时候你如果直接往里塞 Agent最危险的不是 Agent 本身出错而是你根本不知道它触发了老系统里哪条隐藏的路径。特征测试Characterization Test这个概念来自 Michael Feathers 的《修改代码的艺术》核心思想是在改动遗留代码之前先写测试把当前行为“钉死”不管这个行为看起来是对是错。它的目的不是验证正确性而是建立一个行为基线。对棕地 Agent 工程来说这一步的价值被严重低估了。因为 Agent 的输出是概率性的你没法用传统的断言去测它但你可以测它调用的那些老接口、老函数、老数据流在特定输入下是否还保持原来的行为。我做过一个项目老系统里有个订单状态计算函数逻辑写得极其绕嵌套了七八层 if-else还有几个魔法数字。我们当时想用 Agent 来自动判断订单异常结果测试阶段发现 Agent 给出的判断跟系统实际状态对不上。排查了两天才发现那个函数里有个隐藏的分支当订单金额恰好等于某个阈值时会走一条特殊路径而这条路径在代码注释里完全没提。如果没有特征测试把这个行为固定下来Agent 上线后就会在这类边界订单上持续出错而且很难定位。2.2 特征测试在 Agent 场景下的具体做法具体怎么做我的经验是分三步走。第一步找出 Agent 将要触碰的所有老系统入口点包括 API、数据库读写、消息队列、定时任务。第二步针对每个入口点用生产环境的真实数据脱敏后跑一批样本记录输入和输出把这些记录变成回归测试用例。第三步把这些测试用例接入 CI每次 Agent 相关代码有改动就自动跑一遍确保老系统的行为没有被意外改变。这里有个关键细节特征测试的样本要覆盖“正常路径”和“异常路径”两类。正常路径好办异常路径才是坑最多的地方。比如老系统里对空值、超长字符串、特殊字符的处理往往跟现代框架的默认行为不一样。Agent 生成的参数如果没做清洗很容易触发这些老逻辑里的边界问题。我一般会专门构造一批“脏数据”样本把老系统在各种奇怪输入下的反应都记录下来。提示特征测试不是一次性的工作。每次 Agent 迭代、每次老系统本身有变更都要重新跑一遍基线测试。我见过太多团队做完一次就丢在一边结果三个月后老系统被人改了一行代码Agent 就开始出各种诡异问题。2.3 测试覆盖率的取舍别追求 100%还有一点要提醒在遗留系统上追求 100% 的特征测试覆盖率是不现实的也没必要。你的目标是覆盖 Agent 实际会走到的那些路径而不是整个老系统。我通常会把 Agent 的调用链路画出来只对链路上的节点做特征测试链路之外的代码暂时不管。这样能把工作量控制在可接受的范围内同时保证 Agent 相关的行为是可控的。这个取舍背后有个逻辑棕地 Agent 工程是增量改造不是全面重构。你不需要理解整个老系统你只需要理解 Agent 会碰到的那部分。把有限的精力集中在关键路径上比漫无目的地给整个系统补测试要高效得多。3. 法则二Agent 的“智能”要放在边缘别往核心业务逻辑里塞3.1 核心逻辑与智能逻辑的边界划分这是我在第二个项目里用血泪换来的教训。当时我们的做法是把 Agent 的判断逻辑直接嵌入到老系统的订单处理主流程里让 Agent 在关键节点做决策。听起来很美好实际上是一场灾难。因为老系统的核心流程是强事务、强一致的而 Agent 的调用有延迟、有失败率、有不确定性。一旦 Agent 超时或者返回了意料之外的结果整个订单流程就卡住了。后来我们调整了架构把 Agent 放在核心业务流程的“边缘”让它做辅助决策而不是主决策。具体来说老系统的核心流程保持不变Agent 在旁路运行它的输出作为“建议”写入一个独立的表或队列由核心流程在合适的时机以非阻塞的方式读取。如果 Agent 挂了或者超时核心流程照常走原来的逻辑只是少了智能增强的部分。这样既保证了老系统的稳定性又让 Agent 的能力能够逐步渗透。这个原则可以总结成一句话Agent 可以影响决策但不能阻塞决策。在遗留系统里任何可能阻塞主流程的东西都是高危的因为老系统的容错设计往往很粗糙一个环节卡住可能引发连锁反应。3.2 旁路模式的三种落地形态旁路模式具体怎么落地我实践过三种形态各有适用场景。第一种是异步建议模式。Agent 在独立进程或独立服务里运行消费老系统发出的消息或事件处理后把结果写回一个建议表。老系统在需要的时候去查这个表查到就用查不到就走默认逻辑。这种模式对老系统侵入最小适合那些主流程极其敏感、不能有任何额外延迟的场景。第二种是同步旁路模式。Agent 作为一个独立的服务老系统通过一个带超时和熔断的调用去问它。超时时间设得很短比如 200 毫秒超了就降级。这种模式适合那些需要实时智能判断、但又能接受偶尔降级的场景。关键是熔断和降级逻辑要写好不能让 Agent 的故障传导到老系统。第三种是影子模式。Agent 和老系统并行处理同一批数据但 Agent 的结果只记录不生效用来对比和验证。这种模式适合 Agent 刚上线、还在验证阶段的场景。跑一段时间确认 Agent 的判断准确率达标了再切换到生效模式。影子模式是我最推荐的上线策略没有之一。3.3 为什么“智能放边缘”反而效果更好有人可能会问把 Agent 放边缘它不就发挥不了全部价值了吗恰恰相反。在遗留系统里Agent 的价值不在于替代核心逻辑而在于处理那些核心逻辑处理不好的“模糊地带”。比如工单的语义分类、非结构化文本的提取、多系统之间的数据对账这些活儿老系统做不了或者做得很差Agent 来做刚好。而核心的金额计算、库存扣减、状态流转这些有明确规则的事情老系统已经做得很稳了没必要让 Agent 去掺和。把边界划清楚Agent 和老系统各司其职整体效果反而比让 Agent 大包大揽要好。这也是棕地工程和绿地工程思维上的一个根本差异绿地工程追求的是端到端的智能棕地工程追求的是在现有约束下的最优增量。4. 法则三迁移盲区比技术债更致命得先画“雷区图”4.1 什么是迁移盲区迁移盲区这个词是我自己总结的指的是那些在遗留系统里“看起来能用、实际上没人真正理解”的部分。它和技术债还不一样。技术债是你知道它有问题、知道欠了什么只是暂时没还。迁移盲区是你根本不知道它有问题甚至不知道它的存在。它可能是一个没人维护的定时脚本、一个硬编码在配置文件里的特殊规则、一个只有某个老员工才知道的运维操作。在棕地 Agent 工程里迁移盲区是最致命的东西。因为 Agent 的行为是数据驱动的它会去读各种数据、调各种接口很容易踩到这些盲区。我遇到过一个案例老系统里有个每天凌晨跑的脚本会把某些订单的状态批量改掉这个脚本没有任何文档也不在监控范围内。Agent 上线后在凌晨时段读取订单状态时经常读到“中间态”导致判断出错。排查了很久才发现是这个隐形脚本在作怪。4.2 画雷区图的四个信息源要发现迁移盲区我一般从四个信息源入手。第一个是代码考古。用静态分析工具扫一遍老代码找出那些没有被任何测试覆盖、没有被最近修改过、但仍在被调用的函数和脚本。这些是盲区的高发地带。特别要关注那些带定时任务、带数据库直连、带文件读写的代码它们往往游离在主干逻辑之外。第二个是运维日志。去翻生产环境的日志、监控、告警记录看看有没有一些“不明来源”的操作。比如某个表的数据在特定时间点被修改但找不到对应的业务操作。这些异常往往是盲区的信号。第三个是人肉访谈。找那些在老系统上工作多年的运维、DBA、业务人员聊问他们“有没有什么系统行为是你知道但文档里没写的”。这个问题往往能挖出很多宝藏。我就从一个老运维那里得知系统里有个隐藏的管理员入口可以在特定条件下绕过某些校验这个入口在代码里藏得很深。第四个是数据血缘分析。追踪关键数据的来源和流向看看有没有“断头路”或者“幽灵写入”。数据血缘能帮你发现那些不在正常业务链路上的数据操作。4.3 雷区图怎么用把盲区找出来之后要画成一张“雷区图”标注每个盲区的位置、影响范围、触发条件、风险等级。然后针对每个盲区决定是绕开、是封装、还是先补测试再动。我的原则是高风险盲区一律绕开中风险盲区先封装再加监控低风险盲区可以边用边观察。绕开的意思是Agent 的设计要主动避开这些区域。比如那个凌晨脚本我们后来让 Agent 在读取订单状态时加了一个时间窗口判断避开脚本运行的时间段。封装的意思是给盲区加一层适配层把它的行为固定下来Agent 只跟适配层打交道。补测试的意思是如果这个盲区必须被 Agent 用到那就先写特征测试把它钉死再让 Agent 接入。这张雷区图不是画完就完了它应该是一个活文档随着你对系统理解的加深不断更新。我一般会把它放在项目 Wiki 的显眼位置让所有参与 Agent 开发的人都能看到。5. 法则四别迷信“大模型什么都能干”该写规则就写规则5.1 大模型在遗留系统里的能力边界现在有一种风气好像什么问题都想用大模型解决。在绿地项目里这么想问题不大但在遗留系统里这种思维会害死人。大模型擅长的是语义理解、模糊匹配、文本生成这类任务它不擅长的是精确计算、状态管理、事务控制。而遗留系统里大量的逻辑恰恰是后一类。我见过一个团队想用 Agent 来自动处理对账差异。他们的做法是把两边的数据都丢给大模型让模型判断哪些是差异、差异原因是什么。结果准确率惨不忍睹因为对账涉及大量的金额计算、时间窗口匹配、多字段组合判断这些用规则引擎几行代码就能搞定的事情大模型反而做不好。后来他们改成规则引擎做初筛、大模型只负责对差异原因做自然语言解释效果立刻上来了。这个案例的教训是在遗留系统里能用确定性规则解决的问题就不要用概率性模型。规则引擎是确定的、可测试的、可解释的而大模型是不确定的、难测试的、黑盒的。在棕地环境里确定性是稀缺资源能保留一点是一点。5.2 规则与模型的混合架构那什么时候用规则、什么时候用模型我的经验是画一条线输入和输出都是结构化数据、判断逻辑可以用明确的 if-else 表达的任务用规则输入是非结构化数据、或者判断逻辑涉及语义理解的用模型。比如订单金额校验、库存扣减、状态机流转这些用规则。工单内容分类、客户意图识别、非结构化文本提取这些用模型。两者结合的场景也很多比如先用规则做粗筛把明显正常的过滤掉剩下的模糊案例交给模型做精细判断。这种混合架构在棕地 Agent 工程里特别实用因为它把大部分流量挡在了确定性逻辑里只有少量真正需要智能的请求才会走到模型既保证了稳定性又控制了成本。5.3 规则的可维护性设计用规则还有一个好处可维护性。遗留系统本身就已经很难维护了如果你再塞一堆模型调用进去后面接手的人会更痛苦。规则至少是看得懂、改得动的。但规则也要设计好不能写成一堆散落的 if-else。我一般会把规则做成配置化的用表格或者 DSL 来描述而不是硬编码在代码里。这样业务人员也能参与维护改规则不用改代码、不用重新部署。在遗留系统里减少部署次数本身就是一种稳定性保障。规则引擎我推荐用成熟的、轻量的方案不要自己造轮子也不要用太重的东西毕竟是在老系统上做增量。6. 法则五Agent 的可观测性要比老系统本身还强6.1 为什么老系统的监控不够用遗留系统的监控往往是薄弱的可能只有基本的存活检测和错误日志。这在传统场景下勉强够用但加了 Agent 之后完全不够。因为 Agent 的行为链路更长、更复杂涉及模型调用、外部服务、数据读写多个环节任何一个环节出问题都可能导致最终结果异常而老系统的监控根本看不到这些。我坚持一个原则Agent 相关的每一个决策点都要有日志每一次模型调用都要有记录每一个降级和熔断都要有告警。这不是过度设计而是棕地环境的必然要求。因为老系统本身就是一个黑盒你再加一个黑盒进去出了问题根本没法排查。可观测性是把 Agent 从黑盒变成灰盒的唯一手段。6.2 可观测性的三个层次具体来说我会从三个层次建设可观测性。第一个层次是调用链追踪。给每个 Agent 请求分配一个唯一 ID把这个 ID 贯穿到所有相关的日志、模型调用、数据库操作里。这样出问题时你可以用这个 ID 把整条链路串起来看。在微服务架构里这是标配但在遗留系统改造场景里经常被忽略。我一般会用轻量的方案比如在日志里打标记不一定非要上全套的分布式追踪系统。第二个层次是决策记录。Agent 每次做判断都要记录它的输入、输出、置信度、以及它依据的规则或模型版本。这些记录在排查问题时极其有用。比如用户投诉 Agent 判断错了你可以回放当时的决策过程看到底是输入数据有问题、还是模型版本不对、还是规则配置错了。没有这些记录你只能靠猜。第三个层次是效果监控。Agent 上线后要持续监控它的准确率、响应时间、降级率、异常率这些指标。这些指标要跟老系统的业务指标关联起来看比如 Agent 的准确率下降是否导致了业务异常率的上升。我一般会做一个简单的看板把这些指标放在一起方便一眼看出问题。6.3 日志的成本控制可观测性做得好日志量会很大成本是个现实问题。我的做法是分级记录关键决策点的日志全量保留普通调用日志采样保留调试日志只在需要时开启。另外日志的存储要有生命周期管理比如热数据保留 7 天、温数据保留 30 天、冷数据归档。在遗留系统里存储资源往往也紧张不能无节制地写日志。注意可观测性建设要在 Agent 上线之前完成不能等出了问题再补。我见过太多团队上线时图快监控没做好结果出了问题排查了三天才定位到原因业务损失远超过提前做监控的成本。7. 法则六上线策略比技术方案更重要灰度是唯一正确答案7.1 为什么棕地 Agent 不能一次性全量上线绿地项目里新功能全量上线风险相对可控因为整个系统都是新的出问题影响范围有限。但棕地项目不一样你是在一个承载着真实业务的老系统上动刀一旦出问题影响的是正在跑的业务。所以棕地 Agent 的上线策略必须是渐进的、可回滚的。灰度发布是唯一正确答案没有之一。但灰度怎么做有很多讲究。我一般会分四个阶段影子阶段、小流量阶段、扩量阶段、全量阶段。每个阶段都有明确的准入和退出条件不达标就不进入下一阶段。7.2 四个阶段的具体操作影子阶段Agent 跟老系统并行跑但结果不生效只记录。这个阶段主要验证 Agent 的准确率和稳定性。准入条件是 Agent 的准确率达到预设阈值、没有严重错误。这个阶段一般跑一到两周覆盖足够多的业务场景。小流量阶段选一小部分业务流量比如 1%让 Agent 的结果真正生效。这个阶段主要验证 Agent 在真实生效场景下的表现以及跟老系统的交互是否正常。准入条件是小流量下没有业务异常、没有性能问题。这个阶段要密切监控一旦有异常立即回滚。扩量阶段逐步扩大流量比例比如 1% 到 5% 到 20% 到 50%。每个比例都要观察一段时间确认稳定后再继续扩。这个阶段主要验证 Agent 在更大流量下的稳定性以及是否有一些低频问题开始暴露。全量阶段流量到 100%。但即使全量了也要保留快速回滚的能力。回滚开关要做得简单可靠最好是一键操作不需要重新部署。7.3 回滚机制的设计要点回滚机制是灰度发布的保险绳必须设计好。我的经验是回滚要能在分钟级完成且回滚后系统状态要能恢复到 Agent 介入之前。这就要求 Agent 的所有写操作都是可逆的或者至少是可补偿的。具体做法上我会给 Agent 的每个写操作设计一个对应的补偿操作。比如 Agent 修改了某个订单的状态补偿操作就是把它改回去。这些补偿操作要预先写好、测试好不能等回滚时才临时想。另外回滚的触发条件要明确可以是人工触发也可以是自动触发比如错误率超过阈值自动回滚。自动回滚要谨慎阈值设得太敏感容易误触发设得太迟钝又起不到保护作用。我一般会设一个相对宽松的自动回滚阈值同时配合人工监控两者结合。8. 法则七团队能力结构比技术选型更决定成败8.1 棕地 Agent 团队需要什么样的人最后一个法则也是我认为最重要的一个棕地 Agent 工程的成败很大程度上不取决于你选了什么框架、用了什么模型而取决于团队的能力结构。这个活儿需要的人跟纯 AI 团队或者纯后端团队都不一样。你需要至少一个懂老系统的资深工程师。这个人不一定是架构师但他必须对老系统的历史、坑、盲区有深入了解。他能告诉你哪些地方能碰、哪些地方不能碰、哪些地方碰了会出什么事。没有这个人你就是在雷区里蒙眼狂奔。你需要一个懂 AI Agent 的工程师。这个人要理解 Agent 的基本原理、主流架构、常见坑知道怎么设计 prompt、怎么处理模型的不确定性、怎么做效果评估。他不一定要是算法专家但要有实际的 Agent 落地经验。你还需要一个懂运维和可观测性的工程师。这个人负责把 Agent 的运行状态变得可见、可控。在棕地环境里这个角色的价值被严重低估。很多时候 Agent 出问题不是逻辑错了而是环境问题、依赖问题、配置问题这些都需要运维视角的人来排查。8.2 团队协作模式的调整除了能力结构协作模式也要调整。传统的开发模式是“需求-开发-测试-上线”的线性流程但棕地 Agent 工程更适合小步快跑、快速验证的模式。因为 Agent 的效果很难在开发阶段完全预测必须尽早放到真实环境里验证。我一般会组织一个小的“攻坚小组”包含上面说的三类人直接对 Agent 的效果负责。这个小组有较大的自主权可以快速做决策、快速试错。同时要跟老系统的维护团队保持密切沟通任何可能影响老系统的改动都要提前对齐。8.3 知识沉淀与传承棕地 Agent 工程还有一个容易被忽略的点知识沉淀。因为涉及老系统的隐性知识、Agent 的调优经验、踩过的坑这些东西如果不沉淀下来人员一变动就全丢了。我一般会要求团队维护三份文档老系统的雷区图、Agent 的设计决策记录、踩坑与解决方案库。这三份文档要持续更新成为团队的共同资产。说到底棕地 Agent 工程是一个系统工程技术只是其中一部分。把人的问题、流程的问题、知识的问题解决好技术方案才能真正落地。我在几个项目里最大的体会就是那些失败的案例往往不是技术不行而是团队没准备好、协作没理顺、知识没沉淀。反过来那些成功的案例技术方案可能很朴素但团队配合得好、节奏控制得好最后效果反而超出预期。如果你正准备在遗留系统上做 Agent我的建议是先别急着选框架、调模型先花时间把上面这七条法则过一遍看看自己的团队和系统准备好了没有。准备好了再动手比仓促上马然后反复返工要快得多。这个领域没有银弹但有方法可循希望这些经验能帮你少踩几个坑。