Sandbox 总览
DB-GPT 使用 sandbox(沙箱)让智能体在隔离的运行环境中执行代码和工具,而不是直接在宿主机环境中运行。
这对 agent 工作流非常重要,因为智能体往往不仅仅需要文本推理,还需要:
- 执行代码
- 运行 shell 命令
- 安装依赖
- 生成文件
- 在多轮执行之间保持状态
Sandbox 就是把这些执行能力放在一个更安全、可控、可管理的边界内。
什么是 sandbox?
在 DB-GPT 中,sandbox 是一个隔离执行环境,供智能体在任务过程中执行代码、运行命令、处理文件或调用执行型工具。
它避免智能体直接操作宿主机,并提供:
- 进程隔离
- 资源限制
- 可控工作目录
- 可选依赖安装能力
- 会话生命周期管理
- 清晰的“推理”和“执行”边 界
Sandbox 如何作用于 agent
智能体负责决定下一步做什么,sandbox 负责安全地执行这个动作怎么运行。
为什么 agent 需要 sandbox
如果智能体可以不受限制地直接执行代码,那么在真实环境中很难安全落地。Sandbox 为 DB-GPT 提供了一个专门的执行层,用于支持:
- 代码执行
- shell 命令执行
- 依赖安装
- 文件创建与读取
- 多步骤、有状态的数据分析
这对数据分析、报表生成和工具驱动型工作流尤其重要,因为这些场景需要把推理和真实执行结合起来。
DB-GPT 当前的 sandbox 方案
DB-GPT 当前的 sandbox 实现位于:
packages/dbgpt-sandbox/
它是一个分层的、可扩展的沙箱运行时系统,支持多种 backend。
Runtime backends
当前应用侧 Agent 集成默认使用 LocalRuntime。容器执行需要通过 SANDBOX_RUNTIME=docker(或显式选择 Podman/Nerdctl)开启。如果配置的容器运行时 无法初始化或会话创建失败,Agent 执行器会返回错误,不会在本地执行用户代码。 LocalRuntime 是默认值,而不是故障兜底,且不提供容器隔离。
关于配置、镜像要求、执行生命周期和验证命令,请参阅 Sandbox 运行时配置。
实现锚点:
packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/execution_layer/runtime_factory.py
Docker 不会因为已经安装在机器上就自动启用。这样默认安装无需预先构建 Agent 镜像, 同时允许部署方显式选择容器执行。
dbgpt-sandbox 的分层架构
1. Execution layer
执行层提供具体 runtime 实现与核心抽象:
base.py:定义 runtime / session / result / config 等公共接口docker_runtime.py、podman_runtime.py、nerdctl_runtime.py、local_runtime.py:具体运行时实现runtime_factory.py:负责自动选择 backend