本文深入分析 Agent-in-Sandbox 与 Code Interpreter Sandbox 两种主流架构模式，结合 Manus、Happycapy、Perplexity 等生产级系统的实践，探讨 Agent 沙箱的技术选型、多租户隔离、高并发架构与框架边界设计。
引言
2026 年，随着 Manus（已被 Meta 收购）、Happycapy 等云端 AI Agent 产品的爆发，Agent 沙箱架构成为构建自主智能体的核心基础设施。本文系统性地分析了两种主流沙箱架构模式（Agent-in-Sandbox 与 Code Interpreter Sandbox），并基于业界最佳实践，提出了生产级框架的设计原则。
核心议题：
- 两种沙箱模式的本质区别与适用场景
- 高并发 Agent SaaS 的架构分工
- 控制平面与框架层的职责边界
- 多租户隔离的最佳实践
- 生产级框架的设计指导思想
目录
一、架构模式对比与选型
- 1.1 两种架构模式概览
- 1.2 业界项目模式对照
- 1.3 向 Agent-in-Sandbox 演进的要点
- 1.4 两种模式深度对比（优缺点与最佳实践）
- 1.5 商业模式与订阅套餐对比
二、安全与隔离
- 2.1 独立沙箱的必要性（六大角度）
- 2.2 数据主权风险与 BYOC 模式
- 2.3 联网风险与出口控制
- 2.4 API Key 安全工程化：Tool Proxy 模式
三、高并发与基础设施
- 3.1 谁来扛高并发？
- 3.2 压力下沉：纯 Agent-in-Sandbox 的并发真相
- 3.3 Firecracker microVM 与持久化容器
- 3.4 三种模式全面对比（成本、基建、高并发）
四、架构分工与边界
- 4.1 纯模式 vs 混合模式（orchestrator 外 + sandbox）
- 4.2 Perplexity 为何选择混合模式
- 4.3 非 Agent-in-Sandbox 的缺点（深度分析）
- 4.4 LangChain Pattern 商榷
- 4.5 控制平面与镜像层职责全对比
五、框架设计与最佳实践
- 5.1 数据库位置与多租户后果
- 5.2 严禁多用户共用实例
- 5.3 本地与 SaaS 切换
- 5.4 框架内是否需要考虑多租户
- 5.5 记忆系统隔离最佳实践
- 5.6 框架边界的完整定义
- 5.7 提供最佳实践：预设方案详解
- 5.8 最终框架设计指导思想
一、架构模式对比与选型
1.1 两种架构模式概览
案例研究：OpenPerplexity 的架构定位
OpenPerplexity 属于 Code Interpreter Sandbox（代码解释器沙箱）模式。
证据：
LLM 在服务器进程内运行 [base_agent.py:42-45] 使用 LangChain + BaseChatModel，LLM 调用发生在 FastAPI/Granian 服务器进程中。
Agent 循环在服务器进程内
[base_agent.py:83] 使用 LangGraph create_agent，规划、工具调用、反思等都在服务器进程完成。
沙箱只负责执行
[SANDBOX_SYSTEM.md:36-42] 数据流为：
【代码执行沙箱】local_storage/sandboxes/ 或 Docker /workspace/ 或 E2B /home/user/
│ execute() / execute_bash()
▼
【结果】stdout/stderr → Agent
工具调用链路
[bash_executor.py:86-94] BashExecutor 接收 SandboxExecutor，LLM 生成 tool call → 工具调用 executor.execute_bash() → 沙箱执行 → 结果返回给 LLM。
定义：
Code Interpreter Sandbox：LLM 和 Agent 在服务器进程中运行，只把代码/命令发送到沙箱执行，结果再返回给 Agent 继续推理。
1.2 业界项目模式对照
| 项目 | 模式 | 简要说明 |
|---|---|---|
| Manus | Agent-in-Sandbox | 每任务一台 Firecracker microVM，Agent 完整在云 VM 内 |
| Happycapy | Agent-in-Sandbox | 浏览器内持久化容器，Agent 在容器内运行，用户看「直播」 |
| Devin 云端版 | Agent-in-Sandbox | 云端沙箱，Agent 在云电脑中自主执行 |
| Claude Code（桌面） | Code Interpreter Sandbox | Claude 在本地，代码在 OS 级沙箱（Seatbelt/Bubblewrap）执行 |
| Claude Code（云版） | 偏 Agent-in-Sandbox | 云环境更接近「给 Agent 一台云电脑」 |
| ChatGPT Code Interpreter | Code Interpreter Sandbox | GPT 在外，只把代码丢进沙箱执行 |
| Perplexity Computer | 混合 | 三层：cloud backend 编排 + E2B sandbox 执行 + cloud browser；子 agent 在沙箱内，但 orchestration 在外 |
| Perplexity Sandbox API | Code Interpreter Sandbox | 作为 Agent API 的工具，Agent 决定要执行什么，再派发到 Sandbox |
| E2B 基础 SDK | Code Interpreter Sandbox | 仅提供代码执行沙箱，不包含 Agent |
| LangChain Code Sandbox | Code Interpreter Sandbox | 外部 Agent + 代码沙箱 |
| OpenPerplexity（本项目） | Code Interpreter Sandbox | LLM/Agent 在服务器，沙箱只执行代码/命令 |
重点项目说明
Claude Code
- 桌面版：Claude 在本地，代码在 OS 级沙箱（macOS Seatbelt / Linux Bubblewrap）执行 → Code Interpreter Sandbox。
- 云版：若整个 Claude 运行在云端沙箱内，则更接近 Agent-in-Sandbox；具体取决于 Anthropic 的实现细节。
Perplexity Computer
- 架构：三层：cloud backend（编排） + E2B Linux sandbox（执行） + cloud browser（展示）。
- 逻辑：子 agent 在 E2B 沙箱内，共享文件系统，但权限受限。主 orchestration 在 cloud backend，因此是混合模式：编排在外，执行在沙箱内。
1.3 向 Agent-in-Sandbox 演进的要点
若希望从 Code Interpreter Sandbox 升级到 Agent-in-Sandbox，大致需要：
- 把 Agent 搬进沙箱：在沙箱内运行 LangGraph Agent 循环，而不是在服务器进程。
- 沙箱作为"云电脑"：每任务或每会话分配独立 VM/容器，提供完整 OS、文件系统、网络等。
- 多 Agent 协作拓扑 (Multi-Agent Swarm)：
- 核心原则："共享文件系统 (Shared Workspace)" 是协作的基石。
- 最佳实践：推荐将协作的多个子 Agent（如 Coder、Tester、Reviewer）进程全部跑在同一个沙箱 VM 内。
- 优势：子 Agent 之间通过本地文件系统或 Unix Domain Socket 通信，无需跨网络同步文件，性能比"一 Agent 一沙箱"快 10 倍以上。
- 持久化与 24/7：支持长时间运行、后台服务、多 agent 协作等。
当前架构（LLM 在服务器、沙箱只执行）是典型的 Code Interpreter Sandbox，与 ChatGPT Code Interpreter、LangChain Code Sandbox、E2B 基础用法等一致。
1.4 两种模式深度对比（优缺点与最佳实践）
根据 2026 年行业标准（如 LangChain 的 Deep Agents 论述和 E2B/Manus 的公开架构说明），这两种模式的本质区别在于「大脑（LLM 编排）与手脚（执行环境）的距离」。
核心架构对比表
| 维度 | Agent-in-Sandbox (Manus / Happycapy) | Code Interpreter Sandbox (本项目 / ChatGPT) |
|---|---|---|
| Agent 位置 | 沙箱内部（Agent 进程在 VM/容器内跑） | 沙箱外部（Agent 在你的服务器进程跑） |
| 交互逻辑 | Agent 本地调用 Shell/文件，低延迟 | Agent 跨网络发送代码，等待沙箱返回结果 |
| 状态持久性 | 高：整个 OS 状态随任务持久化 | 低：通常仅文件持久化，进程状态易失 |
| 安全边界 | 隔离 Agent 本身（防止 Agent 逃逸） | 隔离代码执行（防止恶意代码损毁宿主） |
| 凭据管理 | API Key 需注入沙箱（风险较高） | API Key 留在服务器（更安全） |
| 典型技术 | Firecracker MicroVM / 专用 Micro-OS | Docker / gVisor / E2B SDK |
| 2026 术语 | Pattern 1: Agent IN Sandbox | Pattern 2: Sandbox as a Tool |
深度优缺点分析
模式 A：Agent-in-Sandbox（全沙箱模式） 代表：Manus, Happycapy, Devin 2.0
✅ 优点：
- 极致的执行性能 (Local Loop)：由于 Agent 的"思考-执行-观察"循环全部在沙箱本地完成，没有跨网络的 I/O 延迟。处理复杂任务速度比传统模式快 5-10 倍。
- 真正的"云电脑"体验：Agent 拥有完整 root 权限、systemd、环境变量和后台进程能力。
- 环境一致性：Agent 运行的环境就是它修改的环境，完美模拟真人开发者操作。
❌ 缺点：
- 安全风险（凭据外泄）：必须把 LLM API Key 传进去。如果沙箱被攻破，凭据直接暴露。
- 部署复杂度高：需要动态拉起完整虚拟机（如 Firecracker）。
- 更新不便：修改 Agent 逻辑可能需要重构沙箱镜像。
模式 B：Code Interpreter Sandbox（工具调用模式） 代表：OpenPerplexity, ChatGPT, Claude Code (桌面版)
✅ 优点：
- 安全可控 (Security First)：Agent 大脑在受控服务器端。沙箱是黑盒，即使
rm -rf /也不会影响主系统。 - 开发极其简单：只需通过 SDK（如 E2B）远程调用
execute()即可。 - 极高的灵活性：可以随时更换 LLM、调整 Prompt，无需干扰执行环境。
❌ 缺点：
- 网络延迟 (Network Overhead)：每行代码执行都要跨网络往返，长链条任务会有明显卡顿。
- 状态断层：沙箱通常只保证文件存在，不保证后台进程、环境变量同步。
- 能力受限：很难运行复杂 GUI 或需要多端口协同的长期服务。
Agent-in-Sandbox 的缺点、对策与最佳实践
该模式在长时程自主、隔离强度上叙事最强，但并非无代价。
主要缺点与解决办法
| 排序 | 缺点 | 严重度 | 解决办法（实用） | 落地难度 |
|---|---|---|---|---|
| 1 | 调试与审计难（黑箱） | ★★★★★ | 结构化 JSON 日志落 stdout；控制平面拉取沙箱日志；关键操作 HITL 审批 | 中 |
| 2 | 成本不可预测（长任务 / 死循环） | ★★★★☆ | 沙箱超时；sleep / recycle 机制；控制平面 CPU/预算阈值暂停或降级 | 低 |
| 3 | 单沙箱崩溃影响面大 | ★★★★☆ | 快照或周期性 artifact 上传对象存储；崩溃后新建沙箱并恢复关键产物 | 低–中 |
| 4 | 镜像与模板更新复杂 | ★★★☆☆ | 蓝绿 / 多版本模板；新任务新模板、老任务自然退出；skills 等热加载 | 中 |
| 5 | 过程透明度不足 | ★★★☆☆ | 可视化桌面（Happycapy 类）；或控制平面进度事件流 | 低–中 |
| 6 | 数据主权与合规 | ★★★☆☆ | BYOC / 自托管沙箱；企业侧加密与驻留策略 | 中 |
生产向最佳实践
- 框架层：坚持单沙箱单用户语义；记忆与文件租户隔离由控制平面注入 prefix/schema；任务结束统一导出
/output。 - 控制平面：任务注入、日志/指标拉取、快照回收视为「运维三件套」；强制超时、并发上限、每用户沙箱配额。
- 部署：SaaS 建议默认打开快照/恢复策略中的关键路径；大文件走对象存储，避免堆进 OLTP。
2026 年行业分水岭：为什么 Manus 选择了前者？
在 2026 年的 Deep Agents 范式中，行业得出了一个重要结论："如果你想让 Agent 像人一样工作，它必须住在电脑里。"
- Manus 模式 (Agent-in-Sandbox) 追求的是 "自主性 (Autonomy)"。它不再是一个对话框，而是一个 24/7 在云端帮你打工的"数字员工"。
- OpenPerplexity 模式 (Code Interpreter) 追求的是 "辅助性 (Assistance)"。它是一个增强版的搜索和编码助手。
总结建议
- 选择 Agent-in-Sandbox 如果：你在做一个 "AI 员工" 或 "自动驾驶 Agent"。任务非常复杂（>50 步），需要安装软件、运行后台服务。
- 选择 Code Interpreter Sandbox 如果：你在做一个 "AI 助手" 或 "增强型搜索"。任务相对独立（<10 步代码执行），强调安全和快速迭代。
本项目 (OpenPerplexity) 目前的定位是"高性能 AI 搜索与知识处理助手"，因此采用 Code Interpreter Sandbox 是目前最理性的架构选择。
1.5 商业模式与订阅套餐对比（Manus vs Happycapy，2026 年 3 月）
两者均偏按量付费：Manus 以 credits 为主，Happycapy 以 Claude Code credits + 算力/存储 为主；年付常有折扣。更高档通常对应更长 sleep/更大存储与更高并发。
套餐档位摘要
| 档位 | Manus Claw | Happycapy |
|---|---|---|
| Free | $0；约 300 credits/天；1 concurrent task | $0；有限 trial + 基本 sandbox |
| 入门 Pro | 约 $20–39/月；约 4000 credits/月 | 约 $20/月；约 2000 credits；2c/4GB/50GB |
| 高阶 Pro / Max | 约 $40–199/月；8000–19900+ credits | 约 $200/月；「无限」credits；4c/8GB/200GB |
沙箱与持久化影响
- Manus：Task VM；更高档 → 更长 sleep（Free 7 天 / Pro 21 天）+ 智能恢复。
- Happycapy：Per-user Workspace；更高档 → 更大专用存储（50GB→200GB），强调长期不丢。
选型建议
- 想省钱且看重持久化存储 → Happycapy Pro (约 $20) 是性价比选项。
- 追求高智能与并发、credits 弹性 → Manus Pro 区间 ($39–199) 更贴复杂任务。
二、安全与隔离
2.1 独立沙箱的必要性（六大角度）
核心定义与流程对比
| 维度 | 仅运行代码 (Code Interpreter) | Agent-in-Sandbox |
|---|---|---|
| 核心逻辑 | LLM 外部生成代码 → 扔进沙箱跑 | 整个 Agent 项目完整跑在沙箱内 |
| 自主程度 | 中（多依赖外部 LLM 往返） | 高（长时程、少打断） |
| 典型流程 | 用户任务 → LLM 生成代码 → 沙箱执行 → 回传 | 启 VM/容器 → Agent 迁入 → 内循环 Plan/Execute |
为什么需要独立沙箱？
只要涉及代码运行、浏览器控制、文件操作、API 调用，99% 的生产级云端 SaaS 都强制采用每个用户/每个任务一个独立沙箱。
| 维度 | 核心原因 | 无独立沙箱的风险 | 独立沙箱带来的价值 |
|---|---|---|---|
| 安全隔离 | Agent 代码不可信 | 容器逃逸、内核共享漏洞 | Firecracker 硬件级隔离 |
| 隐私与数据 | 用户文件须隔离 | 跨用户泄露、PII 暴露 | Per-user filesystem、零信任 |
| 爆破半径 | 单用户故障勿拖垮全平台 | OOM、死循环拖慢全站 | 自毁、资源限额、隔离崩溃 |
| 资源公平 | 避免「吵闹邻居」吃资源 | 全站卡顿、免费用户不可用 | Ephemeral 按需创建与回收 |
| 持久化 | 跨会话文件、context | 状态冲突、互相覆盖 | Manus sleep/恢复；Happycapy 专用存储 |
| 合规与企业 | GDPR/HIPAA 审计 | 难以上线、数据主权质疑 | 可审计、可证明隔离 |
2.2 数据主权风险
数据主权风险：数据实际受哪国法律管辖。在 Agent-in-Sandbox 模式下，数据全程在云端运行，风险被放大。
- Manus：总部新加坡，核心团队在中国，数据可能用西方云。
- Happycapy：沙箱容器大概率托管在全球云（AWS/GCP）。
- BYOC (Bring Your Own Cloud) 缓解方案：SaaS 厂商提供控制平面，沙箱基础设施（E2B/K8s）运行在客户自己的云账号内。数据不出客户内网，满足金融、医疗等行业的极高合规要求。2026 年企业级 Agent SaaS 的标配。
2.3 联网风险与出口控制
「云电脑」类能力通常需要完整出站联网。产品侧一般用 强隔离 + Zero Trust + 出口控制。
- Manus：沙箱与平台账号物理隔离。协作模式下 Connectors 自动禁用，防止队友访问你的私有账号。
- Happycapy：所有流量走容器 egress proxy，域名/端口白名单过滤。
- 缓解建议：高敏感数据用单独 task；企业版申请 BYOC 自定义出口规则。
2.4 API Key 安全工程化：Tool Proxy 模式
在 Agent-in-Sandbox 模式下，为了不让用户在沙箱里偷走 API Key，推荐使用 Tool Proxy（工具代理） 模式。
架构示意：
- 沙箱内工具：不持有真正的 API Key，只持有短命的
sandbox_token。 - 控制平面代理：持有真正的 API Key，校验
sandbox_token后代为请求外部 API。
控制平面代理（示意）：
@app.post("/tool/{tool_name}")
async def call_tool(tool_name: str, payload: dict, authorization: str | None = None):
# 1. 校验短命 sandbox_token (JWT 或 Redis 临时 Key)
user_ctx = verify_sandbox_token(authorization)
# 2. 从控制平面数据库取该用户的真实 Key (如 OpenAI/Google Key)
real_key = get_user_api_key(user_ctx.user_id, tool_name)
# 3. 代为请求外部 API，Key 永远不进入沙箱
return await call_external_api(tool_name, payload, api_key=real_key)
沙箱内工具（示意）：
import requests
def google_search(query: str, sandbox_token: str) -> dict:
# 沙箱内代码只知道代理地址，不知道真实 Key
r = requests.post(
"https://proxy.example.com/tool/google_search",
json={"query": query},
headers={"Authorization": f"Bearer {sandbox_token}"},
timeout=60,
)
r.raise_for_status()
return r.json()
三、高并发与基础设施
3.1 谁来扛高并发？
| 模式 | 并发压力主要在哪？ | 核心逻辑 | 谁来扛？ |
|---|---|---|---|
| 纯 Agent-in-Sandbox | 沙箱创建层 (IaaS) | 压力下沉：中央服务只管"发钥匙"，Agent 在 VM 内自转 | E2B / K8s 横向扩容 |
| 混合模式 (Perplexity) | 中央 Orchestrator | 压力集中：中央服务需维持数万个活跃 HTTP/WS 连接 | 自研队列、限流、熔断 |
| Code Interpreter 式 | 共享 Executor Pool | 资源竞争：多用户抢占同一个代码执行队列 | Celery / 线程池等 |
3.2 压力下沉：纯 Agent-in-Sandbox 的并发真相
- 独立性：每个用户/每个任务 = 一个独立沙箱（Firecracker microVM 或容器）。
- 单线程：Agent 的全部逻辑（规划、执行、反思）在自己的沙箱里跑。这意味着你的中央控制平面不再需要处理复杂的异步状态机。
- 控制面极轻：中央服务只负责"发钥匙"（
Sandbox.create）和"收盘子"（获取结果）。 - 量化逻辑：在 Pattern 2 中，1 台 8C16G 的机器可能因为要维持 5000 个 Agent 的上下文而 OOM；但在 Pattern 1 中，同样的机器可以支撑数万并发用户，因为压力全部下沉到了基础设施层的 VM 调度。
系统瓶颈与扩展
虽然框架层不需要写并发代码，但系统层面仍需水平扩展：
- 单机瓶颈：一台物理宿主机最多跑几十个沙箱，超过会 OOM。
- 解决方案：
- 方案 A (推荐)：直接用 E2B 云托管，自动在全球 scale。
- 方案 B：自建 K8s 集群，控制平面部署多个实例。
生产侧数据参考
- Manus：中央控制平面仅用 3 台小机器，支撑数万并发用户（靠 E2B 自动 scale）。
- Perplexity：2026 年多次砍限额（unlimited → 200 次/天），主因是中央 Orchestrator 扛不住海量长连接的上下文压力。
3.3 Firecracker microVM 与持久化容器
核心区别
- Firecracker microVM：硬件虚拟化、独立 guest 内核，隔离最强。Manus / E2B 常用。
- 持久化容器 (OCI)：共享内核，namespaces/cgroups 隔离。Happycapy 常用。
对比表
| 维度 | Firecracker microVM | 持久化 OCI 容器 |
|---|---|---|
| 隔离机制 | KVM + 独立内核 | namespace + cgroup |
| 安全强度 | ★★★★★ | ★★★★☆ (需 gVisor 加固) |
| 冷启动 | 约 125–150ms | 常 <50ms |
| 持久化 | Ephemeral + 智能恢复 | 原生持久卷、百 GB 工作区 |
| 可视化 | 常为 Web/App 报告 | 浏览器里「直播」操作 |
gVisor 容器是什么？
gVisor 是 Google 开源的 OCI 兼容 runtime（runsc）。它在用户空间实现了一个轻量内核（Sentry），拦截所有系统调用。Happycapy 的持久化容器通常就是 OCI 标准容器 + gVisor 安全加固。
3.4 三种模式全面对比（成本、基建、高并发）
| 维度 | 纯 Agent-in-Sandbox | 混合偏 (Perplexity) | 加强版 Code Interpreter |
|---|---|---|---|
| 运营商成本 | 约 $13–27 (边际低) | 约 $25–50+ (路由重) | 约 $12–25 |
| 高并发能力 | ★★★★★ | ★★☆☆☆ | ★★★☆☆ |
| 基础设施 | microVM / 容器池 | Firecracker + 复杂编排 | E2B + 共享 Pool + 队列 |
| 适用场景 | 长期自动化、建站 | 企业审计、研究 | 快速原型、简单脚本 |
四、架构分工与边界
4.1 纯模式 vs 混合模式（orchestrator 外 + sandbox）
二者核心差在 Agent 大脑是否在沙箱内。
| 维度 | 纯 Agent-in-Sandbox (Manus) | 混合偏 (Perplexity Computer) |
|---|---|---|
| 大脑位置 | 全在沙箱 (Planner + Executor) | Orchestrator 在外，sandbox 跑子任务 |
| 启动方式 | 单次拉沙箱，箱内跑全程 | 多轮：外部分解 → 下发 → 回传 |
| 自主程度 | ★★★★★ | ★★★★☆ |
| 延迟 | 低 (本地循环) | 中 (每步外呼 LLM) |
| 审计 | 中 (需自建日志) | ★★★★★ (子任务级轨迹) |
选择建议：
- 个人/生产力重度任务 → 纯模式 (Manus/Happycapy)。
- 企业/严格审计/金融 → 混合偏模式 (Perplexity)。
4.2 Perplexity 为何选择混合模式
在 2026 年的架构博弈中，Perplexity 坚持"编排在外、执行在内"的混合模式，主要基于以下四个核心考量：
- 多模型协调 (Multi-Model Coordination) 是其核心竞争力： Perplexity 的搜索过程往往需要同时协调 19–20 个不同的模型（包括专用的 Rerank 模型、Query 生成模型等）。将这些复杂的调度逻辑放在外部 Orchestrator，可以更灵活地进行动态路由和 A/B 测试。
- 企业级可审计性 (Enterprise Auditability) 优先： 大脑留在外面，意味着每一轮决策、每一个子任务的派发都有清晰的、不可篡改的外部日志。对于金融、法律等对合规性要求极高的企业客户，这是比"极致自主性"更重要的卖点。
- 精细化的成本控制 (Granular Cost Control)： Orchestrator 可以实时评估任务的复杂度。如果是简单的搜索，直接在外部轻量级推理；只有涉及代码执行或复杂操作时才拉起昂贵的沙箱资源。这种"按需下沉"的策略极大地优化了其毛利。
- 极速的迭代与热部署 (Hot Deployment)： 外部协调层方便快速接入新模型、新工具或调整 Prompt 策略，而无需频繁地重新构建、测试和分发庞大的沙箱镜像（Image）。
Perplexity 方式的优缺点
- 优点：
- 智能上限高：能够整合全球最顶尖的多个模型协同作战。
- 合规性强：天然支持子任务级的审计轨迹（Audit Trail）。
- 搜索原生：与实时 Grounding 结合得更紧密。
- 缺点：
- 自主性天花板：由于大脑不在现场，处理需要极高实时反馈的任务（如复杂的 GUI 自动化）时，表现弱于纯模式。
- 中央瓶颈：随着用户激增，中央 Orchestrator 的并发压力巨大，导致其不得不频繁限制免费额度。
- 成本门槛：为了维持这套复杂的编排系统，其 Pro 计划（如 Max 计划）往往定价较高（$200/月）。
4.3 非 Agent-in-Sandbox 的缺点（深度分析）
非纯模式（Pattern 2 / Sandbox-as-Tool）的核心代价是 「大脑留在外面」，这在生产级 Agent 应用中会引发一系列连锁反应：
- 网络延迟 (Network Latency) 爆炸： 每次工具调用都需要跨越网络边界（Agent -> Sandbox -> 执行 -> 返回 -> Agent）。在长链路任务（如 50+ 步的编码任务）中，累积延迟会导致用户体验从"流畅"降级为"卡顿"，甚至引发 LLM 超时。
- 长时程自主性 (Long-term Autonomy) 极弱：
由于 Agent 进程在沙箱外，它无法真正实现"无人值守"。一旦网络连接中断或服务器进程重启，正在进行的复杂任务上下文极易丢失，无法像沙箱内进程那样通过
checkpoint完美恢复。 - 同步与运维爆炸 (Sync & Ops Overhead)： 开发者必须自己处理繁琐的文件同步逻辑（rsync/websocket）、用户数据存储、以及多租户下的文件权限校验。而在 Agent-in-Sandbox 模式下，这些都由沙箱基础设施（如 E2B）天然解决。
- 成本失控 (Cost Inefficiency)： 多轮外部 LLM 往返调用产生的 Token 消耗，以及为了维持外部 Orchestrator 高可用而投入的算力资源，在规模化后往往高于"沙箱内闭环 + sleep/recycle"的成本。
- 环境不一致 (Environment Mismatch)： Agent 在外部"想象"的环境状态（如环境变量、已安装的包）与沙箱内部的真实物理状态极易产生断层，导致"我觉得我装了，但运行报错"的典型幻觉。
- 安全审计的"伪命题"： 虽然大脑在外看似好审计，但实际上由于执行过程被切碎，很难还原 Agent 的完整意图链条。
4.4 LangChain Pattern 商榷
第一轮：基于官方文档的质疑（Harrison Chase 的观点）
LangChain 创始人 Harrison Chase 在 2026 年初曾极力推荐 Pattern 2 (Sandbox-as-Tool)，其核心理由是：
- 安全性：API Keys 留在沙箱外，防止 Agent 逃逸后窃取。
- 易更新：Agent 逻辑更新只需重启服务器，无需重新构建庞大的沙箱镜像。
- 架构解耦：大脑（LLM）与手脚（Sandbox）职责分离，符合传统软件工程美学。
第二轮：反驳与折中（生产级 Claw 类 Agent 的视角）
对于 Manus、Happycapy 这种追求极致自主性的 Claw 类 Agent，Pattern 1 (Agent-in-Sandbox) 才是唯一的出路：
- 长任务支持：只有大脑在里面，才能支持 24/7 的长时程打工，不受外部网络波动影响。
- 高并发降压：中央 Orchestrator 变得极轻，压力下沉到 IaaS 层（Firecracker），这是 SaaS 规模化的唯一解。
- 成本优势：通过沙箱的
sleep/recycle机制，可以在不损失状态的前提下极大地降低闲置成本。 - 安全博弈的另一面：Harrison 认为 Key 在外更安全，但忽视了 "Agent 逃逸" 的风险。在 Pattern 2 中，Agent 运行在你的服务器进程，一旦被注入攻击，它能访问服务器的所有环境变量和内网资源。而在 Pattern 1 中，Agent 被物理隔离在沙箱内，即使被攻破，也只能拿到一个短命的
sandbox_token。
最终共识：LangChain 的建议是面向"通用开发框架"的保守方案，而如果你要打造一个"数字员工"级别的 SaaS 产品，必须勇敢地拥抱 Pattern 1。
4.5 控制平面与镜像层职责全对比
核心分工表
| 维度 | 控制平面 (Control Plane) | 镜像层 (Image / Framework) |
|---|---|---|
| 职责 | 谁在用、开几个、谁付钱 | 怎么干活、Agent 逻辑 |
| 隔离性 | 管跨用户隔离 (Tenant-ID) | 仅管单沙箱内逻辑 |
| 并发 | 管多沙箱横向扩展与队列 | 管单沙箱内异步/并发 |
| 生命周期 | 沙箱自毁与 Artifact 导出 | 任务执行与 状态检查点 (Checkpoints) |
沙箱生命周期闭环：自毁与 Artifact 导出
在 SaaS 环境下，任务结束后的处理至关重要：
- 任务结束：Agent 进程发出
SIGTERM或完成信号。 - Artifact Sync（关键）：沙箱进入
terminating状态前，控制平面必须执行同步逻辑。- 哪些留：
/output导出到 S3；/memories增量同步到向量库；关键日志。 - 哪些丢：
/tmp临时文件；未持久化的环境变量；进程内存状态。
- 哪些留：
- 状态检查点 (Checkpoints)：框架层必须在每一轮 Loop 结束后，将 Agent 的内存状态（State）持久化到沙箱内的挂载卷。这样即使沙箱崩溃重启，控制平面重新拉起镜像后，Agent 能"瞬间找回记忆"继续工作。
- 彻底自毁：基础设施回收 VM/容器资源，确保零残留。
镜像层更新策略：不可变镜像 vs 技能热加载
在 Agent-in-Sandbox 模式下，Agent 逻辑的更新是一个工程痛点：
- 方案 A：不可变镜像 (Immutable Image)：
- 机制：Agent 逻辑固化在 Docker 镜像里。
- 优点：环境绝对一致，启动极快。
- 缺点：改一行 Prompt 都要重造镜像，迭代慢。
- 方案 B：技能热加载 (Skills Hot-reload)：
- 机制：镜像只包含基础环境（Python, Node, LangGraph 运行时），Agent 逻辑（Skills/Prompts）在启动时从控制平面动态拉取。
- 优点：秒级更新 Agent 逻辑，无需重启基础设施。
- 最佳实践：采用"基础镜像 + 动态技能包"模式，兼顾性能与灵活性。
框架层要不要管企业特性？
| 特性 | 框架层是否需要 | 原因 |
|---|---|---|
| 高并发核心 | 不需要 | 并发靠多沙箱实例扩展 |
| 多租户隔离 | 不需要 | 隔离由沙箱 + 控制面完成 |
| 用户/计费 DB | 不需要 | 属于控制平面职责 |
| 多模型路由 | 按需 | 框架可提供接口，但策略由控制面注入 |
框架应做的优化：
- 单沙箱内内存管理：防止 Agent 进程 OOM。
- 启动加速 (Lazy Import)：减少沙箱拉起后的冷启动时间。
- 执行缓存 (Execution Cache)：对相同工具调用结果进行缓存，节省 Token 和时间。
- 错误恢复 (Self-Healing)：Agent 进程崩溃后，框架能利用 Checkpoint 自动重启。
- 僵尸进程收割 (Process Reaping)：Agent 逻辑退出后，强制清理其拉起的子进程（如浏览器、Shell 进程），防止资源泄露。
五、框架设计与最佳实践
5.1 数据库位置与多租户后果
数据库到底在哪？
数据库 100% 在控制平面层。镜像里不连数据库，只处理单次任务。
5.2 严禁多用户共用实例
在设计 SaaS 时，绝对禁止将多个用户塞进同一个沙箱实例：
- 数据泄露：用户 A 运行
ls -R /就能看到用户 B 的私有文件。 - 资源抢占：用户 A 的一个死循环会直接导致用户 B 的 Agent 响应超时（OOM 或 CPU 耗尽）。
- 审计失效：无法区分某条恶意指令到底是哪个用户下达的。
- 框架准则：应在 README 明确声明"本框架采用单实例单用户物理隔离设计"。
5.3 本地与 SaaS 切换
为了兼顾开发体验与生产扩展，控制平面应支持通过 MODE 环境变量一键切换。
配置示例 (.env)：
# .env.local
MODE=local
DATABASE_URL=sqlite:///local.db
SANDBOX_PROVIDER=docker
# .env.saas
MODE=saas
DATABASE_URL=postgresql://user:pass@db.example.com
SANDBOX_PROVIDER=e2b
控制逻辑 (伪代码)：
if os.getenv("MODE") == "local":
# 本地模式：挂载磁盘，极速调试
db = SQLiteDB()
sandbox = LocalDockerRunner(mount_path="./workspace")
else:
# SaaS 模式：云端隔离，增量同步
db = PostgresDB()
sandbox = E2BRunner(template="agent-prod")
底层差异说明：
- Local 模式 (Volume Mounting)：读写几乎零延迟，框架层
FileSystem抽象应直接调用 OS 原生 IO。 - SaaS 模式 (Network Sync)：存在网络延迟，必须设计
sync_on_save或auto_sync机制，FileSystem抽象层封装为远程 API 调用。
混合云架构下的"影子文件系统" (Shadow FS)
在 SaaS 模式下，为了解决网络延迟带来的体验问题，业界常采用 Shadow FS 模式：
- 控制平面：维护一份本地缓存（影子）。
- 沙箱：异步将文件变更同步回控制平面。
- 优势：用户在 Web 端查看文件时，直接读控制平面的"影子"，无需跨网络请求沙箱，体验如丝般顺滑。
极端隔离：无网络沙箱 (Air-gapped Sandbox)
针对极高安全要求的场景（如处理核心算法、财务数据）：
- 机制：沙箱创建后，控制平面通过 IaaS API 彻底切断其出站网络（Egress）。
- 通信：Agent 仅能通过受控的
stdio或Tool Proxy与外界交换极少量数据。 - 价值：从物理层面杜绝了数据外泄。
5.4 框架内是否需要考虑多租户
答： 框架层完全不需要考虑多租户逻辑。记忆系统的按用户隔离，不是框架层该做的事，而是控制平面在创建沙箱时负责。
核心分工
| 层级 | 负责什么 | 是否需要考虑多租户 |
|---|---|---|
| 框架层 | 提供记忆系统的抽象接口和 Backend 支持 | 不需要 |
| 控制平面 | 在创建沙箱时注入用户专属配置（Prefix/Env） | 必须 |
| 沙箱实例 | 实际运行时使用注入的配置自动隔离 | 运行态隔离 |
5.5 记忆系统隔离最佳实践
核心思路：框架只提供带 namespace/prefix 的记忆系统，控制平面在创建沙箱时动态注入不同前缀。
框架层实现（推荐写法）：
# framework/memory.py
class AgentMemory:
def __init__(self, backend_config: dict):
# 关键：从配置中获取前缀，支持 user-id 和 assistant-id 嵌套
# 默认：user-{user_id}/assistant-{assistant_id}/
self.prefix = backend_config.get("memory_prefix", "default/")
self.backend = self._create_backend(backend_config)
def save(self, key: str, value: Any, namespace: str = "default"):
# 自动拼接前缀：实现多租户与多 Agent 隔离
full_path = f"{self.prefix}{namespace}/{key}"
self.backend.write(full_path, value)
def load(self, key: str, namespace: str = "default"):
full_path = f"{self.prefix}{namespace}/{key}"
return self.backend.read(full_path)
控制平面在创建沙箱时注入隔离（关键一步）：
# 控制平面代码（创建沙箱时）
sandbox = e2b.Sandbox.create(
template="your-agent",
env_vars={
"MEMORY_BACKEND": "s3",
"MEMORY_PREFIX": f"user-{user_id}/assistant-{assistant_id}/", # 核心：嵌套隔离
"S3_BUCKET": "agent-memories"
}
)
结果：两个用户天然完全隔离，框架代码无需修改。框架保持极简干净，以后想加新 Backend 或新功能都非常容易。
记忆系统分层：短期 vs 长期
在 2026 年的 Deep Agents 架构中，记忆系统通常分为两层：
- 短期记忆 (Short-term / Working Memory)：
- 位置：沙箱本地文件或内存 (Redis)。
- 内容：当前任务的推理链、临时变量、对话上下文。
- 同步：任务结束时作为 Artifact 导出。
- 长期记忆 (Long-term / Semantic Memory)：
- 位置：外部向量库 (Postgres/Pinecone) 或对象存储 (S3)。
- 内容：用户偏好、历史成功经验、跨任务知识。
- 同步：通过
AgentMemory抽象层异步写入，利用prefix实现跨沙箱隔离。
LangChain DeepAgents Backend 与沙箱模式
问：LangChain 的 DeepAgents Backend 是不是就是解决多租户的？ 答： 绝对不是。
- DeepAgents Backend 解决的是单个 Agent 的可插拔虚拟文件系统（State, Store, Filesystem）。它让 Agent 觉得自己在操作一个本地文件系统，但底层可以映射到 S3 或数据库。
- 多租户隔离 依然靠控制平面注入
prefix或schema。 - 收束结论：框架层只管"怎么读写记忆"，控制平面管"读写谁的记忆"。
5.6 框架边界的完整定义（核心原则）
在 Agent-in-Sandbox 架构中，框架层边界的清晰界定是保持系统简洁性与可扩展性的关键。这一原则已被 Manus、Happycapy 等生产级 Agent 系统实践验证。
框架不感知（完全不碰）
| 特性 | 说明 | 理由 |
|---|---|---|
| user_id | 用户身份标识 | 框架无需知道"谁"在使用，只需完成任务 |
| 多租户隔离 | 跨用户的资源与数据隔离 | 隔离由沙箱物理边界 + 控制平面配置注入保障 |
| TAURI / SaaS 部署模式 | 本地桌面 vs 云端 SaaS | 框架一旦感知部署模式会迅速变重、变复杂 |
| 跨用户限流 | 全局流控、配额管理 | 属于控制平面的资源调度职责 |
核心理由：这些都是控制平面的责任。框架一旦开始感知 user_id 或部署模式，就会迅速变重、变复杂，违背「保持框架干净」的核心原则。
框架只关心（核心职责）
| 职责 | 具体内容 | 目标 |
|---|---|---|
| 单沙箱内的资源管理 | 内存限额、文件清理、临时目录管理 | 让单个 Agent 不会自己把自己搞崩 |
| 单沙箱内的性能优化 | 启动加速（lazy import）、执行缓存、增量计算 | 把单次任务跑得又快又省 |
| 单沙箱内的自我保护 | 熔断、限流、内存监控、超时中断 | 避免死循环或资源耗尽拖垮沙箱 |
| 提供最佳实践 | 预设配置方案、推荐架构模式 | 降低开发者接入门槛 |
框架应额外提供（生产级必备）
除了上述核心职责，以下 4 点虽然容易被忽略，但在生产环境中非常关键：
| 特性 | 说明 | 价值 |
|---|---|---|
| 清晰的生命周期钩子 | on_task_start、on_task_complete、on_low_memory、on_error | 控制平面可轻松实现快照、结果导出、告警 |
| 结构化日志 + 可观测性 | 强制输出 JSON 格式日志（带 step、tool、token_usage 等字段） | 便于控制平面实时拉取和监控 |
| 可配置的 Backend 前缀支持 | 记忆系统、文件系统必须支持 memory_prefix / storage_prefix 配置 | 不是多租户，而是单沙箱内的可扩展性 |
| 资源使用报告机制 | Agent 结束时自动输出 resource_report.json（耗时、峰值内存、token 数等） | 方便控制平面计费和优化 |
5.7 提供最佳实践：预设方案详解
核心理念：框架在设计时，主动提供几套开箱即用的"最佳配置模板"，让开发者不需要从零开始研究，就能直接拿到生产可用的推荐方案。
必要性分析：
- 降低上手门槛：尤其对本地用户，一行代码即可启动优化好的配置
- 减少配置错误：很多开发者不熟悉内存、日志优化，预设方案避免常见坑
- 建立专业形象：自带最佳实践的框架更容易获得开发者信任
- 标准化对接：控制平面可以直接调用这些预设，降低集成成本
设计原则：预设方案不是强制要求，而是"框架送给用户的礼物"——用户可以直接 use_preset("recommended") 得到优化配置，同时保留完全自定义的能力。
推荐实现的五大预设方案：
1. 内存优化预设（最重要）
适用场景：资源受限的沙箱环境，需要在有限内存下稳定运行。
# 使用方式
agent = create_agent(preset="memory-optimized")
# 框架内部实现
PRESETS = {
"memory-optimized": {
"memory_backend": "filesystem",
"max_memory_mb": 400,
"auto_gc": True, # 自动垃圾回收
"lazy_load_tools": True, # 工具按需加载
"context_window_limit": 8000 # 限制上下文长度
}
}
2. 生产级日志预设
适用场景：需要接入监控系统、追踪 Agent 行为的生产环境。
agent = create_agent(preset="production-log")
# 效果
# - 自动输出结构化 JSON 日志到 stdout
# - 包含 step、token_usage、tool_name、timestamp
# - 支持实时推送给控制平面
# - 符合 ELK/Prometheus 采集标准
3. 长期记忆预设（最常用）
适用场景：需要跨会话记忆、用户偏好学习的智能体。
agent = create_agent(preset="long-term-memory")
# 内部自动配置
{
"memory_backend": "s3", # 或 postgres
"memory_prefix": "memories/", # 留给控制平面注入 user_id
"auto_save_interval": 300, # 每5分钟自动保存
"memory_compression": True, # 自动压缩历史记忆
"semantic_index": "vector_db" # 启用语义检索
}
4. 自我保护预设（防止沙箱爆炸）
适用场景：不可信的用户输入、需要严格资源控制的环境。
agent = create_agent(preset="safe-mode")
# 包含
{
"max_steps": 50, # 最大执行步数限制
"memory_threshold_mb": 512, # 内存上限触发熔断
"timeout_per_step_sec": 30, # 单步超时时间
"loop_detection": True, # 死循环自动检测
"sandbox_isolation": "strict" # 严格沙箱隔离
}
5. 本地极简预设（开发友好）
适用场景：个人开发者本地调试、快速原型验证。
agent = create_agent(preset="local-light")
# 特点
{
"memory_backend": "in-memory", # 内存后端，无需外部依赖
"log_level": "INFO", # 简洁日志
"auto_install_deps": True, # 自动安装缺失依赖
"fast_startup": True, # 跳过非必要初始化
"minimal_tools": True # 仅加载核心工具
}
预设方案对比
| 预设名称 | 适用场景 | 内存占用 | 启动速度 | 功能完整度 |
|---|---|---|---|---|
| memory-optimized | 资源受限环境 | ★★★★★ | ★★★☆☆ | ★★★★☆ |
| production-log | 生产监控 | ★★★☆☆ | ★★★☆☆ | ★★★★★ |
| long-term-memory | 跨会话智能体 | ★★☆☆☆ | ★★☆☆☆ | ★★★★★ |
| safe-mode | 不可信输入 | ★★★★☆ | ★★★★☆ | ★★★☆☆ |
| local-light | 本地开发 | ★★★★★ | ★★★★★ | ★★★☆☆ |
实现建议：
- 统一入口：在框架主入口提供
preset参数，用户一行代码即可切换 - 可组合性：允许预设叠加，如
presets=["memory-optimized", "production-log"] - 可覆盖性：用户可以在预设基础上覆盖特定配置项
- 文档完善：为每个预设提供详细的使用场景说明和配置清单
代码示例（框架实现）：
# framework/presets.py
PRESETS = {
"memory-optimized": {...},
"production-log": {...},
"long-term-memory": {...},
"safe-mode": {...},
"local-light": {...}
}
def create_agent(preset: str | list[str] = None, **custom_config):
config = {}
# 加载预设
if preset:
presets = [preset] if isinstance(preset, str) else preset
for p in presets:
config.update(PRESETS[p])
# 用户自定义配置覆盖预设
config.update(custom_config)
return Agent(config)
最佳实践总结：框架层强烈推荐实现以上五个预设方案，既能显著降低用户接入成本，又为控制平面集成提供标准化接口。这是框架从"能用"到"好用"的关键一步。
5.8 最终框架设计指导思想（收束版）
经过对 Manus、Happycapy、Perplexity 等生产级系统的深度分析，以及对 LangChain DeepAgents 架构的反复商榷，我们得出以下框架设计的最终指导思想：
框架的唯一使命
把单个沙箱内的 Agent 做到极致（快、省、稳、好调试），其他所有"多人相关"的事一律不碰。
四大核心原则
- 框架不感知：user_id、多租户、部署模式、跨用户限流。
- 框架只负责：单沙箱内的资源管理、性能优化、自我保护 + 提供优秀钩子和最佳实践。
- 边界清晰：
- 「怎么干活」→ 在镜像（框架层）
- 「谁在用 / 谁付钱 / 谁的权限」→ 在控制平面
- 状态无缝迁移：通过 Checkpoint 机制，Agent 应具备"在 VM A 挂起，在 VM B 恢复"的能力，这是实现 SaaS 级弹性调度的基石。
具体实践指南
| 层级 | 职责 | 实现方式 |
|---|---|---|
| 框架层 | 提供能力（记忆、工具、规划） | 单沙箱单用户语义；提供 prefix/namespace 配置支持 |
| 控制平面 | 隔离与调度 | 创建沙箱时注入 user_id 对应的 prefix/env；管理多沙箱并发与队列 |
| 沙箱实例 | 执行任务 | 使用注入的配置自动隔离；输出结构化日志与资源报告 |
为什么这样设计？
- 简洁性：框架代码保持干净，不会因为多租户逻辑而膨胀
- 可扩展性：控制平面可以自由选择 TAURI 本地模式或 SaaS 云端模式，框架无需修改
- 高性能：并发压力通过多沙箱实例横向扩展，而非框架内部复杂的并发控制
- 易维护：职责分离，框架迭代不影响控制平面，控制平面升级不影响框架
与业界实践的对照
这个设计思想已经被验证，和 Manus / Happycapy 实际采用的思路高度一致：
- Manus：框架层只管"怎么执行任务"，多租户隔离由 Firecracker 物理隔离 + 控制平面动态创建实现
- Happycapy：框架层只管"单个 Workspace 内的 Agent 运行"，用户隔离由持久化容器 + 存储 prefix 实现
- Perplexity Computer：子 Agent 框架极简（E2B sandbox 内），多模型协调全部在外部 Orchestrator
总结
本文深入分析了 Agent 沙箱的两种主流架构模式，并基于 Manus、Happycapy、Perplexity 等生产级系统的实践，提炼出以下核心结论：
-
模式选型：Agent-in-Sandbox 适合"数字员工"级别的自主智能体（>50 步复杂任务），Code Interpreter Sandbox 适合"AI 助手"级别的辅助工具（<10 步代码执行）。
-
高并发真相：纯 Agent-in-Sandbox 通过"压力下沉"实现数万并发，中央控制平面极轻；混合模式则需自研复杂的队列、限流、熔断机制。
-
框架边界：框架层只管单沙箱内的"怎么干活"，完全不感知 user_id、多租户、部署模式等控制平面职责。记忆系统隔离通过
prefix注入实现，无需框架层修改。 -
安全工程化：通过 Tool Proxy 模式、BYOC 部署、出口控制等手段，在"极致自主性"与"安全可控"之间取得平衡。
-
生产级要素：生命周期钩子、结构化日志、Backend 前缀支持、资源使用报告是框架从"能用"到"好用"的关键。
-
预设方案最佳实践：框架应提供五大开箱即用的配置模板（memory-optimized、production-log、long-term-memory、safe-mode、local-light），大幅降低开发者接入门槛，同时为控制平面集成提供标准化接口。
最终指导思想：把单个沙箱内的 Agent 做到极致（快、省、稳、好调试），控制平面负责多租户隔离与全局调度。职责分离、边界清晰，是构建可扩展 Agent SaaS 的基石。
声明：文中定价、速率限制等数据为 2026 年 3 月口径，引用前请以各厂商最新文档为准。本文侧重架构分析与设计原则，不涉及具体商业推荐。
