使用远程沙箱 | LangChain 中文文档

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

要更深入地了解沙箱架构、集成模式和安全最佳实践，请参阅沙箱。

安装提供商依赖

    每个内置提供商都以可选附加项（extra）的形式提供。可以在会话中使用 `/install` 安装一个，或从 shell 中使用 `dcode --install`。E2B 等第三方提供商作为包安装，使用 `--package` 标志：

LangSmith

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

AgentCore

In sessionShell

txt

/install agentcore

bash

dcode --install agentcore

Daytona

In sessionShell

txt

/install daytona

bash

dcode --install daytona

In sessionShell

txt

/install modal

bash

dcode --install modal

Runloop

In sessionShell

txt

/install runloop

bash

dcode --install runloop

Vercel

In sessionShell

txt

/install vercel

bash

dcode --install vercel

E2B

            E2B 是由 `langchain-e2b` 包发布的[第三方提供商](#third-party-providers)。请将其作为包安装，而不是 `deepagents-code` 的可选附加项：

In sessionShell

txt

/install langchain-e2b --package

bash

dcode --install langchain-e2b --package

    要一次性安装对所有内置提供商的支持，请使用 `all-sandboxes` 附加项：在会话中执行 `/install all-sandboxes`，或从 shell 执行 `dcode --install all-sandboxes`。`all-sandboxes` 附加项不包含 E2B 等第三方提供商。

设置提供商凭据

LangSmith

bash

export LANGSMITH_API_KEY="your-key"

AgentCore

bash

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"

Daytona

bash

export DAYTONA_API_KEY="your-key"

bash

modal setup

Runloop

bash

export RUNLOOP_API_KEY="your-key"

Vercel

bash

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

            在 Vercel 上运行时，会自动改用 [OIDC](https://vercel.com/docs/oidc) 凭据。

E2B

bash

export E2B_API_KEY="your-key"

使用沙箱运行 Deep Agents Code

LangSmith

bash

dcode --sandbox langsmith

AgentCore

bash

dcode --sandbox agentcore

Daytona

bash

dcode --sandbox daytona

bash

dcode --sandbox modal

Runloop

bash

dcode --sandbox runloop

Vercel

bash

dcode --sandbox vercel

E2B

bash

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`

示例：

bash

# 创建一个新的 LangSmith 沙箱
dcode --sandbox langsmith

# 复用现有沙箱（跳过创建和清理）
dcode --sandbox runloop --sandbox-id dbx_abc123

# 沙箱创建后运行设置脚本
dcode --sandbox modal --sandbox-setup ./setup.sh

# 使用配置中设置为 [sandboxes].default 的提供商
dcode --sandbox

INFO

由于 --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——无需配置：

bash

# 安装发布该提供商的包，然后使用它
dcode --sandbox acme

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

bash

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 无需实例化提供商就能展示你的工作目录和能力标志：

python

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` 中注册入口点：

toml

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

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

配置声明的提供商

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

toml

[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"

class_path (string)（必填）：采用 module.path:ClassName 格式的完全限定的提供商类。Deep Agents Code 会导入并实例化此类作为该提供商。
working_dir (string)：沙箱内的默认工作目录。默认为 /workspace。
package (string)：当提供商的依赖缺失时，错误消息中建议的包名。
supports_sandbox_id (boolean)：是否允许此提供商进行 --sandbox-id 重新附加。默认为 true。
supports_snapshot_name (boolean)：是否允许此提供商使用 --sandbox-snapshot-name。默认为 false。
params (object)：转发给提供商 get_or_create() 的额外关键字参数。

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

WARNING

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

设置脚本

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

bash

#!/bin/bash
set -e

# 使用 GitHub token 克隆仓库
git clone https://x-access-token:${GITHUB_TOKEN}@github.com/username/repo.git $HOME/workspace
cd $HOME/workspace

# 使环境变量持久化
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

沙箱隔离了代码执行，但智能体面对不受信任的输入仍然容易受到提示注入的攻击。请仅使用人在回路审批、短期机密和受信任的设置脚本。详情请参阅安全注意事项。

Going to production

Interpreters

Patterns

Configuration

安装提供商依赖

LangSmith

AgentCore

Daytona

Runloop

Vercel

E2B

设置提供商凭据

LangSmith

AgentCore

Daytona

Runloop

Vercel

E2B

使用沙箱运行 Deep Agents Code

LangSmith

AgentCore

Daytona

Runloop

Vercel

E2B

沙箱标志和示例

可插拔提供商

第三方提供商

发布沙箱提供商

配置声明的提供商

设置脚本

安装提供商依赖 ​

LangSmith ​

AgentCore ​

Daytona ​

Modal ​

Runloop ​

Vercel ​

E2B ​

设置提供商凭据 ​

LangSmith ​

AgentCore ​

Daytona ​

Modal ​

Runloop ​

Vercel ​

E2B ​

使用沙箱运行 Deep Agents Code ​

LangSmith ​

AgentCore ​

Daytona ​

Modal ​

Runloop ​

Vercel ​

E2B ​

沙箱标志和示例 ​

可插拔提供商 ​

第三方提供商 ​

发布沙箱提供商 ​

配置声明的提供商 ​

设置脚本 ​

安装提供商依赖

LangSmith

AgentCore

Daytona

Modal

Runloop

Vercel

E2B

设置提供商凭据

LangSmith

AgentCore

Daytona

Modal

Runloop

Vercel

E2B

使用沙箱运行 Deep Agents Code

LangSmith

AgentCore

Daytona

Modal

Runloop

Vercel

E2B

沙箱标志和示例

可插拔提供商

第三方提供商

发布沙箱提供商

配置声明的提供商

设置脚本