★ FEATURED ARTICLE 1. 先搞清楚一件事智能体工程不等于调Prompt这两年周围聊智能体的人突然多了起来朋友圈里到处是AI自动写周报AI帮我订机票的截图。但如果你真去复现过这类东西大概率会遇到一个尴尬情况demo跑得挺欢一放到真实业务里就各种翻车。我见过不少团队花了两个星期把智能体框架搭起来结果上线第一天就闹出笑话——让AI查个库存它把查询接口和下单接口顺序搞反了差点给客户重复发货。问题出在哪很多人把智能体工程理解成写一段好Prompt再调几个API。真正的智能体工程核心是把LLM当成一个不可靠的员工来管理它会偷懒、会臆想、会忘记交代过的事情、会自作主张。你要做的不是让它跑起来而是设计一套机制让它在犯错时能被发现、被纠正、被限制在安全边界内。这也是我这篇要讲的主题智能体工程到底是什么、一个生产级智能体由哪些部分组成、从零搭建时每一步该怎么做以及那些网上教程基本不会告诉你的翻车点。不管你之前只会写Python脚本还是已经在搞大模型应用这篇都值得花十分钟看完。补充一句这里说的生产级不是指代码能上线而是指——面对真实用户、真实数据、真实业务逻辑时智能体仍然能稳定、可预期、可排查地完成工作。这三个词是硬指标后面会反复用到。2. 拆开智能体看五个组件各自要解决什么问题2.1 大脑模型选型与温度设置的取舍很多人觉得智能体的大脑就是选个最强模型其实工程视角下选模型要考虑三件事推理能力、调用稳定性、成本。推理能力决定了智能体能不能处理复杂任务调用稳定性决定模型在遇到模糊指令时是乖乖返回结构化结果还是自己编一个格式出来成本则是商业项目里逃不开的紧箍咒。我见过一个数据看板项目为了让智能体更聪明无脑上了一个超大参数模型结果每次会话平均消耗两万多token一个月下来账单比团队工资还高。温度参数这里有个反直觉的点很多人以为温度越低越稳定就一设设成0。实际使用中温度过低会导致模型在工具调用时过于机械尤其在多个候选工具都能完成同一件事时它可能反复卡在同一个错误选择上。我建议工具调用相关场景温度设在0到0.3之间需要创意生成的场景另说。另外要提醒一点模型选型不是一步到位的事。项目初期可以用强模型做能力验证跑通后实测业务场景的调用成功率再逐步替换成更便宜的模型。我习惯的做法是同一套评测集让两个模型各自跑一遍对比工具调用成功率、回答被采纳率、兜底触发率用数据说话。2.2 手和脚工具调用Function Calling的关键设计智能体之所以是智能体而不是聊天机器人核心在于它能调用工具。工具调用可以简单理解为模型在对话中输出一个结构化意图比如我要查天气城市北京然后由你的代码去执行真实的查询函数再把结果回传给模型继续生成回答。这里有个初学者最容易踩的坑把工具当Prompt写。比如你要让模型查订单直接在系统Prompt里写你可以调用query_order函数查询订单——这样模型大概率只是假装调用返回一段我已经查了您的订单的文字而不是真正触发函数。正确的做法是用模型厂商提供的function calling或tool use接口在API请求里显式声明工具的结构化定义包括函数名、参数类型、参数描述。这样模型才会输出严格的JSON结构你的代码才能解析并执行。工具定义里的参数描述非常关键。描述写得越清楚模型的参数填充准确率越高。举个例子用户ID和用户的唯一标识字符串类型来自登录态注意是数字字符串而不是用户名——后者明显让模型更容易填对。我在项目里见过参数描述写得模糊模型经常把用户名当用户ID传给接口这在工程上属于数据污染级别的问题。2.3 记忆短期上下文与长期存储的边界记忆这个词被用烂了但工程上必须区分两种记忆一种是会话内的上下文记忆即当前对话窗口里模型能看到的所有消息另一种是跨会话的长期记忆需要存储到数据库、向量库或其他外部系统里。很多智能体对话越久越傻的根因恰恰是这两种记忆混着用。短期记忆的管理核心是控制上下文长度。你不可能把所有聊天记录一直往模型里塞否则token成本上升、响应变慢、模型还容易被无关信息干扰。常见的做法是做消息摘要当会话超过一定轮次把早期对话用一次LLM调用压缩成摘要再塞回上下文。这个方案成熟且成本低适合大多数场景。长期记忆的典型形态是让智能体记住用户的偏好、历史操作、业务规则。这里我强烈建议不要把所有东西都丢进向量库检索大多数业务偏好是结构化的比如用户偏好邮件而不是短信通知一条字段就能存下来没必要做向量化。向量检索只在处理非结构化内容比如历史聊天全文、文档片段时才是正当选择。2.4 规划与执行循环从问一句答一句到自动拆解任务单轮工具调用解决不了复杂任务比如帮我整理这个季度的销售报表并给异常数据写说明——这需要智能体内部先规划再一步步执行。这就是所谓的ReAct循环思考Reason、行动Act、观察Observe如此往复直到任务完成。实现这套循环的工程难度比很多人想象的大得多。你要设定最大循环次数防止智能体陷入死循环你要在某些步骤失败时给出重试策略你还要判断什么时候任务算完成。很多入门项目里智能体在第三步做错了然后接下来的十步全建立在错误结果上最后自信满满地给出一个错误答案——这种情况你有没有见过我的经验是不要完全放任模型自主规划。更高可靠的方案是先让模型输出执行计划由代码校验计划的合法性比如步骤是否依赖未完成的前置条件再逐步执行。这种模式牺牲了一点自主性但换来的是每一步都是可审查、可中断、可回滚的。生产系统里可控性永远比炫酷重要。2.5 护栏输出校验与安全边界最后这一层是区分玩具和产品的分水岭。护栏的含义是智能体的输入、输出、行为都要经过代码层面的校验不能让模型的输出直接穿透到业务系统里。最简单的护栏有两种结构校验和内容校验。结构校验是指模型返回的JSON必须经过schema验证字段类型不对、缺字段都直接拒绝内容校验是指对模型生成的文本做敏感信息扫描、违规词过滤、以及必要的格式检查。更进阶的护栏还包括工具调用的权限控制这个AI能调用哪些接口、不能调用哪些、运行时超时熔断、操作审计日志。我见过一个真实事故智能体被用户诱导后调用了一个内部删除接口因为代码里直接把模型的工具调用结果映射为真实的接口调用没有任何权限校验。所幸是测试环境但那一幕足够让人冷汗直流。记住一条铁律模型没有权限代码才有权限。LLM只负责生成想调用哪个工具的意图最终要不要执行、能不能执行必须由你的代码基于用户身份和业务规则来决定。3. 从一个具体场景入手搭建最小可用的智能体3.1 场景定义与工具设计理论说多了容易飘我用一个具体场景把上面几个组件串起来。假设我们要做一个内部知识问答与工单创建助手员工可以问公司制度、查项目进度如果问题解决不了智能体可以帮忙创建一张工单。这个场景选得好因为它同时涉及两类工具只读类工具查询制度文档、查询项目进度写操作类工具创建工单设计阶段我给每个工具写清楚三样东西功能描述、参数列表、返回结果说明。注意返回结果说明经常被忽略但模型拿到结果后需要判断结果是否足够回答问题如果返回结构混乱模型的判断也会混乱。拿创建工单这个工具为例它的参数包括标题、描述、优先级、指派人。我在参数描述里特别写了描述字段需要包含问题背景、已尝试过的解决步骤因为如果不指定模型经常只填一句话有问题——工单建了等于白建。3.2 核心代码任务循环与工具注册用伪代码说明核心流程。这里不需要特定的框架你自己用任何支持function calling的SDK都能实现def run_agent(user_query, tools, max_steps8): messages [{role: system, content: SYSTEM_PROMPT}, {role: user, content: user_query}] for step in range(max_steps): # 把工具定义随请求发给模型 response llm.chat(messagesmessages, toolstools) msg response.message # 如果模型没有请求调用工具说明任务结束 if not msg.tool_calls: return msg.content # 逐条执行模型请求的工具 for call in msg.tool_calls: result execute_tool(call.name, call.arguments) # 把工具结果追加到对话历史让模型继续 messages.append({ role: tool, tool_call_id: call.id, content: json.dumps(result, ensure_asciiFalse) }) return 已达最大步骤数任务未完成这是一个极简的ReAct循环。你可能注意到真正干活的那句是execute_tool(call.name, call.arguments)但前面所有的消息管理、步骤控制、结果回填才是工程的核心——每一步都是为了不让模型在信息缺失下瞎编。3.3 跑通后再加的三个可靠性细节Demo跑通不难但我在实际项目里一定会补上这三个细节第一个是超时控制。一次完整的智能体任务可能包含多次模型调用和工具调用整体耗时几十秒很正常。但如果某个第三方接口挂了整个任务会卡住。我给每个工具调用设单独超时一般3到5秒给整个Agent循环设总超时一般30到60秒超时即终止并返回暂时无法完成请稍后再试。第二个是中间结果缓存。同一个用户重复问同一个问题没必要每次都完整跑一遍循环。我习惯把用户问题工具执行结果组合成缓存键命中时直接返回上一次的答案。要注意缓存时间别设太长内部知识类问题一般10到30分钟过期避免数据更新后还返回旧答案。第三个是人工介入通道。这是很多人会忽略但生产必需的设计当智能体连续两次工具调用失败、或置信度不足时应该主动把会话转给人工处理而不是硬着头皮继续跑。我见过最严重的案例是智能体一连调了七次接口都没成功它居然每次都重新编造一个不同的错误原因最后给用户一份完全错误的排查建议——如果有一个失败阈值触发转人工的开关这个事故根本不会发生。4. 生产环境里最容易翻车的五个环节4.1 工具调用的参数幻觉比想象中更频繁参数幻觉这个词意思是模型在调用工具时会填入真实参数之外的内容——更准确地说它可能编造一个上下文里并不存在的参数值。比如用户说帮我查一下A客户的项目进度但用户并没有提供客户编号模型可能就自己生成一个客户编号: 10086传进去。为什么说工程上这个问题严重因为代码层面工具调用是自动执行的。模型输出一个JSON你的服务就把这个JSON当作事实直接打到业务接口上。如果参数值里藏着一个错误的、甚至不存在的ID轻则查到空数据重则误操作了别的对象。我的对策有三个在工具定义里给每个参数标注是否必需并把值必须来自用户明确表述不得自行推断写进工具描述参数校验时区分缺失和不明确缺失可以触发追问不明确则直接拒绝对删除、下发等高风险操作一律要求二次确认包括让用户原样复述关键参数。前两条在代码里就能做第三条是流程兜底三者缺一不可。4.2 上下文失控对话越久越笨的根因开头提到过对话越久越笨这里展开讲一下。上下文失控有两种典型表现一种是早期信息被淹没模型只记得最近几句话于是重复问用户已经给过的信息另一种是上下文塞满无关内容模型对关键信息视而不见。这两种情况我在实际系统里都遇到过。最离谱的一次用户和智能体来回聊了四十多轮最后智能体问用户请提供您的姓名——而姓名在第一轮就讲过了中途还重复过三遍。排查后发现上下文里累积了大量工具返回的原始数据重要信息反而被挤掉了权重。解决思路是这样第一控制每轮工具返回的数据量能返回摘要就不要返回全文第二设定会话轮次上限比如20轮超过后强制触发一次摘要压缩第三对关键业务信息用户ID、订单号、客户等级做重要信息持久化从上下文里抽取出来放在每次请求的固定位置比如系统Prompt的最前面。最后这点特别有效等于给模型做了一张常备便签。4.3 成本爆炸循环调用的隐性账单很多人算成本只算了单次调用的token数完全没算循环调用带来的放大效应。一个简单问答可能只调一次模型但一个复杂任务模型思考一次、调工具一次、再根据结果思考一次……一个任务下来可能就是七八次模型调用。如果每次调用的上下文还在增长成本是近似指数级上升的。我见过一个团队的智能客服平均每个会话要调模型十几次单会话成本算下来是普通问答接口的六倍以上。业务方看到账单后差点把项目砍了。怎么控制一是前面说的上下文压缩和缓存二是给模型明确的最小步骤原则能一次工具调用解决的不要分三次三是给每个会话设定预算阈值一旦超过自动降级为简答模式不再做多轮规划。成本问题永远不是上线后才考虑的而是架构设计时就该写进约束条件里。4.4 失败重试策略无脑重试会让故障放大代码写多了的人条件反射式地会写失败就重试。但智能体场景里无脑重试会放大故障。举个例子模型调用工具查库存时库存服务因为负载过高返回超时。如果你的智能体什么都不问就直接重试等于又给库存服务加了一次负载。如果10个用户同时触发系统就雪崩了。更麻烦的是有些失败来自于模型本身比如参数幻觉被校验拦下这种情况下重试一百次结果都一样纯属烧钱。我的建议是分级处理工具返回错误码时区分可重试错误超时、限流和不可重试错误参数错误、无权限。可重试错误采用指数退避最多重试两次中间插入时间间隔不可重试错误直接转人工或返回友好提示绝不重试。另外如果连续多次工具调用都在同一类错误上失败立即中止任务不要让它换个工具继续硬闯。4.5 可观测性缺失黑盒里的追责难题传统后端出问题你有日志、有链路追踪、有监控指标。但智能体呢它的思考过程是不稳定的每次调用的上下文不一样结果也不同。如果你没有完整的运行记录出问题时根本无法判断是模型判断错了、工具定义错了、还是外部接口返回了脏数据。我现在每个智能体项目都会记录三类日志调用日志模型请求和响应的完整内容包括工具调用的参数、决策日志模型每一步的意图、选择哪个工具、为什么停止、质量日志用户后续是否纠正了答案、是否点了不满意。后一类尤其重要它是评估智能体真实表现的第一手数据来源。成本确实高了点但比起出了问题两眼一抹黑这点开销太值了。有一次线上反馈智能体推荐的离职流程是错的我翻决策日志只用了五分钟就定位到原因——某个制度文档查询工具返回了过期的流程版本模型完全照单全收问题根本不在模型身上。没有日志的话这个Case可能得争论一整天。5. 把智能体当业务系统来做评测、发布与维护5.1 没有评测集的开发就是在盲飞普通代码逻辑是确定的你写一个函数输入相同输出基本相同。智能体不是这样模型有随机性工具返回又依赖外部系统所以你不能用改完代码跑一遍没问题来判断质量。唯一靠谱的方式是建立一套评测集每次改动后统一跑一遍对比指标变化。评测集怎么搭我的做法是沉淀三类样例标准正确类正常用户会问的典型问题答案有明确对错边界刁钻类用户给出不完整信息、带错别字、用词模糊的输入考验智能体的追问能力安全防御类试图让智能体越权操作、输出敏感信息、绕过指令的输入必须确保被拦截。每一条用例都要标注期望行为和关键评分点。跑完后记录三个核心指标任务完成率正确完成的比例、工具调用成功率意图识别和参数填充是否正确、兜底触发率转人工的比例是否合理。注意兜底触发率不是越低越好过低可能意味着智能体在硬撑。没有评测集你做的任何Prompt优化都是在撞大运——这是我在这个领域最深的一个体会。你可能调了一句Prompt感觉效果变好了但因为没有对比基线根本说不清是真好还是碰巧。5.2 从测试到灰度智能体的发布流程智能体更新和传统后端发版有一个巨大区别模型的行为不可控。同一个系统Prompt今天和明天跑出来的结果可能都有细微差异更别说模型厂商悄悄更换了底层版本——这种情况发生过不止一次厂商没公告但大家的效果就是变了。所以你不能像发普通功能那样测试完直接全量上线。稳妥的做法是灰度发布先让新版本智能体服务5%的流量跑一天看核心指标对比老版本再逐步扩大到50%、100%。如果评测指标出现回退立刻回滚到上一个版本。很多团队觉得智能体没必要搞灰度直到一次事故让全体用户看到错误答案才后悔没做。5.3 Prompt与版本也要进代码库这是工程化最基础但最容易被忽略的一环。我见过太多团队系统Prompt躺在某个人的聊天窗口里或者散落在几版最终版2.docx里。改动没有记录回退没有依据合作全靠口头传达。正确的做法是把Prompt当作代码看待进代码库、有版本记录、每次改动关联一个任务单。测试环境、预发布环境、生产环境使用不同的Prompt配置但都从同一个仓库拉取。这听起来很基础但能做到的团队真不多而做到之后你在排查和协作上的效率会高出一个量级。顺带说一句Prompt文件里尽量把动态变量和固定文本分开。比如你是{公司名}的智能助手你的职责是{职责描述}变量在运行时注入固定文本进版本管理。这样换团队、换场景时你只需要改配置不用动核心代码。5.4 上线不是终点建立效果反馈闭环最后这一步我非常建议每个团队都做起来在用户侧增加显式的答案是否有用反馈入口并且把反馈结果实时回传。别小看这一个按钮它是你把智能体从能跑打磨到好用的数据源泉。我运营的那个内部助手上线第一周用户反馈没用占到了20%。通过分析反馈对应的日志我发现两个高频问题一是制度类问题会返回不同版本的答案因为底层文档存在多个版本二是用户问报销流程时智能体经常推荐了差旅报销的内容而用户问的是采购报销。针对这两个问题我调整了文档检索的优先级并在工具描述里补充了报销类型需要确认主分类不要默认差旅两周后没用比例降到了不到5%。数据会告诉你下一次迭代该做什么不用靠猜。6. 入门路线建议少走弯路的几个经验如果你是零基础或者只写过少量代码不要被上面这些工程细节吓到。入门智能体工程的最佳路径是这样第一步先跑通一个最简单的函数调用Demo哪怕只是让模型根据你的指令调一个计算器函数。目的是理解模型输出结构化意图、代码执行、结果回填这个闭环。第二步做一个小场景的完整闭环比如做一个会议室查询助手让智能体查空闲会议室、预订会议室、取消预订。做完这个你会自然遇到参数幻觉、上下文管理、权限问题然后再回头看我上面那些章节会更有体感。第三步给智能体加评估和日志。这是从写着玩切换到工程化的标志性一步。给自己定个指标工具调用成功率要超过90%达不到就继续调工具定义和Prompt。第四步多读几个成熟的Agent框架的设计文档重点看他们的工具注册机制、记忆管理策略、错误处理约定。不一定要直接用但借鉴设计思路非常值。我还想特别说一点别一上来就追求全自动零人工。真正可靠的生产级智能体很多场景下做的是辅助人而不是替代人——在关键环节把决策权交给用户反而是更高级的设计。这个认知转变我大概花了三个月才真正想明白。我在这条路上踩过的最大一次坑是花了整整一周调一个让智能体自动处理退款的功能最后发现用户根本不敢用——他们不信任AI可以直接退款。后来我把方案改成AI生成退款建议并填写表单用户点击确认后才提交使用率反而暴增。技术能力再强最终还是要落在信任和体验上。智能体工程是个典型的入门容易做深难的领域。希望这篇能帮你把那些网上教程不会讲的坑提前填平一些。如果你准备动手做自己的第一个智能体建议从最简版本开始跑起来再迭代。
阅读完成 · 觉得有帮助？
