代码解释器 (Interpreters) [Beta]

在 Deep Agents 内部运行轻量级代码，用于编排工具、调度子智能体和执行结构化数据转换

代码解释器为智能体在模型调用循环内部提供了一个可编程的内存工作空间。智能体编写代码来完成复杂逻辑，运行时负责执行并将仅相关的精简结果返回给模型，中间海量的临时计算过程不会直接灌入模型上下文。

如果说沙箱 (Sandboxes) 是在外部环境中采取行动的代码优先方式（如运行命令、安装依赖包和编辑宿主机文件），那么解释器则是在内部编排工具、维持计算状态并精确控制向模型反馈哪些信息的高效代码层。

WARNING

解释器功能目前处于 Beta 预览阶段。各版本之间的 API 与生命周期行为可能会有细微演进。

NOTE

使用解释器需要额外安装依赖包 @langchain/quickjs。

为什么使用代码解释器？

传统智能体的工作流程通常在“模型推理”与“工具调用”之间来回往复。虽然模型单轮可以发出多个工具调用，但该批次在发出的瞬间就已被固定死。在没有开启新一轮模型调用的情况下，无法实现循环、无法基于结果分支跳转、无法自动重试失败，也无法将前一个调用的输出直接管道式传递给下一个调用；而且每一次调用的冗长结果都会塞满模型的上下文窗口。此外，让模型直接遍历派发数百个小任务通常极不可靠，模型往往会偷懒抽样而非完整覆盖。

代码解释器将这种业务编排逻辑转移到代码中执行，使大语言模型只需专注于思考做什么 (What to do)，而无需事无巨细地参与每一个中间机械步骤。

编程式工具调用 (Programmatic tool calling, PTC)

直接从解释器代码中调用白名单工具，支持循环、重试、条件分支与并行批处理。

动态子智能体 (Dynamic subagents)

从代码中派发子智能体，针对海量输入执行扇出并发（Fan-out）、交叉验证与递归工作流。

有状态运算

在运行时状态中保留中间变量与缓存，防止过度膨胀模型上下文窗口。

确定性数据转换

无需消耗额外模型调用轮次，即可对结构化数据进行精确排序、分组、解析、校验、打分和聚合。

架构选型模式对比

• 针对模型循环内部的代码逻辑（编排工具、维持内存状态、控制返回结果）：使用代码解释器。
• 针对面向操作系统的外部环境交互（Shell 命令、安装依赖、编译测试、文件系统修改）：使用沙箱环境。

场景需求	推荐方案
一两个简单的前置外部调用	普通工具调用 (Normal tool calling)
纯内存 JavaScript 运算：循环、分支、重试或数据转换（无需外部工具）	代码解释器 (Interpreter)
在代码中编排大量外部工具调用	带有 编程式工具调用 (PTC) 的代码解释器
针对大批量输入的独立任务单元、多视角评审或递归分析	带有 动态子智能体 的代码解释器
执行 Shell 脚本、安装 NPM/Python 包、运行单元测试或操作系统级文件读写	沙箱环境 (Sandboxes)

快速起步

安装 QuickJS 中间件包，然后在调用 createDeepAgent 时通过 middleware 参数传入解释器中间件：

npm install deepagents @langchain/quickjs

pnpm add deepagents @langchain/quickjs

yarn add deepagents @langchain/quickjs

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

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

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

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

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

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

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

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

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

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

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

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

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 调用之间保持。它会自动捕获 console.log、console.warn 和 console.error，并返回最后一个表达式的计算结果。

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

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;

代码基于轻量级 JavaScript 运行时 QuickJS 执行。默认情况下，解释器代码无法访问宿主机文件系统、网络、Shell 终端、包管理器或系统时钟。它仅能计算、维持内存状态并向控制台输出日志。

通过两个明确的显式桥梁可以安全扩展其能力：

• 工具集成：通过编程式工具调用 (PTC)。在 tools 命名空间下提供工具白名单作为异步函数。
• 子智能体集成：通过动态子智能体。当智能体配置了子智能体时，解释器会暴露一个全局 task() 函数，用于从代码中动态派发子智能体。

编程式工具调用默认关闭，直到你显式启用它。通过 task() 派发子智能体在智能体配置了子智能体时默认开启。除此以外，没有任何外部能力能穿透 QuickJS 的安全隔离边界。

编程式工具调用 (PTC)

编程式工具调用（Programmatic tool calling, PTC）在全局 tools 命名空间下向解释器暴露选定的智能体工具。智能体无需在每一步都由模型发起工具调用、等待结果并思考下一步，而是可以编写 JavaScript 代码在循环、分支逻辑或并发批处理中高效调用工具。

当中间步骤仅作为下一步的输入时，这极具价值：解释器可以在返回模型之前对数据进行清洗过滤或聚合汇总，从而显著节省多步工作流的 Token 消耗。

中间件将每个白名单工具暴露为 tools 下的异步函数。智能体使用 await 调用它并在代码中处理结果，模型最终只接收解释器的最终精炼输出：

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

启用 PTC

通过传入显式的工具白名单数组来启用 PTC：

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

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

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

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

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

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

启用 PTC 后，智能体即可在代码中并行检索并整合信息：

const topics = ["retrieval", "memory", "evaluation"];

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

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

WARNING

PTC 调用目前通过解释器桥接层执行，不经过常规的直接工具调用路径。因此，interruptOn 审批工作流不会在 PTC 内部发起的工具调用上逐个生效。

动态子智能体 (Dynamic subagents)

动态子智能体允许解释器使用内置的全局 task() 函数直接在代码中派发已配置的子智能体。对于涵盖多个独立单元的任务（例如审查目录中的每个文件或分拣批量工单），可以直接编写循环实现扇出并发，并综合最终结论。

常见应用场景：

• 扇出与综合 (Fan-out and synthesize)：并行对多个文件执行相同的审查，然后汇总结果。
• 双重验证 (Verification)：将初步结论发送给独立的验证子智能体，仅保留确认无误的结果。
• 递归工作流：在解释器变量中维护工作集合，不断切片调用子智能体并迭代优化。

const paths = ["src/auth.ts", "src/routes/api.ts"];

const reviews = await Promise.all(
  paths.map((path) =>
    task({
      description: `审查 ${path} 中的身份认证与授权漏洞`,
      subagentType: "reviewer",
    }),
  ),
);

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

安全边界与隔离

解释器使用 QuickJS 运行非受信代码，具备极其严苛的默认隔离。请将其视为作用域限定的计算运行时，而非功能完全的操作系统沙箱。

通过 PTC 暴露的每个工具都是解释器代码可以调用的外部能力。请将 PTC 白名单作为安全权限边界：仅暴露智能体确实需要的工具，切勿随意桥接可能涉及写操作、资金支出或敏感系统访问的高危工具。

功能能力	默认是否可用	如何按需开启
JavaScript 代码执行	是	添加解释器中间件
顶层 await 异步支持	是	在解释器代码中直接使用 Promise
控制台输出捕获	是	可设置 captureConsole: false 禁用
智能体工具调用	否	配置 PTC 白名单列表
文件系统访问	否	将内置文件系统工具加入 PTC 白名单
网络连接访问	否	通过 PTC 显式暴露特定的网络搜索或抓取工具
系统时钟与真实时间	否	按需暴露显式的时间工具
执行 Shell 脚本、安装包、运行系统测试	否	使用专门的沙箱后端

配置参数速查表

createCodeInterpreterMiddleware 支持以下配置选项：

配置项	默认值	作用说明
memoryLimitBytes	64 * 1024 * 1024 (64 MB)	每次会话 QuickJS 堆内存上限
maxStackSizeBytes	320 * 1024	每次会话 QuickJS 栈内存上限
executionTimeoutMs	5000 (5秒)	单次 eval 调用的超时毫秒数。负值表示禁用超时
toolName	"eval"	暴露给大语言模型的解释器工具名称
captureConsole	true	是否捕获 console.log 等日志并返回给模型。设为 false 则直接丢弃
maxResultChars	4000	返回给模型的结果、报错及控制台日志的最大字符截断阈值
systemPrompt	null	解释器工具的自定义系统提示词。为 null 时使用内置提示词
ptc	未指定 (关闭)	暴露给解释器内部 tools.* 的工具名称白名单数组
maxPtcCalls	256	单次 eval 运行中允许的最大 tools.* 调用次数熔断上限
subagents	true	当配置了子智能体时是否注入全局 task()。设为 false 则关闭动态派发