在AI工程化落地的过程中，大多数使用者早已不再执着于大模型的刷榜参数与纸面性能。

对于企业和开发者而言，能在真实业务场景中稳定落地、自主完成工程任务、可控可运维的AI智能体，才是核心刚需。

LLM只是智能体的基础能力底座，而Agent架构设计、运行环境管控、安全能力封装，才是决定智能体能否真正“出活”的关键。

在众多智能体开发框架中，LangChain 开源的 Deep Agents 凭借低上手门槛、全面的功能覆盖、完善的官方文档以及开源免费的核心优势，成为了AI工程化深耕的优选框架。

而在 Deep Agents 整套架构体系里，Sandbox（沙盒）绝非可有可无的附加功能，而是支撑智能体安全执行代码、运行命令、自主完成工程任务的核心基础设施。

很多开发者对沙盒的认知仅停留在“隔离环境”的表层概念，却不了解其底层运行逻辑、与 Backend 的协作关系、核心实现原理以及生产落地规范。

本文将系统拆解 Deep Agents 中 Sandbox 的定义、核心价值、适用场景、底层源码逻辑、文件访问机制、生命周期治理、集成架构、落地实践与安全规范，帮大家彻底吃透这一核心组件。

Harness 顶尖架构： 基于 Deep Agents 深入解析 Harness Sandbox Infa 基础设施

一、核心认知：什么是 Deep Agents Sandbox Infa 基础设施？

1.1 一句话 定义

Sandbox（沙盒）是 Deep Agents 提供的与宿主机完全隔离的独立可控执行环境。

AI 智能体可以在沙盒内部自由完成文件读写、目录遍历、Shell 命令运行、Python 脚本执行、项目依赖安装、代码构建、仓库克隆等各类高危操作，且所有行为均在沙盒内闭环，不会侵入、污染、破坏本地宿主机与生产环境，从根源规避智能体执行带来的系统风险。

1.2 框架核心定位：Sandbox 是特殊的 Backend

这是 Deep Agents 最关键的设计理念，也是区分普通文件能力与沙盒执行能力的核心依据。

在框架体系中，Sandbox 不属于独立外挂功能，而是一种具备安全隔离能力的高级 Backend（能力后端）。

两类 Backend 的能力边界有着明确划分：

【1】普通基础 Backend（如 FilesystemBackend）： 仅为智能体提供纯文件系统操作能力，支持 ls、read_file、write_file 等基础文件操作，无任何命令执行权限，只能让智能体完成文本、文件处理类轻量化任务。

【2】Sandbox 专属 Backend（SandboxBackend）： 在完整继承文件系统操作能力的基础上，额外为智能体开放核心的execute() 工具，支持任意 Shell 命令、代码脚本的执行，同时自带环境隔离、权限管控能力。

简单来说：普通 Backend 让智能体“会操作文件”，Sandbox Backend 让智能体“能干活、敢干活、安全干活”，彻底将智能体从“文本推理工具”升级为可落地的工程化执行体。

1.3 配置 Sandbox 后智能体获得的完整能力

当 Deep Agents 绑定 Sandbox 后端后，智能体将拥有两套完整能力体系，且全部受安全隔离机制保护：

基础文件系统能力：ls（目录遍历）、read_file（文件读取）、write_file（文件写入）、edit_file（文件编辑）、glob（文件匹配）、grep（内容检索），覆盖所有常规文件操作场景。

高级执行能力：通过专属 execute 工具，自由运行 Shell 命令、执行 Python/Node 等各类脚本、安装第三方依赖、运行测试用例、完成项目构建与部署。

核心安全能力：天然隔离宿主文件、环境变量、密钥凭证、系统进程与网络资源，杜绝越权操作与环境污染。

二、核心价值：为什么 Deep Agents 必须依赖 Sandbox Infa 基础设施

Sandbox 的存在核心解决两大问题：智能体执行能力拓展与工程落地安全风控，其中安全性是其不可替代的核心价值。

2.1 安全兜底：解决智能体执行的不确定性风险

AI 智能体的行为具备高度不可预测性，模型自主生成的命令、脚本、操作逻辑无法被提前完全预判。

若直接开放宿主机执行权限，极易出现读取敏感凭证、篡改系统文件、安装恶意依赖、重复执行高危脚本、耗尽系统资源等风险。

Deep Agents 的设计思路极为严谨：默认禁止所有代码执行能力，仅接入合规 Sandbox 后端的智能体，才能获取命令执行权限，而非“默认开放权限，后续逐步限制”。

从架构层面杜绝了权限滥用的可能，全方位保护宿主核心资源：

• 隔离本地私有文件，禁止智能体越权读取、篡改、删除宿主机文件；
• 隔离环境变量与密钥凭证，杜绝 API Key、数据库密码等敏感信息泄露；
• 隔离宿主系统进程，避免智能体操作影响主服务运行；
• 隔离核心网络资源，可控管控智能体网络访问行为。

2.2 能力升级：实现真正的工程化自主执行

无 Sandbox 的智能体，仅能完成文件读写、文本问答等静态任务，本质是“带文件能力的推理器”；接入 Sandbox 后，智能体可独立完成完整工程闭环：创建项目、配置环境、安装依赖、编写代码、运行测试、构建产物、迭代优化，真正具备自动化工程执行能力，适配各类复杂业务场景。

2.3 环境统一：消除“本地可运行、线上报错”的环境差异问题

传统本地开发常因依赖版本、系统配置、环境参数差异，导致智能体行为不一致。

Sandbox 可提供标准化、干净、可复刻的独立运行环境，团队开发、线上部署、多租户场景下环境完全统一，彻底解决环境适配问题，大幅提升迭代效率。

三、落地场景：Sandbox 适配哪些核心业务？

结合 Sandbox 的能力特性与安全优势，其核心适配两类高频、高价值智能体场景，也是目前 AI 工程化落地的主流方向。

3.1 编码工程类智能体

这类场景需要高频执行代码、操作项目工程、变更环境依赖，是 Sandbox 的核心适配场景，具体包括：

• 自主创建、初始化各类编程语言项目；
• 安装、更新、卸载项目第三方依赖；
• 运行单元测试、接口测试、自动化校验脚本；
• 执行项目构建、打包、部署相关命令；
• 克隆代码仓库、迭代优化代码、修复程序 Bug；
• 调用 Git、Docker 等工程工具完成自动化流程。

3.2 数据分析类智能体

数据分析场景需要频繁执行统计代码、处理数据文件、生成可视化产物，依赖可控的隔离环境，具体包括：

• 上传、解析 CSV、Excel 等各类数据文件；
• 安装 pandas、numpy、matplotlib 等数据分析与可视化库；
• 执行数据清洗、统计分析、特征提取等脚本；
• 自动生成数据图表、分析报告、演示文档等产物。

四、底层核心：execute() 方法——Sandbox 的唯一核心入口

Sandbox 整套复杂的隔离执行体系，底层核心设计极其简洁，execute() 方法是沙盒执行所有命令、脚本的唯一底层入口，也是所有沙盒服务商必须实现的核心方法。

这一设计是 Deep Agents 架构优雅性的核心体现。

4.1 execute() 方法的核心作用

所有沙盒内的操作，无论是 Shell 命令执行、Python 脚本运行，还是各类文件系统工具的调用，最终都会统一下沉到 execute() 方法执行。

该方法负责在隔离沙盒环境中运行传入的命令字符串，并返回标准化结果，结果包含四大核心信息： – 标准输出（stdout）： 命令正常执行的返回内容； – 标准错误（stderr）： 命令执行报错、异常信息； – 命令退出码（exit_code）： 标识命令执行成功或失败； – 截断提示（truncated）： 当输出内容过大时的截断标记，避免上下文溢出。

4.2 所有文件工具均基于 execute() 封装

很多开发者误以为 read_file、ls、write_file 等工具是沙盒原生能力，实则不然。

Deep Agents 中 BaseSandbox 基类仅定义工具能力，所有工具的底层执行逻辑，均是通过拼接脚本、调用 execute() 方法实现。

以 ls 目录遍历工具的底层源码为例，可清晰验证这一逻辑：框架会先拼接一段完整的 Python 执行脚本，用于遍历目录、获取文件信息，再通过 execute() 方法在沙盒内运行该脚本，最终返回结构化的目录结果。

def ls(self, path: str) -> LsResult:        
    """Structured listing with file metadata using os.scandir."""        
    path_b64 = base64.b64encode(path.encode("utf-8")).decode("ascii")        
    cmd = f"""python3 -c "import os
import json
import base64
path = base64.b64decode('{path_b64}').decode('utf-8')
try:    
    with os.scandir(path) as it:        
        for entry in it:            
            result = {{                
                'path': os.path.join(path, entry.name),                
                'is_dir': entry.is_dir(follow_symlinks=False)            
            }}            
            print(json.dumps(result))
except FileNotFoundError:    
pass
except PermissionError:    
pass" 2>/dev/null"""        
    result = self.execute(cmd)

由此可见，所有文件系统工具都是框架封装的“上层能力”，execute() 才是沙盒运行的底层基石。

4.3 极简架构带来的两大核心优势

基于单一 execute() 核心方法的设计，让 Deep Agents 的沙盒体系具备极强的扩展性与可维护性：

1. 沙盒服务商接入成本极低：无论是 Daytona、Modal、Runloop、阿里云 AgentRun 等商用沙盒，还是自定义 Docker 沙盒/K8S沙盒，只需实现 execute() 这一个核心方法，即可完成与 Deep Agents 的适配，无需适配各类零散文件工具，大幅降低接入门槛。

2. 能力边界与权限管控更清晰：智能体所有高危执行行为全部收敛到 execute() 入口，框架可统一对命令进行校验、拦截、限流、审计，无需分散管控各类工具，极大降低安全管控与系统维护成本。

4.4 sandbox Infra 的 关注点分离 (Separation of Concerns, SoC)  架构思维

关注点分离是将一个复杂系统分解为多个独立部分的设计原则，每个部分负责一个单独的“关注点”（即特定功能、逻辑或职责）。

这些部分之间通过定义良好的接口进行交互，从而降低耦合度，提高代码的可读性、可维护性、可测试性和可复用性。

5.2 通道一：智能体文件系统工具（沙盒内部闭环操作）

5.2.1 核心基础定义

调用主体：LLM 大模型驱动的 AI 智能体，属于模型推理阶段的自主行为，无需开发者手动编码调用，由智能体根据任务需求自动决策触发。

工具集合：框架内置全套标准化文件操作工具，覆盖所有沙盒内作业场景，包含：read_file（文件读取）、write_file（文件新建/覆写）、edit_file（文件增量编辑）、ls（目录遍历查询）、glob（模糊匹配文件）、grep（内容检索匹配）、execute（命令/脚本执行）。

运行边界：100% 沙盒环境内部闭环，全程不触碰、不访问、不修改宿主机任何资源，所有文件读写、目录操作、脚本运行均在隔离的沙盒容器虚拟文件系统内完成，与宿主机文件体系彻底割裂。

5.2.2 底层核心运行原理

这是框架最核心的极简设计，也是大幅降低自定义沙盒适配成本的关键。

很多开发者误以为 read_file、ls 等工具是沙盒原生独立能力，实则所有文件工具均为框架上层封装的语法糖，底层无独立执行逻辑，全部统一下沉到 execute() 唯一入口执行。

其完整执行链路为：AI 智能体判断任务需要读取/修改文件 → 框架自动拼接标准化 Python/Shell 脚本（规避命令注入、兼容跨系统语法） → 调用沙盒基类 execute() 方法 → 在沙盒隔离环境中执行脚本 → 结构化解析执行结果并返回给大模型。

整套流程无需开发者参与，也无需沙盒实现各类零散文件接口，仅需实现 execute() 一个核心方法，即可自动拥有全套文件系统能力，这也是自定义沙盒适配成本极低的核心原因。

5.2.3 典型落地场景与实操案例

该通道所有操作均服务于智能体自主完成任务，是智能体「干活」的核心依托，典型场景如下：

【1】智能体自主初始化项目： 在沙盒内新建 src、config、tests 目录，创建 README.md、requirements.txt 等项目文件；

【2】智能体自主编码开发： 在沙盒内编写业务代码、配置文件，修改代码逻辑、修复 BUG；

【3】智能体自主排查问题： 通过 ls 遍历项目目录、grep 检索代码关键字、read_file 读取报错日志文件；

【4】智能体自主运行测试： 通过 execute 执行 pytest、单元测试、脚本运行、项目构建命令。

5.2.4 核心特性与约束

• 无跨环境数据流转： 所有新建、修改、删除的文件，仅存在于当前沙盒容器内部，宿主机无法直接感知；
• 环境隔离绝对安全： 智能体即使执行删除根目录、篡改系统配置等高危操作，仅会破坏沙盒内部环境，对宿主机零影响；
• 状态随沙盒生命周期： 文件数据与沙盒实例绑定，沙盒销毁后，所有内部文件全部自动清空，无残留数据；
• 完全自动化触发： 无需开发者编写文件操作代码，由大模型自主决策调用，适配智能体自动化工作流。

5.3 通道二：应用层文件传输 API（宿主机与沙盒跨环境交互）

5.3.1 核心基础定义

调用主体：开发者编写的业务层 Python 代码，属于应用程序主动调度行为，与 LLM 智能体的自主推理、工具调用完全无关，模型无法主动触发该通道能力。

核心接口：仅包含两个标准化核心方法——upload_files()、download_files()，是 BaseSandbox 基类强制要求自定义沙盒实现的底层能力，不依赖框架 execute() 脚本封装逻辑，依托沙盒容器原生文件传输机制实现。

运行边界：专门打通「宿主机本地环境」与「沙盒隔离环境」的双向数据通道，唯一职责是完成跨环境文件资源搬运，不参与沙盒内部的任务执行与文件编辑。

5.3.2 底层核心运行原理

该通道与智能体工具通道底层逻辑完全割裂，不通过 execute() 拼接脚本执行，而是直接调用沙盒底层原生传输能力（Docker 环境为 docker cp 命令，云端沙盒为服务商专属文件传输 SDK）。

完整执行链路分为双向逻辑：

正向上传（宿主机 → 沙盒）：开发者读取宿主机本地文件/二进制数据 → 调用 upload_files() 接口 → 框架通过底层传输协议将数据写入沙盒容器指定路径 → 智能体可通过内部文件工具读取使用。

反向下载（沙盒 → 宿主机）：开发者调用 download_files() 指定沙盒文件路径 → 框架从沙盒容器读取目标文件数据 → 回传至宿主机并持久化保存 → 业务系统可落地、展示、存储产物文件。

5.3.3 核心使用场景（任务全流程覆盖）

该通道贯穿智能体任务执行的「前置准备、中期支撑、后置落地」全流程，是连接业务系统与沙盒智能体的桥梁，核心场景分为三类：

1. 任务前置：资源初始化注入

智能体启动任务前，开发者将宿主机本地的专属资源上传至沙盒，为智能体工作提供基础支撑。

包括：业务专属配置文件、私有数据集、本地存量代码工程、环境变量配置文件、证书密钥文件（可控上传）、静态资源文件等。

解决沙盒初始环境为空、无业务资源的问题。

2. 任务后置：业务产物回收落地

智能体在沙盒内完成编码、数据分析、图表生成、报告编写、项目构建等工作后，所有产物均留存于沙盒内部，无法直接对外提供服务。

此时需通过 download_files() 将沙盒内的代码文件、Excel 分析报表、可视化图表、构建产物、日志文件等下载至宿主机，完成业务落地、数据留存、成果展示。

3. 动态资源迭代更新

长周期任务中，可动态通过上传接口更新沙盒内的配置、补丁代码、增量数据集；也可实时下载沙盒运行日志、中间产物，用于监控任务进度、排查运行异常。

5.3.4 核心特性与约束

• 完全人工可控： 所有跨环境文件流转均由开发者代码主动触发，模型无权限操作，杜绝恶意数据外传、资源篡改；
• 双向数据打通： 支持宿主机向沙盒注入资源、沙盒向宿主机回传产物，双向灵活流转；
• 独立底层能力： 不依赖 execute 脚本，传输效率更高、稳定性更强，支持大文件、批量文件传输；
• 无自动执行能力： 仅负责文件搬运，不修改、不运行文件内容，无任何代码执行风险，安全性极高。

5.3 核心区分总结

• 智能体工具： 管沙盒内部干活，纯环境内操作，无跨环境文件流转；
• 传输API： 管环境之间搬运资源，由开发者控制，用于初始化与产物回收。

六、生产落地关键：sandbox Infra 的 生命周期治理

execute() 方法决定了沙盒“能不能工作”，而生命周期设计决定了沙盒在生产环境中“稳不稳定、会不会失控、成本可控不可控”。

Deep Agents 提供两种官方生命周期隔离模式，适配不同业务场景。

六、生产落地关键：sandbox Infra 的 生命周期治理

6.1 Thread-scoped（会话级隔离，官方默认推荐）

核心规则：每一条用户对话线程对应一个独立沙盒，同一线程的多轮对话复用沙盒环境，新线程自动创建全新干净沙盒，线程过期或销毁后，沙盒同步释放。

适配场景：数据分析、一次性代码执行、临时任务处理、轻量化问答工程任务。

核心优势：每次任务都从干净环境启动，无历史文件、依赖、缓存残留，环境纯净、状态可控，风险极低。

6.2 Assistant-scoped（助手级共享）

核心规则：同一个智能体助手下的所有用户对话、所有任务，共享同一个沙盒环境，已安装的依赖、克隆的仓库、生成的文件可跨会话保留。

适配场景：长期迭代的代码助手、持续维护单一项目的工程智能体、需要复用环境依赖的长期任务。

核心风险：长期运行会出现文件堆积、依赖冗余、磁盘内存占用持续增长，极易导致环境状态不可控，必须配套治理策略。

必备治理方案：配置 TTL 空闲超时销毁、定期快照重置、周期性资源清理，避免沙盒资源堆积、失控。

6.3 生产必配：TTL 超时机制

TTL（空闲超时）是沙盒生产落地的核心刚需，绝非可选配置。

用户对话行为不可预测，若沙盒无过期销毁机制，空闲沙盒会持续占用服务器资源、产生计费成本，长期运行会造成资源浪费与服务卡顿。

官方最佳实践：将沙盒与 thread_id/assistant_id 唯一绑定，配置合理空闲超时时间，沙盒空闲后自动归档、销毁，实现资源按需释放、成本可控。

6.4、sandbox Infra 的  生命周期管理架构

生命周期管理架构是面向临时资源、容器、会话实例的资源治理架构，核心为每一个临时运行实例定义完整标准化生命周期：

• 创建、就绪、运行、空闲、销毁、回收全流程；
• 配套 TTL 空闲超时、状态标记、自动回收、资源兜底清理机制，避免临时资源长期驻留造成内存、磁盘、集群资源泄露，实现资源按需创建、按量释放，控制运行成本与服务稳定性，多用于容器、云沙盒、用户会话、临时 Pod 场景。

Deep Agents 沙盒完整落地标准化资源生命周期架构，为每一个 Sandbox 实例设计闭环生命周期流程，区分两种生命周期隔离模型，配套强制 TTL 超时回收机制，解决多用户并发场景资源失控问题。

生命周期完整链路分为五步：业务层主动创建沙盒实例（初始化 Docker 容器 / K8s Pod）→ 等待环境就绪校验 → 承接智能体多轮任务执行 → 监控空闲时长触发 TTL 超时判定 → 自动销毁容器 / Pod、清空沙盒内部全部文件、释放宿主机 / 集群 CPU 内存资源。

框架提供两套生命周期隔离策略，适配不同业务资源诉求：

• Thread-scoped 会话级生命周期，每条用户对话线程绑定独立沙盒，线程会话结束同步销毁实例，每次任务全新干净环境，无历史依赖、文件残留，适合一次性数据分析、临时代码运行；
• Assistant-scoped 助手级共享生命周期，单个智能体长期复用同一沙盒实例，满足长期项目迭代需求，但配套强制生命周期治理约束，必须配置空闲 TTL 定时重置、定期快照清理，避免依赖堆积、磁盘溢出。

底层插件层内置兜底销毁逻辑，Docker 沙盒__del__析构函数、K8s 沙盒实例销毁时自动执行容器 / Pod 删除命令，防止业务代码异常崩溃导致资源无法释放，形成双层回收保障（业务主动销毁 + 实例析构兜底销毁）。

生命周期架构同时解决成本管控问题，云端商用沙盒按量计费、企业 K8s 集群节点资源有限，依靠 TTL 空闲自动销毁，闲置沙盒不会持续占用计费资源与集群算力，实现资源弹性伸缩。

生产落地层面，生命周期与用户会话 ID、助手 ID 唯一绑定，可追溯每一个沙盒实例的创建时间、运行时长、销毁原因，便于运维监控资源占用情况；

同时生命周期状态与双文件通道联动，沙盒销毁前可批量下载业务产物，销毁后沙盒内部文件彻底清空，不会出现敏感数据残留。

整套生命周期架构从根源解决容器沙盒最常见的资源泄露、环境污染、成本不可控三大生产痛点，是大规模线上落地必不可少的架构设计。

七、 集成与协作：Agent 与 Sandbox 的协作模式

在实际工程集成中，Deep Agents 定义了两种标准架构，适配不同的迭代与部署需求，开发者可根据业务场景灵活选择。

7.1 Agent in Sandbox（智能体内置沙盒模式）

架构逻辑：将智能体框架、运行时环境全部打包进沙盒镜像/容器，智能体直接在沙盒环境内部运行，通过网络与外部应用通信。

核心优势：本地开发与生产部署形态完全一致，环境一致性拉满，智能体与执行环境耦合紧密，运行稳定性高。

核心弊端：API 密钥等配置需内置在沙盒中，密钥风险更高；迭代智能体逻辑需要重新打包镜像，更新效率低；需额外维护 HTTP/WebSocket 通信层。

7.2 Sandbox as tool（沙盒工具化模式，官方默认）

架构逻辑：智能体运行在本地应用服务器，仅当需要执行代码、运行命令、操作高危文件时，通过 SandboxBackend 远程调用沙盒环境，将沙盒作为独立工具使用。

核心优势：智能体代码迭代无需重构镜像，更新效率极高；核心密钥、配置保留在宿主环境，安全性更高；支持并行调用多个沙盒，资源调度更灵活。

核心弊端：远程调用存在轻微网络延迟，不适合极致高频的命令执行场景。

场景选型建议：绝大多数业务系统、线上生产项目优先选择Sandbox as tool；仅本地调试、需要极致环境一致性的场景，可选用 Agent in Sandbox。

八、极简落地：Sandbox 标准接入流程与实战代码

Deep Agents 沙盒的接入流程标准化、轻量化，可拆解为四大核心步骤，适配所有沙盒服务商，以下为通用接入逻辑与简化实战代码。

8.1 标准接入四步法

【1】实例创建： 通过对应服务商 SDK，初始化云端/本地沙盒实例；

【2】能力封装： 将沙盒实例包装为 Deep Agents 可识别的 SandboxBackend；

【3】智能体绑定： 将 backend 传入 create_deep_agent，为智能体注入沙盒执行能力；

【4】资源治理： 任务执行完毕后，主动销毁、释放沙盒资源，避免资源堆积。

8.2 通用实战示意代码

from deepagents import create_deep_agent
from langchain_anthropic import ChatAnthropic
# 1. 初始化沙盒实例（适配Daytona/阿里云AgentRun/Modal等所有服务商）
sandbox = create_provider_sandbox()
# 2. 封装为Deep Agents标准后端
backend = ProviderSandboxBackend(sandbox=sandbox)
# 3. 创建绑定沙盒能力的智能体
agent = create_deep_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    system_prompt="你是一名可以在隔离环境中安全执行代码、完成工程任务的智能体助手。
",
    backend=backend,
)
# 4. 调用智能体执行工程任务
result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "创建一个最小Python项目，安装依赖并运行测试用例",
            }
        ]
    }
)
# 5. 任务结束，主动释放沙盒资源
destroy_provider_sandbox(sandbox)

核心逻辑：沙盒并非智能体自主创建，而是由应用层提前初始化、注入能力、最后统一销毁，全程可控可运维。

8.3 大输出防溢出优化机制

框架内置贴心工程优化：当 Shell 命令、脚本执行输出内容过大时，不会将全部内容直接塞入 LLM 上下文窗口，而是自动将大体积输出保存至沙盒文件，提示智能体通过 read_file 工具分段读取，彻底避免上下文溢出问题，适配日志分析、批量构建、大数据输出等场景。

九、安全架构：Sandbox 能防什么、防不住什么？

很多开发者会误以为沙盒是“万能安全方案”，实则存在明确的能力边界，只有精准认知其防护范围，才能搭建完整的安全体系。

9.1 沙盒可防护的风险

• 杜绝智能体越权读取、篡改、删除宿主机本地文件；
• 隔离宿主机环境变量、密钥凭证，防止敏感信息泄露；
• 隔离宿主系统进程，避免智能体操作导致主服务崩溃、资源耗尽；
• 将智能体异常操作、脚本崩溃、资源占用过高的风险完全限制在沙盒内部。

9.2 沙盒无法自动防护的风险

1. 上下文注入攻击：若攻击者篡改智能体输入内容，可诱导模型在沙盒内执行高危命令。

沙盒仅能隔离宿主风险，无法阻止沙盒内部的恶意命令执行。

2. 网络数据外传风险：若沙盒开放公网访问权限，被诱导的智能体可通过 HTTP、DNS 等方式将沙盒内的数据外传，隔离环境不代表数据绝对安全。

9.3 完整安全加固方案

基于沙盒的基础隔离能力，需配套多层安全策略，构建完整风控体系：

• 按需关闭沙盒公网访问权限，限制网络出站规则；
• 密钥、凭证全部留存宿主机，禁止注入沙盒内部；
• 敏感操作开启人工审核（Human-in-the-Loop）；
• 清洗输入上下文，拦截恶意指令与注入脚本；
• 配置资源配额、执行超时，杜绝资源滥用。

9.4、sandbox Infra 的  最小权限安全架构（最小特权架构 Least Privilege）

最小权限架构是安全领域专属架构设计范式，核心规则：

• 系统中任意程序、进程、代理、组件仅授予完成自身任务必需的最低权限，默认关闭所有高危权限，权限升级必须显式主动申请；
• 通过权限分层、环境隔离、能力拆分缩小系统攻击面，即使组件被诱导执行恶意操作，破坏范围被严格限制在授权边界内，无法横向扩散风险，是生产级隔离系统必备安全架构。

sandbox Infra 的 沙盒设计从顶层框架到底层容器全链路落地最小权限架构，每一层都通过权限拆分、默认拒绝、边界隔离收缩攻击面。

• 首先框架顶层默认权限管控：框架初始化时默认仅注入无执行权限的 FilesystemBackend，完全关闭 execute 命令执行高危权限，属于 “默认拒绝” 最小权限设计；
• 开发者必须主动、显式实例化 SandboxBackend 插件并注入 Agent，才会授予代码执行权限，权限升级完全人为可控，杜绝默认开放权限带来的安全漏洞。
• 第二层能力边界权限拆分，严格区分两套文件通道权限，实现权限分离：智能体 LLM 自主调用的文件工具通道，权限仅限制在沙盒容器内部虚拟文件系统，无任何访问宿主机、向外传输文件的权限；
• 跨宿主机与沙盒的文件上传、下载权限完全剥离到业务层 API，仅开发者编写的业务代码可以调用，大模型智能体完全无法自主触发跨环境文件流转，彻底杜绝数据泄露、宿主机文件篡改风险。
• 第三层沙盒环境容器级权限隔离，即使智能体获得 execute 执行权限，所有命令运行载体是独立隔离容器，容器进程仅分配最低资源配额，无法读取宿主机密钥、环境变量、系统配置文件、宿主进程；智能体在沙盒内执行 rm -rf / 等高危删除命令，仅销毁容器内部文件，无法越权破坏宿主机，风险边界被锁死在沙盒内部。

同时配套分层权限加固策略：

• 沙盒网络权限默认按需关闭出站访问，防止数据外传；
• 密钥、数据库凭证全程保存在宿主机，绝不上传注入沙盒，进一步收缩沙盒权限范围；
• 针对注入攻击，通过输入清洗、执行超时、资源配额补充最小权限短板。

整套架构没有一刀切开放全量能力，而是分层、按需、显式授予权限，完美解决 AI 智能体行为不可预测带来的安全风险，是企业级智能体生产落地安全底座。

十、进阶实践：自定义 Docker 沙盒开发

Deep Agents 支持开发者自定义私有沙盒环境，核心是继承 BaseSandbox 基类，实现三大底层核心方法，即可适配框架全部能力。

核心实现要求：

【1】execute()： 核心方法，实现 Docker 容器内命令执行逻辑；

【2】upload_files()： 实现宿主机到 Docker 容器的文件上传；

【3】download_files()： 实现 Docker 容器到宿主机的文件下载。

十一. 进阶实践：自定义 K8s 沙盒开发

除本地 Docker 沙盒外，在生产级 AI 智能体平台中，Kubernetes 沙盒是多租户、弹性扩容、高并发场景下的标准落地方案。

相比于 Docker 单机容器，K8s 沙盒支持集群化调度、资源配额管控、Pod 生命周期统一治理、权限细粒度隔离，是企业级 Deep Agents 智能体规模化部署的最优方案。

K8s 自定义沙盒的适配逻辑与 Docker 沙盒完全一致，同样遵循框架规范：仅需实现 execute()、upload_files()、download_files() 三大底层方法，框架自动封装全部文件工具、命令执行能力，无需额外改造框架源码。

1. K8s 沙盒核心设计思路

我们基于 K8s Pod 构建独立隔离沙盒，每一个沙盒对应一个独立临时 Pod，具备以下特性：

• Pod 采用 临时一次性机制，任务结束自动销毁，杜绝资源残留；
• 依托 K8s 原生 exec 实现容器命令执行，替代 Docker exec；
• 依托 K8s 原生 cp 实现宿主机与 Pod 双向文件传输，替代 Docker cp；
• 自动生成唯一 Pod 名称、命名空间隔离，支持多智能体并发运行；
• 完整适配框架标准化返回结构体，零改动适配 Deep Agents 上层能力。

2. 前置依赖与环境要求

运行自定义 K8s 沙盒需满足基础环境条件：

• 宿主机安装 kubectl 且完成集群授权（可正常操作目标命名空间）；
• 集群内可用基础 Python 镜像（python:3.10-slim）；
• 开启 Pod 交互式命令执行、文件拷贝权限；
• 支持 Pod 自动清理、TTL 过期回收机制。

十二、核心辨析：Deep Agents 中 Backend 与 Sandbox 的本质区别与协作逻辑

多数开发者混淆二者概念，核心是未分清「能力定义」与「环境承载」的层级关系。

简单总结：Backend 决定智能体能干什么，Sandbox 决定智能体安全在哪里干。

11.1 核心定位差异

Backend（能力抽象层）：是智能体的能力工具箱，负责定义权限边界与可调用资源，分为三类：

• FilesystemBackend： 仅文件操作，无执行权限，轻量化零风险；
• LocalShellBackend： 本地宿主机命令执行，权限最高、风险最大，仅用于本地可信调试；
• SandboxBackend： 安全能力后端，依托沙盒环境实现可控执行。

Sandbox（环境隔离层）：是智能体的安全操作车间，无自主能力，仅提供独立隔离的运行环境，负责规避所有执行风险。

11.2 二者协作链路

完整运行链路：AI Agent 发起操作请求 → Backend 校验权限、匹配可用能力 → 高危操作投递至 Sandbox 隔离环境 → execute() 执行命令 → 返回结果、闭环管控。

核心协作逻辑：Sandbox 必须依托 SandboxBackend 才能生效，SandboxBackend 是普通后端的安全升级版，在保留全能力的同时，将执行载体从宿主机切换为隔离沙盒，实现「能力拉满、风险归零」。

11.3 场景选型对照表

• 本地轻量化文件处理： FilesystemBackend + 无沙盒；
• 本地可信全功能调试： LocalShellBackend + 无沙盒；
• 线上生产、多租户、代码执行场景： SandboxBackend + 云端沙盒。

12.4 sandbox Infra 的   插件化架构（Plugin 插件架构）

插件化架构核心是核心框架与扩展实现完全解耦，框架定义一套标准化抽象接口 / 基类作为插件规范，所有差异化、可替换的业务 / 基础设施能力都以独立插件形式实现；

核心框架仅依赖抽象基类，不绑定任意具体插件实现，运行时可动态插拔、切换、新增插件，无需修改框架核心源码，扩展性极强，广泛用于中间件、AI 框架、多厂商适配场景。

Deep Agents 整套 Backend+Sandbox 体系完全基于插件化架构构建，BaseSandbox抽象基类是统一插件规范，所有沙盒实现都是独立可插拔插件。

框架核心推理、Agent 调度逻辑只依赖 BaseSandbox 抽象接口，仅约定必须实现 execute、upload_files、download_files 三个抽象方法，完全不关心底层是 Docker、K8s、云端商用沙盒哪一种实现，所有差异化环境逻辑全部封装在独立插件内部。

上面实现的 LocalDockerBackend、K8sSandboxBackend 就是两套独立插件，遵循同一套抽象规范，上层创建 Agent 时可以任意切换插件实例，业务代码无需改动；

同时第三方沙盒厂商可以独立开发自有插件（Daytona、Runloop 插件），仅需要实现基类三个方法，无需修改 Deep Agents 框架核心源码，即插即用。

Backend 层同样遵循插件化，FilesystemBackend、LocalShellBackend、SandboxBackend 三类后端作为能力插件，根据业务场景动态注入 Agent，本地调试切换 LocalShell 插件，线上生产切换 Sandbox 安全插件，轻量化文件任务使用纯文件插件，灵活插拔适配不同风险等级场景。

插件架构完美解决生产环境多部署形态差异化需求：

• 本地开发使用 Docker 插件，企业集群生产替换 K8s 插件，SaaS 多租户平台接入云端商用沙盒插件，一套上层业务逻辑兼容全部环境。
• 同时插件隔离带来故障隔离优势，Docker 插件内部容器销毁、K8s 插件 Pod 异常不会污染框架核心 Agent 运行逻辑，插件内部资源销毁、生命周期管理完全自闭环。

生命周期治理逻辑也内嵌在插件内部，Thread-scoped、Assistant-scoped 两种隔离模式作为插件配置参数，切换插件同时配套对应资源回收策略。

插件化架构是该框架能适配个人开发、企业私有化、云端 SaaS 多类落地场景的核心底层支撑。

12.5 sandbox Infra 的  分层架构模式（Layered Architecture）思维

分层架构是软件行业最通用的解耦设计模式，核心思想是将系统按职责垂直切割为多层，每层仅依赖下层、仅向上层暴露标准化接口，层与层之间严格隔离、单向依赖；

上层无需感知下层具体实现，下层可无感知替换、重构、扩展，核心收益是职责分离、易维护、可替换、降低变更风险。标准分层结构一般分为应用接入层、能力抽象层、执行基础设施层、底层资源层。

Deep Agents 沙盒体系sandbox Infra   完全基于分层架构搭建，自上而下清晰划分四层，每层边界完全隔离，完美体现分层设计优势。

• 最上层是 Agent 应用层，面向业务开发者，仅对外暴露create_deep_agent、agent.invoke极简调用接口，开发者无需关心沙盒、命令执行、文件传输底层细节；
• 第二层为 Backend 能力抽象层，是分层核心中间层，统一封装三类后端：纯文件 FilesystemBackend、本地高危 LocalShellBackend、安全隔离 SandboxBackend，该层统一定义文件读写、命令执行、文件上传下载的标准接口，向上给 Agent 提供统一能力调用协议，向下对接不同运行环境；
• 第三层为 Sandbox 隔离执行层，作为 Backend 下层基础设施，仅实现execute()、upload_files()、download_files三个底层标准方法，不感知上层智能体逻辑，仅负责隔离环境的命令运行与文件流转；

最底层是宿主机 / 容器资源层，包含 Docker 容器、K8s Pod、云端商用沙盒资源，提供硬件与容器基础能力。

分层带来的工程价值在文中多处体现：

• 上层 Agent 代码完全不依赖底层沙盒实现，本地 Docker 沙盒、企业 K8s 沙盒、Daytona 商用沙盒可以无缝替换，仅替换底层 Sandbox 实现，上层业务代码零改动；
• Backend 层单独做权限管控，默认禁用高危执行能力，仅显式接入沙盒后端才开放 execute 执行入口，分层隔离天然实现最小权限管控；文件双通道也依托分层实现隔离，智能体工具通道运行在 Backend 上层，跨环境文件传输 API 下沉至沙盒底层，两层互不干扰。
• 分层架构大幅降低定制开发成本，自定义 Docker、K8s 沙盒仅需实现底层三层标准接口，无需修改上层 Agent 推理逻辑，完全解耦业务与底层执行环境，是整套沙盒体系最核心的底层架构支撑。

十三、 Sandbox  infra 基础设施 核心总结

Deep Agents 的 Sandbox  infra 基础设施 架构设计极简且极具工程价值，所有核心逻辑可浓缩为5个核心要点：

【1】定位核心： Sandbox 是安全隔离的高级 Backend，是智能体实现工程化执行的核心基础设施；

【2】架构核心： 单一 execute() 方法为唯一执行入口，所有文件工具均基于该方法封装，扩展性极强；

【3】职责核心： 双文件通道严格区分内外操作，智能体负责沙盒内作业，开发者负责跨环境资源搬运；

【4】落地核心： 依托会话级/助手级生命周期+TTL 机制，实现生产环境资源可控；

【5】安全核心： 沙盒隔离宿主风险，但非万能方案，需配套多层安全策略完善风控体系。

对于 AI 工程化开发者而言，吃透 Sandbox infra 基础设施 的底层逻辑，是开发出稳定、安全、可落地、可商用的企业级 AI 智能体的必备基础。

文章来自：51CTO