
DB-GPT Sandbox为 Agent 构建安全隔离的代码执行运行时【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT本文基于 DB-GPT 官方文档 Sandbox 总览 并结合dbgpt-sandbox包的真实源码展开系统讲解 DB-GPT 沙箱的设计动机、分层架构Execution / Control / User / Display、Runtime 自动选择机制、有状态 Session 模型以及 HTTP 接口面。读完后你将理解为什么 Agent 场景必须把推理与执行隔离、DB-GPT 如何优先选择 Docker/Podman/Nerdctl 容器后端并在受限时安全退化以及如何在应用中把沙箱接入智能体工具链。什么是 Sandbox为什么 Agent 需要隔离执行DB-GPT 使用 sandbox沙箱让智能体在隔离的运行环境中执行代码和工具而不是直接在宿主机环境中运行。这对 agent 工作流非常重要因为智能体往往不仅仅需要文本推理还需要执行代码运行 shell 命令安装依赖生成文件在多轮执行之间保持状态Sandbox 就是把这些执行能力放在一个更安全、可控、可管理的边界内。在 DB-GPT 中sandbox 是一个隔离执行环境供智能体在任务过程中执行代码、运行命令、处理文件或调用执行型工具。它避免智能体直接操作宿主机并提供进程隔离资源限制内存、CPU、超时可控工作目录可选依赖安装能力会话生命周期管理清晰的推理和执行边界如果智能体可以不受限制地直接执行代码那么在真实环境中很难安全落地。Sandbox 为 DB-GPT 提供了一个专门的执行层用于支持代码执行、shell 命令执行、依赖安装、文件创建与读取、多步骤有状态的数据分析。这对数据分析、报表生成和工具驱动型工作流尤其重要因为这些场景需要把推理和真实执行结合起来。Sandbox 如何作用于 Agent智能体负责决定下一步做什么sandbox 负责安全地执行这个动作怎么运行。官方文档给出的调用链路如下从源码看这条链路中执行结果 / observation对应的统一数据结构是ExecutionResult定义在 execution_layer/base.py 中dataclass class ExecutionResult: 代码执行结果 status: ExecutionStatus output: str error: str execution_time: float 0.0 memory_usage: int 0 # bytes exit_code: int 0ExecutionStatus枚举提供四种终态SUCCESS、ERROR、TIMEOUT、RESOURCE_LIMITbase.py。也就是说Agent 观察到的每一次执行都带有状态语义——超时和资源超限是独立的执行结果类型而不是简单的报错这为上层重试、降级逻辑提供了判断依据。dbgpt-sandbox的分层架构DB-GPT 当前的 sandbox 实现位于 packages/dbgpt-sandbox/。它是一个分层的、可扩展的沙箱运行时系统支持多种 backend分为四层。1. Execution layer执行层执行层提供具体 runtime 实现与核心抽象位于packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/execution_layer/base.py定义 runtime / session / result / config 等公共接口docker_runtime.py、podman_runtime.py、nerdctl_runtime.py、local_runtime.py具体运行时实现runtime_factory.py负责自动选择 backendbase.py中的两个抽象基类是整个沙箱的契约class SandboxSession(ABC): 沙箱会话抽象类 async def start(self) - bool async def stop(self) - bool async def execute(self, code: str) - ExecutionResult async def get_status(self) - Dict[str, Any] async def install_dependencies(self, dependencies: List[str]) - ExecutionResultclass SandboxRuntime(ABC): 沙箱运行时抽象类 async def create_session(self, session_id, config) - SandboxSession async def destroy_session(self, session_id) - bool async def list_sessions(self) - List[str] async def get_session(self, session_id) async def cleanup_expired_sessions(self, max_idle_time: int 3600) - int async def health_check(self) - Dict[str, Any] def supports_language(self, language: str) - bool从接口签名可以推断会话是运行时下的一等公民支持过期清理默认闲置 1 小时、健康检查与语言支持探测install_dependencies是可选能力基类默认返回未实现错误由具体运行时如容器后端按需覆盖。2. Control layer控制层控制层负责任务生命周期与执行编排实现锚点为 control_layer.py。它处理的操作完整列表见 schemas.py 中的TASK_TYPEStask_type处理逻辑源码中的 handlerconnect_handle_connect创建新的沙箱会话configure_handle_configure配置沙箱环境例如安装依赖execute_handle_execute在沙箱中执行代码manual_handle_manual进入手动操作模式disconnect_handle_disconnect停止并销毁沙箱会话status_handle_status获取任务/会话状态list_handle_list列出所有活跃会话get_file_handle_get_file获取沙箱内指定文件内容控制层入口是ControlLayer.handle_task(task)它按task.task_type查表分发到对应 handler并用asyncio.Lock对每个task_id加锁保证同一任务的串行执行。几个值得注意的实现细节会话标识约定connect时若未指定session_id则生成 UUID用户层则统一使用{user_id}_{task_id}组合作为 session_id见 service.py从而把用户 任务与沙箱会话一一绑定。资源参数注入_handle_connect构造SessionConfig时固定working_dir/workspace、max_memory512MBmax_cpus与环境变量、network_disabled则从任务的config中读取。shell 语言归一化_handle_execute会把languageshell归一化为bash使 shell 代码走统一的执行路径control_layer.py。3. User layer用户层用户层对外暴露 sandbox 服务接口实现锚点service.pyschemas.pyschemas.py定义了TaskObject——控制层的统一输入载体封装task_type、user_id、task_id、session_id、language、code_content、config、manual_action、file_name等字段并在构造时校验task_type必须属于TASK_TYPES白名单。service.py则把控制层封装为UserLayer类并直接挂载为一套 FastAPI 路由默认挂在/api前缀下可通过initialize_sandbox()启动独立服务或注册到已有 FastAPI 应用接口方法说明/healthGET健康检查/connectPOST建立沙箱会话user_idtask_idimage_type/configurePOST配置沙箱环境如安装依赖/disconnectPOST断开并销毁沙箱会话/executePOST执行代码session_idcode_typecode_content/manualPOST进入手动操作模式/statusPOST获取任务/会话状态/sessionsGET列出所有活跃会话/get_filePOST获取沙箱内指定文件内容/methodsGET获取所有可用接口和方法对应的请求模型ConnectRequest、ExecuteRequest等 Pydantic 模型定义在 service.py 中字段校验在入口处完成。4. Display layer显示层显示层用于封装运行时相关的展示结果或文件型结果实现锚点为 display_layer.py。结合manual任务类型返回的http://sandbox-gui/{session_id}地址可以推断该层面向的是沙箱产物文件、GUI 会话地址等向 Agent / UI 的展示转换。Runtime backendsDocker → Podman → Nerdctl → Local 的自动选择运行时工厂会按以下优先级自动选择 backendDocker基于 Docker SDK并调用client.info()做连通性验证PodmanNerdctlLocal runtime本地进程需显式开启实现锚点runtime_factory.py。关键的安全设计在_local_runtime()本地运行时会直接在宿主机上执行代码因此默认拒绝退化必须由用户显式声明if not SANDBOX_ALLOW_LOCAL_RUNTIME: raise RuntimeError( LocalRuntime executes code on the host. Set SANDBOX_RUNTIMElocal and SANDBOX_ALLOW_LOCAL_RUNTIMEtrue to opt in explicitly. )这意味着 DB-GPT 会优先使用容器隔离如果部署环境没有容器支持且未显式允许本地运行时工厂会直接抛出RuntimeErrorfail closed而不是静默地在宿主机上跑代码。相关环境变量定义在 config.pySANDBOX_RUNTIME可选值docker/podman/nerdctl/local不设时走自动探测。指定后若对应后端不可用会抛出指定的运行时不可用错误而不是继续回退。SANDBOX_ALLOW_LOCAL_RUNTIME布尔开关1/true/yes/on仅在明确允许时才允许使用宿主机本地运行时。语言镜像映射与执行命令容器后端按语言选择基础镜像映射关系定义在 config.pylanguage容器镜像执行命令get_command_by_languagepythonpython:3.11-slimpython {filename}python-vncvnc-gui-browser:latestpython3 {filename}javascriptnode:18-slimnode {filename}javaopenjdk:11-jre-slimjavac {filename} java {filename[:-5]}cppgcc:latestg -o program {filename} ./programgogolang:1.21-alpinego run {filename}rustrust:1.75-slimrustc {filename} -o program ./programpython-vnc一项值得注意它指向带 VNC GUI 的浏览器镜像对应 sandbox 设计中未来扩展到 browser / computer 风格运行时的方向详见下文。会话级配置与资源限制SessionConfigbase.py是每次会话的资源契约字段默认值说明languagepython会话执行语言timeout30秒单次执行超时max_memory256MB内存上限max_cpus1CPU 上限working_dir/workspace容器内工作目录environment_vars{}注入的环境变量network_disabledFalse是否禁用网络此外config.py 还定义了一组全局资源常量作为各后端的限制基线常量值含义MAX_MEMORY256MB单次执行内存上限MAX_CPU_PERCENT50.0CPU 百分比上限MAX_EXECUTION_TIME30s单次执行时间上限MAX_FILE_SIZE10MB文件大小上限MAX_DEPENDENCY_INSTALL_TIME300s依赖安装时间上限MAX_DEPENDENCY_INSTALL_SIZE200MB依赖安装体积上限MAX_PROCESSES10进程数上限这些常量与ExecutionStatus.TIMEOUT/RESOURCE_LIMIT两个终态相呼应任何一条限制被触发执行都会以可辨识的状态返回给 Agent而不是无差别地失败。Session 模型与有状态执行DB-GPT 当前 sandbox 设计的一个重要点是支持基于 session 的有状态执行。这意味着sandbox session 可以先创建一次多个执行步骤可以复用同一个 session上一步安装的依赖在后续步骤中仍然可用前一步生成的文件也可以在后一步继续使用。这非常适合 agent 场景因为很多任务不是一次工具调用就完成而是需要多轮推理 → 执行 → 观察。源码层面这个能力由三层支撑Runtime 维护会话字典SandboxRuntime.__init__中持有sessions: Dict[str, SandboxSession]并通过cleanup_expired_sessions(max_idle_time3600)回收闲置会话base.py控制层持久化任务 → 会话映射ControlLayer.tasks[task_id]记录session_id与状态connected/configured/finished/failed/manual/stoppedconfigure与execute都通过该映射复用同一会话用户层维护活跃会话表UserLayer.active_sessionssession_id → task_id让后续的/execute、/get_file、/status请求无需重复携带 user/task 上下文。dbgpt-sandbox 的 README 也明确了这一设计目标支持有状态的沙箱环境多次代码执行可以在相同环境中并且上次环境的变更能影响下次的执行例如第一次执行安装 pypi 依赖第二次执行安装后的依赖能正常使用同时以插件化方式支持 Docker、Podman、本地进程基于 Cgroup/Namespace/WebAssembly 等等多种实现。dbgpt-app 中的当前接入方式目前 DB-GPT 已经在应用侧 agent 工具里实际使用了 sandbox。例如 agentic_data_api.py 中的shell_interpreter工具就使用了dbgpt-sandbox的LocalRuntime执行 shell 命令工具实现位于 shell_interpreter.py并具备进程隔离内存限制超时限制安全校验当前这里的实现是单次调用无状态的每次工具调用都会创建一个临时 sandbox session执行结束后销毁。因此仓库里实际上同时存在两层能力dbgpt-sandbox中更完整的、可复用 session 的 sandbox 设计dbgpt-app中已经在实际工具执行里接入的 sandbox 用法。两者互补后者验证了沙箱执行在生产工具链中的可行性前者提供了面向多轮 Agent 任务的会话化运行时。DB-GPT 当前支持的方向基于当前dbgpt-sandbox实现DB-GPT 正在走向一个更通用的 agent 执行运行时支持多 runtime 的 sandbox 执行安全代码与 shell 执行有状态 sessionsandbox 内依赖安装任务生命周期控制文件读取与产物管理。这使得 sandbox 很适合支撑代码 agent、数据分析 agent、报告生成 agent以及未来扩展到 browser / computer 风格运行时LANGUAGE_IMAGES中的python-vnc条目即为该方向的早期落地。这张图是概念性的表示 sandbox 作为 agent 应用之下的专门运行时层。当前仓库已经在dbgpt-sandbox中具备 execution、control、session 和 runtime selection 的基础能力。关键实现锚点索引关注点文件路径沙箱设计目标与背景packages/dbgpt-sandbox/README.md架构设计文档packages/dbgpt-sandbox/src/docs/architecture.md使用教程文档packages/dbgpt-sandbox/src/docs/usage.md运行时自动选择runtime_factory.pyRuntime/Session 抽象base.py语言镜像与资源常量config.py任务生命周期编排control_layer.pyHTTP 服务接口service.py任务模型与类型白名单schemas.py应用侧沙箱接入示例agentic_data_api.py【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考