有一次和做企业服务的团队聊他们的 Agent 项目已经完整演示了一个星期。现场看确实顺畅问一句“帮我整理上季度客户反馈”Agent 会自己拆任务、检索知识库、调表格工具、生成报告会议室里一片赞叹。可一接上真实系统第一天就出问题。同一句话上午能跑下午就不行有的任务调了三次工具还没拿到正确字段好不容易跑完一条却发现引用了三个月前的旧文档。日志里只有一句agent terminated due to error没人知道是哪一步挂的。这几乎是 Agent 项目从“惊艳”到“沉默”的标准路径。行业里流传较广的一组观察是大约有四成 Agent 项目最终没能真正进入生产环境或者上线后很快被叫停。这个数字不是模型不够强的证据反而说明很多人把 Agent 项目当成了一场比赛——赛题是“能不能跑通 demo”而不是“能不能在生产环境里稳定、可控、可维护地持续运行”。先说我的核心判断Agent 项目的成败不取决于模型选得多好、Prompt 写得多巧而取决于工程化能力——能不能把模型的不确定行为放进一套可编排、可观测、可评测、可治理的系统里。换句话说不是“实现”难是“落地”难。1. 约四成失败不是模型不行是工程没闭环1.1 先定义清楚什么是 Agent 项目的“失败”很多团队对失败的感知很模糊。项目没有崩溃、demo 也能跑但三个月后业务方不用了这算不算失败算。从工程经验看Agent 项目的失败通常不是“技术不可行”而是下面几种情况概念验证做完后找不到一个愿意为“不稳定”付费的业务场景。试运行期间出错率太高业务方对结果失去信任退回人工流程。项目上线后没人敢改。Prompt、工具、模型版本谁都能碰但出了问题谁都说不清。成本远超预期。一个任务反复重试、上下文越积越长月底账单比开发工资还贵。安全、权限、审计过不了关。Agent 能调工具但谁批准它调它生成的内容谁负责这五种情况都不是模型能力问题而是工程闭环问题。模型负责生成“可能正确的答案”工程系统负责保证“大概率稳定、出错可查、失败可控、变更可回归”。没有后者前者越强反而越危险。1.2 失败通常发生在三个“兴奋期之后”复盘过不少项目后我发现失败不是均匀发生的而是集中在这三个阶段第一个阶段是概念验证期。这时团队最兴奋每天都能看到 Agent 的新能力但看到的往往是精心挑选的、最顺滑的几条路径。长尾输入、错误恢复、并发冲突全都还没出现。第二个阶段是试运行期。一旦开始接真实数据、真实工具、真实用户问题开始密集暴露。真正的麻烦在于团队还没有建立“出错后怎么定位、怎么回滚、怎么快速修”的机制。于是每次报错都是一次临时救火救久了业务方先失去耐心。第三个阶段是扩展期。当 Agent 从一个变成多个工具从一个变成二十个Prompt 从一个文件变成几十个版本问题就从“单点效果”变成“系统复杂度”。常见结果是一个人能跑通团队不敢碰单任务能跑多任务编排一塌糊涂。所以四成失败背后真正缺的不是一次惊艳的大模型能力演示而是一整套跟模型配套的工程系统。2. 五道鸿沟从“看起来能跑”到“真的能用”如果要给 Agent 项目画一张从启动到落地的地图中间至少要跨过五道鸿沟。每一道都不算深但连续跨不过去项目就停在原地。2.1 第一道Demo 与生产之间的鸿沟Demo 里的世界是收敛的输入是预设好的工具是可控的上下文是干净的。生产环境是开放的同一句话可能有一百种写法同一份文档可能有两种编码格式同一个接口可能时好时坏。我见过一个信息提取 Agent在测试集上准确率接近 95%上线后面对真实扫描件准确率直接掉到 70%。原因很简单测试集是运营手工整理过的干净文本真实场景里是歪斜、水印、模糊、表格嵌套。这个差距不是模型能单独解决的必须在工程上补“输入清洗、格式归一、样例扩展”。这也是为什么我一直在强调一个 Agent 项目如果直到上线前才接触真实数据那它大概率要交学费。正确做法是尽早把真实输入样本录下来哪怕只有几十条也比几百条“漂亮样例”有用。2.2 第二道单任务与复杂流程之间的鸿沟单个任务的 Agent 可以做得很好给一段文字它能提炼摘要给一个问题它能做一次检索回答。但一旦任务变成“先读取名单再逐家生成报告最后汇总发送”问题就不一样了。三步流程单步成功率如果是 90%三步连起来只有 72%。如果其中一步还需要调用两个工具、跑三次重试成功率还会继续往下掉。更麻烦的是中途某一步失败后整个任务到底重跑、跳过、还是降级处理团队往往没有设计。这道鸿沟的工程本质是状态管理。你的 Agent 不能只记得“当前这个回答”还要记得“任务进行到第几步、哪些步骤已完成、哪些结果需要缓存、哪些分支需要人工介入”。没有状态就没有流程没有流程就没有可靠的多步 Agent。2.3 第三道模型不确定性与系统稳定性之间的鸿沟同一个 Prompt同一个输入大模型每次输出都可能不一样。这在聊天场景是“灵活性”在自动化流程里是“方差”。当 Agent 要决定调用哪个工具、传什么参数时一次输出偏差就可能让整个流程跑偏。工程上不能假设模型永远正确必须假设每一步都可能出错然后设计校验器、结构化输出、兜底分支。有人把这套工作叫作“认知工程”核心就是把不透明的自动行为拆成几个可控制的阶段先让模型做决策再用规则校验决策最后按校验结果决定是继续、重试还是交给人工。模型负责发散系统负责收敛。这也是为什么我强烈建议Agent 的关键动作尽量输出结构化结果而不是自由文本。比如“选择工具 参数”就应该用 JSON 约束而不是让模型在一大段散文里“顺便提一下”。2.4 第四道输出可用与过程可控之间的鸿沟很多团队对 Agent 的验收标准是“结果对不对”。但生产系统真正要求的往往还有“过程能不能解释、能不能审计、能不能被批准”。举个例子一个客服 Agent 写了一段还算得体的回复但它在过程中读取了一个不该读取的客户隐私字段。结果是好的过程是越权的。如果没有任何审计能力这个风险会在某个更敏感的场景里爆炸。再比如Agent 调用了一个删除类工具。接口本身存在模型也正确地传了参数但没人审核这次调用的必要性。单次看没问题长期看就是一个巨大的隐患。所以第五个判断标准要前置Agent 不仅要能干活还要能让人类随时知道它干了什么、为什么这么干、是谁批准它这么干的。过程可控才是生产环境对 Agent 的真正要求。2.5 第五道个人效率与组织协作之间的鸿沟个人开发者可以在本地把 Agent 调到“自己满意”但一个团队一起维护时问题就来了Prompt 改动了谁负责验证工具新增了谁负责测试模型从 V1 换成 V2 后哪些历史 Case 需要回归如果不建立 Agent 的版本管理、评测基线、变更流程团队很快就会陷入“一个 Agent八个版本没人说得清线上跑的是哪个”的状态。最终结果是没人敢改也没人敢上线新功能。这五道鸿沟其实可以浓缩成一张表鸿沟典型症状工程化回应Demo 到生产换一批真实数据就不灵真实样例库、输入归一、回归集单任务到复杂流程多步任务失败率叠加编排、状态持久化、失败重试模型不稳定到系统稳定同一输入不同输出结构化输出、校验器、兜底分支输出可用到过程可控结果对但过程不可审计日志、权限、人审、Trace个人效率到组织协作一人能跑团队不敢改版本化、评测集、灰度发布3. 系统工程化四板斧把不确定性关进笼子里想跨过这五道鸿沟靠的不是加更长的 Prompt而是四板斧编排、可观测、评测、治理。这四板斧可以简单理解成四个问题它按什么路径跑跑得怎么样怎么知道改没改坏谁允许它这么干3.1 第一板斧用编排把执行流程固化下来Agent 的核心是一个循环理解任务、规划步骤、调用工具、观察结果、再决策。这个循环被叫作 Agent Loop。它的好处是灵活坏处也是灵活——如果不加约束它会一直循环下去或者做出你根本想不到的选择。编排要做的事就是给 Agent 画出一条可管理的路径。这里要先澄清一组容易混淆的概念在很多框架里Agent 指代会自主决策的执行主体Skill 是可复用的能力模块Harness 则更像是承载执行的外壳或上下文管理环境。不同框架的定义有差异但共同点是工程化时要把“可复用的能力”和“动态决策逻辑”分开。具体落地时我的建议是能固化的路径优先固化。比如固定顺序的“读取、清洗、处理、汇总”不需要模型发挥就用工作流写死。只把真正需要判断的地方交给 Agent 决策。比如“用户意图不明确时选择哪个工具”这种才值得用模型判断。永远给 Agent 一个上限。最大步数、最大工具调用次数、单次任务超时时间都要有默认值。一个常见的配置思路是{ max_steps: 10, max_tool_calls: 6, timeout_seconds: 120, retry_count: 2, tool_allowlist: [search_news, read_file, write_csv], require_human_approval: [delete_file, send_email] }有人觉得这种配置限制了 Agent 的能力。但从生产稳定性来看限制不是束缚而是兜底。没有边界的 Agent 不是智能是事故隐患。3.2 第二板斧可观测性是一切复盘的起点一次性的 Agent 演示不需要日志生产环境的 Agent 必须把每一次运行都记录下来。最理想的情况是你能回答下面每个问题这个任务哪来的输入原样是什么模型理解成了什么它生成了几次内部思考它依次调用了哪些工具每次传参是什么工具返回了什么模型如何解读工具结果一共消耗了多少 Token耗时多少成本多少哪一步出了问题是输入、工具、模型还是超时我建议从第一天就为每条执行生成一个run_id。日志里至少要有这些字段字段说明run_id一次完整运行的唯一标识input_text用户原始输入plan模型规划的步骤tool_calls每次工具调用名、参数、返回摘要tokens输入、输出 Token 数latency_ms分步耗时status成功、失败、重试、人工介入error_message关键报错信息memory_snapshot任务开始时加载了哪些记忆片段这类日志的价值不在于“出问题时有人看”而在于支持“失败回放”。当某个任务跑挂时你可以用同一个输入、同一条记忆快照重新执行逐步定位错误点。没有这种能力每次排障都等于重新做一次实验效率极低。我见过有些团队把 Agent 日志当成普通应用日志一样处理只记录“成功/失败”其他细节全部丢弃。等出了问题只能看到一个terminated due to error连是哪一步挂的都不知道。这不是模型的问题是工程缺项。3.3 第三板斧评测集不是上线后才补而是一开始就建Agent 的评测比传统模型困难因为它不是单次输出而是一连串动作。正因如此评测集才更重要。我的建议是项目启动第一天就建一个golden_cases文件哪怕只有二十条。每条样例至少包含{ case_id: agent_001, input: 请统计某目录下所有 CSV 的行数并汇总, expected_trace: [read_dir, read_csv, summarize], must_contain: [total_rows], forbidden: [delete] }每条样例不只是“输出对不对”还要检查“过程对不对”。它必须调用了预期工具必须包含关键信息而且不能触发禁止动作。这样每次改动 Prompt、工具、模型版本后都能跑一遍全量回归看有没有把旧能力改坏。评测集的建立不需要很复杂但要有持续扩展的机制。每次线上出现问题就把出问题的输入沉淀成一条新的测试样例。人工智能工程和普通软件工程在这点上一脉相承今天的 bug就是明天的回归测试。3.4 第四板斧记忆、权限、安全与审计第四个板斧最容易被早期团队忽略也最容易在后期致命。先说记忆。Agent 的记忆分为工作记忆和长期记忆。工作记忆是当前任务里的上下文长期记忆则是跨会话保存的事实与用户偏好。长期记忆通常需要落到外部存储比如专门的记忆数据库但无论用什么都必须回答几个问题记忆有权限边界吗会过期吗可以被删除吗再谈工具权限。Agent 能调用的工具应该有一个明确的允许列表而不是“模型想调哪个就调哪个”。“读文件”和“删文件”、“发邮件”和“读收件箱”在权限上必须分级。危险操作必须走人工审批审批动作还要留在审计日志里。多 Agent 协作时权限问题更复杂。每个 Agent 必须有独立身份和授权范围不能因为主 Agent 有权限就默认子 Agent 全部继承。实践中我见过不少因为“临时复用权限”造成的越权事件最后都只能靠日志倒推。最后是审计。Agent 生成的内容、工具调用、人工审批记录、模型版本、Prompt 版本都应该能形成一条完整的证据链。这不是为了应付检查而是为了当业务方问“它为什么这么干”的时候你能拿出一份清晰的解释而不是说“我也不太清楚”。4. 从 0 到 1 的落地顺序先最小闭环再分层加固很多团队在工程化上失败不是因为不知道要做什么而是因为一起上的东西太多。正确顺序应该是先跑通一条链路再分层加固。4.1 第 0 步先跑通一条最小闭环选一个最核心、最具体的任务比如“读取一份 Excel按模板生成摘要”。不要一上来就做多 Agent 协作也不要同时接十个工具。先验证三件事模型能理解任务。模型能正确调用一个工具。输出能被结构化成目标格式。这一步的目标不是“好用”而是“流程没有断”。只要有一条链路能稳定走通就有资格进入下一步。4.2 第 1 步加上限和重试给 Agent 加约束包括最大步数、超时时间、最大 Token 数、失败重试次数。同时设计简单的兜底策略某一步失败后是重试、跳过、终止还是降级到人工处理。这一步看起来不性感但它直接决定 Agent 从“好玩”变成“可信”。可以把一个项目的演进顺序简化为阶段核心动作验收标准第 0 步最小闭环跑通单任务链路稳定第 1 步加上限、超时、重试失败任务能被系统拦截第 2 步接入日志和 Trace每个失败都可定位第 3 步建评测集并回归改动后能力不回退第 4 步权限、审计、灰度变更可控、可解释4.3 第 2 步上线观测与回放为 Agent 接入完整的日志链路。每一条执行都有run_id每次工具调用都有记录。同时准备一个“失败回放”脚本输入一条历史失败按同样的上下文和记忆快照重新执行复现问题。我通常会建议团队在项目目录里固定一套结构agent_project/ agents/ # Agent 定义 skills/ # 可复用能力模块 tools/ # 工具封装 eval/ # 评测集与评测报告 logs/ # 运行日志 prompts/ # Prompt 版本管理这个结构不是为了好看而是为了让“能力、流程、评测、日志”各自有归属不混在一起。4.4 第 3 步建评测集和灰度发布有了评测集之后每次变更都要先跑回归。这里的变更不只是模型版本还包括 Prompt 调整、工具逻辑修改、记忆策略调整、编排流程调整。上线时不要一次全量。先拿 5% 的真实流量跑灰度看成功率、耗时、成本和安全事件再逐步放大。灰度期间一定要有人盯着日志而不是只盯一个汇总指标。4.5 第 4 步加权限、审计和问责机制最后一步是把你不敢出问题的部分加固。高危工具做好审批敏感记忆做好隔离全部操作做好审计。这个阶段结束时你的 Agent 项目才真正具备“长期住在生产环境”的资格。5. 高频报错与排查链路别一看到 error 就怪模型Agent 项目运行起来后最常遇到的不是“模型不会”而是各种莫名其妙的中途失败。早期团队容易慌一看到agent terminated due to error就认为是模型不行甚至开始重新选型。但大多数时候问题根本不在模型。5.1 先把现象归类排查的第一步不是看具体错误信息而是先回答“它属于哪类现象”现象优先排查方向常见原因直接报错中断Trace 中最后一步工具异常、依赖缺失、超时卡住不结束Step 数、上下文窗口循环未终止、上下文过长空输出输入解析上下文被截断、检索无结果输出格式错误结构化输出约束缺少 Schema、温度过高工具调用错误工具参数参数类型不匹配、字段名错误结果不稳定Prompt 和样例缺约束、缺示例、随机性过高速度慢工具调用次数Loop 过长、检索范围过大成本高Token 消耗上下文无上限、重试过多5.2 一个通用的排查顺序如果问题已经发生我建议按下面的顺序一层一层查不要跳步先看 Trace。找到失败时最后一步发生了什么是模型输出异常还是工具返回异常还是系统超时。再看输入。原始输入是否被正确读取编码、格式、长度是否符合预期再看工具结果。工具是否真的执行成功返回的数据是不是为空有没有权限报错再看上下文与记忆。模型看到的上下文是不是完整是否被截断记忆里有没有混入不相关内容再看模型参数。温度是否过高是否要求 JSON 输出但没给 Schema最大 Token 是否不够再看框架与环境。依赖版本是否正确模型路径、API 地址、端口是否配置无误最后看权限与资源。Token 配额、并发限制、文件权限、工具白名单是否合法。很多所谓的神秘失败到最后都能落到第七层的某个配置上。但如果你不按这个顺序走而是直接换模型、调 Prompt问题大概率会换一种形式再出现。5.3 三条排障经验这里特别想强调三个被反复验证过的经验。第一条先复现再修改。没有复现就改 Prompt等于盲修。复现方法很简单拿到同一份输入、同一份记忆快照、同一份工具返回重新执行一次。第二条先减少变化再扩大。把问题压缩到最小复现路径只保留一个工具、一条输入、一次循环。变量越少定位越快。第三条先加日志再上灰度。如果你的日志连中间步骤都看不到就先别急着扩展 Agent 数量。先把一条链路看得清清楚楚再谈规模化。6. 什么项目适合走这条路什么项目不适合写到最后我想把适用边界说清楚。Agent 工程化不是万能银弹不是所有项目都应该冲进来做 Agent。6.1 适合走这条路的情况适合做 Agent 工程化的任务通常有四个特征任务边界可以被描述。虽然输入可能有变化但目标、输出格式、可用工具是清楚的。结果可以被快速验证。做完一份摘要人扫一眼就知道行不行。允许失败后重试或人工兜底。某个任务偶尔失败重新跑一次或人工介入就能补救。重复劳动量大ROI 可算。原来人工要花两个小时Agent 花两分钟省下的时间能直接换算成成本。满足这四个条件的场景例如信息提取、报告生成、知识库问答、日常数据整理、客服工单初筛都比较适合。6.2 不适合的情况反过来下面这些情况要非常谨慎一次都不能错。比如涉及实时交易决策、医疗诊断结论、法律意见生成的场景如果没有任何人工复核环节就不适合端到端无人干预。输出没有标准无法评测。如果连人都说不清“什么样算对”Agent 就更不可能稳定优化。输入开放且安全后果大。比如完全开放域对话中允许 Agent 执行高风险操作没有严格的权限隔离和审批风险会失控。团队没有任何运维和评测能力。如果项目从头到尾只有一个人写 Prompt没有日志、评测和排障意识规模一大就容易崩。这不是说这类场景永远不能做而是必须把工程化优先级提得更高至少先有“人工审批 完整审计 保守灰度”再逐步放开自主度。6.3 一个可复用的判断清单如果你现在正在评估一个 Agent 项目可以拿下面五个问题过一遍它要处理的输入最大变体是什么它做错的代价是什么谁能兜底它每一步的决策能否被日志完整还原它每次变更有没有一套评测集做回归它的工具调用和记忆访问有没有权限边界和审计前两个问题决定“该不该做”后三个问题决定“能不能长期做”。如果一个项目前两个问题已通过但后三个还是空白那这个项目还停留在 demo 阶段离生产还有一段工程距离。回到最开始那组数字。四成失败听起来吓人但它不是告诉你“别做 Agent”而是告诉你“别只做 Agent 的 demo”。模型负责发散系统负责收敛发散的部分你控制不了收敛的部分必须你来管。把一次任务变稳把一条 Trace 变透明把一份评测集留下来把一次工具调用放进权限边界里——这些事看起来没有写 Prompt 有成就感但决定你的 Agent 项目是从 demo 走向生产还是成为那四成里的又一个教训。我建议你从今天起先别急着加新 Agent把一个已经能跑的任务按“有限步骤 完整日志 样例评测 权限审计”改造一遍。跑完这一遍你大概就能理解那四成失败是怎么发生的也会理解为什么工程化才是 Agent 真正的主战场。