项目刚上生产那几天我每天打开监控面板的心情都很复杂。模型调用那一侧的成功率曲线跑得很漂亮99.7%几乎无懈可击。但业务那边过来问的问题十个里有八个和模型推理一点关系都没有——为什么 OA 里的审批单状态查不到为什么 ERP 传过去的物料编码老是报格式错误为什么 Agent 用着用着就被踢下线还得重新登录一次这个项目就是我们团队做的“FDE MCP Blade”简单说是一个把企业 OA、ERP 等存量系统接入 AI Agent 的 MCP 适配层。今天想把这些踩过的坑、调过的参、重构过的架构完整记录下来。这篇文章适合那些正准备把 Agent 推上生产、或者正在做企业级落地的开发者和架构师。如果你以为难点在模型调优那看完这篇可能会改变想法。1. 项目背景与核心问题Agent 上生产真正的卡点是接入1.1 项目要解决的实际问题企业内部系统其实没有想象中那么现代化。我们接的 OA 系统承载着审批流、公文流转、行政申请ERP 系统则管着进销存、财务凭证、生产计划和物料主数据。业务方提出的诉求非常朴素——希望让 Agent 能直接查审批进度、查库存、创建采购申请甚至主动提醒业务人员哪些单据卡在某个节点超过三天了。听起来不复杂但真正开工才发现问题藏在深处OA 的审批单状态字段在不同模块里居然叫法不一致ERP 的物料编码在采购模块和库存模块的校验规则竟有细微差别更别提有些老系统的接口文档还停留在好几年前。Agent 调用这些系统的每一项能力背后都是一整套业务逻辑和数据口径的对齐工作。1.2 模型不是瓶颈接口才是我当时在团队内部反复强调一个观点大模型的能力已经溢出真正制约 Agent 落地的是它和外部世界之间的通路。你让模型写一首诗、总结一份文档、生成一段代码这些能力在商用模型里已经足够稳定。但你要让它查一下“某张采购订单当前处在哪个审批节点”它需要先知道调哪个接口、传什么参数、怎么解析结果、遇到错误怎么处理。模型侧的准备工作反而是最顺利的。Function Calling 也好Tool Use 也好只要给模型清晰的工具定义和参数说明它基本能正确选择调用。真正的困难在于接口荒很多老系统根本没有开放 API或者只提供了几个残缺不全的接口连最基本的字段说明都对不上。数据结构不标准同一个业务对象在不同系统里名字不同、层级不同、状态枚举不同Agent 拿到数据后经常“看不懂”。权限体系复杂Agent 以什么身份操作业务系统能不能越权每一步操作怎么留审计日志这些在传统系统里都是硬约束。网络与部署环境隔离生产环境中 OA、ERP 常常位于不同网段Agent 服务部署在容器平台中间还隔着一层网络安全策略。后来的经验总结成一句话Agent 上生产本质上是“模型能力 × 系统集成能力 × 稳定性”三者的乘积而系统集成恰恰是变量最大的那部分。2. 为什么选 MCP给 Agent 装一个标准插座2.1 MCP 是什么从“一对一对接”到“统一协议”MCPModel Context Protocol的出现正好解决了我在项目早期最头疼的碎片化问题。可以把它类比成 Agent 界的 USB-C 接口以前每个硬件厂商都有自己的充电口出门得带一堆线USB-C 统一之后一根线走天下。MCP 做的就是这个事——它定义了一套标准协议让 Agent 能够通过统一的方式发现、调用外部系统提供的工具和数据资源。MCP Server 在协议层提供三类核心能力Tools可执行的业务函数Agent 根据用户意图选择调用比如“查询审批单”“创建采购订单”。Resources可读取的数据资源用来向模型注入上下文比如把一份业务报表的内容直接塞给模型做分析。Prompts预设的提示模板用来规范人和模型协作的固定套路比如“审批异常排查流程”的引导话术。这三个概念是理解 MCP 的关键。你不需要把每个系统都做成独立协议对接只需要让每个系统对应一个 MCP ServerAgent 通过 MCP Client 去连接它们。2.2 对比传统 API 网关方案MCP 的价值与代价在做技术选型的时候团队内部也讨论过要不要沿用传统路线——给每个系统单独写适配器统一挂到 API 网关后面再让 Agent 去调网关接口。这条路在工程上完全可行但它有几个绕不开的弊端。传统方案的最大问题是“胶水代码”太多。每接入一个新系统就得在 Agent 侧重新写一套调用逻辑、错误处理、重试策略和参数映射。系统之间各自为政Agent 的代码慢慢变成一个大杂烩。更麻烦的是业务接口的变更需要同步修改 Agent 侧逻辑两边经常对不上版本。MCP 方案的思路是把“接入协议”标准化。每个系统对应一个独立的 MCP ServerAgent 只需要通过标准协议去发现和调用这些 Server 暴露出来的工具。新增一个系统就是新增一个 ServerAgent 核心代码几乎不用动。当然它也不是银弹。MCP 解决的是“协议统一”不解决“接口缺失”和“数据质量”这两个硬骨头你照样得啃。但在一个多系统的企业环境里MCP 至少把集成工作的边际成本降了下来也把团队并行开发的效率提了上去。3. FDE MCP Blade 的整体设计与架构拆解3.1 FDE MCP Blade 的定位与命名由来“FDE”是前端开发工程师Front-End Developer的缩写代表这个项目的牵头视角“Blade”是“刀片”的意思用来比喻一组轻量、可插拔、可独立替换的适配器模块。整套方案的设计理念就是每个业务系统对应一个独立的“刀片”插在同一个 MCP 底座上互不干扰。这个命名的背后有一个实际考量。项目初期团队尝试把 OA、ERP 的适配逻辑写在一个大的 MCP Server 里结果不到两周就发现不行——OA 那边改一个字段映射要重新发布整个服务ERP 那边升级一次 SDKOA 的线程池也跟着重启。后来我们干脆拆成独立进程每个 Blade 只负责一个系统的接入发布、扩缩容、故障隔离都各自独立。这个决定后来被证明是整个架构里最正确的一个。3.2 分层架构接入、协议、安全、运维四层整体架构从下往上分为四层每层职责单一互不越界。业务接入层是直接和 OA、ERP 打交道的部分。它负责处理各系统的 SDK、REST API、数据库只读视图甚至在某些接口缺失的情况下通过定时同步的方式把数据搬到中间库。这一层解决的是“能不能拿到数据、能不能执行操作”的问题每个系统内部的复杂细节都封装在这里不外泄。MCP 协议层在上面对接层的每个能力点做了协议封装。一个查询库存的能力被定义成一个 Tool一个审批单详情的数据视图被定义成一个 Resource。Tool 的入参、出参、错误码都按 MCP 规范声明清楚让模型能准确理解每个工具的用途。协议层不感知具体的业务系统它只做翻译和暴露。安全统一层是生产环境绝对省不掉的一层。所有 Agent 的操作请求都必须经过身份认证、权限校验、数据脱敏和审计日志记录。这一层由统一的服务账号体系支撑Agent 不以任何个人账号身份操作业务系统而是使用独立的服务账号权限范围严格限制在业务方授权的最小集。运维支撑层解决的是稳定性问题。配置中心统一管理各 Blade 的连接参数限流器保护下游系统不被高并发压垮熔断器在 OA 接口异常时快速失败监控面板实时展示每个 Tool 的调用量和错误率。生产环境没有这一层出问题的时候就是两眼一抹黑。3.3 关键设计决策独立进程、Tool 命名规范和确认机制有两个设计决策值得展开因为它们直接影响生产环境的稳定性和 Agent 的行为准确性。第一个决策是每个系统独立一个 MCP Server 进程。之前提到过的“刀片”思想落实到这里就是 OA 一个 Deployment、ERP 一个 Deployment、后续接入的 CRM 再一个 Deployment。好处很直观某个 Blade 出问题不会拖垮其他系统新版 Blade 发布时可以做金丝雀验证。代价是机器资源多了但对于企业级系统来说这点成本完全可接受。第二个决策是关于 Tool 命名的规范化和写操作的确认机制。Tool 命名要像函数命名一样严谨查询类操作统一用query_或get_前缀写操作统一用execute_或submit_前缀。这种命名不是为了好看而是为了减少模型的误判——模型看到get_就知道这是只读操作看到execute_就会更谨慎。更关键的是所有写操作前加了一道“确认”屏障。Agent 在执行创建订单、提交审批这类不可逆操作之前必须先调用一个预检工具确认参数并在回复中提供操作摘要给用户确认。这个机制非常朴素但有效避免了模型在上下文理解偏差时直接产生业务数据。4. 核心开发过程OA/ERP 接入的实操实录4.1 打通 OA认证、表单、审批流的三重考验OA 系统的接入是第一个硬仗。我们面对的是一套运行多年的办公系统对接过程中遇到了三个典型的深坑。认证是第一个坑。OA 系统的登录态管理非常传统基于 Cookie 和 Token 的服务端会话还叠加了一层 CSRF 防护。Agent 进程内保持会话和在浏览器里操作是完全两回事并发场景下 Token 刷新容易出现竞态长时间运行后会话静默过期Agent 还在以为自己有权限。我们的解决办法是给 Agent 申请独立的服务账号不使用任何个人账号避免权限边界问题。同时封装了一层会话管理器统一处理登录、续期、重连底层细节对 Agent 完全透明。表单和自定义控件是第二个坑。OA 里大量使用自定义表单和自定义控件让人头痛的是界面展示的值和系统内部存储的值经常不一致。比如说日期控件在界面上显示“2025-03-18”接口返回的是毫秒时间戳下拉选择框显示的是“已通过”接口存的是数字编码 3。如果我们直接把接口数据抛给模型模型很可能按字面理解给出错误判断。后来我们在适配层做了严格的字段清洗把所有枚举值翻译成业务语言并且明确标注每个字段的口径Agent 拿到的数据必须是“人话”。会签和非会签是第三个坑。审批流里存在会签、非会签、串行、并行、或签、与签等一堆业务概念。Agent 查询任务列表时如果不区分这些状态会给出完全错误的结论。比如一个会签节点有 5 个审批人其中 3 人已通过系统状态显示“审批中”Agent 如果只简单读状态可能以为整个流程卡住了实际上只是等剩余 2 人。我们在 Tool 的描述里把类似场景的语义写清楚同时在返回数据中附加一个“业务解释”字段让模型理解当前状态的准确含义。4.2 打通 ERP主数据、事务、幂等的硬骨头ERP 系统的接入难在另一个维度它对数据的准确性、一致性要求极高容错率极低。主数据的层级和理解是最先遇到的障碍。ERP 里光是物料相关字段就有编码、名称、规格、计量单位、默认仓库、采购价格、销售价格等一大串而且不同模块对同一物料的叫法经常不一样。采购模块说“物料编码”库存模块说“料品编码”财务模块还有一套“存货编码”。Agent 要准确查询不能只看一个表必须把主数据映射关系建立清楚否则查出来的结果可能张冠李戴。事务一致性是第二个难题。ERP 创建一个采购订单往往不是一次接口调用就能完成的事情。从创建订单头、添加行项目、库存预留校验再到生成财务凭证整条链路跨了多个接口。Agent 两次调用之间如果出现网络抖动就可能出现“订单头创建成功但行项目缺失”这种尴尬状态。我们的处理方式是把多步骤业务封装成一个“业务动作”在 MCP Server 内部统一调度减少 Agent 跨多次调用的风险。幂等性是第三个关键点。生产环境里网络重试在所难免但如果某个创建订单的接口被重试了两次后果就是业务数据重复。我们为每个写操作引入了一个幂等键机制Agent 发起创建类操作时携带一个唯一的 requestId服务端根据这个 ID 判断请求是否已被处理过如果处理过就直接返回原有结果不再创建新数据。这样即使 Agent 因为超时重试业务侧也不会产生脏数据。4.3 MCP Server 的 Tool 设计细节MCP Server 实现的代码层面我整理几个可以直接复用的经验。Tool 的 schema 声明一定要严谨。我这里说的严谨不是格式合法而是每个参数都要写清楚用途、取值范围和常见错误示例。模型不是人它不会“猜”参数含义schema 写得不明确它就会在调用时犹豫、试错、甚至编造参数。我们把物料编码参数描述写成“ERP 系统中的物料编码字符串类型长度 20 位以内例如 MTL-2025-001”效果立竿见影错误调用率明显下降。超时设置必须分层。MCP Server 对外的连接超时不能太短因为 Agent 在思考;但同时内部的业务接口超时要设得短一些避免把下游系统拖垮。我们把 MCP 层的超时设为 60 秒业务接口超时控制在 10 秒以内再配合异步任务机制长耗时操作返回任务 IDAgent 轮询任务状态。这个折中方案兼顾了用户体验和系统保护。认证密钥不能出现在代码里。所有 Token、密码、密钥统一放在 Secret 管理服务中进程启动时注入环境变量。这一点我踩过坑——早期为了调试方便把密钥写在配置文件里结果代码库被扫描工具告警差点出事。生产环境必须走正规的密钥管理。4.4 生产环境部署到 K8s 的配置实践部署到 K8s 时我们遵循了几个基本原则。每个 Blade 对应一个 Deployment 和一个 Service。Deployment 负责 Pod 副本管理Service 负责 MCP Server 的地址发现。ConfigMap 存放非敏感配置比如接口地址、超时参数、日志级别Secret 单独存放所有敏感信息。这样做的好处是配置变更不用重新构建镜像改 ConfigMap 后滚动重启即可。资源限制必须设置。Requests 和 Limits 不能空着尤其是内存。MCP Server 处理大响应时内存曲线会陡增如果没设硬限制出现过 Pod 被 OOM Kill然后整个 Blade 无响应的情况。我们的实践是内存 Request 512MiB、Limit 1GiBCPU 按实际压测数据调。就绪探针要处理 MCP 握手。K8s 的存活探针和就绪探针我们都配了但就绪探针的检查逻辑不是简单地返回 200而是做一次内部依赖探测——确认 OA/ERP 的连接池已经初始化完成。否则 Agent 流量打到还没完成握手的实例上会白白占一批超时错误。5. 生产环境常见故障与排查实录5.1 会话超时与登录态失效的排查上线第一周报得最多的错误就是“工具调用似乎执行成功但返回结果异常”。后来发现很多情况下不是接口挂了而是 OA 的登录态在运行了几个小时后静默过期接口返回的不是业务数据而是一个 HTML 登录页面。Agent 拿到这个页面把它当正常回复内容处理又给用户复述了一遍看起来就像“Agent 傻了”。这个问题的根因是MCP Server 把会话管理做得太透明没有把认证异常和业务异常区分开。我们后面在适配层加了错误分类逻辑认证失效返回 401 类错误码业务逻辑异常返回业务错误码模型根据错误码类型决定是重试还是升级给人工干预。同时增加了会话自动续期的定时任务把过期窗口尽可能缩小。5.2 幂等性与重复提交问题的实战记录有一次业务方反馈某条采购申请被创建了两次单据号完全一样。排查下来发现是 Agent 在第一次调用时遇到了网络超时但服务端实际已经处理成功而 Agent 侧收到了超时信号就自动重试了一次。又因为没有幂等机制服务端再次创建了一条相同的记录。这个事件之后我们才把幂等键机制引入所有写操作。无论 Agent 调用多少次同一 requestId 只允许对应一条业务记录。排查问题时建议在日志中把 requestId、业务单据号、Agent 内部的调用链 TraceID 三者串联起来哪一个环节断了通过日志就能一眼定位。5.3 生产环境 K8s 常见故障网络策略、DNS、配置漂移K8s 环境本身也有一些高频故障值得单独列出来。网络策略拦截是第一个。MCP Server 和 OA/ERP 系统之间经常跨 namespace 通信如果 NetworkPolicy 配置遗漏了某个网段的放行规则就会出现“测试环境好好的上了生产就连不上”的诡异问题。排查套路是先看 DNS 解析是否正常再查连通性最后核对网络策略不要上来就怀疑代码。镜像 tag 漂移是第二个。运维同学使用的镜像 tag会存在两个环境拉取到不同版本的可能导致行为和预期不一致。我们的规范是生产环境一律使用完整的镜像摘要或精确的版本号不用 latest。配置漂移是第三个。ConfigMap 改了但 Pod 没有重新加载是最容易忽略的问题。我们后面引入了配置热更新机制文件变化后自动触发重载并在监控面板上标记配置版本号。下面整理一份问题速查表方便大家以后排查时直接对照。现象可能原因排查思路Agent 报工具调用超时下游接口慢 / MCP 超时设置过短检查接口调用耗时分布调整分层超时配置返回结果清一色是登录页OA/ERP 会话过期查看认证状态码增加会话自动续期和错误分类重复创建业务单据缺少幂等机制引入 requestId 幂等键日志串联调用链服务在 K8s 中时而通时而不通DNS / 网络策略问题依次检查 DNS 解析、连通性、NetworkPolicyPod 频繁重启内存告警Limits 未设置或超大响应调整资源限制对流式响应做截断Agent 调用工具参数错误schema 描述不清晰重写 Tool 参数描述补充取值示例和约束5.4 性能与限流老系统被 Agent 高并发打爆最后说一个容易被忽略但极其重要的问题Agent 的并发行为和老系统的处理能力完全不是一个量级。Agent 在多轮对话中可能同时对同一个接口发起多次调用而老系统设计时的预期是“一个用户几秒钟操作一次”。上线第一天我们就发现某 ERP 的查询接口被 Agent 在 10 分钟内调了上千次直接把数据库连接池耗尽。解决方案是双层的。进程内限流每个 MCP Server 根据下游系统的实际承受能力设置每分钟最大调用次数超出部分排队或快速失败。再加上业务侧缓存把频繁读取的只读数据物料列表、审批状态枚举缓存 30 秒到 5 分钟不等大幅减少对下游系统的压力。这在业务侧完全无感知因为数据实时性要求没那么高。上了缓存之后下游系统的负载直接降了一个数量级Agent 的响应速度反而更快了。还有一个细节值得分享写操作尽量做串行化处理。同一个业务对象的写操作如果并发执行即使有幂等键也可能出现状态覆盖问题。我们在 Blade 内部对写操作按业务对象加锁让同一订单的操作串行执行从根源上避免这这类并发冲突。收尾一些真实的体会在整个项目从设计到上线的过程中我最深的体会是“模型只是入口系统集成才是主场”。那些真正让业务方对 Agent 建立信任的时刻不是模型回答得有多机智而是它第一次稳定地查询出正确库存、正确审批状态、正确订单信息。Agent 落地的本质是让 AI 变得可靠、可控、可审计——这背后是无数接口对齐、异常处理和架构取舍的积累。最后分享一个实用的小技巧在 Agent 正式上线前一定要做一轮“系统接口压测”。不是测模型而是用脚本模拟 Agent 高频调用同一批业务接口的场景看看老系统的连接池、数据库、中间件各自能扛多高并发。很多时候Agent 不是被模型拖垮的而是被自家老系统的脆弱环节绊倒的。提前把这些问题暴露出来比上线后面对业务投诉要舒服得多。如果后续有机会我打算把“刀片”家族继续扩展把 CRM、MES、报表平台都接入进来同时完善人工确认机制和审计能力。企业级 Agent 的路还很宽系统接入的深度决定了 Agent 能走多远。希望这篇记录能给正在做类似项目的你提供一些参照少踩几个坑。