Inkdown
Start writing

OpenAI Agents Python

21 filesยท0 subfolders

Shared Workspace

OpenAI Agents Python
00_OVERVIEW.md

09_SANDBOX_SYSTEM

Shared from "OpenAI Agents Python" on Inkdown

Sandbox System - Comprehensive Deep Dive

Overview

The Sandbox system provides isolated execution environments for agents to perform real work with filesystems, run commands, and maintain state across longer time horizons. Think of a sandbox as a "secure workspace" or "container" where an agent can safely interact with files, execute code, and perform tasks without affecting your actual system.

Core Concepts

What is a Sandbox?

A sandbox is an isolated execution environment that:

  • Provides a filesystem for the agent to work with
  • Allows command execution in a controlled manner
  • Maintains state across multiple agent runs
  • Isolates the agent's actions from the host system
  • Supports snapshots for state preservation
Why Sandboxes Matter
  1. Safety - Agents can't accidentally damage your system
01_AGENT_SYSTEM.md
02_RUNNER_SYSTEM.md
03_TOOL_SYSTEM.md
04_ITEMS_SYSTEM.md
05_GUARDRAILS.md
06_HANDOFFS.md
07_MEMORY_SESSIONS.md
08_MODEL_PROVIDERS.md
09_SANDBOX_SYSTEM.md
10_TRACING.md
11_RUN_STATE.md
12_CONTEXT.md
13_LIFECYCLE_HOOKS.md
14_CONFIGURATION.md
15_ERROR_HANDLING.md
16_STREAMING.md
17_EXTENSIONS.md
18_MCP_INTEGRATION.md
19_BEST_PRACTICES.md
20_ARCHITECTURE_PATTERNS.md
  • Statefulness - Work persists across runs
  • Real Work - Agents can actually perform tasks (edit files, run code, etc.)
  • Isolation - Multiple agents can work independently
  • Reproducibility - Snapshots enable reproducible environments
  • Long-Running Tasks - Support for extended work sessions
    • Sandbox Types

    The SDK supports several sandbox implementations:

    1. UnixLocalSandboxClient - Local Unix-based sandbox
    2. DockerSandboxClient - Docker container sandbox
    3. E2BSandboxClient - E2B cloud sandbox
    4. ModalSandboxClient - Modal cloud sandbox
    5. RunloopSandboxClient - Runloop cloud sandbox
    6. DaytonaSandboxClient - Daytona cloud sandbox
    7. VercelSandboxClient - Vercel cloud sandbox
    8. Custom Clients - Implement your own sandbox client

    SandboxAgent

    SandboxAgent Class

    SandboxAgent is a specialized agent designed for sandbox environments:

    Python

    Key Differences from Regular Agent:

    • Manifest - Defines what files/resources are available
    • Sandbox-aware - Knows it's running in a sandbox
    • Workspace focus - Designed for file/workspace operations
    • State persistence - Maintains sandbox state across runs
    Manifest

    The manifest defines the sandbox workspace:

    Python

    Manifest Entry Types:

    • GitRepo - Clone a Git repository
    • LocalFile - Copy a local file
    • LocalDir - Copy a local directory
    • RemoteFile - Download a remote file
    • RemoteDir - Download a remote directory
    • InlineFile - Create a file from inline content
    SandboxRunConfig

    Configuration for sandbox execution:

    Python

    Unix Local Sandbox

    UnixLocalSandboxClient

    Local Unix-based sandbox for development:

    Python

    How it works:

    • Creates a temporary directory on your local filesystem
    • Provides shell access via subprocess
    • Isolates via chroot (if supported)
    • Good for development and testing

    Limitations:

    • Not truly isolated (on same machine)
    • Requires Unix-like system
    • May require sudo for full isolation
    Unix Local Sandbox Options
    Python

    Docker Sandbox

    DockerSandboxClient

    Docker container-based sandbox:

    Python

    Benefits:

    • True isolation via containers
    • Reproducible environments
    • Can use any Docker image
    • Network isolation

    Requirements:

    • Docker installed and running
    • Sufficient disk space
    Docker Sandbox Options
    Python

    Cloud Sandboxes

    E2B Sandbox

    E2B cloud-based sandbox:

    Python

    Benefits:

    • Cloud-hosted (no local resources)
    • Scalable
    • Pre-configured environments
    • Good for production
    Modal Sandbox

    Modal cloud-based sandbox:

    Python
    Runloop Sandbox

    Runloop cloud-based sandbox:

    Python
    Daytona Sandbox

    Daytona cloud-based sandbox:

    Python
    Vercel Sandbox

    Vercel cloud-based sandbox:

    Python

    Sandbox Entries

    GitRepo Entry

    Clone a Git repository:

    Python
    LocalFile Entry

    Copy a local file:

    Python
    LocalDir Entry

    Copy a local directory:

    Python
    InlineFile Entry

    Create a file from inline content:

    Python
    RemoteFile Entry

    Download a remote file:

    Python

    Sandbox Capabilities

    Capability System

    Sandbox capabilities define what operations are allowed:

    Python
    Built-in Capabilities

    The SDK includes several built-in capabilities:

    • ExecCapability - Execute commands
    • ReadCapability - Read files
    • WriteCapability - Write files
    • NetworkCapability - Network access
    • BrowserCapability - Browser automation
    Capability Configuration
    Python

    Sandbox Session Management

    Sandbox Session

    Sandbox sessions maintain state across runs:

    Python
    Session State

    Sandbox sessions can be resumed:

    Python

    Sandbox Snapshots

    Creating Snapshots

    Snapshots capture sandbox state:

    Python
    Using Snapshots

    Restore sandbox from a snapshot:

    Python
    Snapshot Benefits
    • Reproducibility - Exact environment reproduction
    • State Sharing - Share sandbox state across runs
    • Rollback - Return to previous state
    • Testing - Test against known states

    Sandbox Memory

    Memory Rollouts

    Sandbox memory can be rolled out:

    Python
    Memory Types

    Sandbox supports different memory types:

    • File-based memory - Store in files
    • Database memory - Store in database
    • Custom memory - Implement your own

    Sandbox Execution

    Executing Commands

    Agents can execute commands in the sandbox:

    Python
    Reading Files

    Agents can read files in the sandbox:

    Python
    Writing Files

    Agents can write files in the sandbox:

    Python

    Sandbox Errors

    Error Types

    Sandbox operations can raise specific errors:

    Python
    Error Handling

    Handle sandbox errors gracefully:

    Python

    Sandbox Best Practices

    1. Use Appropriate Sandboxes

    Choose the right sandbox for your use case:

    Python
    2. Manage Manifest Size

    Keep manifests efficient:

    Python
    3. Set Timeouts

    Prevent hanging operations:

    Python
    4. Use Snapshots for Reproducibility

    Use snapshots for testing:

    Python
    5. Clean Up Sessions

    Always clean up sessions:

    Python

    Common Sandbox Patterns

    1. Code Repository Analysis

    Analyze a codebase:

    Python
    2. Data Processing Pipeline

    Process data in sandbox:

    Python
    3. Testing Environment

    Run tests in isolated environment:

    Python
    4. Build Process

    Build projects in sandbox:

    Python
    5. Documentation Generation

    Generate documentation:

    Python

    Sandbox and Tracing

    Sandbox Tracing

    Sandbox operations are traced:

    Python
    Sandbox Span Data

    Sandbox operations create spans:

    Python

    Summary

    The Sandbox system provides isolated execution environments. Key takeaways:

    1. SandboxAgent is designed for sandbox environments
    2. Manifest defines the sandbox workspace
    3. SandboxRunConfig configures sandbox execution
    4. UnixLocalSandboxClient provides local Unix sandbox
    5. DockerSandboxClient provides container isolation
    6. Cloud sandboxes (E2B, Modal, etc.) provide cloud hosting
    7. Entries define what's in the sandbox (GitRepo, LocalFile, etc.)
    8. Capabilities control what operations are allowed
    9. Sessions maintain state across runs
    10. Snapshots enable reproducible environments
    11. Memory rollouts provide memory capabilities
    12. Command execution via sandbox tools
    13. File operations (read/write) in sandbox
    14. Error handling for sandbox failures
    15. Timeouts prevent hanging operations
    16. Cleanup prevents resource leaks
    17. Tracing includes sandbox operations
    18. Isolation protects the host system
    19. Statefulness enables long-running tasks
    20. Reproducibility via snapshots

    Sandboxes are essential for agents that need to perform real work with files and commands in a safe, isolated environment.