Skip to content

Code Interpreter as a Primary Agent Tool

Expose a sandboxed code interpreter as a first-class tool for shape-of-data tasks — bounded through capability bridges, output caps, and explicit threat modeling.

A code interpreter is a small embedded runtime — typically Python or JavaScript — that the agent writes against to compose tool calls, transform structured data, and hold intermediate state outside the model context (LangChain, 2026-05-20). It is not a substitute for an OS-level sandbox, and it rules out several workload classes outright (see when this backfires).

When to add an interpreter

Reach for an interpreter when at least two of these hold:

  • The task issues three or more tool calls whose intermediate results feed the next call.
  • Returns are structured (JSON, lists, tables) and need filtering or aggregation before they are useful to the model.
  • Loading every intermediate result into context would exceed the attention budget or trigger context rot.
  • The same operation runs across many items, for example budget checks across 20 employees or scoring 10,000 documents.

Stay with direct tool calls for single invocations, when the model needs intermediate values for its own reasoning, or when the toolset is dominated by MCP-connector tools that cannot be called programmatically.

How the interpreter sits in the loop

The interpreter is middleware between the agent loop and a scoped runtime (LangChain, 2026-05-20): the model writes code against an eval-shaped tool, allowlisted tools cross back to the host through explicit bridges, and the final expression returns to model context.

graph LR
    Model[Model] -->|writes code| Eval[eval tool]
    Eval -->|runs in| Runtime[Scoped runtime]
    Runtime -->|bridge| Tools[Allowlisted tools]
    Tools -->|results| Runtime
    Runtime -->|final value| Model

This shape — narrow runtime, capabilities via explicit bridges, intermediate state off context — recurs in Anthropic's Programmatic Tool Calling (PTC), Cloudflare Code Mode, and LangChain Deep Agents interpreters.

Choosing the sandbox boundary

The boundary determines blast radius, state preservation, and cost:

Boundary State across calls Blast radius Use when
Ephemeral per-call None Smallest Untrusted input, single computation per call
Session-scoped REPL Variables persist between eval calls Bounded to session Multi-step composition over the same dataset
Shared workspace + filesystem Files persist; processes may Largest Long-running agentic CI with durable artifacts

Anthropic's managed PTC sits in the middle: containers persist for 4.5 minutes idle, 30-day hard maximum (Claude API docs). LangChain's QuickJS interpreter keeps a live context across eval calls within a turn and snapshots between turns (LangChain, 2026-05-20).

Bounding side effects

The interpreter starts narrow: language features only — no filesystem, network, shell, package installation, or wall-time access (LangChain, 2026-05-20). Add capabilities back through explicit bridges. At minimum, configure:

  • Capability allowlist — only needed tools cross the bridge; in PTC, allowed_callers: ["code_execution_20260120"] per tool (Claude API docs).
  • Memory limit and per-eval timeout, max programmatic tool calls (which prevents runaway loops), and max result size (which caps the return crossing into context).
  • Network policy — default-deny outbound; allowlist specific registries or APIs.
  • Filesystem policy — if mounted, restrict writes to a working directory under dual-boundary sandboxing rules.

For tenant isolation or untrusted input, the interpreter must sit inside an OS-level sandbox, not replace one: "this does not replace sandboxing when your threat model requires process or VM isolation" (LangChain, 2026-05-20). For shared tenancy, container isolation is weaker than Firecracker microVMs.

Returning results to model context

Keep the return proportional to its information content. Use structured JSON for compact summaries (top-k, aggregate, verdict). Use truncated stdout with an explicit cap when the model needs a sample. Use a referenced artifact (path, container id, object key) when the value is large and downstream tools reload it on demand.

Why it works

The interpreter relocates intermediate state and control flow off the model's attention budget. Calling 20 tools serially pulls every result into context and runs 20 inference passes; code calling the same 20 tools keeps intermediate results in the runtime and crosses only the filtered value back. Anthropic measures 37% token reduction (43,588 to 27,297) on multi-step research (Anthropic, advanced tool use); Cloudflare reports 99.9% input-token reduction on a large API and 81% on complex multi-event tasks (WorkOS analysis); LangChain's PTC-as-middleware tests show about 35% reduction on OOLONG trec-coarse (LangChain, 2026-05-20). Code is a denser representation of control flow than a serialized chain of model-mediated calls.

When this backfires

  • Untrusted input domains. The CIBER benchmark finds execution-first interpreters fail against natural-language-disguised attacks — NL input is +14.1% attack success rate over explicit code attacks, and higher model capability increases susceptibility because stronger instruction adherence is exploitable. Anthropic's Opus 4.7 system card notes Claude Code Security Review "is not hardened against prompt injection" (VentureBeat, 2026). Agents that ingest web pages, emails, or user files must put the interpreter behind a separate OS-level boundary.
  • Single-step tasks. For one tool call, code-gen latency and runtime overhead exceed the saved round trip.
  • Regulated workloads requiring ZDR. Managed PTC excludes Zero Data Retention (Claude API docs); data-residency-bound workloads must self-host or skip it.
  • MCP-connector-dominated toolsets. PTC cannot call MCP-connector tools (Claude API docs); if most of the toolset comes from connectors, the interpreter sits idle.
  • Strict-schema flows. PTC does not support strict: true, tool_choice-forced calls, or disable_parallel_tool_use (Claude API docs); workflows depending on these cannot be wrapped.
  • Interpreter as a bash proxy. Without runtime controls, the agent routes everything through it, bypassing per-tool permission gates. Memory limits, per-eval timeouts, max programmatic tool calls, max result size, and snapshot policy are not optional (LangChain, 2026-05-20).
  • Over-reliance. Agents default to writing code when a direct answer would be cheaper; measure the round-trip count first.

Example

A common shape: filter a dataset across many items and return only the exceptions. Anthropic's PTC example checks budget compliance across 20 employees (Claude API docs). Tools marked allowed_callers: ["code_execution_20260120"] let the model orchestrate 40+ calls in one block and return only the exceptions:

team = await get_team_members("engineering")
levels = list(set(m["level"] for m in team))
budgets = dict(zip(levels, await asyncio.gather(*[
    get_budget_by_level(level) for level in levels
])))
expenses = await asyncio.gather(*[get_expenses(m["id"], "Q3") for m in team])

# Only the filtered result enters context
exceeded = [m for m, exp in zip(team, expenses)
            if sum(e["amount"] for e in exp) > budgets[m["level"]]["travel_limit"]]
print(json.dumps(exceeded))

The traditional approach issues 20 round-trips and pulls thousands of line items through context; the programmatic approach runs every lookup in one container, filters in-runtime, and returns only the employees over their limit (Claude API docs).

Key Takeaways

  • Treat the interpreter as a third context surface alongside message history and the filesystem — for live working values that should not yet be model input (LangChain, 2026-05-20).
  • Reach for it when the task is multi-step structured-data work; stay direct for single tool calls.
  • Choose the boundary (ephemeral, session-scoped, workspace) by blast-radius needs, not convenience.
  • Always set memory limit, per-eval timeout, max programmatic calls, max result size, and default-deny network.
  • The interpreter does not replace OS-level isolation — pair it with dual-boundary sandboxing for untrusted input or shared tenancy.
  • ZDR, MCP-connector-heavy flows, and strict-schema requirements disqualify Anthropic's managed PTC.
Established — multiple independent sources Last reviewed: 2026-06-13
Feedback