OpenAI Sandbox Agents - Giving AI Agents Isolated Workspaces for Real Work

Most AI agent workflows break down the moment you need the agent to actually do something with files. You can give a model a prompt and get a response. You can give it tools and get function calls. But when the task requires reading a directory of documents, running shell commands, producing output files, or maintaining state across sessions - that's where things fall apart if all you have is prompt context.

OpenAI's Sandbox Agents address this directly. A sandbox gives an agent an isolated, Unix-like execution environment with a filesystem, shell, installed packages, mounted data, exposed ports, and snapshot capabilities. It's the difference between asking someone to describe how they'd renovate a house and actually giving them the tools and workspace to do it.

We've been building production AI agent systems for a while now, and the sandbox pattern solves a real problem we've hit repeatedly. Let me explain what it does and when you should use it.

The Harness vs Compute Split

The most important concept in Sandbox Agents is the separation between the harness and compute.

The harness is the control plane. It owns the agent loop, model calls, tool routing, handoffs, approvals, tracing, recovery, and run state. This is your orchestration layer - the code that decides what the agent does next and manages the conversation.

Compute is the sandbox execution plane. This is where model-directed work actually happens - files get read and written, commands run, dependencies install, ports open, and state persists.

Why does this separation matter? Because it lets you keep sensitive control-plane work in trusted infrastructure while the sandbox handles the messy, potentially risky execution in isolation. The sandbox runs code against files with narrow credentials and specific mounts. The harness keeps auth tokens, billing logic, audit logs, human review checkpoints, and recovery state outside the container entirely.

You can run both in the same environment for prototyping - OpenAI acknowledges this in their docs - but for production, keeping them separate is the right call. We've learned this the hard way on projects where mixing orchestration with execution meant a misbehaving script could affect the entire agent loop.

When You Need a Sandbox

Not every agent needs one. If your workflow is "send a prompt, get a text response," use the Responses API directly. If shell access is an occasional tool call, the hosted shell tool might be enough.

Sandbox Agents are the right choice when:

The task involves a directory of documents, not a single prompt. Processing a folder of invoices, analysing a codebase, reviewing a collection of legal documents - these need filesystem access, not just context window stuffing. You can mount the documents into the sandbox and let the agent work through them naturally.

The agent needs to produce artifacts. Markdown reports, CSV exports, JSONL datasets, screenshots, generated websites - if the output is files rather than text, the agent needs somewhere to write them. The sandbox filesystem gives the agent a working directory, and your application can inspect the output afterward.

Commands, packages, or scripts are required. Data processing that needs pandas. Code generation that needs to be tested. Document conversion that needs command-line tools. The sandbox has a shell and can install packages, so the agent isn't limited to what's available in the model's context.

The workflow pauses and resumes. Human review loops are common in real business processes. An agent does preliminary analysis, a person reviews it, then the agent continues. Sandbox state persists between turns, so the workspace is exactly where it was left. Snapshots let you save and restore workspace state for longer workflows.

A service needs to run on a port. Notebook previews, web application previews, report servers - sometimes the agent needs to run something and expose it for inspection. Sandboxes support exposed ports for this.

Building a Sandbox Agent

SandboxAgent extends the regular Agent class from the OpenAI Agents SDK. You still define instructions, tools, handoffs, model settings, output types, guardrails, and hooks. What's different is the execution boundary - the runner prepares the agent against a live sandbox session.

The key pieces are:

The Manifest

Manifest describes what the sandbox workspace looks like at startup. It's your fresh-session contract - what files, directories, repos, mounts, and environment variables should exist when the agent starts working.

Manifest entries include:

• File and Dir for small synthetic inputs, helper scripts, or output directories
• LocalFile and LocalDir for materialising host files into the sandbox
• GitRepo for cloning repositories into the workspace
• Cloud storage mounts (S3, GCS, R2, Azure Blob, Box) for external data
• Environment variables for configuration the sandbox needs at startup
• Users and groups for providers that support OS account provisioning

All paths in the manifest are workspace-relative. No absolute paths, no .. directory traversal. This keeps manifests portable across local, Docker, and hosted sandbox providers.

Good manifest design means putting your inputs, repos, and output directories in the manifest. Put task specifications and instructions in workspace files rather than cramming everything into the agent's prompt. The agent can read files from the workspace, so let it.

Sandbox Clients

The sandbox client determines where the workspace physically runs. Options include Unix-local (for development), Docker (for local isolation), or hosted providers (for production workloads). The choice is a deployment decision that doesn't affect how you write the agent.

Run Configuration

SandboxRunConfig controls per-run behaviour. It determines whether a run should create a new sandbox session, resume an existing one, or inject specific inputs into an existing workspace. This is where you handle the "human reviews, then agent continues" pattern - the second run references the same session as the first.

Saved State

RunState and session_state persist agent and workspace state for later runs. Snapshots capture the entire workspace at a point in time, letting you roll back or fork from a known state.

Architecture Decisions That Matter

Turn Boundaries

A common misunderstanding - a turn in the sandbox agent isn't a single shell command or file operation. It's a model step. The agent might execute several sandbox operations (run a command, read output, write a file) before needing another model response. The runtime only consumes a turn when it needs to go back to the model.

This is important for cost estimation. You're paying for model calls, not sandbox operations. A well-prompted agent that handles a complex file processing task in a single turn (with multiple sandbox operations) costs the same as one model call.

What Goes in the Manifest vs What Goes in the Prompt

We've found this rule works well: put data and configuration in the manifest, put task instructions in the prompt or in workspace files.

Don't try to describe the contents of a 50-file directory in the prompt. Mount the directory and tell the agent to explore it. Don't pass a CSV as base64 in the prompt. Mount it as a file and tell the agent where to find it.

The manifest is for the "what" - what does the workspace contain. The prompt is for the "why" and "how" - what should the agent do with it.

Session Reuse vs Fresh Sessions

For stateless tasks (process this batch of documents, generate this report), create a fresh session each time. The manifest guarantees a clean starting state.

For stateful workflows (iterative analysis, multi-step review processes, ongoing monitoring), reuse sessions. The workspace accumulates state, and the agent can build on previous work.

The decision isn't just technical - it's about reliability. Fresh sessions are predictable. Reused sessions can accumulate state that makes behaviour harder to predict. We generally lean toward fresh sessions with explicit state passing for anything running in production.

Practical Considerations for Australian Businesses

Data residency matters here. When you're mounting business data into a sandbox, you need to know where that sandbox runs. For organisations in regulated industries - financial services, healthcare - the sandbox provider and its data centre locations become compliance questions.

If you're using a hosted sandbox provider, understand their data handling. Does the sandbox persist after the session ends? Are snapshots stored encrypted? Where geographically does the compute run? These aren't hypothetical questions for Australian organisations dealing with the Privacy Act and industry-specific regulations.

For sensitive workloads, Docker-based sandboxes running in your own Azure infrastructure give you full control over data location. The trade-off is you manage the infrastructure yourself.

When Not to Use Sandboxes

Not everything needs this level of isolation. Simple Q&A agents, chatbots that look up information, classification tasks that take text in and return labels - these don't need a workspace. Adding a sandbox where prompt context is sufficient just adds complexity and cost.

The question to ask is: does this agent's output depend on work done in a workspace? If the answer is yes - it needs to process files, run code, produce artifacts, or maintain state - use a sandbox. If the answer is no, skip it.

OpenAI's Sandbox Agents documentation covers the full API surface including capabilities, provider-specific options, and advanced configuration. Currently the sandbox agent feature is only available in the Python Agents SDK.

Where This Is Heading

Sandbox Agents represent a meaningful step toward agents that can do real work rather than just talk about doing work. The pattern of isolated, persistent, mountable workspaces is exactly what's needed for document processing, code generation, data analysis, and any workflow where the agent needs to interact with the real world rather than just the model's context window.

For our AI development work, this changes the types of projects that are feasible. Tasks that previously required custom infrastructure for agent execution now have a standardised pattern. That means faster development, more predictable behaviour, and easier handover to client teams who need to maintain the system after we leave.