Defines instructions and capabilities
AI Models & Assistants / Knowledge library
Sandboxed Agent Execution
Runs agent-selected code or computer actions inside a constrained environment
Why learn Sandboxed Agent Execution?
It allows useful code and computer interaction without granting unrestricted host access.
The problem it solves
It contains mistakes and adversarial actions that could otherwise affect unrelated systems or data.
Where it came from
A sandbox limits filesystem, process, network, credential, and resource access around untrusted or model-generated actions. Isolation reduces blast radius but still requires explicit capability boundaries and safe artifact transfer.
Build your understanding
Work through these exercises in order. Try the task before opening a reference.
- Define Sandboxed Agent Execution and identify its place in an agent architecture.
- Choose a task where Sandboxed Agent Execution improves an agent system.
- Diagnose one failure caused by misusing Sandboxed Agent Execution.
- Interpret a trace or state transition involving Sandboxed Agent Execution.
- Explain one operational tradeoff of Sandboxed Agent Execution.
Documentation and sources
- OpenAI Agents SDK: Sandbox agents (openai.github.io)
Connect the ideas
Explore next
Real World Example
Automated Financial Document Reconciliation
Financial auditing firms managing high-volume client document processing.
The business problem
Manual verification of client-submitted financial statements is slow, error-prone, and risks exposing sensitive host-system files to unauthorized scripts.
How this topic solves it
Use a SandboxAgent with a constrained filesystem to isolate document processing. The agent uses filesystem tools to read client files, perform calculations, and generate reconciliation reports within a temporary, isolated workspace.
- Define a SandboxAgent with a Manifest that mounts the specific client document directory as a read-only workspace.
- Configure the agent capabilities to include Filesystem access for reading statements and Shell access for running validation scripts.
- Initialize a DockerSandboxClient to ensure that all agent-executed code runs within a containerized, OS-isolated environment.
- Execute the agent using a SandboxRunConfig that points to the client-specific snapshot for consistent processing.
- Verify the output artifacts generated in the sandbox workspace before promoting them to the firm's primary storage.
The flow shows how the agent definition and configuration interact with the sandbox environment.
Determines client and session source
Binds agent to session
Isolated workspace for execution
- SandboxAgent → provides definition → Runner
- SandboxRunConfig → injects session config → Runner
- Runner → binds and executes → SandboxSession
Implementation example
This code initializes a SandboxAgent with necessary capabilities and selects a Docker backend, which maps to the solution of using isolated environments for financial document processing.
from agents import SandboxAgent, DockerSandboxClient
# Define the agent with filesystem capabilities
agent = SandboxAgent(
name="ReconciliationAgent",
capabilities=[Filesystem(), Shell()] # Allows file edits and shell commands
)
# Configure the run to use Docker for isolation
config = SandboxRunConfig(client=DockerSandboxClient())Expected business outcome
Secure, reproducible document processing where the agent operates on isolated data without risking host-system integrity.
Limitations and checks
The sandbox session does not provide inherent OS-level confinement when using the UnixLocalSandboxClient; developers must choose a Docker or hosted backend to ensure true process isolation.