How to Use CodeInterpreterTool for Sandboxed Code Execution in openai-agents-python

The CodeInterpreterTool enables agents to execute arbitrary Python code in isolated sandbox environments, protecting the host system while giving the model full computational capabilities.

The CodeInterpreterTool is a built-in utility in the openai-agents-python repository that allows agents to safely run code. When attached to an Agent, it handles the entire lifecycle from tool declaration to sandbox execution, ensuring that potentially dangerous operations remain contained within temporary containers.

Architecture of CodeInterpreterTool for Sandboxed Execution

The CodeInterpreterTool operates through a seven-stage pipeline that transforms a model's tool call into sandboxed execution results:

1. Tool Declaration — In src/agents/tool.py, the CodeInterpreterTool class stores configuration specifying the sandbox backend. The default container: {type: "auto"} defers backend selection to runtime.

2. Container Selection — The runtime evaluates available backends. With container.type: "auto", it prefers the hosted E2B sandbox (E2BSandboxType.CODE_INTERPRETER) but can fall back to local subprocess execution.

3. Model Request — When the agent processes a query requiring computation, the LLM generates a ResponseCodeInterpreterToolCall object, defined in src/agents/models/openai_responses.py.

4. Turn Resolution — The turn_resolution.py module detects the ResponseCodeInterpreterToolCall and instantiates a ToolCallItem that encapsulates the code to be executed.

5. Sandbox Execution — In src/agents/extensions/sandbox/e2b/sandbox.py, the E2BSandbox class provisions an isolated container, writes the Python code, executes it, and captures stdout, stderr, and return values.

6. Result Propagation — The sandbox response is normalized into a ToolRunCodeInterpreterCall object in src/agents/items.py, then emitted as a run_item_stream_event through the agent's output stream.

7. Optional Approval — Before execution, src/agents/run_internal/tool_execution.py checks for a tool_approval callback, allowing human-in-the-loop review or automatic approval based on code content.

Implementing CodeInterpreterTool with Auto Container Detection

The standard configuration uses automatic container detection, which selects the best available sandbox backend:

import asyncio
from agents import Agent, CodeInterpreterTool, Runner, trace

async def main():
    agent = Agent(
        name="Math wizard",
        model="gpt-4o-mini",
        instructions="Use the code interpreter for any numeric calculation.",
        tools=[
            CodeInterpreterTool(
                tool_config={
                    "type": "code_interpreter",
                    "container": {"type": "auto"}
                }
            )
        ],
    )

    with trace("Code-interpreter demo"):
        result = Runner.run_streamed(
            agent,
            "Calculate the factorial of 7 and return the integer result."
        )

        async for ev in result.stream_events():
            if ev.type == "run_item_stream_event":
                item = ev.item
                if item.type == "tool_call_item" and item.raw_item.get("type") == "code_interpreter_call":
                    print("Executed code:\n", item.raw_item["code"])

        print("Final answer:", result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

The tool_config dictionary in src/agents/tool.py accepts a container specification. The "auto" value triggers the runtime logic in src/agents/extensions/sandbox/e2b/sandbox.py to prefer the E2B hosted sandbox when available.

Running CodeInterpreterTool in Local Mode

For environments without network access or when avoiding external dependencies, use the local container mode:

from agents import Agent, CodeInterpreterTool, Runner

agent = Agent(
    name="Local python runner",
    model="gpt-4o-mini",
    instructions="Always use the code interpreter for calculations.",
    tools=[
        CodeInterpreterTool(
            tool_config={
                "type": "code_interpreter",
                "container": {"type": "local"}  # Forces subprocess execution

            }
        )
    ],
)

result = Runner.run(agent, "What is 2**20?")
print(result.final_output)   # Output: 1048576

Setting container.type to "local" forces the execution path to use a local Python subprocess rather than the hosted E2B sandbox. This mode is implemented in the same sandbox abstraction layer but bypasses the container orchestration logic.

Implementing Tool Approval for CodeInterpreterTool

For security-sensitive applications, implement an approval hook to review code before execution:

from agents import Agent, CodeInterpreterTool, Runner, ToolApprovalItem

def auto_approve(ctx, approval_item: ToolApprovalItem) -> dict:
    # Inspect the code before approving

    code = approval_item.raw_item.get("code", "")
    if "import os" in code or "import sys" in code:
        return {"approve": False, "reason": "Forbidden imports detected"}
    return {"approve": True}

agent = Agent(
    name="Approved runner",
    model="gpt-4o-mini",
    instructions="Use code interpreter when needed.",
    tools=[CodeInterpreterTool(tool_config={"type": "code_interpreter"})],
    tool_approval=auto_approve,  # Attach the approval hook

)

result = Runner.run(agent, "Compute the sum of the first 100 primes.")
print(result.final_output)

The tool_approval callback receives a ToolApprovalItem describing the pending code_interpreter_call. Returning {"approve": True} permits the sandbox execution to proceed; {"approve": False} aborts the operation.

Key Source Files for CodeInterpreterTool Implementation

Understanding the following files helps when debugging or extending the CodeInterpreterTool:

• src/agents/tool.py — Defines the CodeInterpreterTool dataclass and its tool_config schema.
• src/agents/models/openai_responses.py — Contains the ResponseCodeInterpreterToolCall model that represents the LLM's tool invocation.
• src/agents/run_internal/turn_resolution.py — Detects code interpreter calls and creates ToolCallItem instances.
• src/agents/extensions/sandbox/e2b/sandbox.py — Implements the E2B sandbox backend for hosted container execution.
• src/agents/items.py — Defines ToolRunCodeInterpreterCall for normalizing execution results.
• src/agents/run_internal/tool_execution.py — Handles the approval flow and orchestrates sandbox invocation.

Summary

• CodeInterpreterTool enables secure, sandboxed Python execution within the openai-agents-python framework.
• The container configuration (auto, local, or custom) determines whether code runs in hosted E2B containers or local subprocesses.
• Streaming events expose the exact code being executed via run_item_stream_event objects with type code_interpreter_call.
• Approval hooks let you inspect and authorize code before execution, providing security against malicious imports or operations.
• The implementation spans src/agents/tool.py, src/agents/extensions/sandbox/e2b/sandbox.py, and src/agents/run_internal/turn_resolution.py.

Frequently Asked Questions

What is the difference between auto and local container modes?

The auto mode selects the best available sandbox backend, preferring the hosted E2B container when network access is available, while local forces execution through a local Python subprocess. Use local when running in air-gapped environments or when avoiding external dependencies, and auto for production workloads requiring stronger isolation guarantees.

How does CodeInterpreterTool protect against malicious code?

The tool runs all code in isolated containers (either E2B hosted sandboxes or restricted local subprocesses) that have no access to the host filesystem or network unless explicitly configured. Additionally, the tool_approval callback allows you to implement pre-execution filtering to block dangerous imports like os or sys before the code reaches the sandbox.

Can I customize the sandbox environment for CodeInterpreterTool?

Yes, you can specify custom container configurations through the tool_config parameter. While the default auto and local modes cover most use cases, the underlying sandbox abstraction in src/agents/extensions/sandbox/e2b/sandbox.py supports custom environment variables, pre-installed packages, and network policies when using hosted containers.

Where is the sandbox execution logic implemented?

The sandbox execution logic resides in src/agents/extensions/sandbox/e2b/sandbox.py, which implements the E2BSandbox class for hosted container execution. For local mode, the same abstraction layer handles subprocess management. The orchestration logic that invokes the sandbox is located in src/agents/run_internal/tool_execution.py, while the tool definition itself is in src/agents/tool.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}