分层 API 架构设计

分层 API 架构设计

学习目标

读完本章后，你将能够：

• 理解分层架构在 AI 框架中的价值：兼顾灵活性与易用性
• 设计 Core / AgentChat / Extensions 三层 API 的职责边界
• 分析不同分层策略的权衡
• 为不同用户群体提供合适的抽象级别

---

核心概念

三层架构模型

各层职责

层级	目标用户	核心职责	抽象级别
Extensions	集成开发者	具体实现：模型后端、工具适配器、运行时	最低（具体协议）
Core	框架开发者	基础设施：消息路由、Agent 生命周期、模型/工具抽象	中（接口 + 协议）
AgentChat	应用开发者	业务逻辑：Agent 编排、对话管理、终止条件	最高（业务概念）

层间依赖规则

关键设计原则：Core 不依赖任何 Extensions 的具体实现。Core 定义接口协议（Protocol），Extensions 实现这些协议。这确保了：

1. Core 可以独立发布和版本管理
2. 新增 Extensions 不需要修改 Core
3. 用户可以选择性安装所需 Extensions

典型使用路径

路径一：快速原型（仅 AgentChat）

用户只需要理解 Agent、Team、Termination 三个概念即可构建多 Agent 应用。

路径二：自定义 Agent（Core + Extensions）

需要自定义消息路由、订阅策略、序列化格式的用户进入 Core 层。

路径三：扩展模型/工具（Extensions）

集成新模型提供商或工具的用户只需要实现 Core 定义的接口。

问题与规避

API 版本耦合

陷阱：AgentChat 依赖 Core，Core 的破坏性变更会级联影响 AgentChat。

规避策略：

• 使用语义化版本（SemVer）
• Core 的接口变更需要伴随 AgentChat 的同步更新
• 在 monorepo 中统一管理多包版本

层间泄漏

陷阱：用户在使用 AgentChat 时被迫理解 Core 层概念（如 Topic、Subscription）。

规避策略：

• AgentChat 内部封装 Core 层的复杂性
• 仅在高级场景下暴露 Core API（通过可选参数 runtime）
• 文档分层：快速入门不涉及 Core 概念

设计取舍

为什么分层而非单一大包？

优势：

• 用户选择权：新手用 AgentChat，高级用户用 Core
• 独立演进：每层可独立发布版本
• 依赖精简：仅使用 AgentChat 的用户不需要安装 Extensions 的依赖

代价：

• 维护成本：三层 API 需要同步维护
• 文档复杂度：需要为不同层级编写不同文档
• 用户困惑：不清楚应该使用哪一层

替代方案

方案	灵活性	易用性	维护成本	示例
分层 API	高	高（高层）/ 低（底层）	高	AutoGen, LangChain/LangGraph
单一大包	中	中	低	早期 AutoGen v0.2
插件式	高	低	高	LlamaIndex
极简核心 + 社区扩展	最高	最低	最低	OpenAI SDK

参考来源

• Layered Architectures in Software Engineering — 分层架构的经典论述
• AutoGen Architecture Overview — 官方架构说明