Build AI agents that actually run code

The canonical agent pattern

Most "AI runs code" demos break the moment the model needs to install a package, debug a traceback, or hold state across turns. With stateful sessions, that loop just works.

Code example: OpenAI tool calling + Python SDK

Here's the entire wiring you need. The agent picks the tool, the SDK calls SandboxAPI, the result goes back to the model. Wrap it in a loop and you have a code interpreter.

import os
from openai import OpenAI
from sandboxapi import SandboxAPI

client = OpenAI()
sb = SandboxAPI(api_key=os.environ["SANDBOX_API_KEY"])

# Open a session up front so files and packages persist across tool calls
session = sb.sessions.create(language="python3", idle_ttl=600)

tools = [
  {
    "type": "function",
    "function": {
      "name": "execute_python",
      "description": "Run Python code in a stateful sandbox. Files and packages persist across calls.",
      "parameters": {
        "type": "object",
        "properties": {"code": {"type": "string"}},
        "required": ["code"],
      },
    },
  },
  {
    "type": "function",
    "function": {
      "name": "install_packages",
      "description": "Install pip packages in the current session.",
      "parameters": {
        "type": "object",
        "properties": {"packages": {"type": "array", "items": {"type": "string"}}},
        "required": ["packages"],
      },
    },
  },
]

messages = [{"role": "user", "content": "Read the CSV at /tmp/sales.csv and report total revenue."}]

# Agent loop
while True:
    resp = client.chat.completions.create(
        model="gpt-4o", messages=messages, tools=tools,
    )
    msg = resp.choices[0].message
    messages.append(msg.model_dump())

    if not msg.tool_calls:
        print(msg.content)
        break

    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        if call.function.name == "execute_python":
            result = sb.sessions.execute(session.id, code=args["code"])
            content = result.stdout + (("\n" + result.stderr) if result.stderr else "")
        elif call.function.name == "install_packages":
            sb.sessions.install(session.id, manager="pip", packages=args["packages"])
            content = "Installed " + ", ".join(args["packages"])
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": content,
        })

sb.sessions.close(session.id)

Why SandboxAPI fits AI agents

• Sessions — files and installed packages persist between tool calls. The agent doesn't re-do setup work.
• Package install — the agent can pip install what it needs in <3s. No pre-baking the image.
• Modern runtimes — Python 3.12, Node 22, TypeScript 5.4, Go 1.22, Java 21, GCC 14, and Bash 5.2.
• gVisor isolation — when an agent generates code, you don't trust the code. We don't either.
• MCP-native — Claude Desktop, Cursor, Cline, VS Code — drop in a JSON config, you're done.
• Streaming output — show the agent's stdout in real time as long-running scripts execute.

Common patterns

Code interpreter for any LLM

Wrap the SDK in two tool definitions (execute_python, install_packages) and you have a fully-featured code interpreter for any model that supports function calling.

Self-correcting agent

When the LLM produces broken code, the traceback feeds back as the next message. With sessions, the fix doesn't lose context. Most coding tasks converge in 1–3 iterations.

Multi-language pipelines

The agent can drop down to Bash to inspect a file, switch to Python to analyze it, and produce a JSON output. Each language gets its own session — sessions are cheap.

Auto-grading agent demos

Building a "show me you can solve LeetCode" demo? Run a small harness inside the sandbox, print JSON with passed/total counts, and let the agent inspect stdout for the verdict.