调用一次大模型接口通常只需要少量代码，把它做成可以长期使用的企业应用，却会连续遇到一系列问题：模型怎样统一接入，企业知识怎样管理，Agent 如何调用业务接口，复杂任务是否需要工作流，做好的能力又怎样提供给员工和现有系统。任何一项没有处理好，应用都很容易停留在演示阶段。
我们团队在设计云程智能体开发平台第一版时，一开始就要确定各类功能怎样分层、彼此之间怎样建立稳定的关系，页面上需要放多少功能反而是后续问题。经过实际开发，平台最终形成了从模型与基础设施、知识与外部能力、智能编排、AI 应用到用户入口的整体结构，并用权限、版本和运行追踪把各层连接起来。
这篇文章不讨论某个类或某张数据表的实现，而是结合这一版产品的设计过程，说明几个会影响智能体平台长期发展的架构选择。对于正在规划 AI 应用平台，或者准备把模型能力接入企业系统的团队，这些选择通常比"支持多少个模型、多少种节点"更值得提前想清楚。
一、平台边界：连接 AI 能力与业务系统
如果不断把报销、合同、客服等业务做进智能体平台，它最后会变成一套边界不清的综合业务系统；如果只提供模型对话和流程画布，应用做完以后，权限、发布、系统集成和运行问题仍然要由使用者自行解决。
云程智能体开发平台选择的位置是在两者之间：平台负责接入模型和企业知识，组织 Agent 与工作流，连接外部业务能力，并把建设结果发布成可以使用和管理的 AI 应用；ERP、OA、CRM、合同、报销和工单等业务数据，仍由原有系统负责。
这种边界会形成双向连接。一方面，平台中的 Agent 和工作流需要调用业务接口，例如查询客户资料、查验发票或写入报销业务模块；另一方面，企业现有系统也需要通过网页嵌入或 API 调用平台中的 AI 应用。平台承担的是 AI 与业务之间的组织和连接工作，而不是重新实现一遍所有业务功能。
图中的层次不是为了把模块分得越多越好，而是为了让每一类变化尽量停留在自己的范围内。更换模型服务时，不应要求重新设计应用入口；更新企业制度文档时，不应修改 Agent 的整体编排；工作流内部增加一个审核环节，也不应迫使业务系统更换调用地址。层次之间通过明确的资源引用和运行接口连接，平台才有可能在持续变化中保持稳定。
二、技术路线：选择适合企业系统的开发体系
智能体平台的技术选型不能只比较框架功能，还要考虑团队已有技术基础、需要连接哪些系统、怎样部署，以及未来由谁维护。
大模型研究和算法原型中有非常丰富的 Python 生态，但云程智能体开发平台的主要任务不是训练模型，而是建设和运行企业 AI 应用。平台需要接入已有的 Java 服务，复用身份认证、权限、数据访问和接口资产，还要处理事务、文件、缓存、审计以及私有化部署。因此，后端采用 JDK 21 和 Spring Boot，前端采用 Vue 3、TypeScript 和 LogicFlow，能够更好地接入现有企业技术体系，也更符合团队长期维护的条件。
在 AI 框架上，Spring AI 提供了模型调用、向量检索、工具调用和 MCP 等相对统一的 Java 接口。它的价值在于隔离不同模型服务的基础接入差异，让业务代码不必围绕每一家厂商重新写一套。Spring AI Alibaba 则在此基础上提供 Agent 和图编排相关能力，用于处理 ReAct、多 Agent 协作、状态流转、流式执行和运行恢复等问题。
不过，选用框架并不等于把平台交给框架定义。统一的模型接口无法抹平不同模型在多模态、结构化输出和工具调用上的差异，Agent 框架也不会替企业解决资源权限、应用发布和版本管理。云程智能体开发平台将框架调用主要限制在模型适配与编排执行层，平台自己的资源定义、工作流配置、应用交付和运行治理不直接依附于某个框架对象。这样既能使用成熟框架提供的基础能力，也能控制框架升级对上层功能的影响。
第一版后端采用模块化单体部署，模型、知识库、Agent、工作流和应用在代码上保持清晰边界，但作为一套服务统一发布。当前阶段，这些模块之间存在较多资源依赖和一致性要求，私有化部署也需要尽量控制组件数量，过早拆成多套微服务只会增加调用链路和运维成本。等到某一类执行任务确实需要独立扩容，或者脚本运行需要更严格的隔离时，再拆分对应的运行服务，会比一开始按功能名称拆服务更稳妥。
三、能力分层：模型、知识和外部能力独立管理
如果每个 Agent 都单独填写模型地址、上传一份文档，再接入一次业务接口，几个应用之后就会出现大量重复配置。同一个接口可能使用不同的参数定义，同一份制度可能保留多个版本，密钥和权限也散落在不同 Agent 中，后续几乎无法统一调整。
因此，云程智能体开发平台把模型、知识库和外部能力作为独立资源管理，Agent 和工作流只引用它们。单独管理既能减少重复配置，也让每项资源拥有自己的生命周期：可以分别配置、测试、授权和发布，还可以查看哪些应用正在依赖它。
模型接入不只是保存 API 地址和密钥。平台需要区分对话、视觉、Embedding 和 Rerank 等模型用途，并验证图片输入、工具调用、结构化输出等具体能力。一个服务声称兼容某种接口，不代表每项功能的行为都完全相同。只有经过验证的模型能力，才适合提供给上层 Agent、工作流和知识库选择。
知识库也有独立的处理过程。文档要经过解析、切片、向量化和索引才能用于检索，更新频率和访问权限又通常由业务部门决定。一套企业制度知识库可能同时服务于制度问答、合同审核和报销流程，不应依附于其中某个 Agent，更不应随着某个应用删除而一并消失。
外部能力则根据接入方式分为 Tool、MCP 和 Skill。三者都能扩展 Agent 的能力，但解决的问题并不相同。
| 能力 | 主要用途 | 适合的接入方式 |
|---|---|---|
| Tool | 调用已有业务接口 | 将 HTTP 或 OpenAPI 接口包装成参数、返回值明确的工具 |
| MCP | 接入遵循 MCP 协议的外部服务 | 同步服务提供的工具，并按权限选择开放范围 |
| Skill | 为 Agent 提供一套专项工作方法 | 组合说明文档、参考资料、脚本和模板，按任务需要加载 |
Tool 和 MCP 可以由 Agent 或工作流直接调用；Skill 主要由 Agent 使用，工作流需要这类能力时，可以通过 Agent 节点间接完成。它们在平台中统一接受配置、发布、授权和日志管理，但仍然保留不同的运行方式与安全限制。特别是涉及内网接口、访问密钥和脚本执行时，平台还要控制目标地址、网络范围、超时时间和可用资源。能力资源越丰富，这些边界越不能只依靠使用者自行约定。
四、编排方式：Agent 与工作流承担不同任务
Agent 和工作流采用不同的任务控制方式，根本差别在于执行路径由谁决定。Agent 把较多判断交给模型，模型结合上下文决定怎样回答、调用哪个工具，或者把任务交给哪个专业 Agent；工作流则在设计阶段明确节点、变量、条件、循环和异常处理，用确定的流程控制任务执行。
| 判断维度 | Agent | 工作流 |
|---|---|---|
| 执行路径 | 运行时由模型和编排方式共同决定 | 设计时通过节点和连线确定 |
| 适合任务 | 开放问答、研究分析、动态查询、专业 Agent 协作 | 审核、报销、数据处理、系统集成、人工确认 |
| 主要风险 | 模型判断和工具选择存在不确定性 | 流程过长后，节点与变量维护较复杂 |
| 排查重点 | 上下文、模型决策、工具和子 Agent | 节点输入输出、变量、分支和失败位置 |
在实际业务中，两种方式经常需要组合。以发票报销为例，文件解析、发票查验、金额校验和写入报销业务模块都有明确顺序，适合由工作流控制；用户口头描述费用用途、制度条款解释或异常情况判断，则更适合交给 Agent。工作流中的 Agent 节点把两者连接起来：确定的步骤由流程保证，确实需要理解和判断的环节再使用模型。
云程智能体开发平台中的 Agent 支持普通对话、ReAct 和多 Agent 协作，工作流可以组织模型、Agent、知识检索、Tool、MCP、HTTP、条件、循环、数据处理和人工输入等节点。实际设计时，能够写成明确规则、顺序和校验条件的内容，应放进工作流；无法预先确定步骤、需要模型动态选择能力的内容，更适合由 Agent 处理。
五、应用交付：通过 AI 应用统一发布和集成
Agent 和工作流描述的是任务怎样执行，但最终用户通常不关心内部采用了哪种编排方式。他们关心的是从哪里进入、是否需要登录、会话能否保留；业务系统关心的则是调用地址、访问凭证、输入输出和正式版本是否稳定。
如果把这些配置分别放在 Agent 和工作流中，两种编排方式就要重复建设网页入口、API、会话和权限，外部系统也会直接依赖内部资源。以后把一个 Agent 调整为工作流，或者在工作流前增加一层业务处理，都可能影响所有调用方。
因此，云程智能体开发平台将 AI 应用设计为统一交付单元。每个应用绑定一个入口 Agent 或工作流，并集中管理 WebApp、网页嵌入、API、客户端通道、访问凭证、会话、记忆和使用权限。内部编排可以继续迭代并发布新版本，员工和业务系统仍然从应用入口访问。
AI 应用由此成为平台与外部环境之间相对稳定的边界。平台中的 Agent 和工作流通过 Tool、MCP 或 HTTP 等方式调用业务系统，企业门户、OA、移动端和其他系统则通过 WebApp、Embed 或 API 使用 AI 应用。前一条链路让 AI 能够办理业务，后一条链路让业务系统能够使用 AI，两者缺少任何一边，平台都很难真正进入现有工作流程。
统一入口只能保持访问方式相对稳定，不能消除输入输出的兼容问题。新的 Agent 或工作流如果改变了参数、返回结构或会话方式，仍然可能影响调用方。应用层还要管理发布版本和接口约定，在内部调整时检查兼容性，这也是"发布应用"与"直接运行一个 Agent"的区别。
六、运行治理：权限、版本和追踪贯穿各层
模型、知识库、外部能力、Agent、工作流和应用都可以独立管理以后，平台也会出现新的问题：用户能看到哪些资源，正式应用依赖的是哪个版本，一次失败究竟发生在哪个环节。这些内容不一定是产品演示中最显眼的部分，却直接决定应用上线后能否持续维护。
权限首先要覆盖真实的资源关系。用户能进入 Agent 页面，不代表可以引用平台中的所有知识库和业务接口；某个 Agent 获得了知识库使用权，也不代表最终用户可以绕过知识权限检索全部文档。页面、接口和资源权限需要共同生效，知识检索等环节还要根据当前身份缩小可见范围。
版本管理用于分开正在修改的设计态和对外运行的发布态。应用发布时，不能只保存应用本身，还要确认入口 Agent 或工作流以及下游知识库、Tool、MCP 和 Skill 的版本。否则，开发人员修改一个仍在设计中的资源，就可能在没有发布记录的情况下改变正式应用行为。平台需要保存依赖关系，并在发布、下线或删除资源时检查影响范围。
链路追踪解决的是问题定位。一次应用调用可能依次经过工作流、Agent、知识检索、模型和外部接口，只记录最终报错很难判断真正原因。完整的运行记录应包含每个环节的状态、输入输出、耗时、错误和资源版本，并能够查看知识召回内容、工具参数和模型交互。这样才能分清问题来自权限过滤、知识检索、Prompt、模型响应、工作流变量，还是业务接口本身。
这些治理能力需要从架构开始就进入每一层。应用增加以后再补权限，往往会发现资源关系没有记录；上线后再补追踪，也可能只能看到零散日志。较早建立统一的身份、版本和运行上下文，后续增加新的模型、节点和能力类型时，维护成本会更可控。
结语
智能体开发平台的价值，不是把模型、Agent、工作流和知识库放进同一个菜单，而是把这些能力组织成可以建设、发布、接入和维护的 AI 应用。AI 框架决定了平台可以从哪里开始，平台边界、能力分层、编排方式和运行治理，则决定它能否进入真实业务并长期运行。
本文内容来自云程智能体开发平台第一版的设计与开发实践。规划类似平台时，可以从现有系统和实际任务出发，明确每一层负责什么、怎样连接，以及一项变化会影响哪些部分。