1. 从模型越强Agent越好用这个错觉说起过去一年我经手过七八个 Agent 项目从最简单的文档问答机器人到带工具调用、多轮规划、能自己写代码跑测试的复杂工作流几乎每一类都踩过一遍。最开始我也和大多数人一样觉得 Agent 效果不好第一反应就是模型不行换个更强的。于是从中小参数模型一路换到旗舰大模型token 成本翻了好几倍结果发现——问题根本没解决甚至有些场景换了大模型反而更不稳定。这个现象非常反直觉。按理说模型能力越强Agent 应该越聪明才对。但实际跑下来你会发现一个 Agent 系统能不能稳定干活模型只占其中一部分真正决定它越用越坑还是越用越顺的是工程纪律。这个词听起来有点虚我换个说法你有没有把 Agent 当成一个正经的软件系统来对待而不是一个提示词调一调就上线的玩具。我见过太多团队的做法是这样的写一段 system prompt接几个工具跑几个 case 觉得还行就直接上线。上线之后用户反馈各种奇怪问题——工具调错、参数瞎填、循环调用、上下文爆炸、同一个问题每次回答都不一样。然后团队就开始调 prompt今天加一句你必须仔细思考明天加一句不要编造prompt 越堆越长效果时好时坏最后谁也说不清到底哪句话起了作用。这篇文章我想聊的就是这件事Agent 越用越坑缺的不是模型是工程纪律。我会把这一年多踩过的坑、总结出来的约束机制、验证方法、以及那些文档里不会写但实际必须做的东西尽量讲透。不管你是刚接触 Agent 开发还是已经上线了一两个项目正在被稳定性折磨应该都能从里面找到能直接抄作业的部分。关键词里提到的 Agent、工程纪律、模型、AI 辅助编程、Skills这几个词其实是一条线模型是原料Skills 是能力封装AI 辅助编程是应用场景而工程纪律是把它们串起来不散架的那根绳。2. 为什么换个更强的模型救不了你的 Agent2.1 模型能力提升的是上限不是下限先讲一个我印象最深的案例。当时做一个代码修复 Agent输入是一段有 bug 的代码和一个失败的测试要求它定位问题、改代码、跑测试直到通过。用中等模型的时候成功率大概 40%失败的原因五花八门。我心想换旗舰模型肯定能上 70%。结果换完之后成功率到了 55%但失败模式变了——它开始过度自信明明测试没跑通却在总结里说已修复或者改了一堆无关代码把原本能过的测试搞挂了。这件事让我意识到一个关键点模型能力提升的是它能做到的上限但 Agent 系统的稳定性取决于下限。上限决定它在理想情况下能多聪明下限决定它在边界情况下会不会闯祸。而用户感知到的坑绝大多数来自下限——那些它本不该犯的低级错误。旗舰模型的下限不一定比中等模型高。它可能更会推理但也可能更会合理化自己的错误。你给它一个模糊的指令中等模型可能老老实实说我不确定旗舰模型反而会编一个听起来很合理的答案。这就是为什么单纯换模型解决不了问题。2.2 Agent 的失败大多不是不会而是没约束我把这一年遇到的 Agent 失败案例做了个粗略归类大概是这样的失败类型占比我的经验估计换模型能解决吗工具调用参数错误约 25%部分能但不稳定多步任务中途跑偏约 20%基本不能上下文超限/信息丢失约 15%不能反而更严重循环调用/死循环约 12%不能幻觉编造结果约 15%旗舰模型可能更严重输出格式不符合预期约 13%部分能你看真正靠模型更聪明能解决的可能只有工具参数错误和格式问题的一部分。剩下的跑偏、超限、死循环、幻觉本质上都是系统设计问题不是模型智力问题。举个具体的。多步任务中途跑偏典型场景是用户让 Agent帮我分析这份销售数据并生成报告Agent 第一步读数据没问题第二步开始做统计也没问题第三步它突然开始猜测数据里没有的字段第四步基于猜测生成了看起来很像那么回事但完全错误的结论。你换再强的模型只要没有在第三步设置校验点它照样会跑偏。因为模型的本能就是把任务完成而不是在信息不足时停下来。2.3 一个反直觉的结论约束越明确弱模型也能干得不错我后来做了个对比实验同一个任务从一堆 issue 里筛选出需要紧急处理的并生成摘要用两套方案方案 A旗舰模型 一段比较宽松的 prompt让它自行判断。方案 B中等模型 严格的输出 schema 明确的判断规则 校验重试。结果方案 B 的准确率反而更高而且稳定性好得多。方案 A 偶尔会给出惊艳的结果但方差极大今天 90 分明天 50 分。方案 B 基本稳定在 80 分上下很少翻车。这个实验说明什么Agent 的可靠性更多来自约束的明确性而不是模型的智力。你把规则写清楚、把输出格式定死、把边界情况列全中等模型完全能胜任。反过来你给旗舰模型一个模糊的任务它给你的就是薛定谔的结果。这也是工程纪律的第一层含义不要指望模型猜你的意图要把意图翻译成它能执行的明确规则。3. 工程纪律的第一层把 Prompt 当代码来管3.1 Prompt 散落在代码里是万恶之源我接手过一个项目Agent 的 prompt 分散在十几个文件里有的是字符串拼接有的是 f-string有的藏在配置文件还有几段是硬编码在函数里的。结果就是改了一处另一处没同步行为变得诡异想回滚到上个版本发现根本不知道当时改了什么新人接手看了三天还没搞清楚完整的 prompt 长什么样。这就是典型的没有工程纪律。Prompt 是 Agent 的核心逻辑它的地位等同于传统软件里的业务代码但你却让它散落各处、没有版本、没有测试。我的做法是把所有 prompt 集中管理当成一等公民。具体来说每个 prompt 模板独立成文件用清晰的命名比如agent_system.md、tool_selector.md、output_formatter.md。模板里用占位符而不是字符串拼接比如{{user_input}}、{{available_tools}}渲染逻辑统一封装。所有 prompt 文件纳入版本控制每次修改必须写清楚改了什么、为什么改。关键 prompt 配对应的测试用例改完之后跑一遍回归。这套做法听起来很基础但我敢说至少一半的 Agent 项目没做到。大家觉得 prompt 是软的东西随手改改就行结果就是越改越乱。3.2 版本管理不只是 git commit光用 git 管 prompt 文件还不够。因为 prompt 的效果依赖模型版本、依赖工具定义、依赖上下文长度你单独回滚 prompt 文件可能因为模型升级了导致效果又不一样。我的经验是给每次 prompt 变更打一个组合快照记录 prompt 内容、模型版本、工具定义、关键参数temperature、max_tokens 等。这样出问题的时候能精确定位是哪次变更引入的。具体可以维护一个简单的变更日志格式大概这样版本: v1.3.2 日期: 2024-XX-XX 变更: tool_selector prompt 增加了当工具参数缺失时必须追问的规则 模型: xxx-model-v2 影响: 工具调用准确率从 78% 提升到 89%但平均轮次增加 0.4这个日志不需要多复杂一个 markdown 文件就够。关键是养成习惯——每次改 prompt 都当成一次发版。3.3 别让 prompt 无限膨胀还有一个特别常见的坑prompt 越堆越长。今天发现 Agent 编造加一句不要编造明天发现它不追问加一句信息不足时要追问后天发现它输出太啰嗦加一句保持简洁。几个月下来system prompt 从 500 字涨到 5000 字里面全是各种不要必须注意。问题是prompt 越长模型对每一条的遵守程度越低。这就像你给员工写了一份 50 页的规章制度他大概率只会记住前几条。而且长 prompt 里经常有互相冲突的规则模型只能随机选一条遵守。我的处理原则是能写成硬约束的比如输出格式不要靠 prompt用代码校验。能拆成独立步骤的不要塞在一个 prompt 里拆成多个 Agent 节点。定期清理 prompt把已经通过其他机制保证的规则删掉。每条规则都要能回答如果不写这条实际会出什么问题答不上来的就删。提示判断一条 prompt 规则该不该留最直接的方法是把它删掉跑一遍测试集。如果指标没变化说明这条规则要么没用要么已经被其他机制覆盖了。4. 工程纪律的第二层给 Agent 装上刹车和仪表盘4.1 没有步数上限的 Agent 就是个定时炸弹我踩过最惨的一次坑是一个 Agent 在某个边界输入下进入了循环它调用工具 A拿到结果觉得不对又调用工具 B 验证B 的结果让它觉得需要再调 A如此往复。因为当时没设步数上限它就这么跑了十几分钟烧掉了一大笔 token最后是我手动 kill 的。从那以后我给所有 Agent 都加了硬性限制最大步数根据任务复杂度设定简单任务 5-8 步复杂任务 15-20 步超过就强制终止并返回当前状态。最大 token 消耗单次任务的总 token 预算超了就停。最大工具调用次数防止某个工具被反复调用。单步超时每个工具调用设置超时避免卡死。这些限制不是限制 Agent 能力而是保护系统不被异常输入拖垮。就像电路里的保险丝正常情况用不到但关键时刻能救命。4.2 可观测性你得知道 Agent 每一步在干什么Agent 和传统程序最大的区别是它的执行路径不固定。传统程序你读代码就知道它会怎么走Agent 你得看它实际跑了什么。所以日志和追踪是刚需不是可选项。我一般会记录这些东西每一步的输入包括完整的上下文模型输出的原始内容不只是解析后的结果工具调用的名称、参数、返回每一步的耗时和 token 消耗最终结果和中间状态的差异这些数据攒起来之后你会发现很多问题一目了然。比如某个工具的参数错误率特别高说明工具描述写得有问题比如某类任务平均步数特别多说明任务拆解不合理比如某些输入下 token 消耗异常说明上下文管理有漏洞。我习惯用一个简单的结构化日志格式每步一行 JSON方便后续分析{ step: 3, type: tool_call, tool: search_database, params: {query: ...}, result_summary: ..., tokens: 1250, latency_ms: 830 }有了这个排查问题的时候就不用靠猜了。4.3 校验点在关键节点强制停下来检查前面说多步任务跑偏解决方案就是在关键节点设校验点。什么叫校验点就是在 Agent 完成某个子任务后不直接进入下一步而是先检查这一步的结果是否符合预期。校验可以分几类格式校验输出是否符合 schema必填字段是否齐全。逻辑校验结果是否和输入矛盾比如输入说3 条数据输出统计了 5 条。范围校验数值是否在合理区间比如百分比是否超过 100。一致性校验多次调用同一工具结果是否一致。校验不通过怎么办两种策略一是重试带上错误信息让模型修正二是终止并上报。重试次数也要设上限一般 2-3 次超过就说明这个任务本身有问题不该硬撑。我实测下来加了校验点之后多步任务的端到端成功率能提升 15-25 个百分点而且失败的时候是干净地失败不会产出一堆看起来对其实错的结果。5. 工程纪律的第三层Skills 和工具设计的克制5.1 工具不是越多越好新手做 Agent 特别容易犯一个错恨不得把所有能想到的能力都做成工具塞进去。搜索、计算、读文件、写文件、发邮件、查数据库……工具列表几十个。结果模型面对这么多工具选择困难经常选错或者选了一个不合适的工具硬用。我的经验是工具数量控制在 5-8 个以内超过就要考虑合并或分层。而且每个工具要有明确的适用边界不能有功能重叠。如果两个工具都能完成某件事模型就会犹豫行为就不稳定。工具的描述也极其重要。很多人工具描述就写一句搜索数据库模型根本不知道什么时候该用、参数怎么填。好的工具描述应该包含这个工具做什么一句话什么时候该用适用场景什么时候不该用边界每个参数的含义、格式、示例返回值的结构这其实就是 Skills 的思路——把能力封装成模型能准确理解和调用的单元。Skills 做得好Agent 的工具调用准确率能上一个台阶。5.2 参数校验要在工具内部做不能指望模型我见过太多项目工具的参数校验完全依赖模型填对。模型填错了工具就直接报错或者产生错误结果。这是很危险的。正确的做法是工具内部做严格的参数校验不合法就返回明确的错误信息。比如一个查询工具如果模型传了个不存在的字段名工具应该返回字段 xxx 不存在可用字段有 a、b、c而不是直接抛异常或者返回空。这个错误信息会回到模型那里模型看到之后往往能自我修正。这比你在 prompt 里写一百遍请确保字段名正确都管用。5.3 幂等性让重试变得安全Agent 会重试这是常态。所以工具最好设计成幂等的——同样的输入调用多次结果和副作用一致。查询类工具天然幂等但写入类工具就要小心。比如发送通知这种工具如果 Agent 重试了用户可能收到两条通知。解决方案是给工具加一个幂等键或者把写入操作设计成先检查再写入。这个细节很多人不注意上线之后才发现用户被重复打扰。6. 工程纪律的第四层测试集和回归机制6.1 没有测试集的 Agent 优化就是玄学这是我感受最深的一点。没有测试集的时候你改 prompt、换模型、调参数全靠感觉好像好了一点。今天觉得好了明天用户又反馈问题你也不知道是真变差了还是遇到了新的边界情况。建一个测试集是 Agent 工程化的分水岭。测试集不需要很大初期 30-50 个 case 就够但要覆盖典型正常场景占大头边界场景空输入、超长输入、特殊字符已知的失败场景之前踩过的坑对抗场景故意诱导 Agent 犯错每个 case 记录输入、期望行为不一定是精确输出可以是应该调用工具 X不应该编造应该追问这类断言。有了测试集每次改动跑一遍看通过率变化。通过率掉了就回滚涨了就保留。这样优化才有方向。6.2 用 LLM 做评估但别全信Agent 的输出很多是自然语言没法用精确匹配来评估。这时候可以用另一个模型来做评估LLM-as-judge。但要注意评估模型本身也有偏差不能全信。我的做法是LLM 评估做初筛人工抽查做校准。LLM 评估快速跑一遍标出可能有问题的 case然后人工看其中一部分确认评估标准是否合理。定期校准避免评估标准漂移。评估的维度也要明确不能只给一个总分。我一般会分几个维度打分任务完成度、工具使用正确性、输出格式合规性、是否有幻觉。这样出问题的时候能定位到具体维度。6.3 回归测试要自动化测试集建好之后一定要做成自动化的。每次改 prompt、换模型、加工具自动跑一遍回归出报告。手动跑测试集坚持不了几次就会放弃。自动化回归的门槛其实不高一个脚本 一个结果对比就够了。关键是养成改完必跑的习惯。我现在的工作流是改 prompt → 跑回归 → 看报告 → 决定是否保留。整个过程十几分钟比上线后救火划算太多。7. 那些文档里不会写的实操心得7.1 上下文管理不是塞得越多越好很多人觉得给 Agent 的上下文越多它越聪明。实际上恰恰相反。上下文里塞太多无关信息模型注意力会被稀释关键信息反而被淹没。我的做法是分层管理上下文系统层角色、规则、工具定义固定不变。任务层当前任务的目标、约束、已知信息。历史层之前的步骤和结果但要定期压缩或摘要。即时层当前这一步需要的具体信息。历史层是最容易膨胀的。我的经验是超过一定轮次之后把早期的详细步骤压缩成摘要只保留关键结论和状态。这样既省 token又让模型聚焦在当前任务上。7.2 温度参数不同环节用不同值一个 Agent 系统里不同环节对创造性的需求是不一样的。工具选择、参数填充这种环节需要的是确定性温度应该调低0 到 0.3。而生成解释、写摘要这种环节可以适当高一点0.5 到 0.7。我见过有人全程用默认温度结果工具调用时随机性太大同样的输入每次选的工具都不一样。这种问题调温度就能解决一大半。7.3 失败要优雅不要崩溃Agent 失败是常态关键是怎么失败。好的失败是明确告诉用户我卡在哪了我尝试了什么需要什么信息才能继续。坏的失败是编一个看起来对的答案或者抛一个用户看不懂的错误。我在系统里加了一个兜底逻辑当 Agent 达到步数上限或者校验连续失败时不是直接返回错误而是生成一个结构化的说明包含已完成的部分、卡住的原因、建议的下一步。这样用户至少知道发生了什么而不是面对一个莫名其妙的失败。7.4 别忽视简单任务的优化大家都喜欢优化复杂任务觉得那才有技术含量。但实际上简单任务占了大多数流量简单任务的稳定性对整体体验影响更大。我做过统计一个 Agent 系统里 70% 的请求是相对简单的任务。如果这些任务能做到 99% 稳定用户满意度就上去了。而复杂任务哪怕优化得再好占比小对整体感知影响有限。所以我的策略是先把简单任务做到极致稳定用规则、用模板、用最直接的路径再考虑复杂任务的优化。不要一上来就追求全能 Agent那是给自己挖坑。8. 一个可以照着搭的最小工程框架说了这么多原则最后给一个我实际在用的最小框架你可以直接照着搭。目录结构agent/ prompts/ # 所有 prompt 模板 system.md tool_selector.md formatter.md tools/ # 工具定义和实现 search.py calculate.py core/ runner.py # 主循环含步数/token 限制 validator.py # 校验逻辑 context.py # 上下文管理 tests/ cases/ # 测试用例 run_regression.py logs/ # 结构化日志 CHANGELOG.md # prompt/模型变更日志核心循环的伪代码逻辑def run_agent(task, max_steps15, max_tokens50000): context build_initial_context(task) for step in range(max_steps): if context.token_count max_tokens: return graceful_fail(token 预算超限, context) action model.decide(context) if action.type final: return action.content result execute_tool(action) if not validate(result): context.add_error(上一步结果校验失败) continue context.add_step(action, result) return graceful_fail(达到步数上限, context)这个框架不复杂但它把前面说的所有纪律都落到了实处prompt 集中管理、步数和 token 有上限、每步有校验、失败有兜底、日志可追溯。搭起来之后你会发现 Agent 的坑少了一大半。剩下的坑才是真正需要靠模型能力或者更复杂设计去解决的。而那时候你已经有了测试集和日志能清楚地知道问题出在哪而不是盲目地换模型、堆 prompt。我个人最大的体会是Agent 开发 80% 的功夫在工程20% 在模型。把工程纪律做扎实中等模型也能做出稳定的产品工程纪律缺失旗舰模型也救不了你。这个道理踩过足够多的坑之后自然会懂但希望你能少踩几个。
