开头之前我发过一篇文章聊 AI Agent 开发评论区有个老哥留言说“搞了半天这玩意 90% 还是在写代码、搞架构、处理异常跟以前做后端没什么两样啊。”我当时回了一句“恭喜你悟了。”说真的这句话我特别认同。很多人一听到“AI 智能体开发”第一反应是“要学深度学习了吧”、“要调模型了吧”、“是不是得天天研究 Prompt”——但等我真把一个智能体从 Demo 推到线上踩完一整轮坑之后回头看发现真正的难点根本不是模型而是那些听起来很朴素的词需求边界、数据管道、接口契约、错误处理、超时重试、日志监控、回归测试、成本控制。这些东西的名字就叫软件工程。这篇文章我打算彻底摊开讲清楚为什么 AI 智能体开发里 90% 其实是软件工程这个 90% 到底落在哪些具体环节每个环节要怎么做才能避免“Demo 跑得欢、上线就翻车”特别是 2025 年以来行业里越来越多人提的 harness engineering智能体工程化/护栏工程本质上也是一套系统工程打法而不是单纯的算法问题。如果你是后端或前端程序员正在考虑转 Agent 开发那这篇文章就是给你写的。如果你已经入坑但是总感觉智能体“时灵时不灵”“不敢放给用户用”那看完这篇文章你会明白问题到底出在哪。1. 先打破一个误区AI 智能体不是“会写 Prompt 就行”1.1 智能体到底是什么先给个简单的定义。一个能真正干活的 AI 智能体至少由四部分组成模型大脑、记忆短期长期、工具调用能力手、任务规划能力执行逻辑。模型负责理解和生成但光有模型它只是个“聊天机器人”跟你说话可以干不了活。工具调用让它可以查数据库、调 API、发邮件、操作软件。记忆让它可以记住上下文和用户偏好。任务规划让它自己拆解步骤、按顺序执行、遇到问题调整方案。这四个部分凑在一起才叫 Agent。但这四部分全做出来了也只是“有手有脚”而已真正让智能体在真实业务里稳定跑起来的是它外面那一圈工程外壳上下文怎么管理、工具接口怎么定义、出错怎么处理、权限怎么控制、数据怎么流转、效果怎么评估。所以我现在对“智能体开发”的定义很简单让模型稳定地、可控地、低成本地完成真实业务任务的全部工程实践。模型选型只是第一步剩下大部分时间都是在跟工程细节较劲。1.2 “90% 软件工程”这个比例是怎么估出来的这个比例不是我拍脑袋乱说的是我自己做了几个实际项目之后的一个体感。你可以把自己代入一下假设你要做一个“智能客服工单分类与自动回复”的 Agent从零到一推到线上需求澄清和边界划定大概要花 3 天接口协议设计和工具函数定义2 天数据清洗和 RAG 知识库准备5 天Agent 工作流编排和提示词初版3 天模型效果调试和 Prompt 迭代5 天测试集构建、自动化回归、评估体系搭建4 天部署、灰度、监控告警、成本看板4 天线上问题排查和迭代后面就没完没了了。你仔细看看真正“面向模型写提示词”的时间只有 3 到 5 天剩下十几二十天都在干软件工程师的活。哪怕你按投入时间算模型相关的部分占比也就 10% 到 20%。说“90% 是软件工程”一点不夸张。1.3 为什么很多 Demo 跑得通一上生产就废我见过太多类似的场景了演示的时候模型聪明得不行按照 Prompt 一步步把问题解决得很漂亮。结果一上生产各种幺蛾子全来了——用户在输入框里打了一长串语音转文字的废话模型把这些内容当成指令工具返回的数据格式跟预期不一致模型直接编了个假结果某个流程超过 30 秒没响应用户刷新页面Agent 的状态丢了高峰期并发一上来Token 消耗飙升账单一天跑了过去一个月的量。这些问题没有一个是“模型不聪明”导致的全是工程上的疏忽。Demo 环境里数据是干净的、调用是串行的、一次任务就结束、并发为零、失败就重来。生产环境完全相反脏数据、并发、部分失败、状态持久化、超时控制、成本预算每一项都是工程问题。所以如果你现在正准备做 Agent 开发我真心建议你先把“软件工程”四个字刻在脑子里后面每一步都问自己一句这一块算模型问题还是工程问题2. 从开发全流程看软件工程到底嵌在哪几环2.1 需求层最难的不是“想做什么”而是“不能做什么”做传统软件时需求分析最常见的产出是“功能清单”这个系统要支持登录、要支持下单、要支持退款记录。但做 AI 智能体的需求分析光列“要做什么”是远远不够的更关键的是把“不能做什么”和“边界在哪”说清楚。举个例子。你要做一个“招聘助手 Agent”它负责从简历库里筛选候选人、生成初筛报告。表面需求很好理解筛简历、出报告。但真正的工程难点是什么条件的候选人需要转给人工 HR 而不是直接发拒信边界条件怎么写清楚如果模型对简历信息的理解有误把“5 年经验”看成了“不限经验”造成的误判谁来兜底模型要不要具备向候选人发送邮件的权限还是只生成草稿、人工确认后再发出报告时涉及薪酬预期的判断这是高敏感内容模型说的不算还是算这些问题简单说就是要在需求阶段把“自动化的边界”画出来。哪条线以内模型可以自主行事哪条线以上必须有人介入这是任何一个 Agent 产品落地前必须想明白的事。我做过一个智能工单系统当时花了整整一天跟业务方一起定了一个“兜底矩阵”问题类型、复杂度、涉及金额、用户情绪四个维度组合起来有十几种场景每个场景都明确写清楚智能体是“直接处理”还是“生成建议转人工”。这套矩阵后来就变成了 Agent 工作流里的路由规则直接决定了系统能不能稳定上线。2.2 架构层把智能体拆成可维护的模块传统后端讲究模块化、分层、解耦Agent 开发一样要这么干绝对不能把所有逻辑塞进一个超大 Prompt 里。一个相对成熟的 Agent 系统架构我个人体会至少要拆成这几层模型层负责基础理解和生成包括模型选型、部署、上下文窗口管理。对绝大多数团队来说用 API 调用最省心。编排层任务规划与执行引擎决定 Agent 当前该调用哪个工具、下一步执行什么操作这部分可以用 LangChain、LlamaIndex 这类框架也可以自己写状态机。工具层把内部系统 API、数据库查询、第三方服务等包装成模型的“可调用函数”。这一层最讲究工程规范每个工具都得有明确的入参、出参、错误码。记忆层管理会话上下文、用户画像、长期知识存储。这里的核心是“该记什么、不该记什么、什么时候清空”纯工程取舍。接入层打通前端、IM 工具、业务系统处理鉴权、限流、消息格式转换。每一层都可以独立开发、独立测试、独立部署。如果你把提示词、工具逻辑、业务流程全写在了一个文件里那后期就是无尽的噩梦改一句话整个 Agent 行为变了而且你还不知道是哪里变的。2.3 数据与评测层Prompt 也要“版本管理”普通开发者最容易忽略的就是对 Prompt 的版本管理和回归测试。代码有 Git 管着但 Prompt 在很多团队里就是躺在文档里的一段文本改没改过、什么时候改的、上线之后效果如何完全无记录。等到线上指标下滑你都不知道是不是某个同事改了一句 Prompt 导致的。我自己的做法是所有 Prompt 模板都作为代码文件纳入 Git 管理每次修改必须有 commit、有 review、有评估记录。同时建立一份固定的评测集里面放 20 到 50 个典型用户问题每个问题标注标准答案或评分标准。每次改 Prompt 或者换模型先把这份评测集跑一遍看通过率变化。这套做法本质上就是把“测试驱动开发”从传统代码搬到了 Prompt 的世界里。你想想这不就是软件工程吗2.4 基础设施与生命周期传统技能的平移再往下就是更传统的部分了。Agent 跑在线上它也是服务一样需要API 网关处理鉴权和限流缓存降低重复请求的 Token 消耗消息队列削峰填谷数据库做任务状态持久化日志系统记录每一次模型调用监控大盘展示成功率、延迟、Token 消耗灰度发布和回滚机制这些能力任何一个经验丰富的后端工程师都能直接上手搭出来。而且你会发现做过正经后端的人做 Agent 开发有天然优势——因为你早就习惯性地考虑“系统崩了怎么办”“并发高了怎么办”“数据丢了怎么办”而这些问题恰恰是 Agent 落地最致命的风险点。我见过一些以 Prompt 工程起家的团队他们能把一个智能体在演示环境里调得完美无瑕但一聊到“如果模型超时怎么办”“怎么保证不重复扣款”就哑火了。模型不背这个锅是你没有用工程标准去要求这个系统。3. harness engineering学会给智能体“上缰绳”3.1 Harness 到底是什么先解释一下这个英文词。Harness 在英文里有“马具、挽具”的意思引申为“控制和约束装置”。放在 AI 智能体领域harness engineering 直译就是“缰绳工程”更准确的说法是“智能体工程化/护栏工程”。它指的是围绕模型构建一套系统性的控制、校验、约束和评估机制让模型的能力被限定在业务可接受的范围内输出。模型本身是不可完全预测的同一个 Prompt 可能这次回得很好、下次就胡说八道。规模小的时候你靠运气规模大了就只能靠制度这个制度就是整套 harness。你可以把大模型想象成一个极其聪明但偶尔会“飘”的新人员工。你不可能因为他在某一件事上做得好就把整个公司的决策权直接交给他。你需要的是明确他的职责边界、给他配置好工具和材料、设定校验机制、安排好审批环节以及一套考核标准。这一整套管理机制就是 harness。3.2 可控性设计把自由度收窄到业务可接受的范围Harness 的核心目标之一是“可控”。具体怎么落地我分享几个我在项目里实测过的方法第一约束输出格式。不要依赖模型自由发挥强制它输出 JSON并且套用固定的 Schema。大多数模型都支持 JSON mode 或结构化输出你要在工程层把它变成约定而不是期望。第二工具调用白名单化。Agent 能调用的工具必须预先声明不能让它自己“发明”工具。每个工具的参数要做严格校验宁可拒绝执行也不能让脏参数进入生产系统。第三人工审批节点。对于高风险的业务动作比如发送邮件、转账、删除数据、对外发布内容一定要加人工审批环节。技术上的实现就是Agent 生成操作请求写入待审批队列人工确认后执行。第四执行退出策略。一定要给 Agent 设定最大的工具调用轮数上限。比如最多允许调用 10 次工具超过之后强制结束。很多线上事故就是 Agent 在一个错误分支里反复调用工具最终造成大量 Token 花费甚至数据污染。3.3 可评测性设计没有评估就没有优化Harness 的第二个核心目标是“可评测”。如果把 Agent 丢上线之后才发现效果不行那你连“不行在哪”都说不清。所以在一开始就要把评测机制设计好。我自己的做法是搞三重评测第一重是离线评测集。固定的 100 个左右问题样本覆盖正常场景、边界场景、对抗场景。每次发版前跑一遍看通过率和失败原因。第二重是仿真环境。用一份脱敏的历史业务数据让 Agent 在测试环境里跑真实任务验证它在接近生产环境下的表现。第三重是线上指标。上线后密切跟踪三个核心指标任务完成率、平均任务时长、单位任务 Token 消耗。这三个指标任何一个异常都要立即回滚定位。这套东西听起来很重但你想想传统软件工程里的单元测试、集成测试、线上监控是不是同一个逻辑无非是把“代码行为”换成了“模型行为”。3.4 对中小团队的启示没有大厂资源怎么办大厂做 Agent 可以养一个团队专门建 harness 平台但中小团队没这个资源。我的经验是不要追求大而全先把最小闭环跑起来。你只需要三样东西一个版本控制仓库同时管代码和 Prompt一份评测集哪怕只有 30 个问题也足够抓住最明显的回归一个日志平台能够记录每次模型调用的输入、输出、工具结果和耗时。这三样加起来成本极低都是现成工具拼一拼就行。但有了它们你就拥有了对 Agent 最基本的管理能力。很多人做 Agent 失败不是因为模型不够好而是因为完全没有“反馈闭环”——改没改好、哪里坏了、为什么坏全部靠感觉。4. 动手实操从 0 到 1 搭建一个能落地的 AI 智能体这一节我用一个真实做过的项目来复盘智能工单分类与自动回复 Agent。不扯概念直接讲每个环节我做了什么、怎么做的、当时踩了什么坑。4.1 需求拆解与边界划定这个系统的目标很朴素客户通过网页提交工单系统自动判断工单类型、紧急程度并生成初版回复建议。如果判断为高优或涉及退款转人工处理。听起来很简单对吧但真正写代码前我们花了两天时间跟业务方一起敲定边界。最后画出来的是这样几个硬规则工单类型一共 8 类如账号类、支付类、技术故障类、投诉类等分类结果必须从这 8 类里选不许自由发挥紧急程度由“用户是否有明确时间诉求 问题是否阻断核心功能”两个因素决定不接受模型自行加入第三个判断维度涉及金额超过 100 元的退款诉求一律转人工用户语言包含明显的辱骂或威胁时不生成回复直接升级人工。这些规则没有一个是模型“学”出来的全是业务专家和工程师一起梳理出的工程约束。没有这些约束Agent 就是脱缰野马跑得越快越危险。4.2 技术选型与工作流设计选型上我当时的判断是不要迷信最强模型要选“够用 便宜 响应快”的。工单分类这个场景绝大多数是不需要深层推理的任务用中档模型就够。大模型放在那里做复杂意图分析和最终答案润色。工作流设计我采用了“漏斗式”结构每一步都有明确的输入输出契约接收工单 → 意图识别 → 关键信息抽取 → 工具调用查用户订单/查历史工单 → 分类与紧急度确认 → 生成回复草稿 → 风险判定是否转人工 → 输出每一步对应一个模块可以单独测试、单独替换。这里的核心工程点在于每一步的输出都定义成严格的数据结构某一步失败时系统知道从哪个节点重试而不是整条链路推倒重来。4.3 关键工程实现上下文管理与结构化输出这是我觉得最值得展开的部分也是“软件工程含量”最高的地方。第一上下文管理。模型上下文窗口是有限的你不能把整段对话历史和几十页业务手册全塞进去。我的方案是设计了一套“工作记忆”结构当前工单原文、抽取出的实体列表、已调用的工具结果、模型当前状态。每次调用模型时把“工作记忆”和预先编译好的“业务规则”拼成上下文。业务规则按照工单类型分模块先分类成功再只塞入对应模块的规则大幅缩短上下文长度。第二结构化输出。我给每一步都写死了 JSON Schema模型必须按照这个 Schema 输出。比如意图识别这一步输出只能是{ category: payment, confidence: 0.95, reason: 用户提到重复扣款和订单金额异常 }如果模型输出不符合 Schema系统自动重试一次并提示“请严格按照给定格式输出”。不要小看这个机制它省掉的解析 Bug 数量非常可观。第三工具调用的容错。查用户订单的 API 有时候会超时或返回异常数据。我在工具层做了一层包装每个工具最多重试两次、有明确的超时时间、失败时必须返回结构化的错误码模型根据错误码决定是换一种方式查询还是转人工。这些代码跟传统后端开发里的重试、熔断、降级逻辑几乎一模一样。4.4 测试与灰度上线前不慌测试方面我建了一个 80 条的评测集覆盖 8 类工单的正常场景、还有我特意构造的边界场景。其中有个边界场景我印象特别深用户写的工单特别短只有“怎么退钱”四个字。这种模糊工单模型经常会把类型判成“投诉”或者“退款”但实际可能是技术问题导致的退款诉求。这个 case 被我们单独拿出来反复调 Prompt直到模型学会了一个原则信息不完整时宁可触发追问流程也不要瞎猜。灰度策略上我们先把 Agent 的判定结果与纯人工判定结果做对比在后台跑了三周影子模式比对一致率达到 93% 之后才敢正式开放自动回复。Shadow mode 是一个实用的工程技巧强烈推荐大家在 Agent 项目里用起来。4.5 上线后我最关注的三个指标系统跑起来之后我给自己定了三个每日必看的指标转人工率。如果一个智能体的转人工率长期偏高说明它的能力边界明显不足要么训练数据不够要么期望值定太高。平均处理时长。对比人工处理时间如果 Agent 并没有节省时间那这个系统的价值就要打个问号。单位工单的 Token 成本。模型调用不是免费的成本失控会让整个业务模式不成立。其实后两个指标就是传统软件里的“性能监控”和“成本监控”换成 Agent 场景照样适用。你会发现工程思维在这里的价值一点不比写代码的能力低。5. 常见问题与排查技巧实录最后把我在多个 Agent 项目里踩过的坑集中列一下。这些都是真实遇到过的我把症状、原因和排查方法整理成了一张速查表。症状根本原因排查思路我的解法Agent 答非所问像喝多了上下文太长关键信息被淹没检查实际送到模型的上下文内容精简上下文把业务规则分模块按需注入Token 消耗爆炸一天烧掉一个月预算没有限制工具调用轮数、循环调用查看日志里的调用序列和轮数设定最大轮数上限、增加缓存机制工具调用经常返回格式错误模型输出不稳定JSON 结构偶尔变体查看返回原文多半是字段名漂移强制结构化输出 失败重试机制线上效果与测试环境差异巨大测试数据太干净线上数据太杂对比测试集和线上典型输入影子模式灰度逐渐切流量同一个问题这周答得好下周答得差Prompt 或模型版本被无感知修改追溯 Prompt 变更历史Prompt 纳入 Git 管理发版走评审Agent 在某些分支里死循环没有退出条件或退出条件被绕过查执行日志里的循环路径强制轮数上限 超时熔断用户骂了一句Agent 回了一篇论文模型被脏输入带偏缺少输入过滤看原始输入的上下文加敏感词过滤识别攻击性输入直接转人工下面挑三个最有代表性的展开细说。5.1 模型反复“胡说八道”但评测集却通过这个问题的典型情况是评测集通过率 95%上线之后用户反馈里全是“答非所问”。为什么会这样因为评测集太“正”了全是标准场景、标准输入。真实用户会打错字、会一段话里混着多个意图、会用口语化的黑话。怎么破我的办法是“脏数据采集”上线后前两周把线上真实工单里用户输入的部分全部脱敏存下来每天挑 20 条模型回答得不好的手工标注正确答案加进评测集里。两周之后评测集从 80 条涨到 240 条模型的效果才真正开始稳定。这个流程本质上就是传统软件里“线上 Bug 转回归测试用例”的翻版。5.2 Token 成本失控我见过最夸张的一次是某 Agent 在用户毫不知情的情况下自己循环调了 20 次工具最终一次性消耗了相当于 200 次正常对话的 Token。排查日志时发现原因是模型在一个错误分支里反复尝试调用同一个失败的接口。解法是双管齐下一是工程层设置硬性上限——单次任务最多 10 轮工具调用达到上限强制终止二是 Prompt 层明确要求——“如果工具调用连续两次返回相同错误停止尝试以最后可用信息生成回答”。一个靠机制一个靠引导合起来成本立刻就降下来了。5.3 Agent 一旦开始犯错就容易连环犯错这是 AI 智能体最头疼的问题之一前面一个步骤出错后错误信息会顺着上下文传给下一步模型基于错误信息继续推理越错越远最终输出的东西根本没法用。我排查过的一个典型案例是某个工单是支付重复扣款Agent 第一轮调用查订单接口时因为参数传错拿到了另一个用户的订单。它没有发现数据异常反而顺着这份错误数据继续生成回复。这个 Bug 的根因是Agent 缺少一个“数据自检”环节。后来我在工具层加了一个东西每个工具返回数据时同时返回一个“数据完整性标志”。比如查订单接口如果用户 ID 与工单中的用户 ID 不一致就必须返回错误码而不是数据。模型看到错误码后会触发“数据不一致”的处理分支要么重新获取要么转人工。这层校验除了工程思维没有任何模型能力能替你兜住。结尾写到这里我想说几句实在话。AI 智能体开发确实不是传统意义上的纯软件工程——因为你面对的核心引擎是一个不可完全预测的系统这跟“输入确定、输出确定”的传统程序有本质区别。承认这种不确定性然后用软件工程的手段去管理它这才是 Agent 工程化的精髓。我个人在实际操作中的体会是模型能力决定了智能体的上限软件工程决定了它的下限。市面上的模型已经足够聪明绝大多数 Agent 项目做砸了问题都出在下限——没有边界、没有评测、没有熔断、没有护栏。所以每次有朋友问我“我想转 Agent 开发该学什么”我给的建议都是先把软件工程基本功练扎实再去碰模型。框架可以等提示词可以调但工程底子不行项目越大死得越快。最后再分享一个小技巧。当你完成第一个 Agent 项目之后把整个开发过程复盘一遍统计自己在“模型相关”和“工程相关”上分别花了多少时间。如果比例真的接近 1:9那说明你已经正式入门了。这不是天分问题是这个领域本来就该有的常态。