> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-docs-zh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用远程沙盒

> 在 LangSmith、AgentCore、Daytona、Modal、Runloop、Vercel 或 E2B 沙盒中运行 Deep Agents 代码工具执行。安装提供者依赖项，设置凭证，并使用标志和设置脚本。

深度智能体代码采用[sandbox作为工具](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/sandboxes.md#沙盒作为工具模式)模式：大语言模型循环、记忆和工具调度（`dcode`过程）在您的本地机器上运行，但智能体工具调用（`read_file`、`write_file`、`execute`等）会靶向远程沙盒，而非本地文件系统。要将文件导入沙盒，请使用[设置脚本](#配置脚本)或供应商的文件传输API（参见[文件操作](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/sandboxes.md#处理文件)）。

要深入了解沙盒架构、集成模式和安全最佳实践，请参考[沙盒](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/sandboxes.md)。

**1. Install provider dependency**

每个内置供应商均作为可选附加组件提供。在会话中通过 `/install` 安装，或在shell中通过 `dcode --install` 安装。第三方供应商如E2B通过添加`--package`标志安装为软件包：

> [tab] LangSmith
>
> 随`deepagents-code`安装时已包含，无需额外安装。

> [tab] AgentCore
>
> ```txt In session theme={null}
> /install agentcore
> ```
>
> ```bash Shell theme={null}
> dcode --install agentcore
> ```

> [tab] Daytona
>
> ```txt In session theme={null}
> /install daytona
> ```
>
> ```bash Shell theme={null}
> dcode --install daytona
> ```

> [tab] Modal
>
> ```txt In session theme={null}
> /install modal
> ```
>
> ```bash Shell theme={null}
> dcode --install modal
> ```

> [tab] Runloop
>
> ```txt In session theme={null}
> /install runloop
> ```
>
> ```bash Shell theme={null}
> dcode --install runloop
> ```

> [tab] Vercel
>
> ```txt In session theme={null}
> /install vercel
> ```
>
> ```bash Shell theme={null}
> dcode --install vercel
> ```

> [tab] E2B
>
> E2B是由`langchain-e2b`软件包发布的[第三方供应商](#第三方提供程序)。需作为软件包而非`deepagents-code`附加组件安装：
>
> ```txt In session theme={null}
> /install langchain-e2b --package
> ```
>
> ```bash Shell theme={null}
> dcode --install langchain-e2b --package
> ```

要一次性安装所有内置供应商支持，使用`all-sandboxes`附加组件：在会话中执行 `/install all-sandboxes`，或在shell中执行 `dcode --install all-sandboxes`。`all-sandboxes`附加组件不包含第三方供应商如E2B。

**2. Set provider credentials**

> [tab] LangSmith
>
> ```bash theme={null}
> export LANGSMITH_API_KEY="your-key"
> ```

> [tab] AgentCore
>
> ```bash theme={null}
> export AWS_ACCESS_KEY_ID="your-key"
> export AWS_SECRET_ACCESS_KEY="your-secret"
> export AWS_REGION="us-west-2"
>
> # Only when using temporary/STS credentials:
> export AWS_SESSION_TOKEN="session-token"
> ```

> [tab] Daytona
>
> ```bash theme={null}
> export DAYTONA_API_KEY="your-key"
> ```

> [tab] Modal
>
> ```bash theme={null}
> modal setup
> ```

> [tab] Runloop
>
> ```bash theme={null}
> export RUNLOOP_API_KEY="your-key"
> ```

> [tab] Vercel
>
> ```bash theme={null}
> 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)凭据会自动使用。

> [tab] E2B
>
> ```bash theme={null}
> export E2B_API_KEY="your-key"
> ```

**3. Run Deep Agents Code with a sandbox**

> [tab] LangSmith
>
> ```bash theme={null}
> dcode --sandbox langsmith
> ```

> [tab] AgentCore
>
> ```bash theme={null}
> dcode --sandbox agentcore
> ```

> [tab] Daytona
>
> ```bash theme={null}
> dcode --sandbox daytona
> ```

> [tab] Modal
>
> ```bash theme={null}
> dcode --sandbox modal
> ```

> [tab] Runloop
>
> ```bash theme={null}
> dcode --sandbox runloop
> ```

> [tab] Vercel
>
> ```bash theme={null}
> dcode --sandbox vercel
> ```

> [tab] E2B
>
> ```bash theme={null}
> dcode --sandbox e2b
> ```

## 沙盒标志和示例

| Flag | 描述 |
| - | - |
| `--sandbox TYPE` | 使用沙盒提供程序。内置提供程序：`langsmith`, `agentcore`, `daytona`, `modal`, `runloop`, `vercel`（默认：`none`）。[第三方](#第三方提供程序)和[配置声明](#配置声明的提供者)提供程序也受支持。设置 `--sandbox` 无值时，将使用 `[sandboxes].default` 从您的配置中 |
| `--sandbox-id ID` | 通过ID重用现有沙盒（而非创建新沙盒）。跳过创建和清理流程。仅适用于支持通过ID重附着的提供程序。请参考沙盒文档获取更多信息 |
| `--sandbox-snapshot-name NAME` | 使用或创建沙盒快照。支持 `langsmith`, `daytona`, `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 theme={null}
# Create a new LangSmith sandbox
dcode --sandbox langsmith

# Boot from a named snapshot (langsmith, daytona, or runloop)
dcode --sandbox daytona --sandbox-snapshot-name my-env

# 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` 接受可选值，保留裸形式的 **last** 在命令行。否则后续参数（如 `dcode --sandbox agents`）会被当作标志值。显式指定提供程序名称可避免歧义

## 可插拔提供程序

内置提供程序并非唯一选项。Deep Agents Code 会从三个来源发现沙盒提供程序，因此您可以使用其他包提供的提供程序或自行声明，而无需修改 Deep Agents Code：

1. **内置提供程序** — LangSmith, AgentCore, Daytona, Modal, Runloop, 和 Vercel，随 `deepagents-code`（默认 LangSmith，其他作为扩展包）附带
2. **[第三方提供程序](#第三方提供程序)** — 通过 Python 入口点发布的其他已安装包
3. **[配置声明提供程序](#配置声明的提供者)** — 定义在 `~/.deepagents/config.toml` 中的提供程序

当两个来源定义同名提供程序时，**配置优先于第三方入口点，第三方入口点优先于内置提供程序**，因此配置文件可完全覆盖发现逻辑。

### 第三方提供程序

包可通过 `deepagents_code.sandbox_providers` [入口点组](https://packaging.python.org/en/latest/specifications/entry-points/) 发布沙盒提供程序。安装此类包后，其提供程序会自动成为 `--sandbox` 可用——无需配置：

```bash theme={null}
# Install the package that publishes the provider, then use it
dcode --sandbox acme
```

例如， `langchain-e2b` 包发布了一个 `e2b` 提供程序（参见[sandbox 整合](https://langchain-docs-zh.mintlify.site/langchain/oss/python/integrations/sandboxes.md)）。安装该包、设置凭证后即可选择使用

```bash theme={null}
dcode --install langchain-e2b --package
export E2B_API_KEY="..."
dcode --sandbox e2b
```

如果传递一个未安装或未声明的 `--sandbox` 名称，Deep Agents Code 会列出可用的提供者并说明如何安装或配置缺失的提供者。

> [accordion] Publishing a sandbox provider
>
> 要使用户在安装您的包后能够运行 `dcode --sandbox <name>`，需实现 `SandboxProvider` 子类并将其注册在 `deepagents_code.sandbox_providers` 入口点组下。
>
> 重写 `metadata` 属性，使 Deep Agents Code 可以暴露工作目录和能力标志（无需实例化提供者）：
>
> ```python theme={null}
> 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` 中：
>
> ```toml theme={null}
> [project.entry-points."deepagents_code.sandbox_providers"]
> acme = "acme_sandbox.provider:AcmeProvider"
> ```
>
> 若省略 `metadata` 属性，则使用通用默认值（`/workspace`，无快照支持）。

### 配置声明的提供者

对于不想打包的内部或本地提供者，在 `~/.deepagents/config.toml` 的 `[sandboxes.providers]` 中声明它。这与[任意模型提供者](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/code/config-file.md#任意提供者)类似，并使用相同的 `class_path` 信任模型。

```toml theme={null}
[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"
```

**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`](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/code/config-file#任意提供者)相同：您掌控自己的机器和配置文件。

## 配置脚本

使用 `--sandbox-setup` 在沙箱创建后运行 shell 脚本。此功能适用于代码仓库克隆、依赖安装和环境变量配置。

```bash title="setup.sh" theme={null}
#!/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]
>
> 沙盒环境可以隔离代码执行，但智能体仍可能因使用不可信输入而受到提示注入攻击。请仅使用人工审核、短期密钥和可信设置脚本。详见[Security considerations](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/sandboxes.md#安全注意事项)。

***

> 官方原文：[src/oss/deepagents/code/remote-sandboxes.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/deepagents/code/remote-sandboxes.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.