1. 从Demo到生产：Agent落地最容易被低估的那道坎
模型选型、Prompt调优、工具链编排，这些话题在过去一年里被反复讨论，几乎每一个做Agent的团队都能说出一套自己的方法论。但真正把Agent推到生产环境的人会发现，最耗时间、最容易翻车、最不像"AI问题"的环节，恰恰是那些看起来最传统的部分——把OA、ERP这些企业里跑了十几年的老系统接进来。
我所在的团队做FDE（Forward Deployed Engineer，前沿部署工程师）相关的工作，过去大半年时间一直在处理Agent与企业内部系统的对接问题。我们踩过的坑包括但不限于：泛微OA的会签节点在API层面根本没有暴露、致远OA的自定义控件需要通过特定的扩展机制才能被外部调用、ERP的进销存接口在手机版和PC版返回的数据结构不一致、Oracle JDeveloper 10g时代留下的OA Extension接口文档早已失传。这些问题没有一个能靠换个更强的模型解决，它们全部指向同一个核心矛盾：Agent的"大脑"再聪明，也需要有手有脚去操作真实的业务系统。
MCP（Model Context Protocol）的出现，本质上是在解决这个"手脚"的问题。它定义了一套标准化的协议，让Agent能够以统一的方式发现和调用外部工具。但协议标准只是起点，真正的工作量在于：如何把OA、ERP这些系统的接口封装成MCP Server，如何处理认证、权限、数据格式转换，如何保证在生产环境下的稳定性和可观测性。这篇文章不讲模型原理，也不讲Agent框架的编排逻辑，只聚焦一件事：当你决定把Agent接入企业现有的OA和ERP系统时，你需要面对什么、准备什么、避开什么。
无论你是刚开始做Agent项目的开发者，还是正在负责企业AI落地的FDE，这篇文章里的经验都来自真实的生产环境，不是实验室里的Demo。我会从架构设计、协议选型、具体系统的对接细节、生产环境的坑四个维度展开，尽量把每个决策背后的"为什么"讲清楚。
2. MCP协议到底解决了什么问题，以及它没解决什么
2.1 没有MCP之前，Agent是怎么接外部系统的
在MCP出现之前，让Agent调用外部系统的方式基本有三种。第一种是硬编码Function Calling，每个系统的每个接口都写一个函数定义，塞进模型的tools参数里。这种方式在接口数量少的时候还能用，一旦超过二三十个，光是维护这些函数定义就是噩梦，而且每次调用都要把全部定义塞进上下文，token消耗巨大。
第二种是写一个统一的API网关，把所有外部系统封装成RESTful接口，然后Agent通过HTTP调用。这种方式比硬编码好一些，但问题在于每个团队封装的接口风格不一样，参数命名、错误码、认证方式各不相同，Agent需要针对每个接口做适配。更麻烦的是，当接口数量增长时，Agent如何知道在什么场景下该调用哪个接口，这个问题并没有被解决。
第三种是RPA式的方案，让Agent模拟人在UI上操作。这种方式理论上可以绕过所有接口限制，但稳定性极差，页面改一个按钮位置就可能全盘失效，而且执行速度慢，不适合生产环境。
MCP的思路不一样。它把每个外部系统封装成一个独立的MCP Server，Server负责声明自己提供哪些工具（Tools）、哪些资源（Resources）、哪些提示模板（Prompts）。Agent通过MCP Client连接到Server，动态发现可用的工具，然后根据任务需要调用。这个架构的关键优势在于：工具的定义和Agent的推理是解耦的，Agent不需要在启动时就加载所有工具定义，而是按需发现、按需调用。
2.2 MCP的传输层选择：stdio还是SSE
MCP协议支持多种传输方式，最常用的是stdio和SSE（Server-Sent Events）。stdio适合本地进程间通信，MCP Server作为一个子进程启动，通过标准输入输出和Client交换消息。这种方式简单、延迟低，但缺点是Server必须和Client在同一台机器上，无法跨网络部署。
SSE方式则允许MCP Server部署在远程服务器上，Client通过HTTP长连接接收Server推送的事件。这种方式适合企业环境，因为OA、ERP系统通常部署在内网服务器上，Agent可能运行在另一台机器上。但SSE方式需要处理认证、连接保持、断线重连等问题，复杂度明显更高。
在实际项目中，我们的选择是：对于部署在同一个Kubernetes集群内的服务，用stdio方式通过Sidecar容器通信；对于跨网络访问的OA、ERP系统，用SSE方式，并在MCP Server前面加一层API Gateway处理认证和限流。这个决策的依据是：stdio的延迟在毫秒级，适合高频调用的场景；SSE的延迟在几十毫秒到几百毫秒之间，适合低频但需要跨网络的场景。
注意：SSE方式下，MCP Server需要维护长连接，如果企业防火墙对长连接有超时限制，需要在Server端实现心跳机制，否则连接会被静默断开，Agent端表现为调用超时但没有任何错误日志。
2.3 MCP没有解决的那些问题
MCP解决了工具发现和调用的标准化问题，但它没有解决以下这些问题，而这些恰恰是生产环境中最耗时间的部分。
第一，认证和授权。MCP协议本身不定义认证机制，你需要自己决定MCP Server如何验证Client的身份，以及如何控制Agent能访问哪些数据。在OA系统中，不同角色的用户能看到的表单、能审批的节点是完全不同的，Agent以什么身份调用接口，直接决定了它能做什么。
第二，数据格式转换。OA和ERP系统返回的数据格式往往是嵌套很深的JSON或者XML，字段命名可能是拼音缩写或者内部编码。Agent需要的是语义清晰的输入，所以MCP Server需要做一层数据清洗和转换，把原始数据映射成Agent能理解的格式。
第三，错误处理和重试。企业系统的接口经常返回一些模糊的错误信息，比如"操作失败，请联系管理员"。MCP Server需要把这些错误翻译成Agent能理解的语义，比如"当前用户没有权限审批该节点"或者"该表单已被其他人锁定"。
第四，幂等性和事务。Agent可能会重复调用同一个接口，比如网络超时后重试。如果接口不是幂等的，就会产生重复数据。MCP Server需要实现幂等性保证，或者提供补偿机制。
3. OA系统对接：泛微、致远、蓝凌的差异化处理
3.1 泛微OA的接口体系与Agent适配
泛微OA在国内企业市场的占有率很高，它的接口体系经历了多个版本的演进。E10版本之前，主要依赖SOAP风格的WebService接口；E10之后，逐渐转向RESTful API。但实际项目中你会发现，很多企业用的还是老版本，或者虽然升级了E10但只购买了部分模块的API权限。
泛微OA的会签和非会签节点在API层面的处理逻辑完全不同。会签节点需要收集所有参与人的审批意见，API返回的是一个数组，每个元素包含审批人、审批时间、审批意见、审批结果。非会签节点则只返回最后一个审批人的信息。如果你的Agent需要判断一个流程是否已经完成，必须区分这两种情况，否则会误判。
泛微OA的建模引擎是另一个需要重点关注的部分。很多企业用建模引擎搭建了自定义的业务模块，这些模块的接口不在标准API文档里，需要通过建模引擎的元数据接口动态获取。我们的做法是：在MCP Server启动时，先调用建模引擎的元数据接口，获取所有可用模块的字段定义和操作权限，然后动态生成对应的Tool定义。这样当企业新增或修改建模模块时，MCP Server不需要重新部署，只需要重新加载元数据即可。
泛微OA E10的初始密码问题也值得提一句。很多企业在部署后没有修改默认管理员密码，这在生产环境中是严重的安全隐患。我们的MCP Server在连接OA时，会强制要求使用独立的服务账号，而不是管理员账号，并且该账号的权限被限制在必要的范围内。
3.2 致远OA自定义控件的MCP封装
致远OA的自定义控件机制允许企业扩展表单的输入方式，比如增加一个下拉树、一个关联查询框、一个附件上传组件。这些控件在浏览器端通过JavaScript渲染，但在API层面，它们的数据提交格式和标准控件不一样。
我们遇到的一个典型问题是：致远OA的自定义控件在提交表单时，会把控件的值序列化成一个特定的JSON结构，而不是简单的字符串。如果MCP Server直接把这个JSON结构传给Agent，Agent很难理解。我们的解决方案是在MCP Server中增加一个转换层，把自定义控件的值反序列化成人类可读的格式，比如把{"type":"tree","value":"001.002.003","text":"研发部/后端组/平台小组"}转换成"研发部/后端组/平台小组"。
致远OA的另一个坑是它的附件上传接口。标准API只支持上传单个文件，而且文件大小有限制。如果Agent需要上传多个附件，需要循环调用上传接口，每次上传后获取一个文件ID，最后在提交表单时把这些ID关联起来。这个过程如果中间某一步失败，需要回滚已上传的文件，否则会产生垃圾数据。
3.3 蓝凌OA的管理员培训与权限模型
蓝凌OA的权限模型比泛微和致远更复杂，它支持基于组织架构、角色、岗位、群组的多维度权限控制。这意味着同一个接口，不同用户调用时返回的数据范围可能完全不同。Agent在设计时需要考虑：它是以哪个用户的身份调用接口？这个用户能看到哪些数据？
蓝凌OA的管理员培训中通常会强调"最小权限原则"，但在实际配置中，很多企业为了方便，会给服务账号过大的权限。我们的做法是：为Agent创建一个专用的服务账号，该账号只被授予必要的菜单权限和数据权限，并且定期审计该账号的调用日志，发现异常调用及时告警。
蓝凌OA还有一个特点是它的流程引擎支持非常复杂的条件分支和并行网关。Agent在发起流程时，需要根据业务规则选择正确的流程模板和分支条件。我们的MCP Server中内置了一个流程路由表，根据表单类型和关键字段的值，自动选择对应的流程模板。这个路由表可以通过配置文件动态更新，不需要修改代码。
4. ERP对接：进销存、财务、供应链的接口陷阱
4.1 ERP接口的版本碎片化问题
ERP系统的接口版本碎片化比OA更严重。同一个ERP产品，不同客户用的版本可能相差好几年，接口的URL、参数名、返回格式都可能不一样。更麻烦的是，很多ERP的接口文档不完整，或者文档和实际行为不一致。
我们的应对策略是：在MCP Server中实现一个适配层，把不同版本的ERP接口统一成一套内部标准接口。适配层通过配置文件区分版本，每个版本对应一个适配器。当接入新客户时，只需要确认ERP版本，选择对应的适配器即可。如果遇到文档中没有描述的接口行为，通过抓包或者查阅数据库存储过程来确认实际逻辑。
ERP进销存模块的手机版和PC版接口差异也是一个常见问题。手机版接口通常做了简化，返回的字段更少，分页逻辑也不一样。如果Agent需要获取完整的库存信息，必须调用PC版接口。但PC版接口可能不支持移动端认证方式，需要单独处理。
4.2 财务模块的幂等性与对账逻辑
ERP财务模块的接口对幂等性要求极高。一张凭证如果被重复录入，会导致账目不平，后续对账非常麻烦。我们的MCP Server在调用财务接口时，会先生成一个唯一的业务流水号，把这个流水号作为幂等键传给ERP。ERP端如果发现该流水号已经处理过，会直接返回之前的结果，不会重复记账。
对账逻辑是另一个需要特别注意的地方。Agent在查询财务数据时，可能会同时调用多个接口获取不同维度的数据，比如总账、明细账、辅助核算。这些接口返回的数据在时间戳和金额精度上可能不一致，需要MCP Server做一致性校验。我们的做法是：在MCP Server中实现一个对账检查工具，Agent在完成数据查询后，可以调用这个工具验证数据的一致性，如果发现不一致，会提示Agent重新查询或者人工介入。
4.3 供应链模块的并发冲突处理
供应链模块的库存扣减、订单分配等操作存在并发冲突。多个Agent或者Agent与人工同时操作同一批库存时，如果没有正确的锁机制，会导致超卖或者库存数据错误。
我们的MCP Server在调用供应链接口时，会先获取一个分布式锁，锁的粒度是库存SKU级别。获取锁成功后，先查询当前库存，确认足够后再执行扣减，最后释放锁。如果获取锁失败，会等待一段时间后重试，重试次数超过阈值后返回错误给Agent，由Agent决定是等待还是放弃。
这个锁机制需要在ERP端有对应的支持。如果ERP本身不支持分布式锁，我们会在MCP Server层面实现一个基于Redis的锁服务，所有对同一SKU的操作都通过这个锁服务串行化。这种方式会增加一些延迟，但能保证数据一致性。
5. FDE视角：生产环境部署的五个关键决策
5.1 MCP Server的部署形态选择
MCP Server的部署形态直接影响运维复杂度和性能。我们评估过三种方案：独立进程、Sidecar容器、集中式服务。
独立进程方案是把每个MCP Server作为一个独立的系统服务部署，通过systemd或者supervisor管理。这种方案简单直接，但缺点是每个Server都需要单独配置网络、认证、日志，当Server数量增多时，运维成本线性增长。
Sidecar容器方案是把MCP Server和Agent部署在同一个Pod中，通过localhost通信。这种方案适合Kubernetes环境，网络延迟最低，但缺点是Server的生命周期和Agent绑定，Agent重启时Server也会重启，不适合需要保持长连接或者维护缓存的场景。
集中式服务方案是把所有MCP Server部署在一个独立的集群中，Agent通过API Gateway访问。这种方案运维成本最低，可以统一做认证、限流、监控，但缺点是网络延迟相对较高，而且API Gateway可能成为瓶颈。
我们最终选择的混合方案是：对延迟敏感、调用频率高的Server（比如OA表单查询）用Sidecar部署；对延迟不敏感、调用频率低的Server（比如ERP报表生成）用集中式部署。这个决策的依据是：Sidecar的资源开销虽然高一些，但能保证关键路径的响应时间；集中式部署虽然延迟高，但能统一管理，适合非关键路径。
5.2 认证令牌的生命周期管理
Agent调用OA、ERP接口时，需要携带认证令牌。令牌的生命周期管理是一个容易被忽视但非常重要的问题。如果令牌过期时间太短，Agent需要频繁刷新，增加延迟；如果太长，令牌泄露的风险增加。
我们的做法是：在MCP Server中实现一个令牌管理模块，负责获取、缓存、刷新令牌。令牌的过期时间设置为略短于实际过期时间（比如实际2小时过期，我们设置为1小时50分钟），这样在令牌即将过期时主动刷新，避免调用时才发现过期。令牌缓存在内存中，不落盘，Server重启后重新获取。
对于需要用户上下文的接口，令牌中需要包含用户身份信息。我们的做法是：Agent在发起任务时，会携带一个用户身份标识，MCP Server根据这个标识获取对应的用户令牌。这样不同用户的任务使用不同的令牌，权限隔离清晰。
5.3 可观测性：日志、指标、追踪
生产环境的Agent系统必须有完善的可观测性。我们关注的三个维度是：日志、指标、追踪。
日志方面，MCP Server的每次工具调用都会记录一条结构化日志，包含调用时间、工具名称、输入参数（脱敏后）、返回结果（截断后）、耗时、错误信息。这些日志统一收集到ELK或者Loki中，方便排查问题。
指标方面，我们监控的关键指标包括：工具调用成功率、平均耗时、P95耗时、错误率、令牌刷新次数、锁等待时间。这些指标通过Prometheus采集，在Grafana中展示。当错误率超过阈值或者P95耗时异常时，会触发告警。
追踪方面，我们使用OpenTelemetry做分布式追踪。Agent的一次任务可能涉及多个MCP Server的多次调用，通过Trace ID把这些调用串联起来，可以清晰地看到整个调用链路，定位瓶颈。
5.4 降级与熔断策略
企业系统的不稳定性是常态。OA可能在月底结算时响应变慢，ERP可能在批量处理时拒绝新请求。Agent系统必须有降级和熔断策略，否则一个系统的故障会拖垮整个Agent。
我们的策略是：每个MCP Server都配置了熔断器，当连续失败次数超过阈值时，熔断器打开，后续调用直接返回降级结果（比如缓存数据或者默认值），不再实际调用后端系统。熔断器打开一段时间后进入半开状态，允许少量请求通过，如果成功则关闭熔断器，如果失败则继续保持打开。
降级策略根据工具的重要性分级。对于查询类工具，降级时返回缓存数据或者提示用户稍后重试；对于写入类工具，降级时直接返回失败，避免产生不一致的数据。
5.5 安全审计与合规
Agent调用企业系统时，所有的操作都需要被审计。我们的MCP Server会记录每一次工具调用的完整信息，包括调用者身份、调用时间、工具名称、输入参数、返回结果、操作结果。这些审计日志保存至少6个月，支持按用户、按时间、按工具名称检索。
对于敏感操作（比如财务付款、库存扣减），我们增加了二次确认机制。Agent在调用这些工具时，MCP Server会先返回一个确认请求，要求Agent提供额外的确认信息（比如审批单号），确认通过后才执行实际操作。
合规方面，我们确保MCP Server不会在日志中记录敏感数据（比如密码、身份证号、银行账号），所有敏感字段在记录日志前都会被脱敏。同时，MCP Server的访问权限被严格限制，只有经过认证的Agent才能连接。
6. 那些只有上了生产才会遇到的坑
6.1 泛微OA的"连接被阻止"错误
在配置泛微OA的外部地址作为目录时，我们遇到了一个报错："连接被阻止，因为它是由公共页面启动的"。这个错误的根本原因是泛微OA的安全策略限制了跨域请求。解决方案是在OA的配置文件中添加信任域名，或者通过OA提供的代理接口转发请求。
这个坑的隐蔽之处在于：在测试环境中，如果OA和Agent部署在同一台机器上，可能不会触发这个限制；但上了生产环境，Agent和OA分别部署在不同机器上，问题就暴露了。我们的经验是：在测试阶段就要模拟生产环境的网络拓扑，不要图省事把所有服务放在一起。
6.2 Agent执行超时但没有任何错误日志
我们遇到过一次诡异的问题：Agent调用MCP Server时超时，但MCP Server的日志中没有任何错误记录。排查了很久才发现，是SSE连接被企业防火墙静默断开了。防火墙对空闲超过5分钟的长连接会直接断开，但不发送任何通知。MCP Server端认为连接还在，继续等待响应，直到超时。
解决方案是在MCP Server中实现心跳机制，每隔30秒发送一个心跳包，保持连接活跃。同时，Client端也需要检测连接状态，如果发现连接断开，主动重连。
6.3 ERP接口返回的数据结构与文档不符
ERP接口文档和实际返回不一致是家常便饭。我们遇到过一次：文档中说某个字段是字符串类型，实际返回的是数字；文档中说某个字段可能为空，实际返回的是空字符串而不是null。这些差异导致Agent的解析逻辑出错。
我们的应对方法是：在MCP Server中实现一个数据校验层，对ERP返回的数据做类型检查和默认值填充。如果发现数据类型和预期不符，尝试自动转换；如果转换失败，记录警告日志并返回一个安全的默认值。同时，定期对比文档和实际返回，发现不一致时更新校验规则。
6.4 并发调用导致的令牌失效
当多个Agent同时调用同一个MCP Server时，如果令牌管理模块没有正确处理并发，可能会导致令牌被多次刷新，旧的令牌失效，正在使用旧令牌的请求失败。
解决方案是在令牌管理模块中使用读写锁：多个读操作可以并发，但刷新令牌时需要获取写锁，阻塞其他读操作。同时，令牌刷新后，正在使用旧令牌的请求需要能够感知到变化，重新获取新令牌。我们的做法是：在令牌对象中增加一个版本号，每次刷新后版本号递增，请求发送前检查版本号，如果发现版本号变化，重新获取令牌。
6.5 Agent沙盒更新导致的工具定义丢失
有一次我们更新了Agent的沙盒环境，更新后发现Agent无法调用任何工具。排查后发现，沙盒更新时重置了MCP Client的配置，导致工具定义丢失。Agent启动时没有重新发现工具，所以认为没有任何可用工具。
解决方案是在Agent的启动流程中增加一个工具发现步骤，每次启动时都重新连接MCP Server并获取工具列表。同时，在沙盒更新脚本中增加一个检查步骤，确认MCP Client配置没有被重置。
7. 从能用到好用：持续迭代的几个方向
7.1 工具描述的语义优化
MCP工具的描述文本直接影响Agent能否正确选择工具。我们最初的工具描述是直接从API文档复制过来的，充满了技术术语，Agent经常选错工具。后来我们重新编写了工具描述，用自然语言说明这个工具做什么、什么时候用、输入输出是什么，Agent的选择准确率明显提升。
优化的关键是：站在Agent的角度写描述，而不是站在开发者的角度。比如"查询OA表单"这个描述太模糊，改成"根据表单编号查询OA系统中的表单详情，返回表单的所有字段和当前审批状态"就清晰很多。
7.2 错误信息的语义化
企业系统返回的错误信息往往对Agent不友好。我们把常见的错误码映射成语义化的错误信息，比如把"错误码-1"映射成"当前用户没有权限执行此操作"，把"错误码-2"映射成"目标记录不存在"。这样Agent在遇到错误时，能够理解错误的含义并采取相应的行动。
7.3 缓存策略的精细化
不是所有数据都适合缓存，也不是所有数据都需要实时查询。我们对工具调用做了分类：对于变化频率低的数据（比如组织架构、表单模板），缓存时间设置为1小时；对于变化频率高的数据（比如库存数量、审批状态），缓存时间设置为30秒或者不缓存。缓存键的设计也很重要，需要包含用户身份和查询条件，避免不同用户看到相同的缓存数据。
7.4 批量操作的优化
Agent有时需要批量处理数据，比如批量查询多个表单、批量审批多个节点。如果逐个调用接口，效率很低。我们在MCP Server中实现了批量操作工具，支持一次传入多个ID，Server端并发调用后端接口，然后合并结果返回。批量操作需要注意部分失败的情况，我们的做法是返回每个ID的处理结果，Agent可以根据结果决定是否重试失败的项。
7.5 与Agent框架的深度集成
MCP Server只是工具提供方，真正的编排逻辑在Agent框架中。我们发现，如果Agent框架能够感知工具的特性（比如哪些工具是幂等的、哪些工具需要审批、哪些工具耗时较长），就能做出更好的编排决策。我们在MCP工具的定义中增加了元数据字段，标注工具的特性，Agent框架在编排时可以参考这些元数据。
比如，对于需要审批的工具，Agent框架会先暂停任务，等待人工审批后再继续；对于耗时较长的工具，Agent框架会设置更长的超时时间，并在等待期间处理其他任务。这些优化让Agent的行为更加智能和可靠。
我在实际项目中最深的体会是：Agent接入企业系统的难点不在于技术本身，而在于对企业业务逻辑的理解和对生产环境复杂性的敬畏。每一个接口背后都有一套业务规则，每一个错误码背后都有一个业务场景。只有把这些都摸清楚了，Agent才能真正在生产环境中稳定运行。
