解释器

为什么需要它

你有没有试过让 Agent 连续调用十几个工具，每一步都要等模型决定下一步？

什么是解释器

一个内存中的代码运行时——Agent 编写代码，解释器执行并返回结果

解释器为 Agent 提供了一个可编程的工作空间。Agent 通过编写代码来表达意图，一个基于 QuickJS 的轻量级 JavaScript 运行时执行代码并返回结果。默认不暴露文件系统、网络、Shell 或时钟 API。

何时使用

选择正确的执行路径——简单用工具，复杂用解释器，系统级用沙箱

添加解释器

安装 QuickJS 中间件包，一行代码就能启用解释器

# 安装 deepagents 和 QuickJS 中间件
$ npm install deepagents @langchain/quickjs

import { createDeepAgent } from "deepagents";
import { createCodeInterpreterMiddleware } from "@langchain/quickjs";
// 注意：@langchain/quickjs 的部分版本实际导出的是 createQuickJSMiddleware
// （此时工具名为 js_eval 而非 eval，且部分默认值不同）。
// 若上述 import 报错，请改用：
//   import { createQuickJSMiddleware } from "@langchain/quickjs";
//   middleware: [createQuickJSMiddleware()]
// 两者是同一能力的不同封装层。本教程遵循 docs.langchain.com 官方文档的写法。

// 创建带解释器的 Agent
// 中间件会自动添加一个名为 "eval" 的工具
const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  middleware: [createCodeInterpreterMiddleware()],  // 一行启用解释器
});

运行代码

中间件添加了 eval 工具——Agent 编写代码，运行时执行并返回结果

启用中间件后，Agent 就能通过 eval 工具在持久化上下文中运行 JavaScript。运行时捕获 console.log 输出，返回最后一个表达式的值。

// Agent 自动编写的代码示例：用 reduce 聚合团队得分
// 这段代码由模型生成并提交给 eval 工具执行
const rows = [
  { team: "alpha", score: 8 },
  { team: "beta", score: 13 },
  { team: "alpha", score: 21 },
];

// 使用 reduce 按团队累加得分，中间结果留在运行时中
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;  // 最后一个表达式的值作为 eval 的返回值
// 控制台输出：
// alpha score: 8
// beta score: 13
// alpha score: 29
// 返回值：{ alpha: 29, beta: 13 }

编程式工具调用

PTC——把选定的 Agent 工具暴露到解释器的全局 tools 命名空间

编程式工具调用（PTC）让解释器代码能直接调用 Agent 的工具。Agent 不再需要"调用一个工具 → 等模型 → 调用下一个"，而是写一段代码批量处理。

// PTC 调用示例：通过 tools 命名空间直接调用 Agent 工具
// 工具名自动转为驼峰命名：web_search → tools.webSearch()
const result = await tools.webSearch({
  query: "deepagents interpreters",
});

启用 PTC

通过显式白名单启用——只暴露 Agent 需要的工具

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

// 通过 ptc 白名单启用 PTC，只暴露指定的工具给解释器代码
const agent = createDeepAgent({
  model: "openai:gpt-5.4",
  middleware: [
    createCodeInterpreterMiddleware({
      ptc: ["task"],  // 白名单即权限边界，只允许调用 task 工具
    }),
  ],
});

PTC 实战

并行启动多个子代理，合并结果后再返回给模型

// 并行启动多个子代理，各自研究一个主题
// Promise.all 让所有子代理同时运行，而非串行等待
const topics = ["retrieval", "memory", "evaluation"];

const reports = await Promise.all(
  topics.map((topic) =>
    tools.task({  // 通过 PTC 调用 task 工具启动子代理
      description: `Research ${topic} in Deep Agents and return three concise findings.`,
      subagent_type: "general-purpose",
    }),
  ),
);

// 在解释器代码中合并所有子代理的报告
// 只有这个最终结果会返回给模型，中间结果留在运行时
reports.join("\n\n");

// 本地处理失败——不需要让模型介入
try {
  const report = await tools.task({
    description: "Check the migration notes and return breaking changes.",
    subagent_type: "general-purpose",
  });
  console.log(report);
} catch (error) {
  console.log(`Subagent failed: ${error.message}`);
}

递归语言模型

用解释器作为分解工作的工作空间——变量空间与模型上下文分离

递归语言模型是一种高级模式：模型将大型输入保存在运行时变量中，编写代码拆分和检查数据，对较小部分调用子代理，最后在代码中拼接结果。

递归实战

从大量笔记中筛选迁移相关条目，并行分析风险

// 递归语言模型实战：迁移风险分析
const candidates = notes
  .filter((note) => note.includes("migration"))  // 筛选迁移相关笔记
  .slice(0, 5);  // 只取前 5 条，控制并行调用数量

// 并行调用子代理分析每一条迁移笔记
const riskReports = await Promise.all(
  candidates.map((note) =>
    tools.task({  // 通过 PTC 调用 task 工具启动子代理
      description: `Analyze this migration note for release risk.
Return risks, affected users, and recommended follow-up:\n\n${note}`,
      subagent_type: "general-purpose",
    }),
  ),
);

// 在解释器代码中拼接综合报告，只返回精简结果给模型
const releaseSummary = riskReports
  .map((report, index) => `## Candidate ${index + 1}\n${report}`)
  .join("\n\n");

releaseSummary;  // 最后一个表达式作为 eval 的返回值，这是唯一返回给模型的内容

解释器技能

向解释器暴露可复用的代码模块——用于结构化数据工作流

解释器技能是向解释器暴露代码模块的 Skills。当配置了解释器中间件时，Agent 可以从代码中导入这些模块，用于确定性的辅助逻辑。

安全与限制

QuickJS 严格隔离——默认什么都不能做，显式授权才能访问

中间件选项

createCodeInterpreterMiddleware 的完整配置项

动手练习

用解释器 + PTC 构建一个并行研究 Agent

现在轮到你了。设计一个并行研究 Agent，需求如下：

智能体应该：
1. 接收一个研究主题列表（如 ["React", "Vue", "Svelte"]）
2. 为每个主题并行启动子代理做深度研究
3. 在代码中收集和汇总所有子代理的结果
4. 对结果进行排序、过滤或评分
5. 只返回最终的精选摘要给模型

参考答案

一种可行的实现方案——不是唯一答案，但逻辑合理

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

const agent = createDeepAgent({
  model: "openai:gpt-5.4",
  middleware: [
    createCodeInterpreterMiddleware({
      ptc: ["task"],                // 只暴露 task 工具
      executionTimeoutMs: 30000,    // 30 秒超时，并行调用需要更长时间
      maxPtcCalls: 50,              // 最多 50 次工具调用
    }),
  ],
});

// Agent 生成的解释器代码（伪代码，展示概念）：
// const topics = ["React", "Vue", "Svelte"];
//
// const results = await Promise.all(
//   topics.map(async (topic) => {
//     try {
//       return await tools.task({
//         description: `研究 ${topic} 的核心优势、生态和适用场景，返回三条关键发现。`,
//         subagent_type: "general-purpose",
//       });
//     } catch (e) {
//       return `${topic} 研究失败：${e.message}`;
//     }
//   }),
// );
//
// // 过滤失败结果，按质量排序
// const validResults = results
//   .filter((r) => !r.includes("失败"))
//   .map((report, i) => ({ topic: topics[i], report }))
//   .sort((a, b) => b.report.length - a.report.length);
//
// validResults
//   .map((r) => `## ${r.topic}\n${r.report}`)
//   .join("\n\n");

本章回顾

到这里，你已经掌握了 Deep Agents 解释器的完整用法

延伸阅读