开篇先聊一个很现实的场景你的团队花了三周时间用 LangChain 或者自己拼的 Prompt 做了一个 Agent demo在部门内部分享时效果惊艳老板当场拍板说“下个月上线”。于是问题来了——demo 能跑通和生产环境能稳定跑中间差的不是一点半点。我在过去一年多里前后参与过几个企业级 Agent 项目的架构和落地从客服助手到内部知识问答再到工单自动处理几乎每个项目都走了一遍“Demo 十分钟生产十个月”的路。这中间踩过的坑、绕过的弯远比模型选型本身要多得多。很多人以为 Agent 生产化的难点在模型能力实际上模型能力早就不是主要瓶颈真正决定项目能不能活下去的是 Agent Runtime 是否可靠、RAG 链路是否严谨、Tools 是否可控、Workflow 是否可编排、Governance 是否到位以及 Evaluation 能不能帮你兜住底线。这篇文章就按我实际落地项目的经验把企业 Agent 从 Demo 到生产的完整技术骨架拆开讲一遍。内容偏架构和实践适合正在带 Agent 项目、或者准备把 demo 推向生产的工程师和技术负责人参考。我会尽量讲清楚每个模块解决什么问题、关键设计决策背后的原因以及哪些坑是文档里不会告诉你的。1. 先搞清楚Demo 和生产环境的本质差异是什么1.1 为什么 Demo 总是“看起来很美”Demo 的本质是演示一条最顺利的路径。你精心挑选了输入样例Prompt 里的措辞调试了几十遍知识库里放的内容也都是整理好的所以 Agent 每一步都走得对。但生产环境的本质是处理无穷多的边缘情况用户不会按你预设的方式提问数据不会按你期望的格式到达第三方接口随时可能超时模型也有可能在毫无征兆的情况下改变输出风格。我见过最多的一种翻车方式是demo 里用的全部是真实数据切片看起来是“真实场景”但实际上数据量只有几百条而且都是被人工清洗过的。一上生产数据变成几百万条、几十个来源权限体系一接入RAG 的召回质量立刻崩掉很多问题开始答非所问。生产环境的第二个特征是并发与延迟。Demo 的时候你是单用户在终端里慢慢等等 10 秒也无所谓。生产环境里用户等不了 10 秒尤其是嵌入到业务系统里面的 Agent如果一次查询要 15 秒才能返回那这个产品在体验层面直接不合格。这逼着你必须做缓存、做并行、做流式输出、做查询改写和路由而这些在 demo 阶段往往完全不用考虑。1.2 生产级 Agent 的参考架构在具体展开之前我想先给一个整体架构地图。这个地图是我在多个项目里反复调整后沉淀下来的不一定适用所有团队但可以作为讨论的基线。企业级 Agent 生产架构自上而下大概分为五层接入层承担多渠道对接和会话管理编排层处理 Agent Runtime、Workflow 和状态管理能力层包含 RAG、Tools、模型网关和记忆模块治理层负责权限、审计、安全和成本控制评测层则是独立于业务链路之外的持续验证体系。拆开看每一层都有各自的难点。接入层不难难的是会话状态在多种渠道之间的一致性。编排层最复杂因为 Agent Runtime 并不是跑一次就结束而是会经历多轮工具调用、等待、恢复、超时、人工介入。能力层的重点在于 RAG 不能只做向量检索Tools 不能只是写个函数然后让模型去调。治理层在国内企业环境下尤其容易被忽略但往往是在上线评审时被问得最惨的一层。评测层则是决定你敢不敢发版的关键没有评测体系你永远不知道这次 Prompt 改动到底是把效果改好了还是改坏了。后面几节我会按层拆开讲每一层都会带上实际项目里踩过的坑和调整过程。2. Agent Runtime让多轮任务真正“跑得稳”2.1 Runtime 要解决的根本问题Agent Runtime 这个词听起来有点抽象我换个说法当你的 Agent 在一次对话中需要调用多个 Tools、按顺序处理多个步骤并且中途还可能失败重试时谁来负责编排这些步骤、保存中间状态、保证任务能继续跑下去这就是 Runtime 要做的事。Demo 阶段你可以用硬编码的循环——调用 LLM、解析结果、执行工具、再把结果传回去循环 N 次直到模型说“任务完成”。这个写法在单轮、单用户、无故障的情况下完全没问题但到生产环境它至少暴露出三个问题。第一进程重启后任务状态丢失用户在等一个长任务结果服务发版这个任务就没了。第二没有重试和超时管理一个第三方工具卡住整个 Agent 线程就被拖死。第三无法并行执行多个子任务所有步骤只能串行跑效率大打折扣。所以生产级的 Runtime 需要一个类似工作流引擎的能力让 Agent 的执行过程可以被持久化、被恢复、被观测。这也是为什么现在业界很多人把 Agent 的运行时和 Workflow Engine 放在一起讨论它们本质上是同一件事的两种形态。Agent 偏向于动态决策路径Workflow 偏向于固定路径编排但底层都需要一套状态管理、重试机制和可观测性设施。2.2 为什么必须做持久化和状态管理我在一个实际项目里遇到过这样一个情况一个工单分类 Agent 需要依次调用用户身份服务、工单系统、知识库和通知服务整个链路大概需要 40 秒。本来这个时长用户还能接受但有一次底层服务升级导致 Agent 执行到第 3 步的时候进程崩溃重启。由于我们没有做执行状态持久化这单工单直接从系统里消失了用户那边看到的是“客服已读但没有任何回复”。这就是状态管理的价值。生产级 Runtime 至少要支持把一次 Agent 执行的关键节点状态写入外部存储比如 Redis 或者数据库这样即使进程挂掉也能从最近的一个稳定节点恢复执行。这里涉及的一个常见方案是把 Agent 执行建模为有限状态机每个工具调用的结果视为一次状态迁移只要状态可回溯任务就可恢复。另外一个容易踩的坑是模型推理过程本身不可重入也就是说你不能通过“重放同样的输入”来复现模型的某一次中间输出。因此我们一般是在工具调用完成之后、把结果持久化再让模型基于持久化结果继续推理。这样即便模型服务本身抖动也不至于让整个任务从头再来。2.3 引擎选型自研、开源框架还是云托管Runtime 的选型没有标准答案但有几条经验可以参考。如果团队规模小、Agent 复杂度低、调用链不超过三四个节点建议直接基于开源编排框架二次开发把核心状态管理做扎实就够了不要一上来就自研引擎。如果业务链路复杂涉及人工审批、并行子任务、定时触发等那可能需要引入正式的 Workflow Engine甚至把业务上的流程编排也统一接进来。还有一种判断维度是看“失败恢复”的要求有多高。支付的 Agent 化改造和内部知识问答的 Agent 化改造对 Runtime 的要求完全不是一个量级。前者如果任务中断影响真金白银必须做到事务级别的可靠性后者只要做到“用户刷新能看到之前的回答”就能接受。个人建议不要过早迷恋某个特定框架。Runtime 领域的核心抽象基本已经收敛节点、边、状态、触发器、重试策略。你只要把这几样吃透换什么引擎其实差别不大重要的是团队自己对这个抽象模型有把控力。3. RAG生产级知识库检索不是“向量化 相似度”这么简单3.1 先给 RAG 一个清晰的生产定义RAGRetrieval-Augmented Generation检索增强生成这个词被用得太泛了导致很多人对它的理解就是“把文档切碎、向量化、然后做相似度搜索把 Top K 塞给 LLM”。这个概念层面没有错但生产环境的 RAG 至少还应该包含查询理解、路由、混合检索、重排、引用溯源、缓存和知识库更新这几个环节。首先说查询理解。用户在知识库问答场景里提问往往不是一句清晰的话。比如“我们的报销政策里对住宿费有什么限制”系统需要先把这个问题转换成适合检索的形式。可能要做实体识别、同义改写甚至要判断这个问题是不是一个“追问”需要参考上一轮的上下文。接着是路由。不是所有问题都需要走向量检索有些高频问题直接命中缓存更划算有些是结构化查询需要查数据库而不是查文档有些需要走关键词匹配反而比向量更准。在 RAG 链路前面加一个 router让不同类型的 query 分发到对应的处理链路是生产化改造中性价比最高的一步。3.2 混合检索为什么只用向量检索会翻车我见过太多团队在构建 RAG 知识库时只做向量检索结果上线后发现产品型号、工单编号、人名这类精确实体用向量检索效果极差。原因是向量搜索擅长语义相似但如果你索引里存的是“iPhone 15 Pro 用户指南”用户问“A2844 支持什么网络”模型很难通过语义找到准确的关联。解决方案就是混合检索向量检索负责语义扩展关键词检索负责精确匹配然后将两路结果做融合排序。融合的方式可以参考 RRFReciprocal Rank Fusion这类简单有效的算法不一定要上重排序模型。我常用的方案是 Elasticsearch 里同时建向量字段和 keyword 字段查询时并行执行 kNN 搜索和 BM25 搜索然后按 RRF 融合取 Top K再接一个轻量级重排模型把最终顺序排好。混合检索的引入会带来一个额外问题知识库的索引结构变复杂了切片、清洗、元数据提取都得跟上。向量化流程也不再是简单的“chunk - embedding - 写入向量库”而是要先做文档解析、结构识别、标题层级提取、元数据标注、切片策略选择最后才进入向量化和写入。3.3 GraphRAG 和 RAG 评测解决更深层的问题最近 GraphRAG 的话题很热但我建议团队冷静评估一下。GraphRAG 对跨文档关系推理、多跳知识挖掘确实有优势比如“我们公司哪些供应商位于华东地区且认证过期了”这类问题向量检索很难给出好答案知识图谱就有天然优势。但 GraphRAG 的构建成本很高抽取实体、构建关系、图谱存储、查询改写都是额外工程量。我的判断是如果你的 RAG 场景 90% 是单文档或单段落就能回答的问题暂时别上 GraphRAG如果有大量需要聚合多源信息做推理的场景再认真评估。RAG 的评测很多人问业内常提的指标包括召回内容的上下文精度context precision、上下文召回率context recall、忠实度faithfulness和答案相关性answer relevancy。这些指标的实现方式大多依赖 LLM-as-a-Judge 或者手工标注生产环境里我更建议把评测问题集按业务场景分层让业务方参与标注 Ground Truth先跑小批量评测把明显问题修掉再扩大范围。别追求一次性把 RAG 指标做到完美先确保几个核心流程可用再逐步优化。4. ToolsAgent 的能力边界和风险敞口4.1 Function Calling 不是写个函数就行Agent 的能力上限取决于 Tools 的数量和质量这句话不假。但 Tools 接入如果做得不够严谨Agent 的能力边界就会变成风险敞口。我在项目里反复强调一个原则Tools 的 Schema 必须极其精确宁可让模型少调用也不要让它误调用。怎么理解模型调用工具本质上是根据你的函数描述去生成一个结构化的调用参数。如果函数描述写得含糊它就可能在不该调用的时候调用或者在参数上自由发挥。比如你有一个“查询用户订单”的工具参数是 userId描述里如果没写清楚 userId 从哪个上下文取模型可能会编一个看起来合理的 ID 出来而这个 ID 对应的是另一个用户的数据——这就是越权漏洞。所以生产级的 Tools 设计要围绕三件事展开Schema 设计、参数校验和调用前置检查。Schema 层面每个参数要写清楚类型、枚举、格式、是否必填字段描述要包含触发工具和不触发工具的场景。参数校验则是在代码侧做的绝不能信任模型生成的参数要严格验证后才能真正去调用外部系统。4.2 工具的授权、幂等和审计授权是个容易被忽略的大问题。Agent 在调用工具时它的身份究竟是什么是以服务账号身份调用还是以最终用户身份调用这里涉及到 user-level 和 app-level 的权限区分。如果服务端只做了应用级别的鉴权Agent 拿到的是系统级权限那用户在对话里让 Agent “把另一个部门的预算报表发给我”Agent 完全有可能真的调用接口拉取到数据——因为从工具角度看这个请求是合法的。解决方式是把用户上下文透传到每个工具调用里。工具在发起外部请求时需要附带用户的身份令牌由目标系统做细粒度授权Agent 本身不做越权判断。这样权限边界还是在各个业务系统手里Agent 只是一个执行器。幂等性也要提前考虑。Agent 调工具经常遇到超时重试的情况如果工具的副作用设计得不好重试可能造成重复下单、重复审批、重复发消息。建议所有具有写操作的工具都支持幂等键客户端生成唯一 ID服务端根据 ID 去重。审计和 Tracing 是另一个大项。等上了线你会发现业务方经常来问“这个 Agent 刚才为什么调了那个接口参数到底是什么”。如果没有完整的调用日志这个问题根本答不上来。这部分建议跟后面的 Governance 一起看。5. Workflow确定性与智能的平衡5.1 什么时候用 Workflow什么时候让 Agent 自由发挥在企业生产环境里我其实不太建议让 Agent “全自由”地跑完整条业务链路。理由很简单自由意味着不可预测不可预测意味着你没办法对结果负责。更稳妥的做法是“Workflow 为骨架Agent 为分支”。提前把业务流程里相对确定的部分用工作流定义好比如下单流程校验库存 - 预占库存 - 生成订单 - 通知仓库。这个流程的每一步是固定的完全不需要 Agent 参与用代码写清楚就行。Agent 只负责处理需要语义理解的分支比如用户说“我要把刚才那个订单的收货地址改了还换成加急发货”这时候 Agent 需要解析出意图和实体再映射到工作流的参数上。这样做的好处核心流程稳定可控Agent 的能力被限制在它能胜任的子集。团队排障时80% 的问题能快速定位到工作流的某一步而不是在一个黑盒里猜。5.2 语义路由和人工审批节点Workflow 与 Agent 的结合离不开语义路由。你可以把路由理解为一个“Agent 版的网关”入口接收用户请求通过 LLM 判断这个请求应该落入哪条流程、调用哪些工具、是否需要人工介入。比如一个内部 IT 支持 Agent用户说“我的电脑蓝屏了”路由应该把请求分到“故障报修”流程而不是“新设备申请”流程。如果用户说“因硬盘损坏申请更换电脑”那就要走“资产更换”流程而且这个流程里大概率需要插入一个人工审批节点。人工审批节点是我强烈建议所有团队在早期就引入的机制尤其是有写操作或影响面较大的动作。比如 Agent 代替员工提交报销申请这在内部系统里可以接受但如果 Agent 自动审批报销那就必须慎之又慎。人工介入不等于效率低下可以把审批做成异步的Agent 提交申请后先挂起等审批结果到了再继续执行后续动作。5.3 流程可观测性和回滚Workflow 一定要有清晰的执行日志和状态查询界面。想象一个运维场景用户发了一个请求Agent 在 9 个节点里执行到第 6 个节点时失败如果你只有一句“系统错误”无论是用户还是开发都无从下手。如果每步都有 trace能看到失败节点以及失败原因问题就能快速收敛。对于状态型工作流我还建议支持“回滚”或“补偿”机制。比如 Agent 在生成一个销售订单时调用了“创建客户”和“创建订单”两个工具如果“创建订单”成功但“创建客户”因为网络原因实际成功却返回超时Agent 重试的时候就可能创建了重复客户。补偿机制就是要在这种情况发生的时候做一个反向操作把多余的客户档案清掉。这块在流程设计时就要想清楚不要指望事后用人工去修数据。6. Governance企业落地绕不开的治理层6.1 影子 IT 和影子 AI聊 Governance 之前先说一个现象AI 项目在企业里有一个“影子化”趋势。业务部门等不及 IT 部门的流程直接用个人账号去调用各种大模型 API把业务数据塞给外部模型企业完全不知道这些数据去了哪里。这个问题本质上和当年“影子 IT”一样治标要先治本。治理不是只为了合规它是为了降低企业的整体风险。所以在设计 Agent 架构时要把模型访问统一收口到一个网关层业务方不能绕过网关直接访问模型供应商。这个网关上要做几件事密钥管理不能把 API Key 写在代码或环境变量里应该用密钥管理服务托管、模型路由不同场景分配不同模型、成本核算每个部门、每个应用消耗了多少 token、内容审计敏感信息有没有被送到外部。6.2 密钥与多环境隔离密钥管理是我每次做技术评审都会重点检查的一项。Demo 阶段把 key 硬编码在环境变量里无所谓但生产环境一旦出现密钥泄漏后果很严重。我建议的规范是代码仓库里禁止出现任何密钥本地开发用本地密钥文件测试环境用独立的测试密钥生产环境密钥由密钥管理服务统一托管且定期轮换。多环境隔离也要做到位。我在一个项目里见过一个非常低级的事故开发环境的 Agent 因为配置错误调用了生产环境的订单接口生成了几个真实订单导致客户投诉。事故原因就是开发环境与生产环境的配置没有隔离服务发现把流量导到了错误的实例上。多环境隔离听起来是老生常谈在 Agent 这种跨系统调用的架构里一旦做不好出事就是大事。6.3 可观测性从 Tracing 到审计Agent 的调用链比传统 API 网关要长得多传统 Tracing 工具往往只覆盖到“API A 调用了 API B”但 Agent 场景里还多了一层“模型在这个节点做了什么决策”。这块建议关注 OpenTelemetry 对 GenAI 的语义约定它把模型调用、向量检索、工具执行统一建模成 Span能让你看到一次 Agent 执行的完整内部视图。更重要的其实是审计视角谁在什么时间通过 Agent 做了什么操作、看到了什么数据。对于金融、医疗、政务场景这是刚需。实现上可以在模型网关和工具调用两层同时埋点形成两条独立的审计日志流一条记录“人和 Agent 的对话”一条记录“Agent 对外部系统的每一次影响”。这两条流要能按会话 ID 关联起来。7. Evaluation敢不敢发版靠它说了算7.1 没有评测体系Prompt 改动就是开盲盒很多团队改 Prompt 基本靠感觉改完觉得“看起来更好”但无法回答“更好多少、哪些 case 变好了、哪些 case 变差了”。这是 Agent 项目里最危险的事因为一次 Prompt 改动可能在 100 个 case 里修好了 20 个同时也弄坏了 15 个但你的直觉告诉你“确实变好了”。所以 Evaluation 不是上线的最后一步而是从第一天就要开始建设的流水线。如果一个 Agent 项目做了三个月评测集还是空白的我会建议团队先停下手里的活把评测集搭起来再继续开发。评测集的构建要从业务中来。第一步是收集真实用户问题不是凭空编。第二步是把这些问题按场景分层比如“简单问答”“多轮追问”“复杂推理”“工具调用”“敏感输入”等每类至少 20 条。第三步是为每条问题标注参考答案并注明答案可以从哪个文档哪个段落找到依据。这一步最好让业务方参与别让研发自己闭门造车。7.2 评测指标体系和自动化回归从评测指标角度来说离线评测分两块RAG 质量和端到端效果。RAG 质量看上下文是否相关、召回率是否达标端到端效果要结合答案本身是否忠实于上下文、是否满足用户意图来评估。具体落地上可以逐步从人工评分走向自动化。第一步先做每天一次的批量评测每次跑完把结果扔到看板上哪怕是人工快速扫一遍也比没有任何评测强。第二步接入自动评分用 LLM-as-a-Judge但要注意 Judge 本身的偏差最好用 Code-as-a-Judge 的方式把能被确定性程序判断的指标先用程序判断比如引用是否有依据、禁用词是否出现、工具参数是否合法。第三步是设置回归门禁当评测集的关键指标下降超过阈值时阻塞发版。我在实际项目中用过最有效的评测组合是用一套几百条的评测集做每日回归产出整体通过率和分场景通过率另外积累一套“灰名单”用例专门记录线上反馈回来答错的 case每周补充进评测集。这套机制跑起来之后团队改 Prompt 再也不用靠猜每次改动都有数据支撑。8. 落地路径从第一个 MVP 到全量生产8.1 分阶段推进的路线图建议如果非要给一条可执行的落地路径我会建议分四步走。第一步是定义清晰的业务边界。先选一条窄一点的业务流程来做 MVP不要一上来就试图做一个“什么都能干”的企业助手。窄意味着出错造成的影响可控、评测集容易建、用户预期容易管理。第二步是搭基建设施。密钥管理、日志、Tracing、评测集、基础 RAG 链路和 2~3 个核心工具接入这些是骨架。骨架不牢后面全部白搭。第三步是做小范围灰度。挑一个团队内部或者一个友好客户群用真实数据跑几周重点看三类信号任务完成率、用户反馈、失败原因分布。这个阶段不要急着做加法每发现一个问题先修复再放量。第四步才是扩大范围。每接入一个新场景都应该按照“流程梳理 - 数据接入 - 评测集构建 - 灰度 - 上线”这个循环走一遍切忌把几个场景揉在一起同时上线。8.2 团队能力建设和避坑提醒Agent 项目对团队的要求很特别。它不像传统后端项目那样接口定义好后大家各写各的。Agent 项目里模型、数据、流程、评测、产品体验高度耦合团队里需要有人能同时理解 Prompt、工程架构和业务逻辑。如果团队里都是纯后端或者纯算法的人建议先补上一个能跨界的角色。最后再讲几个我反复踩过的坑希望你能避开。第一别让 Agent 直接连接所有人的数据库然后希望通过 Prompt 限制它的行为——权限要在系统层面收紧不能依赖模型自觉。第二别把 RAG 只做成“知识库问答”它更重要的价值在于让 Agent 做决策时有据可依。第三评测集要动态维护模型升级、知识库更新、业务规则变化都会让旧评测集逐渐失真。企业 Agent 的落地本质上不是靠更快更强的模型而是靠一套扎实的工程体系让模型在受控的范围内发挥能力。把 Runtime、RAG、Tools、Workflow、Governance 和 Evaluation 这条链路想清楚Demo 到生产之间的距离并不遥远。我自己做完几个项目后的感觉是真正决定 Agent 项目成败的不是模型选得有多先进而是工程细节和评测闭环做得有多到位。