从业务 API 到 Agent 工具：我的 AI 平台架构设计
AI 平台的核心不只是一个聊天窗口。要让助手使用已有系统，需要处理工具如何进入平台、谁可以使用、参数怎样传递、失败如何记录。本文拆解我正在演进的平台：独立应用、统一工具池、配置化 Agent，以及一次跨系统查询的运行过程。
更新于 2026-09-09。依据平台实现、V2 里程碑和 2026-09-07 产品评估整理。资产服务为演练系统；任务恢复等未来能力在文中单独说明。
部署边界：业务系统保留业务责任
工业采集系统负责设备连接、点位、历史和规则。AI 平台通过 MCP 或 HTTP 调用系统暴露的能力，不直接替代协议采集层。平台拥有独立应用与数据库，可以独立配置模型和助手。
图中展示当前主要职责，不表示所有执行治理已达到完整产品形态。工具池是平台内部模块，不是另一套独立产品；平台作为 MCP 消费方，也不代表已经对外提供统一 MCP Server。
管理流程：从接口到可用工具
系统登记提供地址、接入类型与执行配置。MCP 路径发现已有工具，HTTP 路径可以通过 OpenAPI 导入候选操作，再补齐语义与参数映射。
登记系统 → 发现 / 导入 → 工具草稿 → 校验与发布 → Agent 绑定
导入生成草稿，不等于系统已经可用。接口描述可能缺少单位、返回字段意义、业务前置条件和权限要求；平台需要通过验证和人工判断补足。
我将“结构是否成立”和“模型是否容易理解”分开处理：命名、输入结构、执行配置交给确定性校验；描述与裁剪建议可以由模型辅助。模型提出的合并建议，仍必须满足实际分发条件。
生命周期包含 DRAFT、REVIEWING、PUBLISHED、DEPRECATED。发布是一项治理决定，绑定则决定助手场景；两者不应由同一个“启用”字段模糊代替。
统一工具池为何值得保留
MCP 与 HTTP 工具共用 tool_definition，运行时根据执行器类型构造回调。这样工具描述、发布状态、Agent 绑定和调用记录可以沿着同一套标识关联。
| 层 | 保存或处理什么 |
|---|---|
| 系统配置 | 连接与所属系统 |
| 工具定义 | 名称、描述、输入契约、执行配置、状态 |
| Agent 配置 | 模型、角色、工具绑定与 Skills |
| 执行器 | 协议请求、参数映射与结果处理 |
| 审计 | 调用来源、输入输出摘要、结果与错误 |
若同一业务能力同时有 MCP 和 HTTP 表达，它们不能未经治理就重复进入同一助手。平台曾清理手写包装与动态构造的并行路径；减少这种隐藏分支，比单纯统一命名更能改善可检查性。
运行流程：配置如何影响一次回答
助手可用工具可概括为“已绑定、已发布、当前可执行”的交集。这个关系表达装配条件，不等于完整用户权限体系。
用户选择 Agent 后，平台解析模型与业务指导，构造工具集合。模型提出调用，回调执行请求，结果返回模型继续组织答案，工具事件与最终回答通过对话通道展示。
参数必须保持类型。例如 JSON 中的整数、布尔、数组和对象，不应在 HTTP body 或步骤接力中统一变成字符串。项目已有这方面的修复，也说明跨协议的公共模型需要通过真实请求体验证，而不仅比较序列化后的文本。
结果同样需要分类：传输成功不意味着工具成功。当前 MCP 回调检查 isError，失败进入错误审计；业务系统自己定义的失败码仍需要契约映射，不能仅凭 HTTP 200 判断业务完成。
一次跨系统查询的具体过程
平台 P4 记录使用工业系统与独立资产示例服务演练只读接力。资产服务是 8 条内存记录，预先建立与设备名称的关联。
| 步骤 | 使用的数据 | 要验证的结果 |
|---|---|---|
| 查询告警 | 工业系统的设备标识与告警 | 能确定查询对象 |
| 检索资产 | 从上一步取得的设备名称 | 得到候选资产与编码 |
| 查询档案 | 已取得的 assetCode | 返回对应资产信息 |
| 汇总回答 | 两个来源的结果 | 说明来源和缺失，不编造关联 |
这个过程体现单 Agent 调用多个系统的能力，不要求先实现多 Agent。遇到多个匹配结果时，应请求消歧；找不到资产时，应保留工业查询结果并说明资产缺失。
系统停用会使相关工具收缩，是已有演练内容。自动探活、自动熔断与完整降级策略不能由“手动停用有效”推导出来。
Skills 与强制执行的边界
当前 Skills 是可复用业务指导，例如“先确认设备，再读取点位与单位”。它有助于模型规划，但不负责强制授权，也不是持久化任务引擎。
真正不可跳过的条件应进入程序：身份是否可信、动作是否允许、参数是否匹配批准快照、结果是否可核验。把这些只写进提示词，会把确定性要求变成模型遵守建议的概率。
写操作：已经有什么，还缺什么
2026-09-07 的记录与当前抽查代码表明：平台已增加最小用户登记和写权限检查，批准按工具、参数哈希与会话配对，状态转换通过条件更新原子消费。
HTTP 写工具与显式设置 confirmRequired=true 的 MCP 工具复用确认入口。MCP 该配置缺省为 false，因此不能说所有写类 MCP 工具已经自动识别并强制审批；发布治理仍需正确分类。
这些机制改善了当前执行路径，但还不是完整认证、逐工具授权或租户隔离。用户 ID 传递也不能单独证明用户身份可信。
批准只消费一次，也不能保证目标系统副作用只发生一次。请求发出后超时，目标可能已经保存；换一个 ID 重试会制造重复数据。
未来任务运行时需要明确记录：运行、等待批准、成功、失败、结果待核实、部分完成与取消，并保存步骤、参数和业务单号。当前会话与日志持久化不能替代重启后的任务恢复。
为什么下一步优先做一个可靠闭环
以添加设备规则为例，需要先查设备和点位，形成草稿，取得允许后保存，再回读、核对和按授权启用。保存成功不代表已经触发告警；启用失败也不应该隐藏成全部完成。
与其先扩大工具数量，我更希望这条路径能够处理响应丢失、参数歧义和服务重启。它首先证明单业务系统内的受控动作；真正跨多个系统写入，还需要目标系统的幂等与补偿能力配合。
当前架构已经能解释工具如何接入和参与查询。平台继续演进的衡量标准，是业务目标是否可核验地完成，以及接入下一个场景时是否真正减少重复工作。历史设计取舍见AI 演进复盘。