06 · 如何设计 Agent Platform 的架构？ - Design Principles
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：01 · Agent Platform 是什么？它如何工作？ - Fundamentals
文档类型：专题研究
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：如何在明确平台边界、对象模型和运行机制的基础上，制定可验证的 Agent Platform 架构原则，权衡复用、隔离、可靠性、安全性、成本与演进速度，并将原则转化为可执行的架构决策？
专题导读
本篇属 Fundamentals。本篇是 04 · Agent Platform → 01 · Fundamentals 的第六篇、也是本章最后一篇专题。前五篇依次回答定义与边界、核心组件、运行架构、平台类型、平台对象及生命周期；本篇把这些认识转化为可用于设计评审的架构原则、决策规则与验证标准。后续 P1 - P2 - P3 - P4 - P5 - P6 - P7 - P8 - P9 - P10 - P11 - P12 研究具体技术服务，F1 - F2 - F3 - F4 - F5 - F6 - F7 - F8 - F9 - F10 - F11 - F12 研究产品功能，工程实践章研究落地路径。
研究立场：Agent Platform 没有唯一正确的部署拓扑。控制面/执行面是职责视图；模块化不等于微服务；多租户不等于必须共享计算资源；“可扩展”也不意味着从第一天起引入分布式系统。架构设计应以业务约束、失效后果、成本与可观测证据为依据。
核心结论：优秀的平台架构首先明确边界和契约，再设计状态与权限，随后保证任务可恢复、结果可追踪，最后在证据支持下拆分服务和扩大规模。将安全、治理、运行可靠性视为架构内生约束，而非上线前的附加功能。
一、设计目标、范围与非目标
1.1 平台架构要回答什么
平台架构至少需要回答五组问题：为谁服务（用户、开发者、管理员、外部系统）；管理什么（Agent Definition、Version、Deployment、Run、Artifact 等）；如何运行（准入、排队、执行、状态反馈、审批、交付）；谁能做什么（身份、租户、权限、资源边界）；出错后如何处理（幂等、重试、恢复、回滚、审计）。
应同时维护四种视图：①能力视图，说明平台提供什么；②逻辑组件视图，说明谁承担职责；③部署视图，说明服务如何落地；④产品视图，说明用户如何接触能力。四者相互映射但不可混同。
1.2 约束先于技术选型
设计前记录：用户规模、并发 Run 数、平均与长尾执行时长、敏感数据类别、租户数量、部署环境、预算上限、可接受恢复时间、人工审批比例、外部工具失败概率。未知参数应标记为待测假设，不要伪装成事实。
非目标示例：早期 Studio MVP 不追求跨区域主动 - 主动、多云调度、复杂插件市场、细粒度组织计费。将非目标写入 ADR，可减少过度设计。
二、十二项核心架构设计原则
| 原则 | 核心要求 | 典型反例 | 可检查证据 |
|---|---|---|---|
| D1 边界清晰 | 区分平台职责与 Agent System 职责 | 平台直接硬编码 Agent 推理循环 | 组件职责表、调用契约 |
| D2 对象明确 | 定义/版本/部署/运行/产物独立标识 | 用单一 agent.status 表达所有状态 | 领域模型、状态机 |
| D3 契约优先 | 通过稳定 API、事件与模式连接模块 | 前端直接依赖运行器内部结构 | OpenAPI/事件 Schema |
| D4 控制与执行分责 | 准入治理与实际执行分别建模 | UI 请求线程执行数小时任务 | 控制流/执行流时序图 |
| D5 安全默认 | 最小权限、默认拒绝、密钥隔离 | Agent 继承平台管理员凭据 | 权限测试、密钥扫描 |
| D6 隔离可证明 | 租户、工作空间、资源访问边界清楚 | 仅依赖前端隐藏其他租户数据 | 跨租户负向测试 |
| D7 状态可恢复 | Run 持久化、幂等、重试与恢复 | 进程重启后任务记录消失 | 故障注入与恢复测试 |
| D8 可观测可审计 | 关联用户请求、Run、工具、产物 | 只有散乱文本日志 | Trace、审计记录 |
| D9 可扩展但不过度 | 先模块化，再按瓶颈拆分 | 无负载证据即全微服务 | 压测与 ADR |
| D10 资源有边界 | 限流、预算、配额、超时 | Agent 无上限循环调用模型 | 配额拒绝与成本测试 |
| D11 变更可回退 | 不可变版本、灰度、兼容与回滚 | 覆盖生产 Agent 配置无法追溯 | 发布记录、回滚演练 |
| D12 人可干预 | 高风险动作审批、暂停与终止 | 人工审批只在 UI 中模拟 | 审批状态与权限测试 |
这些原则是本文提出的研究性设计框架，不是某一标准组织发布的十二条规范。以下逐项解释权衡与落地。
三、边界与模块化：D1 - D3
3.1 平台与 Agent System 的职责边界
Agent System 内部关注模型调用、工具使用、推理、编排、检查点和执行策略；Agent Platform 关注跨多个 Agent System 的注册、版本、部署、准入、配额、租户、运营和交付。平台可以内嵌 Agent Runtime，但架构设计仍应保持职责分离，以便更换执行引擎而不重写产品与管理系统。
平台对运行器的最小契约可抽象为：submit(run_spec) -> run_id、get_status(run_id)、cancel(run_id)、stream_events(run_id)；长任务还可能需要 pause/resume 与 checkpoint 引用。上述接口是教学契约，不是通用行业 API；不同执行引擎可用适配层实现。
3.2 模块化与部署边界不是同一回事
建议在单体后端内先建立清晰模块：Identity、Workspace、Registry、Deployment、Run Control、Resource Catalog、Artifact、Audit。模块通过内部接口调用，避免直接跨模块修改数据库表。只有出现独立扩容、故障隔离、团队协作或合规边界等可验证需求时，再考虑拆分部署。
权衡：单体部署降低网络故障、分布式事务与运维成本；服务拆分改善独立伸缩和隔离，却引入事件一致性、版本兼容、链路追踪和服务治理。架构决策应记录为什么拆分、何时拆分、如何回滚。
3.3 契约版本与兼容性
Agent Definition、Run Spec、Tool Binding、Event、Artifact Metadata 应具有明确 schema。兼容变更可以增加可选字段；破坏性变更需要版本化和迁移。客户端与运行器不可依赖“某个 JSON 恰好包含字段”的偶然行为。对于异步事件，消费者必须容忍重复投递，并在契约中定义事件标识、时间、来源与对象版本。
四、控制面、执行面与状态：D4、D7
4.1 控制面与执行面的交互
sequenceDiagram
participant U as User / Client
participant C as Control Plane
participant Q as Queue / Dispatch
participant E as Execution Plane
participant S as State Store
participant A as Artifact Store
U->>C: Create Run (idempotency key)
C->>C: Authenticate / Authorize / Quota
C->>S: Persist Run + Version Snapshot
C->>Q: Dispatch Run
C-->>U: run_id + accepted
Q->>E: Execute run_id
E->>S: Update status / checkpoint
E->>A: Save artifacts
E->>S: Finalize outcome + references
U->>C: Query / Subscribe
C->>S: Read status and artifacts
C-->>U: State + result links图中 Queue 与 State Store 是逻辑角色，可在早期使用数据库任务表和单个 Worker 实现；不必强制采用独立消息中间件。
4.2 可靠状态机
参考 Run 状态：created → queued → running → succeeded | failed | cancelled，并允许 running → waiting_approval → queued/running。真正的实现必须定义合法迁移、权限、终态不可逆规则和超时行为。Run 与 Attempt 应分开：同一个业务 Run 可以有多个执行尝试，避免重试导致用户看到重复任务。
状态迁移要满足持久化先于可见承诺：系统不能先向用户宣布已接收任务，却没有可恢复的任务记录。使用事务性 Outbox 或同类机制可以减少“写数据库成功但派发消息失败”的不一致；是否需要该机制取决于实际存储和队列组合。
4.3 幂等、重试与副作用
创建 Run 应支持客户端幂等键；Worker 处理消息按至少一次投递假设设计。对纯计算步骤可安全重试；对发邮件、扣费、删除文件等外部副作用，必须采用操作幂等键、结果核对或人工补偿，不能假设重试天然安全。Exactly-once 不应作为跨外部系统的默认承诺。
4.4 故障恢复策略
| 故障 | 期望行为 | 验证方法 |
|---|---|---|
| Web 服务重启 | 已接受 Run 仍可查询 | 重启 API 进程 |
| Worker 崩溃 | Run 不永久卡在 running | 杀死 Worker 并恢复 |
| 模型超时 | 记录失败原因并受控重试 | 注入超时 |
| 重复队列消息 | 不产生重复外部副作用 | 重放消息 |
| 审批期间重启 | 审批请求和状态保留 | 重启并继续审批 |
| 产物写入失败 | 不虚报任务交付成功 | 模拟存储不可用 |
五、安全、隔离与治理：D5、D6、D10、D12
5.1 身份与权限必须贯穿整个调用链
至少区分 User Identity、Service Identity 与 Agent Execution Identity。用户请求经鉴权后形成受约束的执行上下文，Worker 只能使用被授予的资源与工具，不应直接继承后台超级管理员凭据。执行敏感操作时，应检查发起主体、租户、资源、操作和审批状态；对高风险操作实行默认拒绝。
5.2 多租户隔离不是单个字段
租户隔离覆盖身份、数据查询、对象存储、缓存、队列、密钥、日志、计量和计算资源。可以采用共享数据库带强制租户过滤、数据库级行安全、独立数据库或独立计算池等模式；不同模式在成本、性能、风险和运维复杂度上有不同取舍。
最重要的验证是负向测试：A 租户是否可能通过 API、资源 ID、共享链接、日志或工具连接读取 B 租户数据。仅在 UI 中隐藏资源不是隔离。
5.3 资源边界与成本控制
设置用户/租户/工作空间三级预算和配额，并定义生效优先级。典型控制包括并发 Run 数、单 Run 最大时长、模型 Token 预算、工具调用次数、文件大小和存储保留期。预算用尽应明确停止、降级或申请授权，不能让 Agent 无限重试。
5.4 人工审批是后端状态，不是弹窗
高风险工具调用应产生持久化 Approval 对象，关联 Run、待执行动作、审批人、超时、决定与审计证据。审批完成前，执行器不能绕过审批直接继续。审批的撤销、超时和重复提交都应有明确状态迁移规则。
六、可观测性与可审计性：D8
平台至少应关联 tenant_id、workspace_id、agent_version_id、run_id、attempt_id、trace_id。指标包括 Run 接受率、成功率、P95 完成时间、排队时间、恢复率、人工审批等待时间、每 Run 成本与租户资源使用量。应区分业务指标（报告是否交付）和基础设施指标（CPU、队列积压）。
审计日志应记录主体、动作、对象、时间、结果和策略依据；对于密钥、个人数据与模型输入输出，遵循最小采集和保留策略，避免为了观测而过度收集敏感内容。日志、Trace、事件和审计记录各有用途，不可互相替代。
七、扩展性、发布与演进：D9、D11
7.1 扩展优先级
优先扩展无状态 API 与独立 Worker；在确有证据时再引入分区队列、专用执行池、缓存层和租户级资源池。伸缩应基于队列等待、任务执行时长、资源消耗与成本指标，而不是仅凭请求 QPS。
7.2 版本固定与安全发布
已发布的 Agent Version 建议不可变。每个 Run 固定 Agent/Workflow 版本、模型路由策略及重要资源引用，以便回溯。发布流程应包含验证、审批、灰度、监控、回滚；注意模型服务与外部工具即使版本固定，行为也可能受提供方更新或外部环境变化影响，因此“版本固定”不等于结果完全可复现。
7.3 演进阶段
| 阶段 | 推荐架构 | 必备能力 | 暂不强求 |
|---|---|---|---|
| S0 概念验证 | 单进程或简单 Web + Worker | 端到端任务闭环 | 多租户、复杂队列 |
| S1 单租户 MVP | 模块化后端、数据库、任务队列 | Run 持久化、版本、审批、产物 | 多区域部署 |
| S2 团队协作 | 权限模型、Workspace、审计、观测 | 团队角色、隔离测试、故障恢复 | 大规模插件市场 |
| S3 平台化运营 | 标准 API/SDK、租户隔离、配额 | 发布治理、成本核算、兼容策略 | 无需求的全球化架构 |
| S4 规模化生态 | 独立执行池、插件与扩展机制 | 容量规划、生态安全、SLO | 固定的微服务数量 |
阶段是建议的成熟度路径，并非行业标准，也不要求每个平台按相同顺序建设。
八、架构权衡与决策方法
8.1 典型权衡矩阵
| 决策 | 方案 A | 方案 B | 主要判断条件 |
|---|---|---|---|
| 后端组织 | 模块化单体 | 微服务 | 团队规模、隔离、独立扩容 |
| 任务调度 | 数据库任务表 | 消息队列 | 吞吐、重试、故障模型 |
| 执行承载 | 共享 Worker | 租户专属执行池 | 安全级别、噪声邻居 |
| 数据隔离 | 共享库 + 行级隔离 | 独立库 | 合规、成本、恢复粒度 |
| Agent 构建 | 代码优先 | 可视化优先 | 用户技能、表达能力 |
| 工作流表示 | 静态 DAG | 动态图/状态机 | 任务动态性、可解释性 |
| 发布策略 | 原地覆盖 | 不可变版本 + 灰度 | 可追溯与回滚需求 |
8.2 Architecture Decision Record（ADR）模板
ADR-ID：
决策主题：
状态：Proposed / Accepted / Superseded
背景与约束：
备选方案：
决策及理由：
主要风险：
被拒方案的原因：
验证指标与实验：
回滚条件：
复审触发条件：任何重要架构决策都应保留“为什么这样做”的证据，而不仅是最终技术栈。
九、贯穿案例：研究报告 Studio 的架构设计
9.1 场景与约束
Studio 包含选题 Agent、研究 Agent、分析 Agent、审核 Agent；支持审核返工、人工确认、长任务运行、资料引用与报告交付。用户需要查看执行状态、批准关键步骤，并能够在异常后恢复工作。初期假设为少量用户和有限并发；真实容量待压测。
9.2 最小可行架构
flowchart TB
UI[Studio Web UI] --> API[Platform API / Control Module]
API --> DB[(PostgreSQL: definitions, runs, approvals)]
API --> Q[Task Queue]
Q --> W[Worker / Agent System Runtime]
W --> DB
W --> OBJ[(Artifact Storage)]
W --> EXT[Models / Tools / Knowledge]
API --> OBJ
API --> AUD[Audit / Metrics]
W --> AUD建议的初始模块：①用户与 Workspace；②Agent/Workflow Registry；③Run Controller；④Approval；⑤Artifact；⑥Resource Connector；⑦Audit。先以模块化单体加 Worker 落地，避免将每个模块拆为独立微服务。
9.3 一次完整运行的契约
- 用户在 Studio 中选择已发布的 Workflow Version，提交研究任务。
- Control Module 验证用户身份、Workspace 权限、预算与幂等键。
- 平台创建 Run，记录版本快照与输入引用，并可靠派发任务。
- Worker 驱动 Agent System，记录步骤事件、Attempt 与检查点。
- 选题审核或高风险操作需要人工确认时，Run 进入等待审批状态。
- 用户审批后，平台核验审批权限与版本一致性，再恢复执行。
- 研究报告保存为 Artifact，关联 Run、版本、引用证据和访问策略。
- 用户查看结果，平台保留审计链路，并按策略归档。
9.4 不应过早引入的复杂性
初期不必实现完整 Agent Marketplace、跨云容灾、多层组织计费、跨区域调度或复杂微服务网格。若研究资料涉及敏感数据，隔离和授权的优先级则必须提前提高。“MVP”只允许缩小功能范围，不允许跳过关键安全边界。
十、验证策略：从原则到可执行检查
以下均为建议实施的测试，不是本文已运行的测试。
| 验证项 | 测试设计 | 通过标准示例 |
|---|---|---|
| 对象边界 | 创建版本、部署、Run 后逐一查询 | ID、状态、引用关系独立 |
| 幂等提交 | 同一幂等键重复提交 | 只生成一个业务 Run |
| 恢复能力 | 运行中强制停止 Worker | Run 可恢复或明确失败 |
| 跨租户隔离 | A 用户读取 B 的 Run/Artifact | 拒绝并记录审计 |
| 审批不可绕过 | 未审批直接调用恢复接口 | 服务端拒绝 |
| 配额执行 | 超预算后继续请求执行 | 明确拒绝或授权升级 |
| 发布回滚 | 新版本灰度失败 | 能切回旧版本 |
| 追踪链路 | 从报告反查任务与 Agent 版本 | 引用链完整 |
| 负载与成本 | 逐步增加并发 Run | 获得容量/成本曲线 |
| 外部副作用 | 重放工具调用事件 | 不重复发信/扣费 |
验收重点：架构原则必须落到接口、数据约束、状态机、监控指标或测试用例。仅在文档中声明“安全、可靠、可扩展”不构成验证。
十一、常见架构反模式
反模式 A：把 Builder 当成 Platform。 可视化编辑器缺少版本、运行、权限与生命周期治理时，仍只是平台的一项能力。
反模式 B：把微服务当成成熟度。 没有清晰领域边界与运维能力的服务拆分，会提高故障面与维护成本。
反模式 C：把 Agent Session 当成 Run。 Session 是交互上下文，Run 是一次可追踪执行；二者可以关联但不应混用。
反模式 D：将业务状态保存在前端。 审批、取消、预算与执行进度必须由服务端维护权威状态。
反模式 E：只记录成功结果。 缺少 Attempt、失败原因和版本快照，会使故障恢复和质量分析无法实施。
反模式 F：用提示词代替权限控制。 提示词可以约束意图，但不能替代工具权限、执行隔离和后端授权。
反模式 G：所有能力一次到位。 没有实际使用数据就建设插件市场、跨区域调度和复杂计费，容易延误产品验证。
十二、与后续研究专题的映射
| 本篇设计原则 | 后续技术专题 | 后续产品专题 |
|---|---|---|
| D1/D3 边界与契约 | P1、P3、P4、P8 | F1 - F2 - F3 - F4、F11 |
| D4/D7 执行与恢复 | P2、P5、P6 | F6 - F7 - F8 |
| D5/D6 安全与隔离 | P11、P12 | F5、F12 |
| D8 观测与审计 | P5、P10、P12 | F8、F10、F12 |
| D9 扩展与集成 | P7 - P8 - P9 | F7、F11 |
| D10 预算与配额 | P7、P12 | F6、F12 |
| D11 发布与回滚 | P3、P5 | F4、F9 |
| D12 人工介入 | P1、P5、P6 | F6、F7 |
本篇的作用是确定设计准则；后续专题需进一步说明数据结构、接口、算法、部署和验证方法，不在本篇重复所有实现细节。
十三、研究结论
- 平台架构的首要任务是管理边界与契约：区分 Agent System 内部执行机制与 Agent Platform 跨系统管理职责，并明确对象模型。
- 控制面/执行面是逻辑分责，而非强制微服务拓扑：可以从模块化单体起步，按独立扩容、隔离和可靠性需求逐步演进。
- 状态、权限与恢复是平台的基础工程约束：Run 持久化、版本固定、幂等、租户隔离、人工审批与审计需要在架构阶段纳入。
- 可扩展性应以证据驱动：通过压测、SLO、成本与故障记录判断何时拆分服务、增加执行池和复杂调度。
- 架构设计必须可验证：每项原则至少对应一项契约、状态约束、指标或测试用例。
- Studio 的合理路径是先闭环、后平台化：先验证任务执行和交付，再建设团队协作、标准 API、多租户与生态能力。
至此，04 · Agent Platform → 01 · Fundamentals 六篇专题研究的主题链条完成：Definition & Boundaries → Core Components → Platform Architecture → Platform Types → Lifecycle Management → Design Principles。下一章进入 02 · Agent Platform 是如何构建和运行的？ - Technical Architecture，建议先撰写章节概述，再进入 P1 Control Plane。
第六轮跨章节契约核对（v1.3-r1；2026-11-01）
[平台设计决策 / 待测试] 本节是领域级一致性修订说明，优先于本篇不一致的历史局部示例；不表示已执行数据库迁移、API 合约或运行测试。统一参考：
04-Agent-Platform-Canonical-Contracts-v1.3-r1.md。
本篇 created、waiting_approval 仅是概念性状态示意；统一 Run 持久化枚举不含 created 或 waiting_approval。Run 创建受理后从 queued 起，审批等待采用 waiting + status_reason=approval；created 可作为创建流程或其他对象的状态，不可混入 Run execution_status。
上述映射不应机械替换其他对象（如 ManagementOperation、Deployment）的同名状态；正式实施应更新 OpenAPI/JSON Schema、SQL 约束、事件消费者、UI 映射及测试。
附录 A：参考文献与原始资料
以下列出与本文设计原则直接相关的官方技术资料与经典工程文献。链接作为进一步核验入口；本文未进行在线逐页核对，产品与规范版本应以原始资料的最新正式发布内容为准。
- NIST, AI Risk Management Framework (AI RMF 1.0), 2023. nvlpubs.nist.gov/nistpubs/ai/NIST.AI.100-1.pdf
- NIST, Zero Trust Architecture (SP 800-207), 2020. csrc.nist.gov/pubs/sp/800/207/final
- OWASP, Top 10 for Large Language Model Applications. genai.owasp.org/llm-top-10
- OpenTelemetry, Documentation. opentelemetry.io/docs
- Google, Site Reliability Engineering, online book. sre.google/sre-book/table-of-contents
- Kubernetes, Controllers. kubernetes.io/docs/concepts/architecture/controller
- Kubernetes, Multi-tenancy. kubernetes.io/docs/concepts/security/multi-tenancy
- AWS, The Amazon Builders' Library - Making retries safe with idempotent APIs. aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs
- Microsoft, Azure Architecture Center - Architecture styles. learn.microsoft.com/en-us/azure/architecture/guide/architecture-styles
- Martin Fowler, Monolith First. martinfowler.com/bliki/MonolithFirst.html
- Michael Nygard, Documenting Architecture Decisions. cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- OpenAPI Initiative, OpenAPI Specification. spec.openapis.org/oas/latest.html
- CloudEvents, Specification. github.com/cloudevents/spec
- PostgreSQL, Row Security Policies. www.postgresql.org/docs/current/ddl-rowsecurity.html
- CNCF, Cloud Native Security Whitepaper. github.com/cncf/tag-security/tree/main/security-whitepaper
附录 B：研究证据、验证声明与适用边界
已知来源与可核验事实：零信任、最小权限、幂等、可观测性、控制器模式、行级安全、API 规范与事件契约均有公开工程资料可供核验。具体应用时须根据所选技术版本确认实现条件。
研究性归纳：本文十二项原则、四种架构视图、Studio 演进阶段、能力映射与验收矩阵均为综合工程实践形成的研究框架，不宣称存在统一行业标准。
未验证内容：示例时序图、状态机、接口、架构拓扑、故障测试和容量策略是参考方案；本文未运行真实系统、压力测试、渗透测试或故障注入，因此不声称达到任何生产 SLO。
适用范围：主要面向可创建、配置、运行、管理多个 Agent 或 Agent System 的软件平台；对于单用途脚本、离线研究原型或严格隔离的高合规环境，应按实际需求缩减或增强设计。
后续验证任务：选择一套具体技术栈，将上述对象模型落成数据库 schema 与 API；对 Run 幂等、Worker 崩溃、跨租户访问、审批绕过、版本回滚进行可重复的集成测试，并记录结果与架构决策。