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

> Learn to use CodeInterpreterTool for secure, sandboxed code execution within openai-agents-python. Empower your agents with computational capabilities while protecting your host system.

- Repository: [OpenAI/openai-agents-python](https://github.com/openai/openai-agents-python)
- Tags: how-to-guide
- Published: 2026-04-17

---

**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`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/src/agents/models/openai_responses.py).

4. **Turn Resolution** — The [`turn_resolution.py`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/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:

```python
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`](https://github.com/openai/openai-agents-python/blob/main/src/agents/tool.py) accepts a `container` specification. The `"auto"` value triggers the runtime logic in [`src/agents/extensions/sandbox/e2b/sandbox.py`](https://github.com/openai/openai-agents-python/blob/main/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:

```python
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:

```python
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`](https://github.com/openai/openai-agents-python/blob/main/src/agents/tool.py)** — Defines the `CodeInterpreterTool` dataclass and its `tool_config` schema.
- **[`src/agents/models/openai_responses.py`](https://github.com/openai/openai-agents-python/blob/main/src/agents/models/openai_responses.py)** — Contains the `ResponseCodeInterpreterToolCall` model that represents the LLM's tool invocation.
- **[`src/agents/run_internal/turn_resolution.py`](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/turn_resolution.py)** — Detects code interpreter calls and creates `ToolCallItem` instances.
- **[`src/agents/extensions/sandbox/e2b/sandbox.py`](https://github.com/openai/openai-agents-python/blob/main/src/agents/extensions/sandbox/e2b/sandbox.py)** — Implements the E2B sandbox backend for hosted container execution.
- **[`src/agents/items.py`](https://github.com/openai/openai-agents-python/blob/main/src/agents/items.py)** — Defines `ToolRunCodeInterpreterCall` for normalizing execution results.
- **[`src/agents/run_internal/tool_execution.py`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/src/agents/tool.py), [`src/agents/extensions/sandbox/e2b/sandbox.py`](https://github.com/openai/openai-agents-python/blob/main/src/agents/extensions/sandbox/e2b/sandbox.py), and [`src/agents/run_internal/turn_resolution.py`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/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`](https://github.com/openai/openai-agents-python/blob/main/src/agents/run_internal/tool_execution.py), while the tool definition itself is in [`src/agents/tool.py`](https://github.com/openai/openai-agents-python/blob/main/src/agents/tool.py).