Agent 沙箱架构深度解析：从 Pattern 选型到生产级框架设计

本文深入分析 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 两种架构模式概览

案例研究：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$ 数据流为：

text 复制代码

【代码执行沙箱】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。

控制平面代理（示意）：

python 复制代码

@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)

沙箱内工具（示意）：

python 复制代码

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)：

bash 复制代码

# .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

控制逻辑 (伪代码)：

python 复制代码

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 的记忆系统，控制平面在创建沙箱时动态注入不同前缀。

框架层实现（推荐写法）：

python 复制代码

# 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)

控制平面在创建沙箱时注入隔离（关键一步）：

python 复制代码

# 控制平面代码（创建沙箱时）
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. 内存优化预设（最重要）

适用场景：资源受限的沙箱环境，需要在有限内存下稳定运行。

python 复制代码

# 使用方式
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 行为的生产环境。

python 复制代码

agent = create_agent(preset="production-log")

# 效果
# - 自动输出结构化 JSON 日志到 stdout
# - 包含 step、token_usage、tool_name、timestamp
# - 支持实时推送给控制平面
# - 符合 ELK/Prometheus 采集标准

3. 长期记忆预设（最常用）

适用场景：需要跨会话记忆、用户偏好学习的智能体。

python 复制代码

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. 自我保护预设（防止沙箱爆炸）

适用场景：不可信的用户输入、需要严格资源控制的环境。

python 复制代码

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. 本地极简预设（开发友好）

适用场景：个人开发者本地调试、快速原型验证。

python 复制代码

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"]
可覆盖性：用户可以在预设基础上覆盖特定配置项
文档完善：为每个预设提供详细的使用场景说明和配置清单

代码示例（框架实现）：

python 复制代码

# 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 月口径，引用前请以各厂商最新文档为准。本文侧重架构分析与设计原则，不涉及具体商业推荐。

Agent 沙箱架构深度解析：从 Pattern 选型到生产级框架设计

引言

目录

一、架构模式对比与选型

1.1 两种架构模式概览

案例研究：OpenPerplexity 的架构定位

1.2 业界项目模式对照

重点项目说明

1.3 向 Agent-in-Sandbox 演进的要点

1.4 两种模式深度对比（优缺点与最佳实践）

核心架构对比表

深度优缺点分析

Agent-in-Sandbox 的缺点、对策与最佳实践

2026 年行业分水岭：为什么 Manus 选择了前者？

总结建议

1.5 商业模式与订阅套餐对比（Manus vs Happycapy，2026 年 3 月）

套餐档位摘要

选型建议

二、安全与隔离

2.1 独立沙箱的必要性（六大角度）

核心定义与流程对比

为什么需要独立沙箱？

2.2 数据主权风险

2.3 联网风险与出口控制

2.4 API Key 安全工程化：Tool Proxy 模式

架构示意：

三、高并发与基础设施

3.1 谁来扛高并发？

3.2 压力下沉：纯 Agent-in-Sandbox 的并发真相

系统瓶颈与扩展

生产侧数据参考

3.3 Firecracker microVM 与持久化容器

核心区别

对比表

gVisor 容器是什么？

3.4 三种模式全面对比（成本、基建、高并发）

四、架构分工与边界

4.1 纯模式 vs 混合模式（orchestrator 外 + sandbox）

4.2 Perplexity 为何选择混合模式

Perplexity 方式的优缺点

4.3 非 Agent-in-Sandbox 的缺点（深度分析）

4.4 LangChain Pattern 商榷

第一轮：基于官方文档的质疑（Harrison Chase 的观点）

第二轮：反驳与折中（生产级 Claw 类 Agent 的视角）

4.5 控制平面与镜像层职责全对比

核心分工表

沙箱生命周期闭环：自毁与 Artifact 导出

镜像层更新策略：不可变镜像 vs 技能热加载

框架层要不要管企业特性？

五、框架设计与最佳实践

5.1 数据库位置与多租户后果

数据库到底在哪？

5.2 严禁多用户共用实例

5.3 本地与 SaaS 切换

混合云架构下的"影子文件系统" (Shadow FS)

极端隔离：无网络沙箱 (Air-gapped Sandbox)

5.4 框架内是否需要考虑多租户

核心分工

5.5 记忆系统隔离最佳实践

记忆系统分层：短期 vs 长期

LangChain DeepAgents Backend 与沙箱模式

5.6 框架边界的完整定义（核心原则）

框架不感知（完全不碰）

框架只关心（核心职责）

框架应额外提供（生产级必备）

5.7 提供最佳实践：预设方案详解

5.8 最终框架设计指导思想（收束版）

框架的唯一使命

四大核心原则

具体实践指南

为什么这样设计？

与业界实践的对照

总结