面向 AI Agent 的能力模型与多协议生成架构设计思考

面向 AI Agent 的能力模型与多协议生成架构设计思考

1. 问题背景

随着 AI Agent 技术的发展，越来越多的业务系统开始面临一个新的问题：如何以统一且可持续的方式向 Agent 暴露自身能力。过去的软件系统主要面向人类开发者，因此通常通过 SDK、REST API、RPC 接口或命令行工具对外提供能力。然而在 Agent 时代，仅仅提供调用入口已经不足够，系统还需要让 Agent 理解自己具备哪些能力、这些能力适用于什么场景以及如何正确使用这些能力。

近年来，MCP（Model Context Protocol）的出现为 Agent 提供了一种标准化的能力发现机制。与此同时，OpenAI Tool Calling、A2A、LangChain Tool、Claude Skill 等方案也在不断发展。面对层出不穷的新标准，一个非常现实的问题开始出现：企业是否应该围绕某一种协议进行建设？如果今天全面拥抱 MCP，那么未来出现新的标准时是否又需要重新建设一套体系？

从长期维护角度来看，这种以协议为中心的设计存在明显风险。协议会演进，框架会迭代，Agent 产品也会不断变化，而企业真正需要保护的资产并不是这些协议本身，而是业务能力。因此，如何让业务能力脱离具体协议而独立存在，成为整个设计思考的出发点。

2. 从协议中心到能力中心

在许多系统中，架构设计往往从协议开始。例如系统首先决定提供 REST API，然后围绕 REST API 组织代码；或者首先决定建设 MCP Server，然后围绕 MCP Tool 构建能力。这种设计方式在系统规模较小时并没有明显问题，但随着能力数量增加，会逐渐暴露出耦合问题。

以日历系统为例，无论用户通过 MCP 创建会议、通过 CLI 创建会议、通过 SDK 创建会议，还是通过 Web 页面创建会议，其本质上调用的都是同一个业务能力——创建日历事件。协议不同，但业务能力并没有发生变化。如果系统内部始终围绕协议组织代码，那么每增加一种协议，就需要重复构建一套映射关系，最终导致系统维护成本不断上升。

因此，更合理的思路是将“能力”而非“协议”作为架构中心。对于日历系统而言，创建事件、查询事件、搜索事件、修改事件和删除事件等能力应当独立于任何具体协议存在。各种协议仅仅是能力的不同暴露方式，而不是能力本身。只有当能力模型成为系统唯一事实来源时，系统才能真正获得长期稳定性。

3. 对 MCP 的重新认识

在整个讨论过程中，一个重要认识是：MCP 的核心价值并不在于远程调用，而在于能力发现。

CLI、SDK、REST API 本质上都能够完成调用动作，但它们并不天然具备能力发现能力。对于 Agent 而言，仅仅知道某个命令存在并不足以理解其用途、参数以及适用场景。因此，传统 CLI 往往需要配套 Help 文档、Skill 文件或者示例代码。而 MCP 则通过标准化 Schema 将这些信息结构化表达出来，使 Agent 能够自动理解系统提供的能力。

然而这并不意味着 MCP 应当成为系统的核心。MCP 本质上仍然是一种协议，它解决的是能力如何被发现的问题，而不是能力如何被建模的问题。从这个角度来看，MCP 更像是一种能力出口，而不是能力模型本身。如果未来出现新的 Agent 标准，企业不应当因为协议变化而被迫重构业务系统。因此，MCP 应当被视为适配层，而不是架构中心。

4. 为什么 Protobuf 不应成为系统中心

在寻找统一能力模型的过程中，Protobuf 是一个非常自然的候选方案。它拥有成熟的生态、广泛的行业应用以及优秀的跨语言代码生成能力。通过 Protobuf 可以自动生成 Java、TypeScript、Python 等多种语言的客户端和服务端代码，同时还具备良好的版本兼容性管理能力。从工程角度来看，它几乎满足一个统一模型所需要的大部分条件。

然而进一步分析后可以发现，Protobuf 更适合作为工程契约，而不是能力模型。Protobuf 擅长表达的是接口、参数、返回值以及服务调用关系，它回答的是“如何调用”的问题。但 Agent 更关心的是“什么时候调用”“为什么调用”以及“调用是否安全”等问题。例如某个能力是否属于高风险操作、是否支持 Dry Run、是否需要用户确认、Agent 在什么场景下应当优先选择该能力，这些内容虽然可以通过扩展机制进行表达，但并不是 Protobuf 的设计目标。

因此，将 Protobuf 作为整个系统的中心会导致一个问题：越来越多与 Agent 相关的语义被强行塞入工程契约之中。随着时间推移，Proto 文件将逐渐承担过多职责。因此更合理的定位是将 Protobuf 视为能力模型生成出来的结果，而不是能力模型本身。

5. Capability DSL 的定位

既然能力模型不应直接建立在协议之上，也不应完全建立在 Protobuf 之上，那么系统需要一个更高层次的抽象来描述能力本身。经过讨论后，我们认为引入 Capability DSL 是一种合理的选择。

这里所说的 DSL 并不是新的编程语言，而是一种统一的能力描述模型。它负责描述能力名称、输入输出结构、权限要求、风险等级、示例用法以及各种协议映射关系。其核心目标是成为系统内部唯一的能力元数据来源。

采用这种设计后，业务开发人员关注的是能力本身，而不是各种协议细节。无论未来需要生成 MCP Tool、CLI 命令、REST API 还是 SDK，这些产物都来自同一个能力定义。这样既避免了重复维护多套描述信息，也为未来支持新的协议提供了扩展空间。

需要特别说明的是，Capability DSL 并不负责实现业务逻辑。业务逻辑仍然由开发人员通过正常代码完成。DSL 的职责仅仅是描述能力，而生成器则根据这些描述自动创建各种协议适配层和工程契约。

6. Contract First 的实现思路

在能力模型确定之后，下一个问题是如何组织业务代码。结合个人开发习惯以及企业级系统的长期维护需求，Contract First 是一种非常值得采用的模式。

在这种模式下，系统首先生成稳定的服务契约接口，然后由业务实现完成这些接口。例如对于日历能力，可以生成 CalendarService 接口，接口中定义创建事件、搜索事件和删除事件等方法。业务代码只需要关注接口实现，而不需要感知 MCP、REST 或 CLI 的存在。

这种设计最大的价值在于形成稳定边界。协议层、业务层以及部署方式都可以围绕这个边界独立演进。当系统需要新增一种协议时，只需要增加新的适配器即可；当业务实现需要重构时，只要保持契约不变，上层协议也无需修改。契约成为整个系统最重要的稳定点。

7. 自动生成的适配层架构

在传统系统中，协议适配层通常由开发人员手工编写。然而随着能力数量增加，这种方式会迅速变得难以维护。因此，一个重要设计原则是尽可能自动生成适配层。

以 MCP 为例，生成出来的 MCP Adapter 并不包含业务逻辑。它仅负责接收 MCP 请求、完成参数转换、调用服务契约接口并返回结果。从设计模式角度来看，这本质上是一个标准的 Adapter Pattern 实现。同样的思想也适用于 CLI、REST 以及未来可能出现的其他 Agent 协议。

由于所有适配层都来自同一个 Capability DSL，因此整个系统实际上只维护一套能力定义。当新增协议时，开发工作主要集中在生成器层，而不是业务层。这种模式能够显著降低系统长期演进成本。

8. 本地实现与远程实现的统一抽象

进一步思考后可以发现，即使契约已经稳定，能力的实现位置仍然可能发生变化。有些能力可能直接运行在当前进程中，而另一些能力则可能来自远程微服务、第三方系统甚至云平台。

因此，契约接口不应假设能力一定来自本地实现。更合理的方式是将契约视为能力访问抽象，而将具体实现隐藏在实现层内部。同一个接口既可以由本地实现完成，也可以由 RPC 客户端、REST 客户端甚至消息队列消费者实现。

这种设计带来的好处是协议与部署方式实现了彻底解耦。MCP Adapter、CLI Adapter 或 SDK 并不关心能力究竟运行在哪里，它们只依赖契约接口。对于调用方而言，本地能力与远程能力具有一致的使用方式，从而降低系统复杂度。

9. 推荐架构

综合上述分析，推荐采用以 Capability DSL 为中心的架构模型。开发人员首先通过代码注解或 DSL 描述业务能力，然后由代码生成器自动生成契约接口、工程契约以及各种协议适配层。生成出来的 Java Interface 成为业务层与协议层之间的稳定边界，而 Protobuf、OpenAPI 等则作为工程契约存在，为 SDK 生成和远程通信提供支持。

在该架构中，Capability DSL 是系统唯一事实来源；Contract Interface 是业务边界；Protobuf 和 OpenAPI 是工程契约；MCP、CLI、REST 以及未来的 Agent 协议都是自动生成的适配层。业务实现只依赖契约，而各种协议适配器也只依赖契约，从而形成清晰且稳定的架构层次。

对于 Java 生态而言，一个更加自然的落地方式是：首先根据 Capability DSL 生成 Java Interface，然后由业务系统实现这些接口；随后根据同一份 DSL 自动生成 MCP Adapter、CLI Adapter、Proto 文件以及其他工程契约。这样既符合 Contract First 的开发习惯，也能够充分利用现有生态提供的代码生成能力。

10. 总结与演进方向

整个设计思考最终指向一个核心结论：企业不应围绕 MCP、CLI 或 Protobuf 构建系统，而应围绕业务能力构建系统。协议会变化，框架会变化，Agent 标准也会变化，但业务能力本身通常具有更长的生命周期。因此，能力模型才是最值得长期投资和保护的资产。

从演进路线来看，一个较为现实的方案是以代码注解作为能力定义入口，以 Capability DSL 作为统一元模型，以 Contract Interface 作为业务边界，并通过自动代码生成构建 MCP、CLI、SDK、Proto 等各种适配层和工程契约。这样既能够充分利用现有成熟生态，又能够避免被某一种具体协议长期绑定。

从长期视角看，这种架构的真正价值并不在于今天支持了多少协议，而在于未来当新的 Agent 标准出现时，企业能够以最低成本接入新的生态，而无需重新设计自己的业务系统。