> ## 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.

# 解释器

> 在 Deep Agents 中运行轻量级代码，以组合工具、编排子智能体和转换结构化数据。

智能体通过解释器在智能体循环内部获得可编程的**内存**工作区。智能体编写代码以完成任务，运行时执行它并仅返回相关结果。中间结果不会成为模型上下文的一部分。

在 [沙盒](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/sandboxes.md)（沙盒）是一种以代码优先的方式对环境进行操作（例如运行命令、安装依赖项和编辑文件），而解释器是以代码优先的方式组合工具、保留状态并决定应返回给模型的信息。

> [!WARNING]
>
> 解释器处于 [**测试版**](https://langchain-docs-zh.mintlify.site/langchain/oss/versioning.md)。API 和生命周期行为可能在版本之间发生变化。

:::python

> [!NOTE]
>
> 解释器需要 `langchain-quickjs>=0.3.0` 和 Python 3.11 或更高版本。

:::

:::js

> [!NOTE]
>
> 解释器需要 `@langchain/quickjs`。

:::

## 为什么使用解释器？

大多数智能体工作在模型推理和工具调用之间交替。模型可以在一次回合中触发多个工具调用，但一旦发出，该批次就是固定的。在没有另一个模型回合的情况下，没有任何东西可以循环、根据结果分支、重试失败或将有一次调用的输出输入到下一次调用，并且每个结果都会返回到模型的上下文中。模型还决定发出多少次调用，因此要求它跨数百个项目分发工作是不可靠的，并且它倾向于覆盖样本而不是每个项目。

解释器将这种编排移入代码，以便模型推理*要做什么*，而不是每个中间步骤。

> [card] [Programmatic tool calling (PTC)](#programmatic-tool-calling-ptc)
>
> 从解释器代码中调用选定的工具，包括循环、重试、分支和并行批次。

> [card] [Dynamic subagents](#dynamic-subagents)
>
> 从代码中分发子智能体以进行发散、验证和大型输入上的递归工作流。

> [card] [Stateful work](#how-interpreters-work)
>
> 在运行时状态中保留中间值，而不会使模型上下文过载。

> [card] [Deterministic transforms](#how-interpreters-work)
>
> 对结构化数据进行排序、分组、解析、验证、评分和聚合，而无需另一个模型回合。

## 选择模式

在智能体循环内部使用解释器：组合工具、保留状态和控制返回给模型的内容。

使用 [沙盒](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/sandboxes.md) 针对环境编写代码：shell 命令、包安装、测试、文件系统编辑和操作系统级执行。

| 需求 | 使用 |
| - | - |
| 一个或两个简单的外部调用 | 普通工具调用 |
| 纯内存 JavaScript：循环、分支、重试或数据转换（不涉及外部工具） | 解释器 |
| 从代码编排许多外部工具调用（需要 [PTC](#程序化工具调用-ptc)） | 带有 [程序化工具调用 (PTC)](#程序化工具调用-ptc) 的解释器 |
| 许多独立的工作单元、多个视角或大型输入上的递归分析 | 带有 [动态子智能体](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/dynamic-subagents.md) 的解释器 |
| Shell 命令、包安装、测试或完整的操作系统文件系统访问 | [沙盒](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/sandboxes.md) |

## 快速入门

:::python
安装 QuickJS 中间件包，然后使用 `middleware` 参数在 `create_deep_agent` 上传递解释器中间件。
:::

:::js
安装 QuickJS 中间件包，然后使用 `middleware` 参数在 `createDeepAgent` 上传递解释器中间件。
:::

:::python

```bash pip theme={null}
pip install -U "deepagents[quickjs]"
```

```bash uv theme={null}
uv add "deepagents[quickjs]"
```

```python Google theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    middleware=[CodeInterpreterMiddleware()],
)
```

```python OpenAI theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="openai:gpt-5.5",
    middleware=[CodeInterpreterMiddleware()],
)
```

```python Anthropic theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="anthropic:claude-sonnet-5",
    middleware=[CodeInterpreterMiddleware()],
)
```

```python OpenRouter theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    middleware=[CodeInterpreterMiddleware()],
)
```

```python Fireworks theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    middleware=[CodeInterpreterMiddleware()],
)
```

```python Baseten theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    middleware=[CodeInterpreterMiddleware()],
)
```

```python Ollama theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    middleware=[CodeInterpreterMiddleware()],
)
```

:::

:::js

```bash npm theme={null}
npm install deepagents @langchain/quickjs
```

```bash pnpm theme={null}
pnpm add deepagents @langchain/quickjs
```

```bash yarn theme={null}
yarn add deepagents @langchain/quickjs
```

```ts Google theme={null}
import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "google:gemini-3.6-flash",
  middleware: [createCodeInterpreterMiddleware()],
});
```

```ts OpenAI theme={null}
import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  middleware: [createCodeInterpreterMiddleware()],
});
```

```ts Anthropic theme={null}
import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-5",
  middleware: [createCodeInterpreterMiddleware()],
});
```

```ts OpenRouter theme={null}
import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "openrouter:z-ai/glm-5.2",
  middleware: [createCodeInterpreterMiddleware()],
});
```

```ts Fireworks theme={null}
import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  middleware: [createCodeInterpreterMiddleware()],
});
```

```ts Baseten theme={null}
import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  middleware: [createCodeInterpreterMiddleware()],
});
```

```ts Ollama theme={null}
import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  middleware: [createCodeInterpreterMiddleware()],
});
```

:::

## 解释器如何工作

中间件向智能体添加了一个 `eval` 工具。当有用时，智能体编写 JavaScript 并调用 `eval`；您不会直接调用解释器。该工具在 QuickJS 上下文中运行代码，其变量可以在 `eval` 调用之间持久化，具体取决于持久化 `mode`。它捕获 `console.log`、`console.warn` 和 `console.error`，并返回最后一个表达式的结果。

智能体可以编写如下代码：

```ts theme={null}
const rows = [
  { team: "alpha", score: 8 },
  { team: "beta", score: 13 },
  { team: "alpha", score: 21 },
];

const totals = rows.reduce((acc, row) => {
  acc[row.team] = (acc[row.team] ?? 0) + row.score;
  console.log(`${row.team} score: ${acc[row.team]}`);
  return acc;
}, {});

totals;
```

:::python
默认情况下（`mode="thread"`），解释器状态在同一个线程内的回合之间持久化。有关 `mode` 选项和快照生命周期的信息，请参阅 [持久化](#持久化)。
:::

代码在 [**QuickJS**](https://github.com/quickjs-ng/quickjs) 上运行，这是一个轻量级的 JavaScript 运行时。默认情况下，解释器代码无法访问主机文件系统、网络、shell、包管理器或时钟。它可以计算、保留状态并写入 `console.log`、`console.warn` 或 `console.error`，并且除此之外不做任何其他操作。

有两个显式的桥梁扩展了这种范围：

* **工具**，通过 [程序化工具调用 (PTC)](#程序化工具调用-ptc)。将允许的工具列表作为异步函数在 `tools` 命名空间下提供。这些可以是智能体自己的工具或您定义并传递的独立工具。
* **子智能体**，通过 [动态子智能体](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/dynamic-subagents.md)。当智能体配置了子智能体时，解释器会暴露一个 `task()` 全局变量用于从代码中调度它们。

程序化工具调用在您 [启用它](#启用-ptc) 之前是关闭的。通过 `task()` 的子智能体调度默认情况下在智能体具有子智能体时开启，并且您可以将其关闭。没有其他东西可以跨越 QuickJS 边界。

## 程序化工具调用 (PTC)

程序化工具调用 (PTC) 在解释器下通过全局 `tools` 命名空间暴露选定的智能体工具。与其要求模型发出一次工具调用、等待结果然后决定下一次调用，不如智能体可以编写代码来在循环、分支、重试或并行批次中调用工具。

这有助于在中间结果仅作为下一步输入时：解释器在结果返回模型之前进行过滤或聚合，保持多步工作流的 Token 高效。它是模型无关的，由中间件实现，而非特定提供者的工具调用 API。

中间件将每个允许的工具作为异步函数在 `tools` 下暴露。智能体使用 `await` 调用它，在代码中处理结果，模型仅看到最终的解释器输出，而非每个中间值。工具名称转换为 camelCase，而输入对象仍遵循工具的架构，因此名为 `web_search` 的工具变为 `tools.webSearch(...)`：

```ts theme={null}
const result: string = await tools.webSearch({
  query: "deepagents interpreters",
});
```

### 启用 PTC

通过显式允许列表启用 PTC：

:::python

```python Google theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    middleware=[CodeInterpreterMiddleware(ptc=["web_search"])],
)
```

```python OpenAI theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="openai:gpt-5.5",
    middleware=[CodeInterpreterMiddleware(ptc=["web_search"])],
)
```

```python Anthropic theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="anthropic:claude-sonnet-5",
    middleware=[CodeInterpreterMiddleware(ptc=["web_search"])],
)
```

```python OpenRouter theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    middleware=[CodeInterpreterMiddleware(ptc=["web_search"])],
)
```

```python Fireworks theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    middleware=[CodeInterpreterMiddleware(ptc=["web_search"])],
)
```

```python Baseten theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    middleware=[CodeInterpreterMiddleware(ptc=["web_search"])],
)
```

```python Ollama theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    middleware=[CodeInterpreterMiddleware(ptc=["web_search"])],
)
```

:::

:::js

```ts Google theme={null}
import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "google:gemini-3.6-flash",
  middleware: [createCodeInterpreterMiddleware({ ptc: ["web_search"] })],
});
```

```ts OpenAI theme={null}
import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  middleware: [createCodeInterpreterMiddleware({ ptc: ["web_search"] })],
});
```

```ts Anthropic theme={null}
import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-5",
  middleware: [createCodeInterpreterMiddleware({ ptc: ["web_search"] })],
});
```

```ts OpenRouter theme={null}
import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "openrouter:z-ai/glm-5.2",
  middleware: [createCodeInterpreterMiddleware({ ptc: ["web_search"] })],
});
```

```ts Fireworks theme={null}
import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  middleware: [createCodeInterpreterMiddleware({ ptc: ["web_search"] })],
});
```

```ts Baseten theme={null}
import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  middleware: [createCodeInterpreterMiddleware({ ptc: ["web_search"] })],
});
```

```ts Ollama theme={null}
import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  middleware: [createCodeInterpreterMiddleware({ ptc: ["web_search"] })],
});
```

:::

启用 PTC 后，智能体可以从解释器代码中调用允许的工具。此示例并行搜索多个主题，并在返回模型前组合结果：

```ts theme={null}
const topics = ["retrieval", "memory", "evaluation"];

const results = await Promise.all(
  topics.map((topic) =>
    tools.webSearch({ query: `${topic} best practices 2025` }),
  ),
);

results.join("\n\n");
```

:::python

> [!WARNING]
>
> PTC 调用当前通过解释器桥接执行，而非通过常规工具调用路径。因此，`interrupt_on` 批准工作流不会针对 PTC 调用的每个工具调用强制执行。

:::
:::js

> [!WARNING]
>
> PTC 调用当前通过解释器桥接执行，而非通过常规工具调用路径。因此，`interruptOn` 批准工作流不会针对 PTC 调用的每个工具调用强制执行。

:::

## 动态子智能体

下方的概述涵盖了何时使用动态子智能体和最小 `task()` 模式。关于配置、编排示例、工作流触发和安全注意事项，请参阅 [动态子智能体](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/dynamic-subagents.md)。

动态子智能体允许解释器使用内置 `task()` 全局从代码中调度配置的 [子智能体](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/subagents.md)。一个跨越多个独立单元的任务，例如审查目录中的每个文件或分派一批工单，变成一个发散工作并综合结果的循环。

使用动态子智能体用于：

* **发散和综合**：并行运行相同类型的工作跨多个项目，然后组合结果。
* **验证**：将发现发送给独立的验证子智能体，并仅保留确认结果。
* **递归工作流**：在解释器变量中保留工作集，选择片段，调用子智能体，并细化结果。

```ts theme={null}
const paths = ["src/auth.ts", "src/routes/api.ts"];

const reviews = await Promise.all(
  paths.map((path) =>
    task({
      description: `Review ${path} for authentication issues`,
      subagentType: "reviewer",
    }),
  ),
);

reviews.join("\n\n");
```

:::python

## 持久化

使用 `mode` 参数在 `CodeInterpreterMiddleware` 上控制跨回合状态：

* **`"thread"`**（默认）：状态跨 `eval` 调用和智能体回合持久。中间件在每个智能体回合后快照解释器状态，并在下一个回合前恢复它。
* **`"turn"`**：状态跨一个智能体回合内的多个 `eval` 调用持久，然后在下一个回合重置。
* **`"call"`**：每个 `eval` 调用在一个新的 REPL 中运行，没有来自先前调用的延续。

使用 `mode="thread"` 时，快照是解释器内存 JavaScript 状态的序列化副本，包括智能体运行代码时存在的全局变量、变量、函数和导入的模块。跨对话回合的生命周期是：

1. 回合开始，中间件恢复线程的最新解释器快照。
2. 智能体调用 `eval` 一次或多次。这些调用共享一个活动上下文；中间件在它们之间不快照。
3. 回合结束，中间件将更新后的快照写入图状态。
4. 下一个回合从该快照恢复，而非空运行时。

> [!NOTE]
>
> 快照仅保留可序列化数据。函数、类和其他不可序列化的运行时对象在恢复后成为无法访问的遗留物。访问它们会抛出类似 `Value for 'fn' was not restored because it is not serializable (type: function).` 的错误

快照保留解释器内存，而非外部世界效果。如果解释器代码通过 PTC 调用工具，恢复先前的解释器快照不会撤销该工具调用的副作用。它仅恢复记录或处理结果的解释器变量。

跨回合持久化不需要检查点：

```python Google theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    middleware=[
        CodeInterpreterMiddleware(
            mode="thread",  # Default
        )
    ],
)
```

```python OpenAI theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="openai:gpt-5.5",
    middleware=[
        CodeInterpreterMiddleware(
            mode="thread",  # Default
        )
    ],
)
```

```python Anthropic theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="anthropic:claude-sonnet-5",
    middleware=[
        CodeInterpreterMiddleware(
            mode="thread",  # Default
        )
    ],
)
```

```python OpenRouter theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    middleware=[
        CodeInterpreterMiddleware(
            mode="thread",  # Default
        )
    ],
)
```

```python Fireworks theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    middleware=[
        CodeInterpreterMiddleware(
            mode="thread",  # Default
        )
    ],
)
```

```python Baseten theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    middleware=[
        CodeInterpreterMiddleware(
            mode="thread",  # Default
        )
    ],
)
```

```python Ollama theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    middleware=[
        CodeInterpreterMiddleware(
            mode="thread",  # Default
        )
    ],
)
```

因为解释器快照存储在图状态中，[检查点](https://langchain-docs-zh.mintlify.site/langchain/oss/langgraph/checkpointers.md) 也会在检查点历史中捕获它们。当你需要持久线程或 [时间旅行](https://langchain-docs-zh.mintlify.site/langchain/oss/langgraph/use-time-travel.md) 时添加一个：

```python Google theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    checkpointer=MemorySaver(),
    middleware=[CodeInterpreterMiddleware(mode="thread")],
)
```

```python OpenAI theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    model="openai:gpt-5.5",
    checkpointer=MemorySaver(),
    middleware=[CodeInterpreterMiddleware(mode="thread")],
)
```

```python Anthropic theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    model="anthropic:claude-sonnet-5",
    checkpointer=MemorySaver(),
    middleware=[CodeInterpreterMiddleware(mode="thread")],
)
```

```python OpenRouter theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    checkpointer=MemorySaver(),
    middleware=[CodeInterpreterMiddleware(mode="thread")],
)
```

```python Fireworks theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    checkpointer=MemorySaver(),
    middleware=[CodeInterpreterMiddleware(mode="thread")],
)
```

```python Baseten theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    checkpointer=MemorySaver(),
    middleware=[CodeInterpreterMiddleware(mode="thread")],
)
```

```python Ollama theme={null}
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    checkpointer=MemorySaver(),
    middleware=[CodeInterpreterMiddleware(mode="thread")],
)
```

将 `mode="turn"` 设置为仅持久化回合内的解释器状态，或使用 `mode="call"` 为每个 `eval` 设置一个全新的 REPL。
:::

## 安全

解释器使用 QuickJS 运行不受信任的 JavaScript，并具有严格的默认隔离。将其视为一个作用域解释器运行时，而非完整的生产沙盒后端。

通过 PTC 暴露的每个工具都是一个解释器代码可以使用的外部能力。将 PTC 允许列表视为权限边界：仅暴露智能体需要的工具，并避免桥接可以访问敏感系统、花费金钱、修改数据或调用无限制网络的广泛工具，除非这种行为是故意的。

:::python

| 功能 | 默认可用 | 如何暴露 |
| - | - | - |
| JavaScript 执行 | 是 | 添加解释器中间件 |
| 顶层 `await` | 是 | 在解释器代码中使用 Promise |
| `console.log`、`warn`、`error` 捕获 | 是 | 使用 `capture_console=False` 禁用 |
| 智能体工具 | 否 | 添加 PTC 允许列表 |
| 文件系统访问 | 否 | 通过 PTC 允许列表添加 [内置文件系统工具](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/overview.md#虚拟文件系统访问) |
| 网络访问 | 否 | 通过 PTC 暴露特定的网络工具 |
| 墙上时钟或日期时间访问 | 否 | 如有必要，暴露显式时间工具 |
| Shell 命令、包安装、测试、操作系统级执行 | 否 | 使用 [沙盒后端](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/sandboxes.md) |
| ::: | | |
| :::js | | |
| 功能 | 默认可用 | 如何暴露 |
| --- | --- | --- |
| JavaScript 执行 | 是 | 添加解释器中间件 |
| 顶层 `await` | 是 | 在解释器代码中使用 Promise |
| `console.log`、`warn`、`error` 捕获 | 是 | 使用 `captureConsole: false` 禁用 |
| 智能体工具 | 否 | 添加 PTC 允许列表 |
| 文件系统访问 | 否 | 通过 PTC 允许列表添加 [内置文件系统工具](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/overview.md#虚拟文件系统访问) |
| 网络访问 | 否 | 通过 PTC 暴露特定的网络工具 |
| 墙上时钟或日期时间访问 | 否 | 如有必要，暴露显式时间工具 |
| Shell 命令、包安装、测试、操作系统级执行 | 否 | 使用 [沙盒后端](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/sandboxes.md) |
| ::: | | |

:::python

> [!NOTE]
>
> **代码执行的工作原理**
>
> 解释器代码在 QuickJS 编译为 WebAssembly 后运行，由 [`quickjs-rs`](https://github.com/langchain-ai/quickjs-rs) 提供。WebAssembly 沙盒是隔离边界：JavaScript 在客体的线性内存中执行，不能读取或写入主机进程的内存。每个 LangGraph 线程获得自己的 WebAssembly 实例，因此一个线程上的解释器状态无法到达另一个线程。
>
> 沙盒在 [wasmtime](https://wasmtime.dev/) 内部主机进程中运行，因此 wasmtime 漏洞是跳出沙盒的剩余路径。保持 `wasmtime` 更新。对于敌对的多租户工作负载，还应在隔离的 Worker 进程或容器中运行智能体。详情请参阅 `quickjs-rs` [安全指南](https://github.com/langchain-ai/quickjs-rs#security)。
>
> 沙盒包含引擎，而不是你赋予它的功能。解释器代码可以调用桥接到其中的每个工具，因此请保持 PTC 允许列表狭窄。

:::

:::js

> [!NOTE]
>
> **代码执行的工作原理**
>
> 解释器代码通过 [QuickJS-Emscripten](https://github.com/justjake/quickjs-emscripten) 在 WASM 沙盒化的 QuickJS 运行时中运行，而不是在主机 Node.js 进程中。将解释器视为范围受限的执行层：仅桥接智能体需要的工具和子智能体，并保持 PTC 允许列表狭窄。

:::

## 配置

:::python
`CodeInterpreterMiddleware` 接受以下选项：

| 参数 | 默认值 | 目的 |
| - | - | - |
| `memory_limit` | `64 * 1024 * 1024` (64 MB) | 每个线程限制 QuickJS 堆内存。 |
| `timeout` | `5.0` | 每个 `eval` 调用的秒级超时限制。 |
| `tool_name` | `"eval"` | 暴露给模型的解释器工具名称。 |
| `capture_console` | `True` | 在工具响应中捕获 `console.log`、`console.warn` 和 `console.error`。设置为 `False` 以丢弃控制台输出。 |
| `max_result_chars` | `4000` | 将返回给模型的结果、错误和 stdout 文本截断到最大字符数。 |
| `ptc` | `None` | 作为 `tools.*` 在解释器内部暴露的工具名称或 `BaseTool` 实例的允许列表。省略以禁用。参见 [启用 PTC](#启用-ptc)。 |
| `max_ptc_calls` | `256` | 每个`eval`允许的最大 `tools.*` 调用次数。仅在受信任的环境中设置为 `None`。参见 [程序化工具调用 (PTC)](#程序化工具调用-ptc) 和 [安全](#安全)。 |
| `subagents` | `True` | 当智能体有子智能体时，暴露内置 `task()` 全局。设置为 `False` 以要求通过正常 `task` 工具进行调度。参见 [动态子智能体](#动态子智能体)。 |
| `mode` | `"thread"` | 控制解释器持久性：`"thread"`（跨回合）、`"turn"`（同一回合内）或 `"call"`（每个 `eval` 的新 REPL）。参见 [持久性](#持久化)。 |
| `max_snapshot_bytes` | `None` | 丢弃大于此字节限制的快照。默认为 `memory_limit`。参见 [持久性](#持久化)。 |
| ::: | | |

:::js
`createCodeInterpreterMiddleware` 接受以下选项：

| 选项 | 默认值 | 目的 |
| - | - | - |
| `memoryLimitBytes` | `64 * 1024 * 1024` (64 MB) | 每个会话限制 QuickJS 堆内存。 |
| `maxStackSizeBytes` | `320 * 1024` | 每个会话限制 QuickJS 栈大小。 |
| `executionTimeoutMs` | `5000` | 每个 `eval` 调用的毫秒级超时限制。负值禁用超时。 |
| `toolName` | `"eval"` | 暴露给模型的解释器工具名称。 |
| `captureConsole` | `true` | 在工具响应中捕获 `console.log`、`console.warn` 和 `console.error`。设置为 `false` 以丢弃控制台输出。 |
| `maxResultChars` | `4000` | 将返回给模型的结果、错误和 console 输出截断到最大字符数。 |
| `systemPrompt` | `null` | 解释器工具的自定义系统提示。当 `null` 时使用内置提示。 |
| `ptc` | 省略 | 作为 `tools.*` 在解释器内部暴露的工具名称或 `StructuredToolInterface` 实例的允许列表。省略以禁用。参见 [启用 PTC](#启用-ptc)。 |
| `maxPtcCalls` | `256` | 每个`eval`允许的最大 `tools.*` 调用次数。仅在受信任的环境中设置为 `null`。参见 [程序化工具调用 (PTC)](#程序化工具调用-ptc) 和 [安全](#安全)。 |
| `subagents` | `true` | 当智能体有子智能体时，暴露内置 `task()` 全局。设置为 `false` 以要求通过正常 `task` 工具进行调度。参见 [动态子智能体](#动态子智能体)。 |

***

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


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