DeepAgents 使用 Docker 沙箱执行 Shell 命令：从 0 到生产部署

DeepAgents 使用 Docker 沙箱执行 Shell 命令从 0 到生产部署一、为什么需要 Docker 沙箱DeepAgents 的execute工具只有在后端实现SandboxBackendProtocol时才会真正执行 Shell 命令。项目里默认使用的FilesystemBackend只负责文件读写不支持执行命令。所以当 Skill 里出现下面这类指令时Agent 无法真正运行脚本python skills/bank-asset-allocation-report/scripts/generate_report.py...直接换成LocalShellBackend虽然简单但它会在宿主机上执行任意命令存在安全风险不适合作为 Web API 的生产方案。更稳妥的做法是使用 Docker 沙箱把命令执行、文件读写都隔离到容器里。二、DeepAgents 沙箱实现原理DeepAgents 已经提供了BaseSandbox它基于两个核心能力实现了大部分文件操作execute()在沙箱里执行 Shell 命令upload_files()把文件传入沙箱download_files()从沙箱取回文件id沙箱唯一标识ls、read、write、edit、grep、glob这些方法都由BaseSandbox自动实现不需要我们重写。三、Docker 镜像准备新建app/docker/DockerfileFROM python:3.12-slim RUN apt-get update \ apt-get install -y --no-install-recommends grep \ rm -rf /var/lib/apt/lists/* WORKDIR /workspace # 如果沙箱里要运行项目脚本就安装项目依赖 RUN pip install --no-cache-dir reportlab python-docx markdown openpyxl pypdf # 容器必须有一个长驻进程否则启动后会立即退出 CMD [python3, -c, import time; time.sleep(1e9)]构建镜像dockerbuild-tdeepagents-sandbox:latest-fapp/docker/Dockerfile.说明python:3.12-slim和项目要求一致。项目pyproject.toml要求3.12,3.13本地.venv也是 Python 3.12。CMD里的time.sleep(1e9)大约 31.7 年对开发环境来说等于常驻而且不占用 CPU。如果容器启动后显示Exited (0)多半是启动命令是裸的python3Python 解释器没有输入就退出了。四、实现 DockerSandbox这里推荐使用 Docker CLI 实现不依赖 Python 的docker包。这样做有两个好处避免项目根目录docker/文件夹和 pip 包docker重名。不需要额外安装 Python SDK生产环境只需要 Docker CLI。新建app/docker/docker_sandbox.pyfrom__future__importannotationsimportioimportsubprocessimporttarfileimporttimeimportuuidfromdeepagents.backends.protocolimport(ExecuteResponse,FileDownloadResponse,FileUploadResponse,)fromdeepagents.backends.sandboximportBaseSandboxclassDockerSandbox(BaseSandbox):def__init__(self,*,image:strpython:3.12-slim,workdir:str/workspace,timeout:int120,volumes:dict|NoneNone,)-None:self._workdirworkdir self._timeouttimeout namefdeepagents-{uuid.uuid4().hex[:8]}cmd[docker,run,-d,--name,name,--workdir,workdir]forhost_path,cfgin(volumesor{}).items():cmd[-v,f{host_path}:{cfg[bind]}:{cfg.get(mode,rw)}]cmd[image,python3,-c,import time; time.sleep(1e9)]procsubprocess.run(cmd,capture_outputTrue,textTrue)ifproc.returncode!0:raiseRuntimeError(fdocker run failed:{proc.stderr})self._container_idproc.stdout.strip()propertydefid(self)-str:returnself._container_id[:12]defexecute(self,command:str,*,timeout:int|NoneNone)-ExecuteResponse:procsubprocess.run([docker,exec,-w,self._workdir,self._container_id,/bin/sh,-c,command,],capture_outputTrue,encodingutf-8,errorsreplace,timeouttimeoutiftimeoutisnotNoneelseself._timeout,)returnExecuteResponse(outputproc.stdoutproc.stderr,exit_codeproc.returncode,)defupload_files(self,files:list[tuple[str,bytes]])-list[FileUploadResponse]:responses[]forpath,contentinfiles:ifnotpath.startswith(/)or..inpath:responses.append(FileUploadResponse(pathpath,errorinvalid_path))continuebufio.BytesIO()withtarfile.open(fileobjbuf,modew)astar:infotarfile.TarInfo(path.lstrip(/))info.sizelen(content)info.mtimeint(time.time())tar.addfile(info,io.BytesIO(content))procsubprocess.run([docker,cp,-,f{self._container_id}:/],inputbuf.getvalue(),capture_outputTrue,)ifproc.returncode0:responses.append(FileUploadResponse(pathpath))else:responses.append(FileUploadResponse(pathpath,errorproc.stderr.decode(errorsreplace).strip()orupload_failed,))returnresponsesdefdownload_files(self,paths:list[str])-list[FileDownloadResponse]:responses[]forpathinpaths:ifnotpath.startswith(/)or..inpath:responses.append(FileDownloadResponse(pathpath,errorinvalid_path))continueprocsubprocess.run([docker,cp,f{self._container_id}:{path},-],capture_outputTrue,)ifproc.returncode!0:errproc.stderr.decode(errorsreplace)errorfile_not_foundifnot foundinerr.lower()orno suchinerr.lower()elseerr.strip()[:200]responses.append(FileDownloadResponse(pathpath,errorerror))continuetry:withtarfile.open(fileobjio.BytesIO(proc.stdout),moder:*)astar:membertar.next()ifmemberisNoneormember.isdir():responses.append(FileDownloadResponse(pathpath,erroris_directory))continuecontenttar.extractfile(member).read()responses.append(FileDownloadResponse(pathpath,contentcontent))exceptExceptionasexc:responses.append(FileDownloadResponse(pathpath,errorstr(exc)[:200]))returnresponses核心实现说明docker run -d创建长驻容器。docker exec在容器里执行命令。docker cp - 容器:/从标准输入接收 tar 包并解压到容器实现文件上传。docker cp 容器:路径 -把容器文件打包成 tar 输出到标准输出实现文件下载。五、接入主 Agent修改app/agent/main_agent.pyfromapp.docker.docker_sandboximportDockerSandbox project_root_pathPath(__file__).parents[1].resolve()(project_root_path/output).mkdir(parentsTrue,exist_okTrue)file_backendDockerSandbox(imagedeepagents-sandbox:latest,workdir/workspace,timeout120,volumes{str(project_root_path):{bind:/workspace,mode:ro},str(project_root_path/output):{bind:/workspace/output,mode:rw},},)这里把app/只读挂载到容器的/workspace把output/单独以可写方式挂载这样Agent 能在容器里读取skills/。生成的文件会写到/workspace/output/session_xxx。宿主机通过app/output/session_xxx直接看到结果。六、验证先验证基础命令dockerrun-dit--namesandbox-test deepagents-sandbox:latest python3-cimport time; time.sleep(1e9)dockerexecsandbox-test python3--version再验证 Python 后端cdD:/AI Learning/financesearch-agents .venv\Scripts\python-B-c from app.docker.docker_sandbox import DockerSandbox s DockerSandbox( imagedeepagents-sandbox:latest, workdir/workspace, volumes{ D:/AI Learning/financesearch-agents/app: {bind: /workspace, mode: ro}, D:/AI Learning/financesearch-agents/app/output: {bind: /workspace/output, mode: rw}, }, ) print(s.execute(python3 --version)) s.write(/workspace/output/test.txt, hello) print(s.read(/workspace/output/test.txt)) 验证完删除测试容器dockerrm-fsandbox-test七、Windows Docker Desktop 常见问题1. 容器启动后立即变成 Exited (0)原因通常是启动命令是裸的python3IMAGE COMMAND STATUS deepagents-sandbox:latest python3 Exited (0)Python 解释器启动后没有 stdin 输入会立即退出。解决Dockerfile 里加CMD [python3, -c, import time; time.sleep(1e9)]。手动运行时使用docker run -dit ... python3 -c import time; time.sleep(1e9)。Docker Desktop 需要处于 Linux 容器模式。2. import docker 指向了项目自己的 docker 目录如果项目根目录有docker/文件夹Python 的import docker会优先解析到这个目录module docker (namespace) from [D:\\AI Learning\\financesearch-agents\\docker]这不是 pip 包docker所以没有from_env()方法。不重命名目录的解决方案就是本文使用的方案不import docker全部改用 Docker CLI。如果一定要用 Python SDK则需要把项目根目录的docker/改名例如infra/否则会一直冲突。3. docker.from_env 需要加载 .env 吗docker.from_env()读取的是进程环境变量不是.env文件。本机 Docker Desktop 默认不需要任何环境变量。远程 Docker 时需要在启动进程前设置DOCKER_HOST、DOCKER_TLS_VERIFY、DOCKER_CERT_PATH等变量。如果这些变量写在.env里需要先调用load_dotenv()再执行docker.from_env()。4. Python 版本不一致有影响吗本地虚拟环境是 Python 3.12.13项目锁定 Python 3.12因此 Docker 镜像使用python:3.12-slim是正确选择。真正需要注意的不是版本而是平台Docker 镜像是 Debian Linux本地是 Windows。脚本里的路径和 Shell 命令要按照 Linux 书写。如果容器里要运行项目脚本必须在 Dockerfile 里安装脚本依赖。八、生产部署建议1. 每个会话使用独立容器当前DockerSandbox每次实例化都会创建新容器。Web 服务里不要让所有用户共用一个容器否则文件会互相污染。建议每个session_id对应一个容器任务结束后dockerstopcontainer_iddockerrmcontainer_id2. 限制挂载权限生产环境不要直接把整个项目目录以可写方式挂载进容器。推荐只挂载必要目录skills/只读挂载。output/可写挂载。数据库配置、密钥、上传文件不要放进容器。3. 远程 Docker部署到远程 Docker 时在服务启动前设置DOCKER_HOSTtcp://192.168.1.10:2375或者DOCKER_HOSTssh://user192.168.1.10使用 Docker CLI 方案时docker run、docker exec、docker cp都会读取同一个环境变量不会出现连接不一致的问题。4. 镜像版本固定生产环境不要使用latest建议固定到具体版本dockerbuild-tregistry.example.com/deepagents-sandbox:2026.08.10.dockerpush registry.example.com/deepagents-sandbox:2026.08.105. 安全控制不要接受不可信用户的任意 Shell 命令。有需要时配合interrupt_on{execute: True}做人工审批。容器内不要安装不必要的网络工具和调试工具。定期清理退出状态的历史容器和未使用的镜像。九、总结这套方案的核心思路是用BaseSandbox继承 DeepAgents 的沙箱接口。只实现execute、upload_files、download_files、id。使用 Docker CLI 替代 Python SDK避免项目目录重名问题。通过只读挂载和独立容器实现生产环境的基本隔离。这样既能让 Agent 真正执行 Skill 里的脚本又比直接在宿主机上执行命令安全得多。