多租户分布式 AI Agent 设计：从功能架构到执行链路的完整拆解

Python_金钱豹

233人浏览 · 2026-06-08 20:39:54

Python_金钱豹 · 2026-06-08 20:39:54 发布

开篇导读

很多人做 AI Agent 产品时，第一反应是：

接入大模型。

加一个聊天界面。

再提供几个工具调用能力。

但真正要做一个可商用、可扩展、可管控的 AI Agent 平台，难点并不在“让模型回复用户”，而在于：

如何让模型安全、稳定、可追踪地执行真实任务。

尤其当平台面向多个租户、多个工作空间、多个用户和多个任务时，系统复杂度会迅速上升。

一个成熟的多租户分布式 AI Agent 平台，至少要解决这些问题：

问题	对应能力
用户和租户之间如何隔离？	Tenant / Workspace / 权限体系
Agent 的一次执行如何排队、运行、暂停和恢复？	Task / Run / Queue / Worker
模型如何安全调用工具？	Tools / Tool Context / Guardrails / Policy
命令和代码如何隔离执行？	Sandbox / K8s Pod
敏感操作如何人审？	Human-in-the-loop / Approval
运行过程如何展示？	Streaming / Event Stream / Tracing
产物如何沉淀？	Artifact / Object Storage
成本如何统计？	Usage / Billing / Quota
定时任务如何执行？	Scheduler / Synthetic Message / Run

所以，AI Agent 平台不是一个聊天系统，而是一套由模型驱动的任务执行系统。

这篇文章围绕 “多租户分布式 AI Agent 设计”，从功能模块、核心概念、实现原理和执行链路几个角度，对这类平台进行完整拆解。

一、先看整体架构

一句话总结

多租户分布式 AI Agent 平台的核心设计原则是：

模型只负责决策，平台负责权限、安全、执行、记录和交付。

模型不能直接访问数据库、文件系统、Kubernetes、对象存储、审批系统或外部网络。

所有真实动作都必须经过平台定义的工具入口。

整体分层

可以把整个平台拆成 8 层：

层级	核心模块	主要职责
用户入口层	Browser / Client	创建任务、发送消息、审批、查看事件、下载产物
接入层	Web / API	鉴权、租户解析、权限校验、创建 Message / Run
业务域层	Tenant / Workspace / Task / Run	多租户隔离、业务上下文、任务状态
队列调度层	Agent Run Queue / Scheduler	异步执行、定时触发、分布式锁
执行层	Agent Worker / Runner	消费 Run，驱动 Agent loop
Runtime 层	Agent / Tools / Guardrails / Sessions / Tracing	模型推理、工具调用、安全校验、上下文管理
平台服务层	Skill / Approval / Sandbox / Artifact / Usage	技能、审批、沙箱、产物、用量
基础设施层	Postgres / Redis / Object Storage / K8s	数据、队列、文件、隔离执行环境

主执行链路

一次普通用户任务的链路可以概括为：

用户发送消息  -> API 鉴权与权限校验  -> 写入 Message  -> 创建 Run  -> Run 入队  -> Agent Worker 消费 Run  -> Runner 启动 Agent Loop  -> 模型推理  -> 如需工具，进入 Tool Layer  -> 权限 / Guardrails / Policy 校验  -> 必要时 Approval  -> Sandbox / Service 执行  -> 结果返回模型  -> 模型继续推理  -> 输出最终结果  -> 写 Assistant Message  -> 登记 Artifact / Usage / Events  -> Run completed

这条链路解决的是一个核心问题：

让模型能够做真实事情，同时又不失控。

二、核心业务对象设计

多租户 Agent 平台里，核心对象不多，但每个对象都非常关键。

可以先用一张关系图理解：

Tenant  -> Users / Tenant Members  -> Workspace      -> Task / Session          -> Messages          -> Runs          -> Run Events          -> Sandbox Session          -> Artifacts          -> Skills

Tenant：第一隔离边界

它解决什么问题？

Tenant 用来表示一个客户、一个组织或一个企业空间。

它是整个平台的第一隔离边界。

平台中的用户、工作空间、任务、消息、运行过程、文件、产物、技能、审批、Sandbox、用量和审计记录，都应该归属于某个 Tenant。

它的核心作用

作用	说明
数据隔离	不同租户的数据不能互相访问
权限边界	用户必须属于当前租户才能操作
资源归属	Sandbox、Artifact、Usage 都要归属到租户
计费统计	Token、工具调用、存储和 Sandbox 成本按租户聚合
审计追踪	安全事件要能回溯到具体租户

设计原则

所有核心业务对象都必须带租户上下文。

所有数据库查询都必须带租户过滤条件。

所有对象存储路径都应该包含租户维度。

所有 Sandbox Pod 都应该打上租户标签。

所有 Usage 和 Audit Log 都必须带租户信息。

最大风险

多租户 Agent 平台最大的风险，是模型通过工具间接访问到不属于当前租户的数据。

因此，模型传来的参数只能表示“意图”，不能表示“授权”。

授权必须由平台后端基于 Tenant、Workspace、Task、Run 和 User 上下文重新判断。

Workspace：业务工作空间

它解决什么问题？

Workspace 是 Tenant 下的业务空间。

它不是一个普通目录，而是任务、技能、文件、权限和配置的业务容器。

例如：

研发 Workspace。

运营 Workspace。

数据分析 Workspace。

客户项目 Workspace。

它的核心作用

作用	说明
业务隔离	同一租户下不同项目分开管理
权限控制	用户属于租户，不代表能访问所有 Workspace
默认配置	默认模型、工具、Sandbox 策略、Skill
文件策略	控制文件访问、产物保留和回写规则
成本聚合	Usage 可按 Workspace 统计

Workspace 配置示例

Workspace 可以保存：

默认模型。

默认工具集合。

默认 Sandbox 策略。

默认启用 Skill。

产物保留策略。

文件访问策略。

是否允许 Sandbox 出网。

Workspace 与文件的关系

不建议让 Sandbox 直接读写 Workspace 原始共享文件。

更推荐：

Workspace 原始文件  -> materialize 到 Task 私有 Sandbox  -> Agent 在 Sandbox 中处理  -> 生成 Artifact  -> 必要时通过受控工具回写 Workspace

这样可以避免多个任务互相污染，也方便追踪每个任务产生了什么结果。

Task / Session：用户目标和长期上下文

它解决什么问题？

用户来 Agent 平台不是为了“聊天”，而是为了完成一个目标。

比如：

生成竞品分析报告。

分析 Excel 文件。

修复代码 Bug。

定时生成日报。

整理文档并输出总结。

这些都应该被建模为 Task。

Task 的作用

Task 表示一个用户目标。

它包含：

用户消息。

Agent 回复。

运行过程。

产物。

文件。

技能。

Sandbox 上下文。

Session 的作用

Session 更偏技术概念，表示一段可持续上下文。

在这个设计里，Task 可以看作一个长期 Session。

同一个 Task 内可以有多次 Run，并共享上下文、文件和产物。

Task 与 Sandbox 的关系

推荐设计：

一个 Task  -> 一个 Sandbox Session

原因是同一个任务往往需要连续上下文。

第一次 Run 下载了依赖，第二次 Run 可以继续使用。

第一次 Run 生成了中间文件，第二次 Run 可以继续处理。

这比每次 Run 都创建新 Sandbox 更高效，也更符合用户对“同一个任务持续推进”的理解。

Run：一次 Agent 执行过程

它解决什么问题？

Run 是 Task 中的一次具体执行。

通常用户发送一条消息，就会创建一个新的 Run。

定时任务触发时，也会自动创建一个 Run。

审批通过后恢复执行，也会回到某个 Run 的上下文中继续。

Run 的作用

Run 用来管理一次 Agent 执行过程的生命周期。

它回答这些问题：

这次执行是否已入队？

是否正在运行？

是否等待审批？

是否已完成？

是否失败？

是否被取消？

执行过程中调用了哪些工具？

产生了哪些事件？

消耗了多少资源？

Run 状态

状态	含义
queued	已创建，等待执行
running	Agent Worker 正在执行
waiting_approval	暂停，等待审批
completed	执行成功
failed	执行失败
cancelled	被取消

为什么需要 Run？

如果只有 Message，没有 Run，系统就无法表达“模型正在执行任务”的过程。

Run 是把“一次 Agent 执行”工程化的核心抽象。

三、Agent Runtime 设计：参考 OpenAI Agents SDK 的标准抽象

Agent Runtime 是整个 AI Agent 平台的执行核心。

它不是简单调用一次模型接口，而是一个能够管理多轮推理、工具调用、任务状态、多 Agent 协作、安全校验、人工审批和隔离执行环境的运行时。

这里可以参考 OpenAI Agents SDK 的标准抽象，把 Agent Runtime 拆成以下能力。

Runtime 标准模块总览

模块	作用
Agent	定义智能体是谁、能做什么、遵守什么规则
Runner / Agent Loop	驱动模型、工具、handoff 的循环执行
Model / Provider	屏蔽不同模型供应商差异
Tools	Agent 可调用的外部能力
Tool Context	注入可信业务上下文
Tool Execution	工具执行、结果回填、错误处理
Handoffs	把控制权交给另一个专业 Agent
Agents as Tools	主 Agent 把专家 Agent 当工具调用
Guardrails	输入、输出、工具调用校验
Human-in-the-loop / Approvals	高风险动作暂停、审批、恢复
Sessions	维护多轮上下文
Context	传递租户、用户、任务、权限等业务上下文
Results / State	返回结果、运行历史、可恢复状态
Streaming	实时输出和事件流
Tracing	调试、链路追踪、可观测性
Sandbox Agents	隔离工作区、文件和命令执行
Run Config / Lifecycle Hooks	运行配置和生命周期扩展
Usage	模型、工具、Sandbox、Artifact 用量统计
Error Handling / Recovery	失败处理、重试、恢复

下面逐个拆解。

Agent：定义一个可执行智能体

它解决什么问题？

Agent 决定“这个智能体是谁”。

它不是单纯的大模型，而是一个配置好的执行单元。

Agent 通常包含

配置项	作用
name	Agent 名称
instructions	系统指令和行为规则
model	使用哪个模型
tools	可以调用哪些工具
handoffs	可以交接给哪些 Agent
guardrails	输入、输出、工具安全规则
output type	输出格式要求
context type	运行时上下文类型
hooks	生命周期扩展点

在多租户平台中的设计

平台可以维护 Agent Template。

真正执行时，再结合 Tenant、Workspace、Task、User 权限和 Skill 配置，动态生成实际可运行的 Agent。

同一个 Agent 模板，在不同 Workspace 下看到的工具、模型、Skill 和安全策略都可能不同。

Runner / Agent Loop：驱动 Agent 执行

它解决什么问题？

Runner 是 Agent 的执行器。

Agent 只是定义，Runner 才负责真正跑起来。

标准循环

Runner 接收 Agent 和用户输入  -> 调用当前 Agent 的模型  -> 检查模型响应      -> final output：结束      -> tool call：执行工具，结果追加回上下文，继续循环      -> handoff：切换到新 Agent，继续循环  -> 超过最大轮次或异常时中断

在平台中的位置

API 不直接跑 Agent。

Agent Worker 消费 Run 后，调用 Runner。

Runner 内部处理模型调用、工具调用、handoff、guardrails、状态返回和最终输出。

这样可以把业务 API 和 Agent 执行逻辑分离。

Model / Provider：模型调用适配层

它解决什么问题？

不同模型供应商的 API、工具协议、流式输出、错误结构、Token 统计方式都不一样。

Model / Provider 用来屏蔽这些差异。

在平台中的作用

它负责：

选择模型。

调用模型。

处理流式输出。

解析工具调用。

统计模型用量。

处理模型错误。

支持备用模型或降级策略。

模型选择依据

Tenant 的模型权限。

Workspace 默认模型。

Task 复杂度。

用户套餐或配额。

是否需要推理模型。

是否需要多模态能力。

是否需要低成本模型做 Guardrail。

是否需要备用模型兜底。

Tools：Agent 连接外部能力

它解决什么问题？

模型不能直接操作真实资源。

Tools 是模型调用外部能力的标准方式。

常见工具

工具	作用
run_command	在 Sandbox 中执行命令
read_file	读取任务工作区文件
write_file	写入任务工作区文件
list_files	查看文件列表
skill_view	查看 Skill 完整说明
create_artifact	登记产物
request_approval	请求人工审批
schedule_task	创建定时任务
browser_open	浏览器访问
knowledge_search	知识检索
database_query	数据库查询
media_process	媒体处理

关键原则

模型只能表达“我要调用这个工具”。

平台决定：

能不能调用。

参数是否合法。

是否需要审批。

在哪里执行。

怎么记录事件和用量。

Tool Context：可信业务上下文

它解决什么问题？

模型传来的参数不可信。

Tool Context 是后端注入的可信上下文。

Tool Context 应包含

tenant_id。

user_id。

workspace_id。

task_id。

run_id。

sandbox_session_id。

enabled_skill_ids。

permission_scope。

trace_id。

quota_context。

示例

模型请求：

read_file("/workspace/report.md")

后端不能只看路径，而要结合 Tool Context 判断：

当前用户是否属于该 Tenant？

是否有 Workspace 权限？

这个文件是否属于当前 Task？

路径是否越界？

当前工具是否允许读取？

这就是 Tool Context 的价值。

Tool Execution：工具执行和结果回填

它解决什么问题？

Tool Execution 是模型意图进入真实世界的边界。

它不是简单执行一个函数，而是完整的受控流程。

执行过程

解析 Tool Call  -> 匹配可用 Tool  -> 注入 Tool Context  -> 校验参数  -> Guardrails / Policy 判断风险  -> 必要时触发 Approval  -> 调用 Tool Handler  -> 写事件和审计  -> 记录 Usage  -> 工具结果返回 Runner  -> Runner 把结果追加回上下文  -> 模型继续推理

关键点

对于命令执行、访问网络、读取文件、安装依赖、删除文件、上传文件等高风险操作，Tool Execution 必须和 Sandbox、Approval、Audit、Usage 联动。

Handoffs：专家 Agent 接管

它解决什么问题？

Handoff 用于多 Agent 协作。

当前 Agent 判断任务应该交给另一个专业 Agent，就把控制权交过去。

示例

Triage Agent 判断任务是代码修复，handoff 给 Code Agent。

Triage Agent 判断任务是数据分析，handoff 给 Data Agent。

客服 Agent 判断问题涉及退款，handoff 给 Refund Agent。

适用场景

Handoff 适合“专家接管”。

一旦发生 handoff，新的 Agent 会成为当前主控 Agent，继续后续对话和执行。

平台需要记录 handoff 事件，方便前端展示和审计。

Agents as Tools：专家 Agent 作为工具

它解决什么问题？

Agents as Tools 也是多 Agent 协作方式。

不同点是：

Handoff 是交出控制权。

Agents as Tools 是主 Agent 保持控制，只把专家 Agent 当工具调用。

示例

主 Agent 调用：

代码扫描 Agent。

依赖分析 Agent。

测试建议 Agent。

报告生成 Agent。

最后主 Agent 汇总结果，生成最终 Artifact。

适用场景

适合“主 Agent 统一编排，专家 Agent 负责局部能力”的任务。

Guardrails：安全校验机制

它解决什么问题？

Guardrails 用于在 Runtime 层做安全、校验和约束。

常见类型

类型	作用
Input Guardrails	检查用户输入
Output Guardrails	检查最终输出
Tool Guardrails	检查工具调用前后的输入输出

在平台中的作用

Guardrails 可以检查：

Prompt Injection 风险。

越权输入。

敏感信息泄露。

模型编造文件内容。

工具参数包含 secret。

危险命令。

文件路径越界。

工具输出是否需要脱敏。

与 Policy 的关系

Guardrails 是 Runtime 级校验。

Policy 是平台业务级权限和风险策略。

两者应该配合使用。

例如：

Tool Guardrail 先检查命令是否明显危险。

Policy 再结合 Tenant、Workspace、User、Quota、Sandbox Policy 做最终判断。

Human-in-the-loop / Approvals：人工审批

它解决什么问题？

模型行为具有不确定性，高风险动作不能自动执行。

Human-in-the-loop 的典型形式就是 Approval。

需要审批的场景

执行危险命令。

删除大量文件。

访问外网。

读取 Secret 或环境变量。

安装系统依赖。

下载未知文件。

上传敏感文件。

消耗大量资源。

修改关键业务数据。

审批链路

模型发起 Tool Call  -> Guardrails / Policy 判断为高风险  -> Runner 暂停当前 Run  -> 保存 Run State  -> Approval Service 创建审批请求  -> 前端通知用户或管理员  -> 审批通过：恢复 Run  -> 审批拒绝：工具返回拒绝结果，模型换方案或结束

关键点

审批必须支持恢复。

如果不能保存 Run State，审批通过后只能重新执行任务，容易造成重复工具调用和上下文丢失。

Sessions：多轮上下文

它解决什么问题？

Sessions 用来维护多轮任务的会话历史。

同一个 Task 内的多次 Run，可以复用 Session 中的历史消息、工具结果摘要、Agent 输出和上下文状态。

Sessions 解决的问题

多轮对话如何延续？

第二次 Run 如何知道第一次做过什么？

审批恢复后如何继续上下文？

Worker 重启后如何恢复历史？

长任务如何保留上下文但不全部塞进模型？

与 Messages 的区别

Messages 是业务记录。

Sessions 是 Runtime 使用的上下文历史。

二者可以同步，也可以通过摘要、压缩和检索策略转换。

Context：运行时业务上下文

它解决什么问题？

Context 是 Runtime 和平台业务系统之间的连接点。

它不是全部给模型看的内容，而是传给工具、Guardrails、Handoffs、Hooks 等运行时逻辑使用的业务对象。

Context 应包含

当前租户。

当前用户。

当前 Workspace。

当前 Task。

当前 Run。

当前权限范围。

当前 Sandbox Session。

当前启用 Skill。

当前配额状态。

当前 Trace ID。

作用

工具执行用它判断权限。

Guardrails 用它判断风险。

Handoff 用它判断目标 Agent 是否可用。

Hooks 用它写事件、审计和用量。

Results / State：结果和可恢复状态

它解决什么问题？

Results / State 表示一次 Runner 执行后的结果和状态。

可能包含

最终输出。

中间生成项。

工具调用记录。

最后一个 Agent。

运行历史。

模型响应 ID。

可继续下一轮输入的上下文。

可恢复执行的 Run State。

在平台中的映射

Assistant Message。

Run Events。

Tool Calls。

Usage Events。

Artifacts。

Run State。

Last Agent。

Trace ID。

关键点

平台不能只保存最终文本。

还要保存运行过程和可恢复状态。

否则无法支持审批恢复、失败重试、断点续跑和审计追踪。

Streaming：实时输出

它解决什么问题？

长任务型 Agent 不能让用户一直等最终结果。

Streaming 可以让前端实时看到 Agent 正在做什么。

可以展示的内容

模型输出片段。

工具调用开始。

工具调用完成。

Sandbox stdout / stderr。

等待审批。

Artifact 创建。

Run 完成或失败。

与 Event Stream 的关系

Runtime 产生 streaming events。

平台写入 run_events。

前端通过 SSE 或 WebSocket 订阅。

Tracing：链路追踪

它解决什么问题？

Tracing 用来调试、监控和分析 Agent 工作流。

记录内容

模型调用。

工具调用。

Handoffs。

Guardrails。

审批暂停和恢复。

Sandbox 执行。

自定义事件。

错误和异常。

与 Event Stream 的区别

Event Stream 更偏用户可见过程。

Tracing 更偏研发调试和平台观测。

一个是给用户看“Agent 正在做什么”。

一个是给研发看“系统内部发生了什么”。

Sandbox Agents：隔离工作区

它解决什么问题？

Sandbox Agents 表示 Agent 可以在隔离工作区中处理真实文件、运行命令和生成产物。

在这个平台中，它可以映射到 K8s Sandbox。

对应关系

Runtime 抽象	平台实现
Sandbox Session	Task 维度 Sandbox Session
Workspace / Files	/workspace 工作目录
Command Execution	Kubernetes exec API
Artifact Collection	Artifact Service
State / Snapshot	Sandbox 状态或文件快照
Permissions	Sandbox Capability / Network Policy

核心原则

Sandbox 不只是执行命令的容器。

它是 Agent Runtime 的隔离工作区能力，是 Tools、Artifacts、Sessions 和 Approvals 的执行基础。

四、Tool Layer 与 Skill 设计

Tool Layer：模型动作的受控入口

Tool Layer 是模型所有外部动作的网关。

模型不能直接操作系统，只能通过工具请求平台执行动作。

Tool Layer 负责

工具注册。

工具参数校验。

Tool Context 注入。

权限判断。

Guardrails / Policy 校验。

审批触发。

调用后端服务。

写入事件和审计。

记录 Usage。

返回工具结果。

一次工具调用链路

模型生成 Tool Call  -> Runner 进入 Tool Execution  -> Tool Layer 接收请求  -> 注入 Tool Context  -> Tool Handler 校验参数  -> Guardrails / Policy 判断风险  -> 必要时 Approval  -> 调用 Sandbox / Service  -> 写 Events / Audit / Usage  -> 返回 Tool Result  -> Runner 继续 Agent Loop

Skill：可管理的专业能力

Skill 不是模型天然能力，也不等同于插件。

更准确地说，Skill 是一组给模型看的专业说明、工作流程、模板、脚本、约束和资产。

Skill 可以包含

任务流程。

工具使用说明。

输入文件处理规则。

输出格式要求。

注意事项。

禁止行为。

脚本模板。

示例文件。

Skill 使用链路

Workspace 安装 Skill  -> Task 选择 Skill  -> Run 开始前注入 Skill Summary  -> 模型判断需要某个 Skill  -> 调用 skill_view  -> Skill Service 返回完整说明  -> Skill Assets materialize 到 Sandbox  -> 模型按 Skill 说明调用工具  -> Usage 记录 Skill 使用

为什么先注入 Summary？

因为完整 Skill 内容可能很长。

先注入 Summary，可以让模型知道有哪些 Skill 可用。

真正需要时再通过 skill_view 读取完整说明。

这样节省上下文，也方便统计 Skill 使用情况。

五、Sandbox 与 K8s 执行设计

Sandbox 的定位

Sandbox 是任务执行的隔离环境。

只要平台允许 Agent 执行命令、处理文件、运行代码、访问网页，就必须有 Sandbox。

Sandbox 解决的问题

防止命令影响真实服务器。

防止读取宿主机敏感文件。

防止不同租户互相影响。

防止任务之间文件污染。

限制 CPU、内存、磁盘和运行时长。

控制网络访问。

记录操作过程。

任务结束后可销毁。

Sandbox 的核心概念

概念	作用
Sandbox Session	某个 Task 的隔离运行会话
Sandbox Backend	Sandbox 运行在哪里，例如 K8s
Sandbox Scope	按什么维度复用，推荐 Task / Session
Sandbox Capability	允许哪些能力，例如 shell、file、artifact
Workspace Access	Sandbox 如何访问 Workspace 文件
Shared Volume	容器间共享的 /workspace
Artifact Sidecar	负责扫描和上传产物

推荐设计

核心原则

即使模型生成危险命令，也要把影响限制在当前 Task 的 Sandbox 内。

六、Approval、Event、Artifact、Usage

Approval：敏感操作的人审机制

需要审批的场景

执行危险命令。

删除大量文件。

访问外网。

读取 Secret 或环境变量。

安装系统依赖。

下载未知文件。

上传敏感文件。

消耗大量资源。

安装或启用新的 Skill。

审批链路

模型发起高风险 Tool Call  -> Guardrails / Policy 命中风险  -> Runner 暂停 Run  -> 保存 Run State  -> Approval Service 创建审批请求  -> 前端通知用户  -> 审批通过：Resume Run  -> 审批拒绝：返回拒绝结果，模型换方案

关键点

审批不是中断点，而是暂停点。

审批通过后，Run 应该能从保存状态继续执行。

Event Stream：让过程可见

任务型 Agent 平台不能只展示最终答案。

用户需要看到 Agent 做了什么。

Run Event 类型

run.started。

message.delta。

tool.started。

tool.completed。

sandbox.output。

sandbox.completed。

approval.required。

approval.approved。

approval.denied。

artifact.created。

usage.recorded。

run.completed。

run.failed。

作用

前端实时展示。

断线续传。

审计回放。

失败排障。

用户建立信任。

Artifact：让结果可交付

很多 Agent 任务最终交付的是文件，而不是文字。

例如：

Markdown 报告。

HTML 页面。

图片。

CSV。

Excel。

PDF。

ZIP。

代码文件。

日志文件。

Artifact 来源

模型调用 create_artifact。

Sandbox 命令生成文件后自动扫描。

用户指定某个文件作为产物。

Artifact 流程

Sandbox 生成文件  -> Artifact Service 上传 Object Storage  -> 写 Artifact 元信息  -> 关联 Task / Run / Message  -> 生成预览信息  -> 提供短期签名下载链接

安全原则

不直接暴露对象存储永久 URL。

下载前必须校验 Tenant、Workspace、Task 权限。

Usage：统计真实执行成本

AI Agent 平台的成本不只有 Token。

还包括：

模型请求。

工具调用。

Sandbox 命令。

CPU / 内存 / 时间。

Artifact 存储。

Skill 使用。

Handoff 次数。

Guardrail 命中。

Scheduler 触发。

Usage 统计维度

Tenant。

Workspace。

Task。

Run。

Agent。

Model。

Tool。

Skill。

Sandbox。

Artifact。

Scheduled Task。

Usage 的价值

计费。

配额。

限流。

异常检测。

成本分析。

告警。

自动停用异常任务。

七、Scheduler：定时任务设计

定时任务的本质

Scheduler 不是一个独立 Agent。

它的本质是：

到点后自动创建一条 Message 和一个 Run，然后复用普通 Agent 执行链路。

用户手动消息链路

用户消息  -> Message  -> Run  -> Agent Run Queue  -> Agent Worker

定时任务链路

Scheduler 到点  -> Synthetic Message  -> Run  -> Agent Run Queue  -> Agent Worker

后续执行完全一致。

Scheduled Task 配置

一个定时任务通常包含：

Cron 表达式。

Tenant。

Workspace。

Prompt。

Skill。

是否允许 Sandbox。

失败重试策略。

最大运行时间。

Target Task Mode。

通知方式。

Target Task Mode

模式	适用场景
new_task_each_time	日报、周报、一次性分析
append_to_task	持续监控、长期采集、连续跟踪

差异

new_task_each_time 会创建新 Task 和新 Sandbox Session。

append_to_task 会复用已有 Task 和 Sandbox Session。

Scheduler 执行链路

Scheduler Tick  -> 查询到期任务  -> 获取分布式锁  -> 检查 Tenant quota  -> 检查 Workspace 策略  -> 创建 Synthetic Message  -> 创建或选择 Task  -> 创建 Run  -> 推入 Agent Run Queue  -> 更新 next_run_at  -> Agent Worker 执行普通 Run 流程

关键点

多实例 Scheduler 必须使用分布式锁。

Scheduler 只负责触发，不负责执行任务本身。

定时任务成本要归因到 Scheduled Task、Tenant 和 Workspace。

连续失败后可以自动停用并通知创建者。

八、Storage、Queue、Security、Observability

Storage：分层存储

存储	用途
Postgres	业务数据、状态、事件、审批、用量、审计
Redis / Queue	队列、锁、缓存、短期状态
Object Storage	Artifact、大日志、附件、Skill Assets
K8s Volume	Sandbox 运行中的工作目录

原则

结构化状态进数据库。

大文件和大日志进对象存储。

运行中的临时文件在 Sandbox Volume。

真正要保留的结果登记为 Artifact。

Queue 和 Worker：异步化长任务

Agent 执行往往是长任务。

它可能包含多次模型调用、多次工具调用、命令执行、等待审批、生成文件。

所以 API 不能同步等待执行完成。

Worker 分工

Worker	职责
Agent Worker	构造 Agent，调用 Runner，处理 Agent 执行
Sandbox Worker	创建 Pod、执行命令、采集输出、销毁 Pod
Artifact Worker	上传文件、生成预览、登记产物
Usage Worker	聚合用量、生成统计

幂等要求

Run 重试不能重复执行危险命令。

审批通过后恢复只能执行一次。

Artifact 重复上传要去重。

Scheduler 重试不能重复创建 Run。

Security：默认不信任模型

AI Agent 平台必须基于一个前提：

模型输出不可信。

模型可能误判、幻觉、被 Prompt Injection 诱导，也可能生成危险命令。

必须具备的安全能力

Tenant 强隔离。

Workspace 权限。

Tool Permission。

Guardrails。

Approval。

Sandbox 隔离。

Secret Masking。

Path Boundary。

Network Policy。

Audit Log。

Rate Limit。

Quota。

核心原则

模型可以提出请求，但不能完成授权。

授权必须由平台后端基于可信上下文完成。

Observability：让系统可观测

Agent 平台链路长，涉及 API、Queue、Worker、Runtime、Model、Tools、Sandbox、Storage、Frontend。

没有观测系统，问题很难定位。

必须监控

Run latency。

Model latency。

Tool latency。

Sandbox startup latency。

Queue backlog。

Token cost。

Tool error rate。

Sandbox pod leaks。

Approval pending time。

Artifact storage growth。

Tenant quota usage。

Trace ID

每个 Run 都应该有 trace_id。

它贯穿：

API。

Agent Worker。

Runner。

Tools。

Sandbox Service。

Artifact Service。

Usage Service。

Event Stream。

这样排查问题时，可以从一个 Run 追踪完整链路。

九、一次完整执行链路

现在把整个系统串起来。

用户在 Workspace 中创建 Task  -> 用户发送 Message  -> API 鉴权  -> 校验 Tenant / Workspace 权限  -> 写入 Message  -> 创建 Run，状态 queued  -> Run 入 Agent Run Queue  -> Agent Worker 消费 Run  -> 根据 Tenant / Workspace / Task / Skill / 权限构造 Agent  -> 准备 Context  -> 绑定 Session  -> 调用 Runner 启动 Agent Loop  -> Runner 调用 Model / Provider  -> 模型推理

如果模型直接生成最终答案：

final output  -> Runner 返回 Results  -> 写 Assistant Message  -> Run completed

如果模型发起工具调用：

Tool Call  -> Tool Execution  -> 注入 Tool Context  -> Guardrails / Policy 校验  -> 低风险：直接执行  -> 高风险：进入 Approval

如果进入 Approval：

创建 Approval Request  -> Run waiting_approval  -> 保存 Run State  -> 前端通知用户  -> 审批通过：恢复 Runner  -> 审批拒绝：工具返回拒绝结果

如果工具需要 Sandbox：

Tool Handler 调用 Sandbox Service  -> 查找或创建 Sandbox Session  -> 创建或复用 K8s Pod  -> Kubernetes exec 执行命令  -> stdout / stderr 写 Run Events  -> 生成文件上传 Object Storage  -> 登记 Artifact  -> 记录 Usage  -> Tool Result 返回 Runner

Runner 继续循环：

工具结果追加回上下文  -> 模型继续推理  -> 可能继续 Tool Call / Handoff / Agents as Tools  -> 直到 final output

最终：

Runner 返回 Results  -> 写 Assistant Message  -> 写 Run Events  -> 写 Tool Calls  -> 写 Usage Events  -> 写 Artifacts  -> 写 Trace  -> Run completed  -> 前端展示最终答案、过程日志和产物下载

十、MVP 范围建议

第一版必须做

模块	MVP 能力
Tenant / User / Workspace	基础多租户和权限
Task / Run / Message	任务、执行和对话记录
Agent Runtime	Agent、Runner、Tools、Sessions、Context、Results
Guardrails	基础输入、输出、工具校验
Event Stream	Run Events + SSE / WebSocket
Skill	Workspace 安装、Task 选择、skill_view
Tools	run_command、read_file、write_file、list_files、create_artifact
Sandbox	K8s Shell / File / Artifact
Approval	高风险操作暂停、审批、恢复
Artifact	上传、预览、下载、权限校验
Usage	模型、工具、Sandbox、Artifact、Skill 用量
Scheduler	Cron 到点创建 Message / Run

第一版可以暂缓

复杂插件市场。

完整 RAG 平台。

浏览器 Sandbox。

数据库 Sandbox。

复杂 Billing Invoice。

Workflow Builder。

多 Agent 深度协同。

复杂模型路由。

复杂 MCP 生态集成。

Sandbox Snapshot 和跨任务恢复。

MVP 的核心闭环

第一版的目标不是做全，而是打通这条闭环：

用户创建任务  -> Agent 能理解任务  -> Agent 能调用工具  -> 工具能进入 Sandbox 安全执行  -> 执行过程能展示  -> 产物能沉淀  -> 用量能统计  -> 敏感操作能审批

只要这条闭环跑通，平台就从“聊天产品”进入了“任务执行平台”的阶段。

十一、最终总结

多租户分布式 AI Agent 平台，本质上不是一个聊天系统，而是一个由模型驱动的任务执行平台。

它的核心不是“模型能不能回答”，而是：

模型能不能在受控系统中完成真实工作。

整套架构可以总结为几个关键分工：

模块	分工
Tenant	组织边界、数据隔离、资源归属、计费归因
Workspace	业务空间、成员权限、默认配置、技能范围
Task	用户目标、长期上下文、产物归属、Sandbox 会话
Run	一次 Agent 执行过程的状态管理
Agent	定义智能体角色、指令、模型、工具和规则
Runner / Agent Loop	持续调用模型、处理工具调用、handoff 和最终输出
Tools	把模型动作收敛为平台可控能力
Tool Context	注入可信租户、用户、任务和权限上下文
Guardrails	输入、输出和工具调用校验
Human-in-the-loop / Approvals	高风险操作暂停、审批和恢复
Sessions	多轮任务上下文延续
Results / State	结果返回、运行历史和可恢复状态
Streaming / Event Stream	实时输出和运行过程展示
Tracing	调试、链路追踪和可观测性
Sandbox	真实文件、命令和代码的隔离执行
Artifact	产物沉淀和交付
Usage	资源消耗和成本归因
Scheduler	定时创建 Message 和 Run
Queue / Worker	长任务异步化和分布式执行
Observability	监控、追踪、告警和成本分析

如果只用一句话概括：

多租户分布式 AI Agent 平台，就是以 Agent 和 Runner 为核心运行时，以 Tools、Guardrails、Sessions、Tracing、Sandbox 和 Human-in-the-loop 为标准能力，把模型决策、平台执行、安全管控、隔离环境和产物交付组织成一条可控的任务执行链路。

真正成熟的 Agent 平台，不能只关注模型能不能回答。

它还必须具备 Agent Runtime 的标准运行能力，以及平台级的多租户隔离、权限控制、工具执行、审批恢复、Sandbox 安全、事件追踪、用量统计和产物管理能力。

因为只有这样，AI Agent 才能从一个“会聊天的助手”，变成一个“能在企业场景中稳定交付结果的任务执行系统”。

学AI大模型的正确顺序，千万不要搞错了

🤔2026年AI风口已来！各行各业的AI渗透肉眼可见，超多公司要么转型做AI相关产品，要么高薪挖AI技术人才，机遇直接摆在眼前！

有往AI方向发展，或者本身有后端编程基础的朋友，直接冲AI大模型应用开发转岗超合适！

就算暂时不打算转岗，了解大模型、RAG、Prompt、Agent这些热门概念，能上手做简单项目，也绝对是求职加分王🔋

在这里插入图片描述

📝给大家整理了超全最新的AI大模型应用开发学习清单和资料，手把手帮你快速入门！👇👇

学习路线:

✅大模型基础认知—大模型核心原理、发展历程、主流模型（GPT、文心一言等）特点解析
✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑
✅开发基础能力—Python进阶、API接口调用、大模型开发框架（LangChain等）实操
✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用
✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代
✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经

以上6大模块，看似清晰好上手，实则每个部分都有扎实的核心内容需要吃透！

我把大模型的学习全流程已经整理📚好了！抓住AI时代风口，轻松解锁职业新可能，希望大家都能把握机遇，实现薪资/职业跃迁～