Agent Platform 是一套面向智能体应用交付的工程化平台设计。
它的目标不是只提供一个聊天界面，也不是把多个 Agent 简单拼接在一起，而是把用户、租户、Agent、技能、模型、数据访问、运行时和运营治理组织成一个可闭环、可扩展、可商业化演进的系统。
本仓库是代码仓库，README.md 同时作为当前阶段的顶层设计文档。后续工程实现会围绕本文档中的模块边界、MVP 流程和演进路线展开。
当前状态：设计与初始化阶段。本文档描述目标架构和 MVP 范围，不代表所有模块已经完成或可直接生产使用。
Agent Platform 面向“智能体应用平台化交付”场景，重点解决以下问题：
- 用户如何注册、登录，并领取自己的专属 Agent；
- Agent 如何按用户维度启动、停止、重启和回收；
- 技能如何沉淀、发布、安装，并被 Agent 加载生效；
- Agent 如何通过受控入口访问模型、数据库和平台工具；
- 平台如何支撑租户隔离、鉴权、安全审计、计量计费和运营观测；
- 一套智能体能力如何从 POC 走向可商业、可治理、可扩展的应用平台。
这套平台遵循 ArchAIHarness 的基本主张：
人定义规则，Agent 在规则内执行，平台负责编排与审计。
平台的设计目标包括：
-
用户专属 Agent
- 用户注册后可以领取专属 Agent。
- 用户登录后，平台自动启动对应 Agent。
- 用户离开或超时后，平台自动回收 Agent 实例。
-
Agent 生命周期管理
- 支持 Agent 创建、启动、停止、重启、回收和状态查询。
- 支持按用户、租户、工作空间维度管理 Agent。
- 支持 Agent API 代理转发，避免运行时实例直接暴露给外部客户端。
-
技能市场驱动扩展
skills-market是平台侧技能市场，负责技能商品管理、发布、交易、下载和版本治理。- 技能以 Markdown 等可读资产形式沉淀和版本化，同时作为可被 Agent 购买和安装的商品。
- 用户可以通过技能市场为专属 Agent 选择技能，实际购买和安装请求由 Agent 发起。
- Agent 通过
npx请求技能市场中的目标技能，完成交易后下载技能包并安装到自身；当前阶段交易价格可以为免费。
-
网关化访问模型与数据
- 模型调用通过
model-gateway统一桥接、审计、计费和负载治理。 - 数据访问通过
db-gateway统一代理，支撑共享服务实例下的租户数据隔离。 - Agent 不直接绕过平台访问核心资源。
- 模型调用通过
-
可商业化演进
- 平台预留用户、租户、技能、模型调用、资源使用等计量边界。
- 后续可扩展订阅、套餐、计费、运营数据和客户管理能力。
- 支持从单用户 MVP 演进到多租户商业部署。
-
可观测与可审计
- 平台需要能查看用户、租户、Agent、技能、模型调用和运行资源状态。
- 关键请求、敏感操作、技能安装、Agent 生命周期变化需要可追踪。
MVP 聚焦一个最小但完整的智能体应用闭环：
flowchart TD
A[用户注册] --> B[领取专属 Agent]
B --> C[用户登录]
C --> D[平台自动启动专属 Agent]
D --> E[用户通过 Web UI 与 Agent 交互]
E --> F[用户通过技能市场选择技能商品]
F --> G[Agent 发起购买和安装]
G --> H[Agent 通过 npx 下载并安装技能]
H --> I[Agent 重启后加载技能]
I --> J[用户继续交互]
J --> K[用户离开或超时]
K --> L[平台自动回收 Agent 实例]
MVP 的关键验收点：
- 用户可以完成注册和登录；
- 注册后可以建立用户与专属 Agent 的绑定关系；
- 登录后可以自动启动用户专属 Agent；
- 用户可以在 Web UI 中与 Agent 交互；
- 用户可以通过技能市场安装技能；
- 技能安装后，Agent 可以通过重启加载新技能；
- 用户离开或超时后，Agent 实例可以被自动回收。
当前平台规划为一组协同工程项目。
| 项目 | 定位 | 技术方向 | 主要职责 |
|---|---|---|---|
webui |
客户端 | React + Vite | 用户注册登录、工作空间加载、Agent 交互、技能市场、可视化操作入口。 |
api-gateway |
API 网关 | Spring Cloud Gateway | 全局 API 请求拦截、路由转发、鉴权、安全审计、统一访问入口。 |
users |
用户与租户服务 | Spring Boot + DDD | 用户、租户、账号、登录态、用户生命周期、用户与 Agent 绑定关系管理。 |
agent-master |
Agent 管理与调度中心 | Bun + TypeScript + Fastify | Agent 注册、启动、停止、重启、回收、状态管理和 Agent API 代理转发。 |
agent-runtime-image |
Agent 运行时镜像 | Dockerfile | 维护 Agent 基础运行环境，供 agent-master 调度创建用户专属 Agent 实例。 |
db-gateway |
数据库网关 | Apache ShardingSphere-Proxy Cluster | 统一数据库访问入口，基于 ShardingSphere-Proxy 集群支撑共享应用服务实例下的租户数据隔离、租户路由、读写分离、SQL 审计和多数据源治理。 |
model-gateway |
模型网关 | LiteLLM Proxy first，New API optional | 统一模型调用入口，优先基于 LiteLLM Proxy 实现 OpenAI-compatible API、模型路由、retry、fallback、调用日志和成本观测；后续按渠道、令牌、额度和分组管理需求评估 New API。 |
skills-market |
技能市场 | Node.js + npx + Markdown | 管理技能商品，支持技能发布、交易、下载、安装、卸载和版本管理；Agent 通过 npx 请求目标技能，完成交易后下载并安装到自身，技能描述以 Markdown 承载。 |
dashboard |
运营后台 | Node.js 全栈 | 前后端一体开发的运营后台，用于用户、租户、Agent、技能、模型调用、资源使用和运营数据管理。 |
说明：
- 每个项目都应该有清晰的工程边界，不把平台能力堆在单体服务里。
- 网关、用户、Agent 调度、运行时、模型、数据和技能市场分别承担不同平台职责。
- 后续可以根据实现复杂度，将部分模块先合并为 MVP 实现，再逐步拆分为独立服务。
flowchart LR
User[用户] --> WebUI[webui\nReact + Vite]
Admin[运营人员] --> Dashboard[dashboard\nNode.js 全栈]
WebUI --> ApiGateway[api-gateway\nSpring Cloud Gateway]
Dashboard --> ApiGateway
ApiGateway --> Users[users\nSpring Boot + DDD]
ApiGateway --> AgentMaster[agent-master\nBun + TS + Fastify]
ApiGateway --> SkillsMarket[skills-market\nNode.js + npx + Markdown]
AgentMaster --> Runtime[agent-runtime-image\nDockerfile]
Runtime --> ModelGateway[model-gateway\nLiteLLM Proxy first]
Runtime --> DbGateway[db-gateway\nShardingSphere-Proxy Cluster]
Runtime --> SkillsMarket
SkillsMarket --> SkillPkg[技能商品\nMarkdown + package]
ModelGateway --> Models[模型供应商\n主模型 / 备用模型]
DbGateway --> Databases[数据库集群\n租户数据隔离]
Users --> Audit[审计与计量]
AgentMaster --> Audit
SkillsMarket --> Audit
ModelGateway --> Audit
DbGateway --> Audit
- 用户通过
webui发起注册。 - 请求进入
api-gateway。 api-gateway完成基础安全检查并转发到users。users创建用户身份、租户归属和初始工作空间。users为用户创建或登记专属 Agent 绑定关系。- 绑定关系供
agent-master后续启动 Agent 时使用。
sequenceDiagram
participant U as 用户
participant W as webui
participant G as api-gateway
participant US as users
participant AM as agent-master
participant AR as Agent Runtime
U->>W: 输入账号并登录
W->>G: 提交登录请求
G->>US: 转发身份校验
US-->>G: 返回登录态与用户上下文
G-->>W: 返回登录结果
W->>G: 加载用户工作空间
G->>AM: 请求启动用户专属 Agent
AM->>AR: 创建或唤醒 Agent 实例
AR-->>AM: 返回运行状态
AM-->>G: 返回 Agent 会话入口或代理路径
G-->>W: 返回工作空间与 Agent 状态
W-->>U: 进入 Agent 交互界面
- 用户通过
webui登录。 api-gateway完成鉴权入口控制。users校验身份并返回登录态。webui加载用户工作空间。agent-master根据用户绑定关系启动专属 Agent。agent-master返回 Agent 会话入口或代理路径。- 用户开始与 Agent 交互。
- 用户在
webui中发送消息或操作指令。 - 请求经
api-gateway进入平台。 api-gateway校验身份、租户和访问边界。- 请求转发到
agent-master。 agent-master将请求代理到对应用户的 Agent 实例。- Agent 按需调用技能、模型网关或数据网关。
- 执行结果原路返回给用户。
sequenceDiagram
participant U as 用户
participant W as webui
participant G as api-gateway
participant AM as agent-master
participant AR as Agent Runtime
participant SM as skills-market
U->>W: 浏览技能市场并选择技能商品
W->>G: 提交技能安装意图
G->>AM: 将安装意图传递给专属 Agent
AM->>AR: 通知 Agent 发起安装
AR->>SM: 通过 npx 请求目标技能
SM->>SM: 校验状态 / 版本 / 依赖 / 价格 / 权限
SM-->>AR: 交易完成并返回技能包
AR->>AR: 根据 Markdown 描述和元数据安装技能
AR-->>AM: 返回安装结果
AM->>AR: 重启或刷新 Agent
AR-->>AM: 返回新技能加载状态
AM-->>G: 返回技能生效结果
G-->>W: 返回安装完成状态
W-->>U: 用户继续使用新技能
- 用户在
webui中访问skills-market。 - 用户选择技能商品，并将安装意图传递给专属 Agent。
- Agent 发起技能购买和安装请求。
- Agent 通过
npx请求skills-market中的目标技能。 skills-market校验技能状态、版本、依赖、价格和安装权限。- 交易完成后，平台记录用户、Agent 与技能的交易和安装关系；当前阶段交易可以为免费。
- Agent 下载技能包，并根据技能的 Markdown 描述和元数据完成安装。
- Agent 重启后加载最新技能配置。
- 用户重新进入交互，技能生效。
sequenceDiagram
participant U as 用户
participant W as webui
participant G as api-gateway
participant AM as agent-master
participant AR as Agent Runtime
participant D as dashboard
U->>W: 退出 / 关闭工作空间 / 长时间无活动
W->>G: 上报离开事件或会话超时
G->>AM: 请求检查 Agent 回收条件
AM->>AR: 查询 Agent 当前状态
AR-->>AM: 返回运行状态与待保存信息
AM->>AM: 保存必要会话状态和运行记录
AM->>AR: 停止并回收 Agent 实例
AR-->>AM: 返回回收结果
AM-->>G: 返回资源释放状态
G-->>W: 更新工作空间状态
AM-->>D: 写入运营与审计记录
- 用户主动退出、关闭工作空间或长时间无活动。
webui或平台会话机制触发离开事件。agent-master判断 Agent 是否可以回收。- 平台保存必要会话状态和运行记录。
agent-master停止并回收用户专属 Agent 实例。- 运营后台可以查看 Agent 回收记录和资源释放情况。
Agent 不是长期无边界运行的黑盒进程。平台必须知道 Agent 属于谁、为什么启动、当前状态是什么、什么时候应该回收。
模型访问、数据访问和外部 API 调用不能散落在 Agent 内部直接完成。平台通过 api-gateway、model-gateway、db-gateway 和技能运行约束统一治理访问边界。
其中，model-gateway 优先基于 LiteLLM Proxy 建设，先解决 Agent 模型调用的统一入口、模型路由、retry、fallback、调用日志和成本观测问题。New API 暂作为后续可选能力，用于模型渠道、令牌、额度和分组管理，不在 MVP 阶段强绑定。
db-gateway 基于 Apache ShardingSphere-Proxy Cluster 建设。MVP 阶段先作为统一数据库访问入口，约束 Agent 和平台服务不要直连真实数据库；商业化阶段再逐步承载租户路由、读写分离、数据脱敏、SQL 审计和多数据源治理。
平台不应该为每个业务场景硬编码 Agent 能力。业务能力应尽量通过技能扩展、安装和版本治理进入 Agent。
平台面向商业化演进，用户、租户、数据、技能安装关系、模型调用记录和运营指标都需要具备隔离边界。
Agent 的启动、停止、重启、技能加载、模型调用、数据访问和异常状态都需要能够被平台观测和审计。
MVP 阶段优先跑通用户注册、登录、Agent 自动启动、交互、技能安装、重启生效和自动回收。多租户高级治理、复杂计费、高可用和企业集成在闭环稳定后再逐步增强。
后续仓库可以按以下方向组织：
agent-platform/
├── README.md
├── docs/
│ ├── architecture.md
│ ├── mvp-flow.md
│ ├── module-boundaries.md
│ └── roadmap.md
├── webui/
├── api-gateway/
├── users/
├── agent-master/
├── agent-runtime-image/
├── db-gateway/
├── model-gateway/
├── skills-market/
└── dashboard/
目录说明：
docs/：放置更细的架构设计、流程设计、模块边界和演进路线。- 各工程目录：按模块独立维护代码、README、启动方式和验证命令。
- 如果某些模块未来拆分为独立仓库，本仓库可以保留为平台总设计和编排入口。
- 初始化仓库结构；
- 明确模块边界和接口方向；
- 实现用户注册、登录和用户-Agent 绑定；
- 实现 Agent 自动启动、交互和回收；
- 实现技能安装与 Agent 重启生效；
- 建立基础运行和验证流程。
- 完善用户、租户和工作空间模型；
- 增强
api-gateway的鉴权、安全审计和访问控制； - 建设基于 LiteLLM Proxy 的
model-gateway，优先验证 OpenAI-compatible API、模型路由、retry、fallback、流式输出、tool call 透传、调用日志和成本观测； - 建设基于 Apache ShardingSphere-Proxy Cluster 的
db-gateway，支撑租户隔离、租户路由、读写分离、SQL 审计和多数据源治理； - 建设
dashboard的基础运营观测能力。
- 支持技能市场治理，技能可作为商品完成交易、下载和安装；当前阶段交易可以免费，后续围绕套餐、订阅或用量统计预留商业化扩展边界；
- 支持租户级资源配额和成本统计；
- 支持企业级权限、审计和部署配置；
- 支持更完整的运营数据分析；
- 支持私有化部署和客户级配置扩展。
- 引入更多 Agent 模板；
- 扩展技能开发、测试、发布和安装规范；
- 接入更多模型供应商和工具系统；
- 建立 Agent、技能、模型和数据访问的审计闭环。
当前阶段不承诺：
- 不承诺所有模块已经完成；
- 不承诺开箱即用的生产级部署；
- 不承诺完整商业计费体系已经实现；
- 不承诺替代所有业务系统；
- 不承诺 Agent 可以无限制访问模型、数据库或内部工具；
- 不在公开仓库中暴露任何真实客户、内部系统、密钥、私有接口或未公开指标。
作为 public 仓库，本仓库遵循以下约束：
- 公开内容只描述通用架构、平台设计、抽象流程和可公开实现；
- 不提交真实密钥、Token、Cookie、
.env、账号密码和内部访问凭证； - 不提交真实客户材料、内部系统地址、未公开业务指标和私有项目细节；
- 设计文档可以讨论安全原则，但不公开可被利用的内部绕过细节；
- 架构图、流程图、时序图等图表统一使用 Mermaid，便于版本管理、代码审查和 GitHub 直接渲染；
skills-market统一表达为平台侧技能市场，技能即商品；Agent 通过npx请求技能市场中的目标技能，完成交易后下载并安装到自身，当前阶段交易可以免费；- 代码和文档变更应保持模块边界清晰，避免把业务逻辑、平台治理和运行时调度混在一起。
当前仓库处于初始化阶段：
- 已创建 public 仓库；
- 已建立顶层 README 设计文档；
- 已规划核心工程项目和 MVP 流程；
- 后续将补充目录结构、模块设计、接口契约和最小可运行实现。
本项目采用 MIT License。
详见 LICENSE。