从去年开始我陆续参与了几个企业级 Agent 项目的落地一个很明显的感觉是大家聊 Demo 的时候都很兴奋一旦谈到生产环境问题就像雪崩一样涌过来。并发怎么扛、知识库怎么更新、工具调用出错怎么办、模型乱说话谁来负责、迭代了一版之后怎么知道有没有变好……这些问题在 Demo 阶段根本不会暴露但它们恰恰是决定一个 Agent 项目能不能真正跑起来的关键。这篇文章我想从自己踩过坑的角度把这套架构完整梳理一遍从 Agent Runtime 到 RAG、Tools、Workflow再到 Governance 和 Evaluation。内容偏实操适合已经在做 Agent 项目、或者正准备把原型推向生产的团队参考。1. Demo 与生产环境的本质差异先说一个我在多个项目中反复看到的场景Demo 阶段用 LangChain 或者直接调 API 写一个几十行的脚本跑通一个漂亮的问答流程老板看了很满意。然后说要上生产问题就从四面八方冒出来了。1.1 Demo 到 Production 的落差在哪里Demo 阶段的核心目标是“证明可行”所以代码通常是线性的收到问题检索知识库丢给模型输出答案。这个流程在 20 个测试用例上跑得很顺但生产环境面临的是另一种复杂度并发访问导致的大模型 API 限流和超时知识库内容更新后Agent 回答的还是旧数据工具调用链路过长导致中间某一步失败时整个任务失败模型输出的格式不稳定解析出错不同部门、不同角色能访问的数据范围不一样但 RAG 检索却是全局的谁用了这个 Agent 做了什么操作出了问题之后完全没有追溯能力我之前和一个团队合作他们的 Demo 效果非常好——在一个客服知识库上做了个很流畅的问答机器人。上了生产之后第一周就翻车了原因是知识库里其实有几百份不同产品线的手册但检索的时候没有做任何过滤导致问 A 产品的问题返回了 B 产品的答案。用户根本不知道 Agent 给错了产品线只会觉得这个机器人不靠谱。1.2 生产级 Agent 必须要回答的问题在动手做架构设计之前我建议团队先把下面几个问题想清楚这些问题基本决定了整个系统的复杂度Agent 的运行状态在哪里维护进程重启之后会话还能不能继续知识库更新需要多长时间生效是全量重建还是增量更新工具调用失败后的降级策略是什么是重试、换一个工具、还是转人工请求涉及多轮对话上下文窗口放不下的时候如何做截断或摘要一个请求从进入到返回中间涉及哪些环节如何设置超时和熔断Agent 的每一次决策和工具调用能不能被完整记录和回溯如果你的回答全是“先跑起来再说”那基本可以断定这个 Agent 离生产还有一段距离。这套问题不一定全都要在第一天解决但要在一开始就有明确的方案演进路线。2. Agent Runtime一切上层能力的地基Agent Runtime 这个名字听起来有点抽象我把话说直白一点它就是 Agent 应用的运行时底座负责管理 Agent 的整个生命周期包括状态管理、执行引擎、上下文维护、与外部系统的通信等。2.1 Runtime 到底管什么很多人觉得 Agent 的核心是模型、是 Prompt、是 RAG这些当然重要但它们其实是跑在一个“壳”里。这个壳就是 Runtime它决定了一个 Agent 能不能稳定服务。以我之前做过的一个项目为例我们的 Agent 服务最开始是一个无状态的服务收到请求就调模型返回结果。后来业务方要求对话要支持多轮上下文而且要能够在用户中断几小时之后继续对话。这时候问题就来了上下文存在哪里是每次请求都把所有历史消息发给模型还是只请求关键信息的摘要如果同时有上千个用户在使用内存里的上下文状态怎么持久化这个项目最终用 Redis 存储会话状态通过一个状态管理器维护每个会话的上下文。具体的做法是把每轮对话的用户输入、Agent 的中期思考、工具调用记录、最终回复都打包成语义块不仅要存储完整内容还要存摘要内容这样后续对话既能引用细节又不会让上下文无限膨胀超出窗口限制。2.2 Runtime 选型的几个判断标准市面上有不少现成的 Runtime比如 LangGraph、LlamaIndex Workflow、Coze、Dify 的自研引擎还有各大云厂商的 Agent 平台。我的经验是选择 Runtime 不要只看它能跑通多复杂的 Demo而要关注几个生产指标状态持久化能力会话挂起、恢复是否天然支持可观测性单个请求的执行链路是否可以被追踪和回放并发模型是否支持异步执行、限流、排队可扩展点能否在 Agent 循环的任意一个环节插入自定义逻辑部署方式是 SaaS 绑定还是有自托管选项之前我在一个金融客户那边做过评估他们最在意的是数据不能出内网所以云平台类的 Runtime 基本被否掉了。最后只能在开源方案里选结合内部私有化部署的模型和知识库做了一个相对轻量的编排引擎。这个案例我印象很深的是团队花了两周时间跑各种 Runtime 的 Demo最后发现最关键的筛选条件不是功能丰富度而是能否方便地接上他们现有的统一登录系统和审计日志系统。我个人的建议是如果团队规模小想快速把项目推进到生产验证可以先选一个成熟的编排框架把注意力放在业务逻辑上但如果是大型组织对数据安全、审计合规有强要求那自研一个轻量编排层或者深度定制开源方案是绕不开的路。3. RAG 管线从“会查资料”到“可信赖的知识服务”RAG 是大多数企业 Agent 的第一站因为企业内部积累的大量文档、知识库、手册不可能靠模型预训练都学进去。但 Demo 级的 RAG 和生产级的 RAG 差距巨大问题主要集中在检索质量、数据新鲜度与权限隔离上。3.1 生产级 RAG 要处理的细节先讲一个最常见的坑嵌入式向量检索不是万能的。你在 Demo 里拿一个 PDF 库切块后用 embedding 模型转向量效果通常不错。但一旦到了生产文档的种类、粒度、关联性都复杂很多单靠向量相似度检索会出现关键词语义漂移的问题。比如用户问“打印机卡纸了怎么办”但在文档里描述这个问题的可能是“纸张无法正常送出”“卡纸故障排除”这类表达。如果只做向量匹配可能召回的片段并不完整需要结合关键词检索来做混合召回。我自己实践下来的一个可行方案是用 BM25 做关键词召回同时用向量召回做语义补充两者结果做一个融合。这个融合不是简单拼接而是要经过 Rerank重排模型打分把真正对该问题有用的片段排在前面。这个流程中每一步都需要自己调参包括召回的数量通常向量召回和关键词召回各取 TOP 50 左右、重排后保留的数量通常 10-15 条。3.2 索引、检索与重排的实操考量在做切块的时候有一个反复迭代的点切得太细语义容易断裂切得太粗向量表达的信息过于混杂检索精度下降。我后来倾向于使用结构感知切分先按 Markdown 标题或 PDF 的章节结构把文档切成一棵章节树再在章节内部按段落切块让每个切块自带上下文路径。这个方案比较前面粗暴的固定 token 切分召回准确率高了不少。还有个容易被忽略的参数是 embedding 模型的选择。企业内部如果以中文文档为主要特别测试中文语义的理解能力。很多英文场景下表现好的 embedding 模型在中文长文档上不一定够用。有一个小技巧拿你自己业务中真实的 100 组相似问题做标注集对比不同 embedding 模型的 Top 5 召回率得到的结论往往比公开榜单更可信。重排这一步我认为在 RAG 里的价值被严重低估了。很多人直接从向量库返回 top-k 然后塞给大模型效果好不好完全看命。接一个 cross-encoder 模型做重排推理耗时一般会增加几十毫秒到几百毫秒但回答质量提升非常明显。做企业项目基本印象是“重排这一步省不了”。3.3 知识新鲜度与权限隔离这个章节是生产 RAG 和企业知识管理结合时的重头戏。文档不是静止的产品手册每季度更新制度文档随时可能调整甚至同一份文档还有多个版本。如果不关注数据新鲜度Agent 就会一本正经地用过期数据误导用户。我在项目里通常设计两种更新路径定时全量更新用于每天或每周从数据源拉取变更实时事件更新用于跟 CMS 或者文件存储的事件通知打通一旦文件变化就触发增量索引。增量索引要处理的细节是切块后如何识别哪些块被修改、删除、新增避免反复重建整个向量库。权限隔离更是 RAG 落地的一个重要关卡。企业内部文档天然具有只有对应角色的人才能看的要求可很多团队的 RAG 架构直接把所有文档切块后放一个向量库检索时完全不区分角色。正确做法是把权限过滤前移到检索阶段要么为每个权限组建独立的文档索引要么在切块元数据里带上可见范围标签在召回后过滤。后者在实践中更常用但对检索质量的影响需要仔细调优因为过滤掉一部分块可能导致最终上下文不足。4. Tools把 Agent 的“手”绑上企业级约束如果说 RAG 是给 Agent 提供知识那 Tools 就是给 Agent 提供行动能力。一个没有工具调用的 Agent 只能“说话”有了 Tools它才能查订单、改状态、发消息。但工具开放得太随意风险也随之而来。4.1 Tool 的 Schema 与可观测性给大模型暴露工具时大家最先关注的是 Function Calling 的 Schema 定义——参数名、类型、描述怎么写。这些细节做过的人都懂描述写得模糊模型就传错参数参数缺省值不设模型就漏传参数。真正到生产后我发现更重要的其实是工具的可观测性和 Schema 治理。你不可能阻止模型偶尔传一个不合理的参数所以工具层要设计好入参校验、异常上报和调用记录。比如某个工具接收订单编号作为参数你在 Schema 里写了“这是 18 位数字”但模型可能传了一个包含字母的字符串进去如果你没有做校验而是直接透传到后台系统就会污染你的交易数据。一个实践中行之有效的做法是为所有工具包一层统一的执行壳在这个壳里处理权限检查、入参清洗、调用日志和错误归一化。这层壳不要绕过去。4.2 权限控制与失败降级权限控制我在需求梳理时通常会分开看用户权限和工具权限。用户权限解决的是“谁能调用这个工具”通常对接企业的 RBAC 系统工具权限解决的是“以什么身份调用这个工具”这背后涉及与第三方系统的集成时用服务账号还是用户身份去做操作。有一个印象深刻的案例在给一个客户做数据查询 Agent 时Agent 需要依据用户问题判断要查哪个部门的报表。因为表结构不同、权限不同我们给 Agent 暴露了一组工具每个工具对应了一个数据域。初期出现的问题非常典型——问“华东区销售情况”Agent 调用了“全国销售明细”的查询工具而不是“华东区报表查询”工具。因为工具描述没有写清楚边界模型存在误调用。之后我们把工具描述改得更具约束性并增加了执行前的规则校验彻底解决这类问题。工具调用失败后的降级逻辑也需要提前设计。工具可能超时、可能返回错误、可能需要二次确认。在 Demo 里这些都不重要模型编一个“工具错误”的回复就行。但生产里想要的效果是明确的失败信息回传给用户或者是自动转给人工客服处理。这里有一个原则不要让模型“强行解释”工具失败的模糊原因宁可把工具返回的原始错误封装后展示给用户也不要用模型润色出一个不知道真假的失败原因。5. Workflow把确定性还给流程Agent 的强项是灵活但在企业场景里灵活的另一面是失控。用户不会每次都把需求表达得清清楚楚而业务处理往往存在相对确定的流程。关键问题是你怎么让 Agent 在确定性的流程里保留必要的智能而不是让它在关键节点上天马行空。5.1 从自由对话到流程编排我一般在项目启动时会和业务方一起梳理一个流程清单哪些环节是刚性节点必须有顺序哪些环节可以并行哪些环节需要人工审批。做客服 Agent 的时候流程可能是用户提问 - 意图识别 - 如果是退款咨询 - 校验订单归属 - 查询退款进度 - 给出结果或转人工。这个流程在 Demo 里可以用一条大 Prompt 让模型自由发挥但到了生产我倾向于用 Workflow 的方式把流程边界定义出来。LangGraph 这类编排框架的价值在于它可以定义一个状态机明确节点的流转条件和路由。模型在其中负责解决节点的内部问题比如从用户对话中提取订单号但由此决定接下来要走哪个节点你要么通过路由规则控制要么给模型设置有限的选择集。这个“有限选择”的设计理念我觉得是 Workflow 的精髓模型不应该在一个开放的空间里自由选择任何一步而应该在预设的轨道上做决策。5.2 人在回路Human-in-the-loop企业场景中很多操作具有高风险属性——发邮件给大客户、修改订单金额、删除数据等。这种操作建议在 Workflow 里强制加一个“人工审批”节点Agent 先完成任务中低风险的前置动作生成行动建议由具体的人点击确认后才执行后面的操作。我记得在一次大促的系统准备过程中业务方提了一个需求客服 Agent 可以直接帮用户申请价格补偿。最初设计的是 Agent 判定符合补偿规则后直接调用优惠券工具。后来安全团队一票否决要求必须有主管审批。于是我们把流程改成了Agent 识别并计算补偿金额 - 生成审批工单 - 推送给主管企业微信 - 主管点击通过 - 系统自动执行。这个链路改动不多但对业务的安全感提升非常大——负责人知道每个自动动作背后有谁能兜底。5.3 实际参考客服场景的混合编排以一个客服工单 Agent 为例看看编排的完整结构入口节点接收用户消息并行做意图识别和实体抽取路由节点根据意图决定走 FAQ 检索、订单查询、售后申请还是人工客服订单查询分支调订单接口取数据然后格式化输出售后申请分支校验订单状态和售后政策如有必要生成审批工单人工兜底当 Agent 置信度低于阈值或者用户明确表达不满时带着上下文转人工这套流程把模型的能力和系统的确定性做了一个很好的平衡。核心逻辑都有挽回余地哪怕模型意图识别错了也能在路由节点被规则纠正回来。6. Governance先合规再智能Governance 是企业 Agent 项目中最容易被拖延、但最后绕不开的环节。如果你们公司有信息安全或法务部门那 Agent 的治理方案肯定会被反复审查。6.1 身份与权限Agent 的身份体系设计与传统员工账号体系不太一样它通常需要对接原有身份系统的同时叠加一层独立的数据权限控制。我做过一个内部知识问答 Agent员工的登录沿用企业微信扫码系统拿到员工身份后需要判断该员工属于哪些部门、职级如何、是否有权限访问某些带密级的文档然后把这个权限上下文传给 RAG 检索层做过滤。这里的坑在于企业在设计文档管理时往往存在“知识库目录权限”与“具体文档内容权限”不一致的情况。你在做 Agent 权限映射的时候要跟着文档走而不是跟着目录走否则会通过目录权限把一份实际上没有阅读权限的文档检索出来。这个问题我们在上线前的一次安全测试中被抓到加班改了两天才修完。6.2 审计追踪企业 Agent 通常会采用“所有交互都可以追溯”的设计原则。用户问了什么、模型看到了哪些上下文、调用过哪些工具、工具返回了什么、最终回复了什么全部落到日志系统。一旦发生争议可以完整回放整个决策过程。这不仅是合规要求对排查线上问题也格外重要。落审计日志的时候要特别关注“模型读了什么”和“用户实际看到什么”之间的差异。在一次事故排查中用户投诉 Agent 泄露了他不该看到的数据后台日志完整记录了用户问了什么、工具返回了什么、最终回复了什么事实链非常完整能准确定位到是知识库目录权限配置错误导致某几篇文档被错误地设置为可检索。如果没有完整的 trace这类问题基本上要靠猜。6.3 内容安全与模型风险管控现在企业内部对模型输出的内容安全越来越重视主要有几个层面输入侧检测用户是否在尝试注入攻击提示注入可以通过在系统提示词中加防护指令、也可以上专门的检测模型输出侧对模型生成内容做 PII个人敏感信息检测、机密信息检测避免 Agent 把不该带出内网的信息输出行为侧对 Agent 的异常行为进行监控比如单次请求调用工具超过一定次数、触发某个敏感工具频率异常等这些管控能力越早考虑、后续返工越少。你可以在 Demo 阶段不管这些但如果生产第一阶段就遇到安全事故项目可能整个停摆。7. Evaluation没有评测就没有迭代在企业内部做 Agent 项目如果没有一套可靠的评测体系后期基本寸步难行。原因在于模型在快速迭代、Prompt 在调整、知识库在变化、工具也在升级你怎么知道某一次变更到底变好了还是变坏了没有评估体系只能凭感觉拍脑袋。7.1 评测集怎么来评测集的建设一定要贴近业务而不是简单拿几个通用题测试。我和业务方协作时的通常做法是从真实使用日志里抽取一批有代表性的 request 和期望结果组成一个评测集。规模不需要太大但覆盖面要广。我在一个项目中把评测集分成了几层单轮问答层覆盖常见业务问题验证 RAG 召回与生成的基础能力多轮对话层覆盖需要多轮对话理解才能完成的场景验证上下文管理能力工具调用层覆盖不同的工具调用路径包括正常流程和异常分支流程端到端层覆盖整个 Workflow 的全链路验证节点编排的正确性每一层又区分语义准确、内容完整性、格式规范等多个打分维度由业务方参与标注标准答案。7.2 离线评估与线上可观测离线评测要快、要可重复。每改一个 Prompt 或者换一个模型都要能拉起一遍评测跑完之后看到总体指标变化。现在很多团队会用 LLM-as-a-Judge 的方式来打分——用一个大模型来评判 Agent 的输出质量。这个方式有参考价值但要注意 Judge 模型本身也有幻觉和偏见需要定期抽样人工复核。还有一个操作细节是要做回归集的版本管理。因为你无法保证新加的场景不会让旧场景变差所以评测集要分层管理每一次模型或流程变更后全部回归一遍。我见过团队因加了工具调用场景就忽略了对 FAQ 场景的回归上线后发现原来的问答能力明显下降这类问题通常就是回归不及时导致的。线上可观测是评估体系延伸到生产的关键环节。用 LLM 的调用时延需要按阶段拆分比如从接收用户请求到首 token 返回的耗时中间 RAG 检索花了多少毫秒重排花多少毫秒模型生成花费多少毫秒工具调用花了多少毫秒。用户实际看到的效果只是一个方面单链路的数据能帮你快速定位性能瓶颈。对于回复质量线上用用户点赞、点踩、复制行为来采集隐式反馈然后把负反馈数据积累下来、定期补充进评测集里重跑不断迭代评测集的能力覆盖范围这是我用过的最有效的迭代闭环。7.3 评测指标怎么定我见过很多团队在做评测指标时只盯着“回答正确率”这个指标在企业场景里往往难以覆盖实际效果。更应该关注几个细分指标任务成功率端到端完成业务目标的比率、步骤成功率单节点或子任务完成的比率、每任务工具调用次数判断是否绕了远路、无效调用率调用了工具但没能使用返回结果以及平均处理时长。这几个指标能帮你快速定位问题方向步骤成功率低往往是意图识别或实体抽取的问题无效调用率高往往是工具定义不对齐或 RAG 召回质量差平均处理时长过高可能是链路太长或者模型推理太慢。评测不是拿来做 PPT 的是为了指导下一步优化目标的。8. 落地路线图与常见坑位回顾如果团队正准备把 Agent 推上生产我建议按阶段规划落地路径不要妄想一步到位。第一个阶段需要先跑通最小闭环建议只选 1-2 个高频场景把 Runtime 稳定跑起来打通 RAG 基础链路定义好 3-5 个工具使用线上真实流量做小范围灰度。这个阶段先不需要追求完美的评测。第二个阶段要把确定性补齐把涉及多步操作的流程用 Workflow 固化加入必要的人工审批节点把权限控制、审计日志等基础能力补全同时开始积累评测集并引入离线评测。第三个阶段要扩展并建立反馈闭环在更多场景中复用底座的通用能力引入线上可观测机制用真实反馈持续完善评测集和 Prompt。推荐先不要碰那些高风险、强合规的金融、医疗类场景把最日常的业务跑顺再逐步扩展。回头看在多个 Agent 项目中踩过的坑大多集中在几个地方高估模型的理解能力在路由和关键决策处没加规则兜底低估工具治理的复杂性没做参校验和失败降级忽略权限与知识库的联动导致越权检索上线后没有评测集和可观测能力迭代只能靠感觉写在最后从我自己的体感来看企业 Agent 的落地难点从来不是“模型不够聪明”而是“工程不够扎实”。Agent Runtime、RAG、Tools、Workflow 这四层决定了 Agent 能做到什么Governance 决定了它能不能被信任Evaluation 决定了它能不能持续演进。有个判断方法我可以分享翻开一个团队演示 Demo 时的流程图再对照它真正生产环境运行的链路图看差异有多大。差异越大说明越多的复杂度和风险被埋在了“演示正常”的表象之下。把这件事理清楚企业 Agent 的高速落地才能真正开始。