使用远程沙箱 - Docs by LangChain中文

Deep Agents Code 使用沙箱即工具模式：dcode 进程（LLM 循环、内存、工具调度）在您的机器上运行，但代理工具调用（read_file、write_file、execute 等）针对的是远程沙箱，而非您的本地文件系统。要将文件放入沙箱，请使用设置脚本或提供程序的文件传输 API（参见使用文件）。有关沙箱架构、集成模式和安全最佳实践的深入介绍，请参见沙箱。

安装提供程序依赖项

每个内置提供程序都作为可选附加组件提供。您可以在会话中通过 /install 命令，或在 Shell 中使用 dcode --install 命令安装一个。第三方提供程序（如 E2B）则作为软件包，使用 --package 标志进行安装：

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

/install agentcore

dcode --install agentcore

/install daytona

dcode --install daytona

/install runloop

dcode --install runloop

/install vercel

dcode --install vercel

E2B 是一个由 langchain-e2b 软件包发布的第三方提供程序。请将其作为软件包安装，而不是 deepagents-code 的附加组件：

/install langchain-e2b --package

dcode --install langchain-e2b --package

要一次性安装所有内置提供程序的支持，请使用 all-sandboxes 附加组件：在会话中执行 /install all-sandboxes，或在 Shell 中执行 dcode --install all-sandboxes。all-sandboxes 附加组件不包括 E2B 等第三方提供程序。

设置提供程序凭据

export LANGSMITH_API_KEY="your-key"

export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"
export AWS_REGION="us-west-2"

# 仅当使用临时/STS 凭据时：
export AWS_SESSION_TOKEN="session-token"

export DAYTONA_API_KEY="your-key"

export RUNLOOP_API_KEY="your-key"

export VERCEL_TOKEN="your-token"
export VERCEL_PROJECT_ID="your-project-id"
export VERCEL_TEAM_ID="your-team-id"

在 Vercel 上运行时，会自动使用 OIDC 凭据。

export E2B_API_KEY="your-key"

使用沙箱运行 Deep Agents Code

dcode --sandbox langsmith

dcode --sandbox agentcore

dcode --sandbox daytona

dcode --sandbox runloop

dcode --sandbox vercel

dcode --sandbox e2b

沙箱标志和示例

标志	描述
`--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

由于 --sandbox 接受可选值，请将不带值的裸形式放在命令行的最后。否则，后面的参数（例如 dcode --sandbox agents）会被当作标志的值来使用。传递显式的提供程序名称可以避免歧义。

可插拔提供程序

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

内置提供程序 — LangSmith、AgentCore、Daytona、Modal、Runloop 和 Vercel，随 deepagents-code 提供（LangSmith 默认包含，其他作为附加组件）。
第三方提供程序 — 由其他已安装的软件包通过 Python 入口点发布。
配置声明的提供程序 — 在您的 ~/.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):
        ...  # 返回一个 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]
# 当您运行不带值的 `dcode --sandbox` 时使用。
default = "acme"

[sandboxes.providers.acme]
# 必需：要导入的提供程序类，格式为 module.path:ClassName。
class_path = "acme_sandbox.provider:AcmeProvider"
# 沙箱内的默认工作目录。
working_dir = "/workspace"
# 当提供程序的依赖项缺失时建议安装的软件包。
package = "acme-dcode-sandbox"
# 能力标志（默认值：supports_sandbox_id = true，supports_snapshot_name = false）。
supports_sandbox_id = true
supports_snapshot_name = false

# 转发给提供程序 get_or_create() 的额外关键字参数。
[sandboxes.providers.acme.params]
region = "us-east-1"

string

required

完全限定的提供程序类，格式为 module.path:ClassName。Deep Agents Code 为此提供程序导入并实例化此类。

string

optional

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

string

optional

当提供程序的依赖项缺失时，在错误消息中建议的软件包名称。

boolean

optional

是否允许此提供程序使用 --sandbox-id 重新附加。默认为 true。

boolean

optional

是否允许此提供程序使用 --sandbox-snapshot-name。默认为 false。

object

optional

转发给提供程序 get_or_create() 的额外关键字参数。

复用内置提供程序名称的配置条目会覆盖该内置程序，同时保留其依赖项预检查。格式错误的条目会被跳过并发出警告，而不是导致启动崩溃。

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

设置脚本

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

setup.sh

#!/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 文件中，供设置脚本访问。

沙箱隔离了代码执行，但代理仍然容易受到来自不受信任输入的提示注入攻击。请仅使用人工审批、短期密钥和受信任的设置脚本。有关详细信息，请参见安全注意事项。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​沙箱标志和示例

​可插拔提供程序

​第三方提供程序

​配置声明的提供程序

​设置脚本

沙箱标志和示例

可插拔提供程序

第三方提供程序

配置声明的提供程序

设置脚本