从去年开始，我陆续参与了几个企业级 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 的高速落地才能真正开始。
