1. 先承认一个事实：Demo 和生产的距离，比想象中远
去年下半年我连续参与了好几个企业级 AI Agent 项目，有做内部流程自动化的，也有做面向客户的智能助手的。这些项目的甲方有一个高度一致的反馈：demo 演示的时候，大家眼睛发光，觉得 AI 时代终于来了；一上生产环境，眼睛发直，怎么十几个小时不处理一次任务，怎么回答突然变得不可理喻，怎么一个 Agent 调用了三个外部接口之后，数据就对不上了。这些问题不是偶发，而是密集出现。
我后来复盘这些项目，发现根子不在模型能力，不在提示词写得好不好，而在于团队把“原型阶段”和“生产阶段”当成了一件事。大家用做 demo 的方式做生产系统，用调 prompt 的方式替代系统工程，用几个精心挑选的测试样例替代评估体系。这在个人项目里问题不大，但在企业环境里，一个每天处理上万次请求、牵扯多个内部系统和外部依赖的 Agent，任何一点不确定性都会被放大成事故。
企业级 AI Agent 和普通软件服务的本质区别，在于它多了一个“不可控的大脑”。传统软件的输入是结构化的，输出也是结构化的，逻辑链是确定的。Agent 不一样，它的中间推理过程是模型生成的，同样一个请求，今天走的是这一步，明天可能走另一条路，后天甚至会在某个工具调用上卡死。你不能像修普通 bug 一样，找到一行错误代码然后改掉，因为很多问题根本没有“那一行代码”，只有一条不稳定的推理路径。
所以企业级 AI Agent 工程方法论的核心，不是怎么把模型调好，而是怎么在模型不确定性之上，建起一套确定性足够的工程体系。让系统在 95% 的情况下稳定可靠，在 5% 的异常情况下有明确兜底，并且所有行为都可以被观测、被审计、被回滚。这篇文章是这套方法论的上篇，重点讲从原型到生产的整体思路、核心架构分层、评估体系，以及稳定性与可观测性这两道最关键的生产门槛。中篇和下篇会继续展开 RAG 工程化、多智能体协作、安全合规和成本治理。
2. 企业级 AI Agent 的核心能力拆解：先搞懂要解决什么问题
2.1 原型阶段的成功标准和生产阶段完全不是一回事
很多团队在设计 Agent 的时候，脑子里想的是“它能不能理解用户意图”“它能不能调用工具完成任务”。这些当然重要，但在企业级环境里，这些只是入场券。真正的核心问题其实是：你能不能承受它出错，以及出错之后你能不能快速知道发生了什么。
我举个具体例子。某个团队做了个内部报销 Agent，员工对着它说“帮我提交一笔差旅报销”，Agent 需要从邮件里抽取行程信息、从财务系统拉取预算、生成报销单、推送给审批人。demo 阶段测试了 5 个场景，全部通过。上线第一天，Agent 把一笔报销单的金额从 1280 元识别成了 1280.5 元，虽然只差五毛钱，但财务系统立刻拦截了，员工以为提交成功，实际上卡在了系统里，然后投诉就来了。
这类问题靠调 prompt 是解决不了的，因为问题不是“模型不认识金额”，而是整个流程里缺少一个结构化的校验环节。生产环境里，任何一个模型输出的字段都可能出错，金额、日期、人员工号、部门编码，每一个都需要被校验、被确认、被人工兜底。这些设计，在原型阶段几乎不会有人想到。所以我把企业级 Agent 的生产要求总结成五个字：稳、透、安、省、快。稳是稳定可靠，透是可观测，安是安全合规，省是成本可控，快是响应性能。后面讲的每一块工程方法，归根到底都在为这五个字服务。
2.2 五个生产级维度，一个都不能少
第一个维度是可靠性。Agent 必须能够在长时间运行中保持正确性，不能上午好用下午就崩溃，不能某个输入一变就全盘失控。可靠性的核心是对不确定性的控制：模型的输出不确定，就用逻辑纠正；外部接口不稳定，就用容错兜底；流程发起后不知道走到哪一步了，就用状态管理追踪。
第二个是可观测性。企业级系统的第一原则是“任何行为都能被解释”。传统软件可以靠日志堆栈追踪，Agent 不行，它的一次任务可能包含多轮模型调用、多个工具调用，中间还有大量自由文本的推理过程。如果没有专门的轨迹记录，出问题的时候你连 Agent 当时在想什么都不知道。这就像一个员工干活，你只看到结果不对，中间过程完全黑盒，那谁都救不了这个项目。
第三个是安全性。Agent 的权限边界、数据隔离、对外输出内容的合规性，都是必须从架构层面解决的问题。一个能调用内部系统的 Agent，如果权限控制得不好，相当于给每个员工发了一把万能钥匙。原型阶段可以忽略这个问题，生产阶段一旦出事就是大事。
第四个是成本。模型调用是有真实成本的，一个复杂的 Agent 任务，可能需要多次调用模型，每一次都是 token 消耗。很多团队原型阶段跑得很开心，没人在意一次任务花了多少钱，上线之后算账才发现，单次任务成本比人工处理还贵，项目直接被叫停。成本治理不是上线之后再做，而是在架构设计时就要算清楚。
第五个是性能。企业级场景通常有明确的响应时间要求。Agent 的内部推理链路长、工具调用多，很容易就把一次请求拉到十几秒甚至几十秒。用户在等一个结果的时候，耐心是有限的。性能问题不能靠加机器解决，要从模型选择、提示词压缩、并行调用、缓存等维度一起下手。
3. 原型阶段的正确打开方式：先跑通最小闭环，再谈远大架构
3.1 别一上来就画复杂架构图
我见过不少团队，第一周就开始画漂亮的架构图，什么编排层、模型层、数据层、网关层，五颜六色，看起来像一个大厂的中间件体系。但实际上业务逻辑都没想清楚，工具调用链还没跑通。这种习惯非常危险，因为你不是在设计架构，而是在逃避核心问题。
原型阶段最该做的事很朴素：用最快的方式跑通一条最小业务闭环。什么叫最小闭环？就是一个用户请求进来，Agent 理解意图，调用必要的工具，拿到结果，生成回复，完整地走出去。这个过程不要追求覆盖所有场景，只挑两三个真正有代表性的核心路径，做透。比如客服场景，就做“查订单状态”和“修改收货地址”这两个高频动作，把从用户输入到外部系统调用的链路完整打通。
我自己的经验是，原型阶段连框架都可以先不选，用 Python 脚本直接调模型 API，把工具函数写清楚，把提示词组织好，能跑就行。因为这一阶段的核心目的是验证两件事：一是模型能不能在提示词的引导下做出正确的工具选择，二是外部系统能不能接受 Agent 调用的方式。这两件事验证通过了，后面再换框架、加架构，都有底气。验证不通过，画再大的图也是空中楼阁。
3.2 原型阶段的代码要留好三个扩展点
虽然说不要过度架构，但有几个扩展点必须在原型阶段就留出来，不然后面重构会非常痛苦。第一个扩展点是工具抽象。Agent 要调用的每一个外部系统，都应该封装成统一的工具接口，输入输出都用清晰的 schema 定义。这样以后换接口、加工具，不用动编排逻辑。
第二个扩展点是消息记录。原型阶段就要把每次 Agent 运行的完整轨迹记录下来，包括用户的原始输入、模型生成的每一步思考、工具调用的参数和返回值、最终的回复内容。这些数据现在看起来只是日志，但以后构建评测集、排查线上问题时，它们是最宝贵的资产。我见过太多团队原型阶段图省事不记录，等上线出了问题，手里没有一条完整的轨迹可供分析。
第三个扩展点是可配置的提示词。不要硬编码在代码里，把提示词模板放在独立文件或配置中心里，方便随时调优。为什么强调这点，因为原型阶段你会发现提示词一天改八遍，如果你每次改提示词都要改代码重新部署，那效率会低到让人绝望。
3.3 原型阶段要回答的四个关键问题
我认为一个合格的原型阶段，结束时必须能回答清楚四个问题。第一个：工具调用链是否可靠。Agent 能不能在真实场景下，稳定地选择正确的工具，并且正确解析工具返回的数据。注意我说的是“稳定地”，不是“偶尔一次成功”。
第二个：模型能力边界在哪里。同一个模型，在哪些任务上表现稳定，在哪些任务上经常出错。这些边界决定了生产阶段你需要设计多少兜底逻辑。比如某个模型在简单意图识别上很好用，但一遇到多轮对话就忘记上下文，那生产阶段就要考虑外置记忆模块来补偿。
第三个：真实成本是否可预估。跑通最小闭环后，统计一下单次任务平均消耗多少 token、平均调用几次模型、延迟是多少。这个数据直接用于后续成本模型和架构决策。如果单次任务要调用 10 次模型，成本高得离谱，那可能需要换模型、精简链路，而不是硬着头皮上。
第四个：用户真实反馈如何。原型阶段一定要让真实用户参与测试，不是开发团队成员自导自演。真实用户会提出你想都没想过的说法方式、口语化表达、表意不清的指令。这些反馈决定了你需要准备多少种提示策略、多少轮澄清机制。我见过很多团队，原型阶段没有真实用户参与，结果一上线就被用户的多样表达击穿，这比技术问题更致命。
4. 评估体系先行：没有评测集的 Agent 工程都是刷流氓
4.1 从“感觉还行”到“可量化”:必须建立评测集
先说一个我踩过的坑。某个项目在原型阶段，开发同学每次改完提示词，就拿几条测试用例跑一遍，觉得“效果不错”，然后继续改下一版。结果改着改着，之前能过的用例突然过不了了，大家完全没有察觉。等到上线前做整体回归，才发现系统在某个核心场景上已经崩了三天。
这就是典型的不把评估当工程的下场。评估体系的第一个核心就是建立评测集，也就是一组带标准答案的测试用例。评测集不是随便找几十条问题，而是要对业务场景做结构化覆盖。我把评测集分成三层：黄金数据集、对抗数据集、回归数据集。
黄金数据集是核心业务场景的标准用例，每条用例都有明确的最佳回答或期望执行结果。对抗数据集的目的是挑战系统弱点，比如故意用模糊说法、包含错别字、语义有歧义的表达，测试 Agent 容错能力。回归数据集是历史问题合集，每次迭代跑一遍，确保修复一个 bug 不会引发另一个 bug。这三个集合加起来，构成了 Agent 质量的基本盘。
4.2 离线评估的四个核心指标
有了评测集，还要有清晰的评估指标。我常用的四个指标是任务完成率、工具调用准确率、单任务延迟、单任务成本。任务完成率，是指 Agent 在评测集上成功完成目标的比例，这是最重要的北极星指标。工具调用准确率单独拆分出来，是因为 Agent 的很多失败发生在工具选择或参数解析上，单独统计有助于定位瓶颈。
单任务延迟和单任务成本是资源指标。这些指标在原型阶段就拿来做基线，每次改动后跑一遍评测集，我们就能直观地看到：这次优化让完成率提高了两个百分点，但延迟涨了 500 毫秒，成本贵了 20%，值不值得。有了数据，所有的讨论都变得理性。没有数据，团队每天都在凭感觉争吵，谁也说服不了谁。
4.3 上线之后，评估体系要从离线走向在线
离线评估永远不能覆盖线上真实情况。所以生产阶段的评估体系，必须包含在线评估机制。我建议做三件事：真实流量抽样、用户反馈回收、人工抽检。真实流量抽样，就是从线上请求中按一定比例随机抽取样本，定期人工评估 Agent 的表现。不要全量，因为人工评估成本高，但抽样比例不能太低，我通常建议每天至少抽 30 到 50 条核心场景请求。
用户反馈回收，包括显式反馈和隐式反馈。显式反馈是用户点“有帮助”“没帮助”、打分等；隐式反馈是用户是否频繁重试、是否在某个环节停滞过久、是否最终转接人工。这些信号都是判断 Agent 真实质量的依据。人工抽检则是定期组织业务专家，对 Agent 在真实场景下的表现做深度点评。这些专家点评往往比自动化指标更能提前发现潜在问题，因为自动化指标只能告诉你“出了错”，专家能告诉你“为什么会错”以及“业务上能不能接受这个错”。
5. 稳定性与容错设计：Agent 的每一项能力都要有兜底
5.1 请求链路的超时、重试、熔断、降级
Agent 和传统微服务不同的一点是，它的一次请求会串联起多个外部依赖。用户说一句话，Agent 可能要调用模型两三次，还要调 CRM 系统、查数据库、发通知。任何一个环节卡住，整个任务就会卡住。所以做生产化改造的第一步，就是给整条请求链路加治理策略。
我的经验是四个词：超时、重试、熔断、降级。超时是最基本的，每个模型调用和工具调用都必须有明确的超时时间，不能一直傻等。模型调用一般设 30 到 60 秒，工具调用根据系统特性设 3 到 10 秒。重试要谨慎，只对幂等的、安全的调用做重试，而且重试次数不要超过两次，间隔递增，避免因为重试造成外部系统压力翻倍。熔断是当某个工具连续失败超过阈值时，直接切断调用，走降级路径。比如查天气的外部服务挂了，Agent 可以停止调用该服务，直接告诉用户“天气服务暂时不可用”，而不是反复尝试最后报错。
降级策略要在设计阶段就定义好。每个核心工具，都要想清楚“这个工具挂了，Agent 怎么办”。有的可以换备用数据源，有的可以用模型自身的常识回答但要注明不确定性，有的必须终止流程转人工。没有降级方案的工具，就是生产环境里的一颗定时炸弹。
5.2 模型输出的结构化约束和校验
这是我认为企业级 Agent 和普通 AI 应用差距最大的一个环节。普通人写 Agent，让模型输出自然文本就结束了。企业级不行，因为 Agent 的输出往往不只是给用户看的文本，还要驱动后续动作，比如提交一个订单、修改一条记录、推送一条审批。这些动作要求输出必须严格符合 schema。所以生产化的标配是，所有要驱动动作的模型输出，都必须定义为结构化 JSON，并做严格校验。
举一个具体场景。Agent 负责提交请假申请，模型输出应该是这样一段 JSON：员工工号、请假类型、开始时间、结束时间、请假理由。模型生成这段 JSON 之后，工程层要做三件事：格式校验、逻辑校验、业务校验。格式校验是确保它是个合法的 JSON，字段齐全；逻辑校验是确保结束时间大于开始时间、时间范围在可请假天数内；业务校验是调用人力资源系统，确认该员工当前没有重叠申请、剩余假期充足。只有这三层校验全部通过，才允许真正提交申请。
我看到很多团队忽略了业务校验，觉得模型能输出合法 JSON 就万事大吉。但实际上，模型可能把“请假三天”理解成“从周一到周三”，而用户真正想请的是“下周三到周五”。这类业务语义错误，靠格式校验永远发现不了，只能靠业务校验兜底。所以我把这套校验体系称为 Agent 的“安全带”，没有它，系统随时会出重大事故。
5.3 外部动作的幂等、事务和补偿
比输出校验更难的，是 Agent 执行外部动作后的数据一致性。Agent 在一个任务里可能会连续调用多个系统，比如先创建订单、再锁库存、再发起支付。问题在于，如果第三个步骤失败了，前两个步骤已经产生了真实影响，怎么处理？
传统软件可以通过数据库事务解决，但 Agent 面对的是多个独立的外部系统，它们之间没有统一的事务管理。所以必须自己做补偿。我的实践方案是：所有具有副作用的外部调用，都要设计成幂等接口。简单说，同一个请求执行多少次，效果都一样。比如创建订单的接口带上业务幂等键，Agent 重试时传同一个键，系统不会创建重复订单。没有幂等保护的接口，一定要在 Agent 层做状态记录，把“已创建订单”记录下来，后续步骤失败时，通过反向接口回滚。
补偿机制的设计原则是宁可漏，不可重。因为漏了可以人工补，重复执行可能造成资金或库存错误，代价大得多。所以在设计 Agent 流程时，我会明确每个步骤是“可自动补偿”还是“需要人工介入”。可自动补偿的，写清楚补偿逻辑；需要人工介入的，一定要发告警，让平台运营人员看到并处理。这是一条很朴素的工程原则：Agent 能做多少事不重要，重要的是它做错事之后，系统能不能兜住。
6. 可观测性体系：没有轨迹记录的 Agent，出了事只能靠猜
6.1 三类日志：运行日志、轨迹日志、审计日志
普通软件的日志体系对 Agent 来说远远不够。一个 Agent 任务的执行过程，不是一行日志能描述的。我把它拆成三类日志：运行日志、轨迹日志、审计日志。
运行日志是传统意义上的程序日志，记录每个模块的调用关系、异常信息、耗时，主要用于系统运维和故障排查。轨迹日志是 Agent 独有的，记录一次任务从用户输入开始，Agent 的每一步思考、每一次工具调用的参数和返回值、中间结果的产生过程。审计日志则面向合规需求，记录谁在什么时间通过 Agent 做了什么操作，这个操作产生了什么业务影响，通常需要长期保存且不可篡改。
很多团队只做了运行日志，觉得系统没报错就行。但 Agent 的很多问题不会报错——模型没有崩溃，代码没有异常，只是推理方向偏了，得出了一个错误结论。这时候运行日志里全是正常记录，只有轨迹日志能告诉你，Agent 是怎么一步步走到错误结论的。我坚持认为，轨迹日志是 Agent 可观测性体系里最核心的部分，没有之一。为了采集轨迹数据，原型阶段就要在关键节点埋点，把模型的输入输出完整记录下来，工具调用的完整请求响应也记录下来。只要数据有了，后面不管是做评估、做分析、做复盘，都有素材可用。
6.2 全链路追踪和成本归因
企业级 Agent 往往部署在微服务架构中，一次 Agent 请求会横跨多个服务。所以传统的分布式追踪系统必须接入，给每次请求分配一个全局 trace ID，从 API 网关到 Agent 编排服务，再到每个工具调用，全部串起来。有了 trace ID，排障时你可以一条链路看下去，知道问题出在模型调用还是某个下游服务。
另一个很容易被忽略的是成本归因。Agent 的模型调用成本分散在各个服务里，如果不对每次任务做成本归因，月底账单出来后你根本说不清钱花在哪里。我的做法是在轨迹记录里加上 token 用量和费用统计，按业务类型、按用户、按工具维度汇总。这样一来，哪个业务线消耗了多少成本、哪个功能性价比低，一目了然。成本归因看似是财务问题，其实是架构问题，因为它的前提是你在每一次模型调用时都做好了计量。这个计量能力必须在架构设计初期就预留，不然后面再加非常痛苦。
6.3 告警体系怎么设才不让人麻木
可观测性的最终目的是发现问题并及时响应。但告警设置很有讲究，设得太多会被忽略，设得太少会漏掉关键故障。我建议告警不要只盯系统指标，更要盯业务指标。系统指标包括模型调用错误率、工具调用失败率、平均延迟、token 消耗异常等，这些是基础保障。业务指标则要考虑正确率、业务成功率、用户转人工率等，这些反映了 Agent 的真实服务效果。
我曾经帮一个团队定位过一个诡异问题：他们的 Agent 表面上全都成功返回了，但用户投诉率却不断上涨。后来查了业务指标才找到原因，原来是 Agent 虽然返回了回答，但经常答非所问，用户只能反复重试然后转人工。系统指标一切正常，业务指标一路飘红，这就是只看系统指标的盲区。所以告警体系一定要同时覆盖这两个层面。还要注意告警收敛，把相似的问题聚合成一条告警，避免告警风暴。告警的意义不在于“多”，而在于“准”，宁可用一条有明确处理指引的告警，也不用十条让人麻木的告警。
7. 基础设施：把 Agent 当成正经服务来管
7.1 Prompt、代码、模型三位一体的版本管理
传统软件版本管理管的是代码，Agent 工程要管的是三样东西：代码、提示词、模型配置。这三者任意一个变化，都可能改变 Agent 的行为。所以版本管理必须做到三位一体：每次发布都要清楚记录，这次线上跑的是哪个版本的代码、哪个版本的提示词、哪个版本的模型。三者必须一一对应，不能出现代码是新版、提示词却是旧版的情况。
我把提示词当成代码来管理，放进 Git 仓库，走 code review 流程，每次改动都有记录和理由。模型配置也是一样，模型名称、版本、参数设置，都要写清楚变更原因。只有做到这一步，当线上 Agent 出现行为偏差时，你才能快速判断是哪个变更引入的问题。否则，代码、提示词、模型三个变量同时悬空，排查问题就变成了一场赌博。
7.2 从手动部署到流水线发布
很多 Agent 项目的发布方式还停留在“开发改完代码，手动跑一下，然后 restart 服务”的阶段。这在原型阶段没问题，生产阶段就是灾难。任何变更都应该走持续的发布流水线。代码合并后自动构建、自动跑一遍评测集，评测集通过后部署到测试环境，再由测试人员在测试环境做快速验证，最后才推到生产环境。
这里要特别说一点，Agent 项目的测试环境和生产环境往往存在差异，主要是模型 API 的不确定性。同样的提示词，在测试环境调用和在生产环境调用，结果可能有细微差别。所以除了自动化测试，灰度发布是必须的。先让 5% 的流量打到新版本上，观测业务指标，确认没有异常后再逐步放量到 20%、50%、100%。一旦发现异常，立即回滚到上一版本。灰度发布和回滚能力，是生产系统的安全气囊，没有它，一次随意的全量发布就可能把整个业务拖下水。
7.3 快速回滚：Agent 的后悔药要提前备好
Agent 回滚比传统服务回滚更麻烦，因为你要回滚的不仅是代码，还有提示词和模型配置。所以每次发布都要生成一个完整的版本快照，包含代码、提示词、模型配置、评测集结果，整体打成一个发布包。回滚时，不是单独回滚某个文件，而是把整个快照恢复回去，确保三件套一致。
我还建议配置一个紧急预案开关。如果线上 Agent 突然出现大面积异常，比如某个核心工具调用失败导致任务堆积，可以一键把 Agent 切换成降级模式。降级模式下，Agent 不再尝试完整流程，而是直接返回标准回复并建议用户走人工通道。这看起来有点“怂”，但比系统整体挂掉、用户完全无法使用要好得多。我见过太多团队，线上 Agent 出故障后，开发手忙脚乱地查代码，用户却在那边干等着。提前准备好降级预案，至少能让你从容地排查问题，而不是一边被业务部门催命，一边面对失控的系统。
现在回头看这套方法论，我最大的体会是：企业级 AI Agent 的成败，其实在原型阶段就已经注定了。如果原型阶段就建立评估集、做好轨迹记录、设计好兜底路径，后面的生产化改造会比较顺利。反之，原型阶段图快、图省事，生产阶段会付出好几倍的代价来还债。这篇“上篇”覆盖了从原型到生产的整体框架、评估体系和稳定性、可观测性、基础设施这几个基本面，后续的中篇和下篇，我打算重点聊 RAG 的工程化实践、多智能体协作的架构模式，以及安全合规与成本治理的完整方案。如果你正在做 Agent 落地，建议先把这一篇提到的东西逐项对照一下，缺哪块补哪块，打牢地基再往上盖楼，比什么都重要。
