使用远程沙箱

在 LangSmith、AgentCore、Daytona、Modal、Runloop、Vercel 或 E2B 沙箱中运行 Deep Agents Code 的工具执行。安装服务商依赖、设置凭据，并使用标志和设置脚本。

Deep Agents Code 使用沙箱即工具模式：dcode 进程（LLM 循环、记忆、工具分发）在你的机器上运行，但智能体的工具调用（read_file、write_file、execute 等）指向远程沙箱，而不是你的本地文件系统。要将文件传入沙箱，请使用设置脚本或服务商的文件传输 API（参见处理文件）。

如需深入了解沙箱架构、集成模式和安全最佳实践，参见沙箱。

↓Install provider dependency

每个内置服务商都以可选 extra 的形式提供。可在会话内使用 /install 安装，或从 shell 使用 dcode --install 安装。诸如 E2B 之类的第三方服务商则使用 --package 标志以包的形式安装：

安装 deepagents-code 时默认包含。无需额外安装。

要一次性安装对所有内置服务商的支持，请使用 all-sandboxes extra：在会话中执行 /install all-sandboxes，或从 shell 执行 dcode --install all-sandboxes。all-sandboxes extra 不包含诸如 E2B 之类的第三方服务商。

⚿Set provider credentials

export LANGSMITH_API_KEY="your-key"

•Run Deep Agents Code with a sandbox

dcode --sandbox langsmith

沙箱标志与示例

标志	描述
--sandbox TYPE	要使用的沙箱服务商。内置：langsmith、agentcore、daytona、modal、runloop、vercel（默认：none）。也接受第三方和配置声明的服务商。传入不带值的 --sandbox 以使用配置中的 [sandboxes].default
--sandbox-id ID	按 ID 复用现有沙箱，而不是创建新的沙箱。跳过创建和清理。仅适用于支持按 ID 重新附加的服务商。更多信息请参阅你的沙箱文档
--sandbox-snapshot-name NAME	使用或创建沙箱快照。由 langsmith 和 runloop 支持（以及任何声明支持快照的第三方服务商）。不能与 --sandbox-id 组合使用
--sandbox-setup PATH	创建时在沙箱内运行的设置脚本路径

每个服务商都会在沙箱内暴露一个默认工作目录。除非被覆盖，设置脚本和 execute 命令都从该目录运行：

服务商	工作目录
LangSmith	/root
AgentCore	/tmp
Daytona	/home/daytona
Modal	/workspace
Runloop	/home/user
Vercel	/vercel/sandbox
E2B	/home/user

示例：

# Create a new LangSmith sandbox
dcode --sandbox langsmith

# Reuse an existing sandbox (skips creation and cleanup)
dcode --sandbox runloop --sandbox-id dbx_abc123

# Run a setup script after sandbox creation
dcode --sandbox modal --sandbox-setup ./setup.sh

# Use the provider set as [sandboxes].default in config
dcode --sandbox

NOTE

由于 --sandbox 接受可选值，请将不带值的形式放在命令行最后。否则后面紧跟的参数（例如 dcode --sandbox agents）会被当作该标志的值消耗掉。请传入显式的服务商名称以避免歧义。

可插拔服务商

内置服务商并非唯一的选择。Deep Agents Code 从三个来源发现沙箱服务商，因此你可以使用其他包提供的服务商，或在不修改 Deep Agents Code 的情况下声明自己的服务商：

1. 内置服务商——随 deepagents-code 一起提供的有 LangSmith、AgentCore、Daytona、Modal、Runloop 和 Vercel（LangSmith 默认包含，其余作为 extra）。
2. 第三方服务商——由其他已安装的包通过 Python 入口点发布。
3. 配置声明的服务商——在你的 ~/.deepagents/config.toml 中定义。

当两个来源定义了相同的服务商名称时，配置优先于第三方入口点，第三方入口点优先于内置，因此你的配置文件始终可以覆盖发现结果。

第三方服务商

包可以在 deepagents_code.sandbox_providers 入口点组下发布沙箱服务商。一旦你安装了这样的包，其服务商就会自动可供 --sandbox 使用——无需配置：

# Install the package that publishes the provider, then use it
dcode --sandbox acme

例如，langchain-e2b 包发布了一个 e2b 服务商（参见沙箱集成）。将其作为包安装、设置凭据，然后选择它：

dcode --install langchain-e2b --package
export E2B_API_KEY="..."
dcode --sandbox e2b

如果你传入的 --sandbox 名称未安装或未声明，Deep Agents Code 会列出可用的服务商，并说明如何安装或配置缺失的那个。

发布沙箱服务商

要分发服务商，使用户在安装你的包后能够运行 dcode --sandbox <name>，请实现 SandboxProvider 子类，并将其注册到 deepagents_code.sandbox_providers 入口点组下。

覆盖 metadata 属性，以便 Deep Agents Code 在实例化服务商之前即可展示你的工作目录和能力标志：

from deepagents_code.integrations.sandbox_provider import (
    SandboxInstallHint,
    SandboxProvider,
    SandboxProviderMetadata,
)

class AcmeProvider(SandboxProvider):
    @property
    def metadata(self) -> SandboxProviderMetadata:
        return SandboxProviderMetadata(
            name="acme",
            working_dir="/workspace",
            install=SandboxInstallHint(kind="package", name="acme-dcode-sandbox"),
            supports_sandbox_id=True,
            supports_snapshot_name=False,
        )

    def get_or_create(self, *, sandbox_id=None, **kwargs):
        ...  # return a SandboxBackendProtocol

    def delete(self, *, sandbox_id, **kwargs):
        ...

实现 get_or_create 和 delete；异步调用方由基类处理。然后在你的包的 pyproject.toml 中注册入口点：

[project.entry-points."deepagents_code.sandbox_providers"]
acme = "acme_sandbox.provider:AcmeProvider"

如果省略 metadata 属性，则会使用一个通用默认值（/workspace，不支持快照）。

配置声明的服务商

对于不想打包的内部或本地服务商，请在 ~/.deepagents/config.toml 中的 [sandboxes.providers] 下声明它。这与任意模型服务商类似，并使用相同的 class_path 信任模型。

[sandboxes]
# Used when you run `dcode --sandbox` with no value.
default = "acme"

[sandboxes.providers.acme]
# Required: the provider class to import, in module.path:ClassName format.
class_path = "acme_sandbox.provider:AcmeProvider"
# Default working directory inside the sandbox.
working_dir = "/workspace"
# Package suggested when the provider's dependencies are missing.
package = "acme-dcode-sandbox"
# Capability flags (defaults: supports_sandbox_id = true, supports_snapshot_name = false).
supports_sandbox_id = true
supports_snapshot_name = false

# Extra keyword arguments forwarded to the provider's get_or_create().
[sandboxes.providers.acme.params]
region = "us-east-1"

string

采用 module.path:ClassName 格式的完全限定服务商类。Deep Agents Code 会为该服务商导入并实例化此类。

string

沙箱内的默认工作目录。默认为 /workspace。

string

当服务商的依赖缺失时，在错误消息中建议的包名称。

boolean

是否允许为此服务商使用 --sandbox-id 重新附加。默认为 true。

boolean

是否允许为此服务商使用 --sandbox-snapshot-name。默认为 false。

object

转发给该服务商 get_or_create() 的额外关键字参数。

复用某个内置服务商名称的配置条目会覆盖该内置服务商，同时保留其依赖预检。格式错误的条目会被跳过并给出警告，而不会导致启动崩溃。

WARNING

设置 class_path 会导致 Deep Agents Code 从指定的模块导入并运行任意 Python——模块级代码会在导入时执行。这与模型 class_path 的信任模型相同：你掌控自己的机器和自己的配置文件。

设置脚本

使用 --sandbox-setup 在沙箱创建后于其中运行 shell 脚本。这对于克隆仓库、安装依赖和配置环境变量很有用。

#!/bin/bash
set -e

# Clone repository using GitHub token
git clone https://x-access-token:${GITHUB_TOKEN}@github.com/username/repo.git $HOME/workspace
cd $HOME/workspace

# Make environment variables persistent
cat >> ~/.bashrc <<'EOF'
export GITHUB_TOKEN="${GITHUB_TOKEN}"
export OPENAI_API_KEY="${OPENAI_API_KEY}"
cd $HOME/workspace
EOF
source ~/.bashrc

Deep Agents Code 使用你的本地环境变量来展开设置脚本中的 ${VAR} 引用。请将机密存储在本地 .env 文件中，以便设置脚本访问。

WARNING

沙箱隔离了代码执行，但智能体在面对不可信输入时仍易受提示词注入攻击。请使用人在回路审批、短期有效的机密，并只使用可信的设置脚本。有关详细信息，参见安全注意事项。

---