Interpreters 为 agents 提供 programmable workspace，使其可以探索 data、协调 tool calls，并将 intermediate work 保持在 model context 之外。Agent 编写 code 来表达 intent，然后 in-memory runtime 执行该 code 并返回 relevant results。 如果说 sandboxes 是 code-first 地作用于 environment 的方式（例如 running commands、installing dependencies 和 editing files），那么 interpreters 就是 code-first 地作用于 agent loop 内部的方式：composing tools、preserving state，并决定哪些 information 应返回给 model。
Interpreters 处于 beta。APIs 和 lifecycle behavior 可能会在 releases 之间变化。
Interpreters 需要 langchain-quickjs>=0.1.0 和 Python >=3.11。

​
When to use an interpreter

大多数 agent work 会在 model reasoning 和 tool execution 之间交替。对于简单 actions 这很有效，但当 agent 需要 compose many steps、reason over structured data 或 manage intermediate state 时，这会变得笨拙。 Interpreter 为 agent 提供处理这些 work 的 runtime。Agent 不必让 model 一次选择一个下一步 tool call、等待 result，再决定下一个 call；它可以编写一个 small program，用来运行 control flow、调用 allowlisted tools、存储 variables，并向 model 返回 compact result。 当 agent 需要执行以下操作时，请使用 interpreters：
  • 使用 code compose multiple tool calls，包括 loops、branching、retries 和 concurrency。
  • 通过 code 协调 subagents：将 work 拆成 focused calls、存储其 results，并将这些 results 拼接成 final synthesis。
  • 将 intermediate values 保留在 runtime state 中，而不是把每个 temporary result 都送回 model context。
  • 确定性地 transform structured data，例如 sorting、grouping、parsing、validating、scoring 或 aggregating。
  • 探索 large variable space，并只向 model 返回 selected evidence、summaries 或 outputs。
它通过在 QuickJS 中运行 code 实现，QuickJS 是为 embedded execution 设计的 lightweight JavaScript runtime。默认情况下，该 runtime 为 agent 提供一个 evaluate code 的位置，但不会暴露 host filesystem、network、shell、package 或 clock APIs。 QuickJS 是 interpreter code 的 execution boundary。显式 bridges，例如 programmatic tool calling，会决定 code 可以访问哪些 capabilities。

​
Choose the right execution path

NeedUse
一两个 simple external callsNormal tool calling
需要 loop、branch、retry 或 aggregate results 的 small programInterpreter
许多 selected tool calls 需要从 code 运行带 programmatic tool calling 的 Interpreter
跨 threads 使用的 reusable helpers带 interpreter skills 的 Interpreter
Shell commands、package installs、tests 或完整 OS filesystem accessSandboxes

​
Add an interpreter to an agent

安装 QuickJS middleware package，然后在创建 agent 时添加 middleware。 
pip install -U "deepagents[quickjs]"

from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

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

​
Run code in the interpreter

Middleware 会向 agent 添加 eval tool。该 tool 在 persistent context 中运行 TypeScript、捕获 console.log，并返回最后一个 expression 的 result。 Agent 可以编写如下 code： 
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;
默认情况下，interpreter state 也会在同一 thread 的多个 turns 之间 persist：每次 agent run 后 snapshot working state，并在下一次 run 前 restore。

​
Programmatic tool calling

Programmatic tool calling（PTC）会在 interpreter 内的 global tools namespace 下暴露 selected agent tools。Agent 不必让 model 发起一个 tool call、等待 result，再决定下一个 call；它可以编写 code，在 loops、branches、retries 或 parallel batches 中调用 tools。 当 intermediate tool results 只是下一步的 inputs 时，这很有用。Interpreter 可以先 process、filter 或 aggregate 这些 results，再将任何内容返回 model context，这能让 multi-tool/multi-step workflows 更节省 tokens。 PTC 在 Deep Agents 中是 model-agnostic 的。它由 middleware 实现，而不是 provider-specific code-execution 或 tool-calling API。

​
工作原理

  1. 你通过 ptc allowlist 选择 interpreter 可以调用哪些 tools。
  2. Middleware 将这些 tools 作为 async JavaScript functions 暴露在 tools 下。
  3. Agent 编写 interpreter code，并使用 await 调用这些 functions。
  4. Interpreter 运行 tool bridge、接收 tool result，并继续执行 code。
  5. Model 接收 final interpreter output，而不是每个 intermediate value。
每个 allowlisted tool 都会成为 async function。Tool names 会转换为 camel case，但 input object 仍遵循该 tool 的 schema。例如，名为 web_search 的 tool 会变成 tools.webSearch(...)： 
const result: string = await tools.webSearch({
  query: "deepagents interpreters",
});

​
Useful patterns

PatternWhat the interpreter can do
Batch processing循环处理许多 inputs，并为每个 input 调用 tool。
Parallel work对 independent calls 使用 Promise.all。
Conditional logic根据 earlier results 选择 next tool call。
Early termination在满足 success condition 后停止调用 tools。
Data filtering只向 model 返回 relevant rows、snippets、errors 或 summaries。
Recursive orchestration反复调用 task，然后在 code 中合并 subagent results。

​
Enable PTC

使用 explicit allowlist 启用 PTC： 
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="openai:gpt-5.4",
    middleware=[CodeInterpreterMiddleware(ptc=["task"])],
)
启用 PTC 后，agent 可以从 interpreter code 调用 allowlisted tool。此 example 会并行启动多个 subagents，并在返回 model 前合并它们的 final reports： 
const topics = ["retrieval", "memory", "evaluation"];

const reports = await Promise.all(
  topics.map((topic) =>
    tools.task({
      description: `Research ${topic} in Deep Agents and return three concise findings.`,
      subagent_type: "general-purpose",
    }),
  ),
);

reports.join("\n\n");
因为这是 code，agent 也可以在本地处理 failures： 
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}`);
}
PTC calls 目前通过 interpreter bridge 执行，不经过 normal tool calling path。因此，interrupt_on approval workflows 不会按每个 PTC-invoked tool call 强制执行。

​
Recursive language models

Recursive language models 使用 interpreter 作为 decomposition workspace。Model 将 large input 或 working set 保存在 runtime variables 中，编写 code 来 inspect 和 split 它，对较小 pieces 调用 subagents 或其他 model tools，然后在 code 中拼接返回的 results。 这会把 variable space 与 agent 的 context 分离。Variable space 是存储在 interpreter 中的信息，而 agent 的 context 是 model 在下一次 model call 中实际处理的内容。Model 可以决定哪些 snippets 成为 subagent tasks、哪些 results 需要再处理一轮，以及 final synthesis 应该向 main conversation 返回什么。 该 pattern 的背景请参阅 Recursive Language Models paper。 在 Deep Agents 中，recursive call 通常是通过 programmatic tool calling 暴露的 task tool。Interpreter 可以在许多 slices 上调用 subagents、合并 answers，并返回单个 synthesized result： 
const candidates = notes
  .filter((note) => note.includes("migration"))
  .slice(0, 5);

const riskReports = await Promise.all(
  candidates.map((note) =>
    tools.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;

​
Interpreter skills

Interpreter skills 是向 interpreter 暴露 code modules 的 skills。配置 interpreter middleware 后，agent 可以从 code import 这些 modules，并将其用于 deterministic helper logic。 当 agent 需要 structured data workflows 的 reusable helpers 时，Interpreter skills 很有用，例如 sorting、grouping、scoring、parsing、validating 或 aggregating data。Setup details 请参阅 Interpreter skills。

​
Snapshots and time travel

CodeInterpreterMiddleware 默认会在每次 agent run 后 snapshot interpreter state，并在下一次 run 前 restore。Snapshot 是 interpreter in-memory JavaScript state 的 serialized copy，包含 agent 完成运行 code 时存在的 globals、variables、functions 和 imported modules。 跨 conversation turns 时，lifecycle 如下：
  1. 一个 turn 开始，CodeInterpreterMiddleware 为 thread restore 最新 interpreter snapshot。
  2. Agent 调用 eval，code 可以 read 或 mutate interpreter variables。
  3. Agent run 完成，middleware 将更新后的 interpreter state snapshot 到 graph state。
  4. 下一个 turn 从 restore 后的 interpreter state 开始，而不是从 empty runtime 开始。
在单次 agent run 内，重复 eval calls 会使用 live interpreter context object。Middleware 不会在这些 calls 之间 snapshot 和 restore；它会在 run 完成时 snapshot context，以便稍后的 turn 或 checkpoint replay restore。
在 conversation turns 之间，snapshots 只保留可合理 serialized 的 values。请将其用于 data，而不是 live runtime objects。Functions、classes 和其他 unserializable values 会被 restore 为 inaccessible artifacts。如果 interpreter code 在 restore 后访问其中一个 value，eval tool 会抛出类似 Value for 'fn' was not restored because it is not serializable (type: function). 的错误。
Snapshots 会保留 interpreter memory，而不会保留 outside-world effects。如果 interpreter code 通过 PTC 调用 tool，restore 先前的 interpreter snapshot 不会撤销该 tool call 的 side effects。它只会 restore 记录或处理 result 的 interpreter variables。 当 graph 使用 checkpointer 时，这会与 LangGraph time travel 配合使用。Restoring graph checkpoint 可以 restore graph state 中存储的 interpreter snapshot，因此你可以在 debugging 或 replaying 时返回 earlier agent context 和 interpreter state。 
from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware
from langgraph.checkpoint.memory import MemorySaver

checkpointer = MemorySaver()

agent = create_deep_agent(
    model="openai:gpt-5.4",
    checkpointer=checkpointer,
    middleware=[
        CodeInterpreterMiddleware(
            snapshot_between_turns=True,  # Default
        )
    ],
)
你可以使用 snapshot_between_turns=False 禁用 cross-turn snapshots。

​
Security and limits

Interpreters 使用 QuickJS 以 strict default isolation 运行 untrusted JavaScript。请将其视为 scoped interpreter runtime，而不是完整 production sandbox backend。 你通过 PTC 暴露的每个 tool 都是 interpreter code 可以使用的 outside capability。请将 PTC allowlist 视为 permission boundary：只暴露 agent 所需 tools，并避免桥接可访问 sensitive systems、spend money、mutate data 或调用 unrestricted networks 的 broad tools，除非这正是预期 behavior。
CapabilityAvailable by defaultHow to expose it
JavaScript executionYes添加 interpreter middleware
Top-level awaitYes在 interpreter code 中使用 promises
console.log captureYes使用 capture_console=False 禁用
Agent toolsNo添加 PTC allowlist
Interpreter skill modulesNo添加 module entry，并配置 skills_backend 或 skillsBackend
Filesystem accessNo通过 PTC allowlist 添加 built-in filesystem tools
Network accessNo通过 PTC 暴露 specific network tool
Wall-clock or datetime accessNo如有需要，暴露 explicit time tool
Shell commands、package installs、tests、OS-level executionNo使用 sandbox backend
Code execution 的工作方式Interpreter code 在 embedded QuickJS context 中运行，而不是在单独 VM 或 process 中运行。在 Python 中，该 runtime 由 quickjs-rs 提供；其 Security guide 记录了 same-process execution boundary。请将 interpreters 视为 capability-scoped execution layer，而不是 host-memory isolation boundary。对于 untrusted 或 semi-trusted code，请在 isolated worker processes 或 containers 中运行 agents，并保持 PTC allowlist 狭窄。

​
Middleware options

CodeInterpreterMiddleware 接受以下 options：
KwargDefaultPurpose
memory_limit64 * 1024 * 1024
(64 MB)		QuickJS heap memory limit，以 bytes 为单位。
timeout5.0Per-eval timeout，以 seconds 为单位。
max_ptc_calls256每次 eval 的最大 tools.* calls 数。仅在 trusted environments 中使用 None。
tool_name"eval"暴露给 model 的 interpreter tool name。
max_result_chars4000从 result 和 stdout blocks 返回的最大 characters。
capture_consoleTrue是否捕获 console.log、console.warn 和 console.error output。
ptcNonePTC allowlist：tool names 或 BaseTool instances list。
skills_backendNone用于 resolve interpreter skill modules 的 Backend。
snapshot_between_turnsTrueInterpreter state snapshots 是否跨 agent turns persist。
max_snapshot_bytesNone最大 serialized snapshot size。默认值为 memory_limit。
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.