AI智能体这四个字这一年多我听得太多了。但大部分人聊的其实不是智能体开发而是怎么把大模型接进对话框里。真正能稳定上线的Agent会牵涉需求拆解、架构分层、工具调用、记忆管理、评测体系、灰度迭代等一系列工程问题。我最近刚好把一个客服工单自动分类与回复的智能体从零做到上线中间迭代了十几版踩了不少坑。这篇文章不想讲花哨的概念就按我实际执行的顺序把AI智能体的开发流程从头到尾拆一遍顺便把常规文档里不会写的细节也补上。适合谁看如果你正要开始做Agent但脑子里只有用大模型写个智能助手的模糊想法这篇能帮你先理清完整步骤如果你已经跑通了一个Demo却发现一换场景就崩、一问复杂问题就胡编、一上线就不敢用这篇里的坑位和排查思路应该能对上号。1. 先想清楚Agent到底要解决什么问题才有开发价值1.1 把模糊需求翻译成可验收的目标很多人做AI智能体第一步就错了一上来就挑模型、调接口、写Prompt做完才发现根本没人用因为那个Agent解决的问题不是用户真正的问题。做Agent的第一步不是写代码而是把脑子里的模糊想法变成一个能说清楚、能验收的目标。我那个客服工单项目最初需求只有一句话让AI替客服回消息。这句话没法开发。替客服是全天候还是工作时间回什么消息所有工单都回吗回错了怎么办我拉着需求方开了三次会把这句话拆成了三条细则第一自动识别工单类型包括退货、催单、咨询、投诉分类准确率不低于90%第二自动生成回复草稿客服只需要做一次确认第三识别失败或者情绪激烈的工单一律转人工不能让机器硬着头皮回。这里有个非常关键的经验目标必须能被测试。准确率不低于90%就意味着你要提前准备标注好的测试集不能最后说效果感觉还行。目标必须能做取舍。Agent不是越智能越好在成本和风险敏感的行业你宁可让它少做也不能让它乱做。目标里还得写清楚不做什么——我当时专门列了禁止Agent处理的场景比如涉及账号注销、退款审批、投诉升级这些高风险操作一句话都不允许模型触碰。这个不做什么清单帮我后面省了至少一半的返工时间。1.2 场景边界与交互方式设计目标定完之后下一步是设计Agent的工作流。这个环节我见过很多人直接跳过去开发到一半再回来补流程返工成本高得离谱。具体要考虑三件事。第一是触发条件。Agent什么时候启动是用户主动来问还是系统里某个事件发生就自动跑起来客服场景很典型新工单一创建Agent立刻拿到工单内容、客户历史记录、商品信息先跑一遍分类和分析。如果只靠用户主动发问很多用户根本不知道什么时候该问、怎么问Agent的使用率会非常难看。第二是输出形态。Agent的输出不一定要走自然语言对话。如果你的任务是生成摘要就直接输出结构化字段如果是做表格整理就输出数据文件。对话只是交互方式之一。我这个项目的第一个版本把分析结果全写在自然语言段落里客服要一句一句读太累了。后来改成结构化卡片工单类型、紧急度、建议回复、是否需要人工介入客服扫一眼就能操作。这个改动比换模型带来的体验提升还明显。第三是异常出口。必须明确什么情况下转人工、什么情况下终止流程、什么情况下向用户确认信息。很多Agent没有设计兜底结果在边缘场景里反复循环既浪费token又让用户失去耐心。我在设计里直接写了一条硬规则分类置信度低于某个阈值就输出该工单需人工处理绝不强行生成回复。2. 架构设计一个Agent由哪几块构成2.1 模型层、工具层、数据层与控制层的分工当目标和场景都清晰了再来看架构。一个可用的Agent通常可以拆成四个核心层面模型层、工具层、数据层、控制层。先说说我是怎么分的。模型层负责理解与生成。它接收任务描述和上下文输出计划、动作、最终回复。你选的基座模型决定了这个Agent的基本能力但它不是全部后面控制层才是真正决定交互质量的地方。工具层负责执行动作。Agent不会自己下单也不会自己查数据库它必须通过你暴露给它的函数或API来完成动作。在客服项目里我一开始只暴露了三个工具查订单、查物流、写工单备注。工具数量越少模型选错的概率就越低等稳定之后再逐步加。模型层每次要执行动作都会先输出一个结构化的调用意图工具层再去真的落地。数据层负责记忆与知识。短期会话上下文、用户长期档案、知识库检索内容都归这一层管。后面我会单独展开讲。控制层负责兜底和编排。这是Agent区别于单纯大模型应用的核心。你要在控制层决定模型下一步调用哪个工具、调用失败怎么重试、循环多少次必须停下来、什么情况下直接结束。不要让决策压力完全丢给模型否则Agent行为会非常不可控。这几层一句话概括模型负责想工具负责做数据负责记控制层负责刹住车。这就是一个稳定Agent底座。2.2 循环控制规划、执行、观测怎么串起来凡是讲智能体的教程几乎都会提到Agent循环模型先生成计划然后调用工具看到运行结果后调整想法再继续下一步直到任务完成。原理就是这么简单但真正落到代码里细节比理论多很多。我用的循环结构大致是这样接收输入系统把用户请求或触发事件整理好交给模型。规划模型根据当前状态决定是直接回答还是需要调用工具。执行如果决定调用工具就执行对应函数把结果返回给模型。观测模型读取工具返回结果判断任务是否完成。循环如果没有完成回到第2步继续规划下一步。终止当模型输出任务完成或达到最大步数、超时条件时强制结束。这个循环讲起来轻松但有三个容易踩坑的地方。第一循环必须设置上限。哪怕模型觉得还要再查一次也不能允许它无限调用。我设了最多5次工具调用超过次数就强制转人工省下来的token成本和故障时间都很值。第二不允许模型直接执行危险动作。工具执行前一定要有参数校验比如写工单备注时限制长度和敏感词避免模型把情绪化内容或者错误信息写进系统。第三循环状态必须能观测。每一步都要留执行日志后面排查问题才不用靠猜。如果给一个最简骨架看起来就像这样MAX_STEPS 5 def run_agent(state): for step in range(MAX_STEPS): action model.plan(state) if action.type finish: return action.result if action.type tool: result execute_tool(action) state.append(result) else: raise InvalidActionError(action) return timeout: transfer to human这个骨架不复杂但正是这个有限循环 工具执行 状态记录的组合才让一个模型从只会聊天变成了能办事。3. 核心模块开发把设计落成能跑的代码3.1 提示词不是写作文是定义行为协议到了真正开发阶段最先面对的是Prompt。我强烈建议不要把Prompt写成你是一个善良的客服要耐心回答用户问题之类的姿态描写那是在训态度不是在定义行为。真正有用的系统提示词应该把三块内容写清楚角色与任务边界、可用工具清单和调用约束、终止条件和输出格式。第一版踩过的坑是把所有规则塞在一大段自然语言里。结果在简单命令上表现还行任务一复杂模型就开始自由发挥。后面我改成结构化写法每条规则尽量可判定。比如只有订单状态为已发货时才能调用查物流工具当用户情绪标签为愤怒时必须直接转人工所有金额数字必须来自工具返回结果禁止模型自行推测。这类规则不是建议是约束能把模型的行为确定性提高一个量级。输出格式也要固定。如果希望Agent输出结构化结果就定义好JSON结构并且在提示词里给一个具体示例。我发现一个规律光写清楚字段类型不够写上一个输入侧的真实案例 对应的期望输出模型照着做的准确率明显更高。比如你说输出类型为单号、状态、预计时间模型偶尔会加解释文字但如果你给出完整示例JSON模型大概率会严格照着输出解释也没了。3.2 工具注册与参数校验Agent的双手Agent要干活必须靠工具。工具调用这块最关键的不是把函数接通而是把模型生成参数和参数安全校验分开。模型生成参数时偶尔会多传一个字段或者把字符串参数传成数组或者把一个枚举值拼错。你要是直接把模型输出塞给内部函数执行轻则报错重则把脏数据写进业务库。我的做法是给每个工具外面套一层解析和校验逻辑。先定义清楚字段类型、必填项、取值范围再用校验逻辑把模型输出规范化。比如查订单工具的order_id必须匹配ORD 10位数字的格式不符合就返回一条错误给模型提示请重新提供有效订单号。这样模型能在下一步自我纠正而不是把错误一直传下去。这里还有一个容易被忽略的细节工具描述写得好不好直接影响模型的规划能力。不要写查询订单接口要写根据订单编号查询订单当前状态和商品明细仅用于处理与订单相关的用户询问。让模型知道这个工具什么时候该用、什么时候不该用工具的误用率会明显下降。我在项目里把两个工具的description各改了三次每次都能看到调用准确率的提升。3.3 记忆模块别让Agent每次对话都失忆记忆是智能体从能对话升级到能持续办事的关键一步。我把Agent记忆分成三级会话内记忆、用户级长期记忆、知识库辅助记忆。会话内记忆最基础把同一个任务中间的上下文保留下来让模型在几步内保持连贯。这里要注意长度控制不能把所有历史都塞给模型否则上下文窗口炸掉成本也吓人。我通常只保留最近几轮结构化的动作记录再往前的信息做一轮摘要摘要丢了就丢了不必追求完整。用户级长期记忆用于用户下次出现时能认出上下文。客服场景特别明显如果这个用户上次投诉过运费贵这次再问售后问题Agent应该记得。做法是把重要信息写入存储比如普通数据库或者向量数据库下一次启动任务时先搜一下相关记忆把命中内容放进上下文。知识库辅助记忆也就是RAG这套思路。把产品手册、规则文档、常见问题离线切片做向量化存储用户问到相关内容时先检索再回答。这一步能明显减少模型一本正经地编造答案。但检索不是召回越多越好一定要加相关性阈值低于阈值就不要把文档塞进上下文否则不相关的片段反而会误导模型。我自己就吃过亏某次把一篇不合时宜的旧版规则召回进上下文模型照着旧规则给出了完全错误的建议那个Case后来成了我评测集里长期留存的经典负面样例。4. 评测体系先过门槛再谈智能4.1 最小可用评测集怎么搭我见过太多AI项目死在开发时感觉不错一上线就是事故原因是只靠几个手动测试场景就把产品推上线了。Agent开发一定要尽早搭评测集哪怕最开始只有三五十条用例也比没有强。评测集至少分三类。第一类是标准功能用例覆盖最常见的任务路径。客服场景里就是退货、换地址、催单、查物流每个类型至少10条用来保证主流程稳定。第二类是边界用例包括空输入、超长文本、完全无关的闲聊、模棱两可的提问。这些Case最能暴露Prompt和循环的脆弱点。第三类是风险用例包括情绪激烈的表达、要求AI做它不可能做到的事、提问里夹带特殊符号或者重复刷屏等。每一类用例除了输入之外还要定义期望行为。注意这里不要期望一个固定死答案而是要期望行为模式。比如输出为结构化卡片未调用任何工具调用查物流工具一次在置信度低时转人工。评测的时候让程序去判断是否满足预期行为而不是肉眼盯着一堆回答看效果。这些用例加起来虽然不多但每次改模型、改Prompt、加工具之后都跑一遍能挡住大部分回归问题。我在项目里跑了两周至少有三次模型换版后出现的低级行为倒退都是评测集提前拦下来的。要是没这套东西大概率要等线上用户骂了才知道。4.2 安全兜底宁可少做不能乱做安全这块必须单独拿出来提醒。Agent的智能如果不受控制后果比一个平庸的对话机器人麻烦得多因为Agent有工具工具就是手脚手脚必须被约束。第一个兜底是权限边界。Agent能调用的工具必须是最小权限集合。客服Agent能查订单、能写备注但绝对不应该有删除工单、改价格、导出用户列表的权限。哪怕模型在某次对话里提出了错误调用意图工具层也要能直接拒绝。权限不是写在Prompt里的君子协议而是要在工具执行层用代码守住。第二个兜底是内容安全策略。不能向用户输出不合规的内容也不能输出无依据的业务确定性结论。我在客服场景里加了一条特别有用的规则凡是金额、时间、库存这类数字信息必须来自工具返回结果而不是模型靠推理编的模型推理只能作为建议不能作为事实。没有这条规则模型会一本正经地告诉用户明天肯定到货实际上包裹还在仓库躺着这种事故一次就能让业务方把Agent整个下线。第三个兜底是循环和异常处理。包括最大调用次数、超时降级、并发控制、退出话术。上线之前把备选路径都列一遍模型服务挂了怎么办工具超时怎么办用户连续追问同一问题怎么办每一个场景都要有明确动作。把这些逻辑做成清单放进测试用例里每次发布前逐条过一遍。这块功夫花下去上线之后才能少救火。5. 部署与迭代上线才是开发的开始5.1 日志、追踪与回归的搭建思路真正上线之后一切才刚刚开始。Agent和普通后端服务不一样一个请求里面可能包含多次模型调用、多次工具调用出问题时很难定位是哪一步岔了。所以日志与追踪的建设在方案设计阶段就要想好。我给每个请求生成一个唯一的会话ID把每一步执行情况都记录下来模型输入和输出、调用了哪个工具、传了什么参数、工具返回了什么、每步耗时多少、最终结果是什么。线上一旦出现一个错误顺着这个ID就能完整还原Agent的执行轨迹。这个能力在排查模型为什么调用错工具的时候特别有用几乎是一把钥匙。这类日志不仅能拿来排查问题还是评测集的持续素材来源。上线第一周我发现了一些开发时完全没想到的输入形态比如有人把订单号和问题混在一句话里、有人连续追问三次相同内容、有人故意发一串乱码来测试。把这类真实输入定期挑一些有代表性的加进评测集回归覆盖会越来越完整。5.2 常见问题排查速查表把自己项目中比较常见的几类问题整理成一张速查表排查效率提高得很明显。这张表也可以给新接手的人看能省下很多重复答疑时间。现象排查方向常用解法工具乱调用看模型输出中工具调用轨迹检查工具描述是否清晰优化工具描述收紧调用条件规则回答明显错误检查是否有不相关内容被检索进上下文补充相关性阈值核对知识库切片质量循环不退出执行轨迹里出现重复工具调用限制最大步数增加终止条件输出不符合预期检查Prompt输出格式约束和示例增加结构化示例解析失败增加重试用户历史记不住检查长期记忆写入时机和召回策略优化记忆写入增加相关记忆召回成本不断偏高看每次调用的输入token分布精简上下文长度合理使用缓存这张表最主要的价值不是那些解法有多高级而是帮你建立了一种排查习惯每次遇到线上问题先看执行轨迹再定位是哪一层出了问题。我在项目里把这个流程固定下来之后团队排查速度和新人上手速度都明显提升。5.3 迭代节奏小步快跑别追求一步到位智能体的迭代最忌讳一次改太多。模型调用链路很复杂你改了一个Prompt可能另一个工具调用行为就跟着变了换一个模型版本可能之前表现稳定的记忆策略又开始退化。所以我在迭代时尽量一次只动一个变量这次只换模型下次只改Prompt再下一次只加一个工具。每次改完跑一遍完整评测集再结合线上数据做对比确认没有副作用才进入下一轮。另一个有效做法是灰度策略。上线时先让Agent处理小比例的真实流量观察客服的确认率和用户反馈稳定之后再逐步扩大比例。不要一上来就把所有流量交给Agent。哪怕评测集全部通过真实环境里的口语表达、异常输入、并发压力都可能超出预期。小步快跑在Agent项目里不是保守是对整个系统负责。最后分享一条我自己的习惯每次发布新版之前我会从上一周的真实数据里随机抽20条当回归用例自己亲眼看一遍Agent的输出。这20条不需要写什么复杂逻辑肉眼扫过就能发现评测集里很难自动发现的细节毛病比如语气突然生硬、某个业务词被误解、回复段落长短失衡。模型能力不能只看准确率还要看手感。Agent开发真正的门槛不在模型本身而在于你愿不愿意为每一处小细节较真。把AI智能体的开发流程做扎实它才能真正从能跑通的Demo变成能扛事的系统。