OpenAI Agents SDK in Practice: Harness and Sandbox Separation Architecture Explained

Model Capabilities Leap Forward, Giving Rise to a New Generation of Agent Frameworks

In the latest Build Hours session, OpenAI API team engineer Steve and Agents product manager Nish provided an in-depth walkthrough of major updates to the Agents SDK. The core message is crystal clear: models are becoming increasingly capable of autonomous work over extended periods, and the Agents SDK's goal is to make it easy for developers to build, deploy, and manage these long-running agents.

The "agent" referred to here is an AI system capable of perceiving its environment, making autonomous decisions, and executing actions. Unlike traditional single-turn Q&A, agents possess the ability to run continuously, invoke tools, and perform multi-step reasoning, enabling them to autonomously plan and execute complex tasks. Over the past two years, as large language model reasoning capabilities have advanced rapidly, agents have moved from academic concepts to engineering practice, becoming one of the core paradigms of AI applications.

Steve mentioned that OpenAI's internal Codex tool can already run continuously for days or even a week. Codex is OpenAI's cloud-based software engineering agent that can autonomously read code, write code, and run tests in an isolated sandbox environment—essentially a "tireless programmer." Security scanning agents built on Codex can automatically detect vulnerabilities in codebases, while data analysis agents can directly connect to data lakes to answer complex queries—work that previously required an hour of writing SQL now needs just a single prompt. A Data Lake is an architecture for centralized storage of massive raw data, supporting unified storage and analysis of structured, semi-structured, and unstructured data, and is a core component of modern enterprise data infrastructure.

However, building production-grade agents in your own systems remains challenging. How do you balance performance with flexibility? How do you manage sandbox container lifecycles and state? How do you make the framework sufficiently customizable? The latest Agents SDK updates are designed to address exactly these pain points.

Agents SDK Architecture Revolution: Harness and Compute Separation

The most critical architectural decision in this update is the complete separation of Harness (orchestration layer) from Compute (compute sandbox).

In the traditional model, the agent's loop logic and file operations run in the same container—like Codex running on your laptop. A "container" here refers to a lightweight virtualized environment based on technologies like Docker, which packages an application and its dependencies in an isolated runtime to ensure environment consistency and resource isolation. Container technology has become the cornerstone of modern cloud-native architecture, but its "ephemeral" nature (containers can be reclaimed or restarted by the scheduling system at any time) also poses challenges for agents that require persistent state.

This works fine during local development, but deploying to production creates serious problems:

• The sandbox becomes load-bearing: Once a container crashes or expires, all state is lost
• Secret management is difficult: Storing secrets in the sandbox exposes them to prompt injection attacks and data leaks. Prompt Injection is a class of security attacks against large language models where attackers embed malicious instructions in input to trick the model into performing unintended operations—such as leaking API keys from system prompts or bypassing security restrictions. When secrets are stored in a sandbox accessible to the agent, the damage from such attacks is significantly amplified.
• State recovery is complex: You need to implement your own snapshot and rebuild mechanisms

After separation, the sandbox becomes a completely ephemeral resource that can be destroyed and rebuilt at any time. The Harness runs on your existing infrastructure (such as Temporal tasks, AWS, etc.), handling state management, snapshots, and recovery. Temporal is an open-source distributed workflow engine specifically designed for orchestrating long-running tasks that require fault tolerance and state persistence. Through its event sourcing mechanism, it automatically records the execution state of each step, enabling recovery from breakpoints even after process crashes—making it ideal as the underlying infrastructure for agent orchestration layers. The Agents SDK handles all of this automatically.

Codex-Style Harness: Core Capabilities Out of the Box

The Agents SDK introduces a Codex-style Harness, bringing battle-tested tools and patterns from Codex into general-purpose agent development. Here's a detailed breakdown of several core capabilities.

Auto-compaction

When conversation context exceeds the window limit, the model can automatically compress the context and continue working. This means agents can theoretically run indefinitely—hours, days, or even weeks—no longer constrained by hard context length limits.

The Context Window is one of the core limitations of large language models, defining the maximum text length the model can "see" in a single inference. Even the most advanced models (like GPT-4o's 128K token window) quickly exhaust context space when facing tasks spanning multiple days. Auto-compaction technology intelligently summarizes and distills key information from earlier conversations into shorter representations, preserving maximum information within a limited window. This is similar to human "working memory"—we don't remember the exact wording of every conversation, but we retain key conclusions and decision rationale.

Asynchronous Shell Interaction

The model can write shell commands and wait for execution results. If a command hasn't completed, it can go do other things and come back to check later. The SDK tracks the state of all running commands, ensuring no asynchronous tasks are missed.

File System Operations

This includes viewing images, using the apply patch tool for inline file editing, and other capabilities that let agents work in codebases just like human developers.

Skills System

A skill is a packaged set of files containing a skill.md main file and related script resources. Steve gave an example of a tax preparation skill: containing all IRS rules, document processing scripts, and form-filling logic.

The design philosophy of the skills system draws from the "reusable components" concept in software engineering. In traditional agent development, domain knowledge is typically hard-coded as lengthy system prompts, making it difficult to maintain and reuse. The skills system encapsulates domain knowledge, operational procedures, and tool scripts into independent, versionable modules—similar to "libraries" or "packages" in programming. This modular design enables teams to independently develop, test, and iterate on individual skills, then combine them into different agents like LEGO blocks, dramatically improving development efficiency and the rigor of knowledge management.

The new Skills API supports uploading, version management, and default version settings. GitHub is also an excellent choice for storing skills—with native support for version control and PR review workflows.

Sandbox Environments: First-Class Multi-Platform Support

The Agents SDK provides first-class support for multiple sandbox platforms, allowing developers to choose flexibly based on their scenarios:

• Docker: The go-to choice for local development and testing
• Modal: An excellent choice for cloud deployment
• Cloudflare, E2B, Vercel, Daytona, Bloxel and other third-party platforms

Switching sandbox backends is straightforward—just swap out the Client and Options definitions. For example, switching from Docker to Modal only requires replacing DockerSandboxClient with ModalSandboxClient.

State Snapshots and Recovery

When a task is paused, the Agents SDK automatically performs the following steps:

1. Stops the sandbox container
2. Takes a file system snapshot (tarball by default)
3. Stores it at your specified location (local disk, R2, S3, etc.)

During recovery, the SDK retrieves the snapshot, starts a new container, and rebuilds the file system. The model has no idea it's running in a new container, achieving seamless recovery.

The snapshot mechanism here draws from mature practices in operating systems and virtualization. Tarball is the standard format in Unix/Linux systems for packaging multiple files into a single archive (.tar or .tar.gz), preserving complete directory structure and file permission information. In container orchestration scenarios, this "freeze-restore" pattern (similar to a laptop's hibernation feature) enables on-demand resource allocation: when agents aren't working, expensive GPU/CPU resources are released; when needed, the complete working environment is rebuilt in milliseconds. This is critical for cost control and large-scale deployment.

State management consists of two parts: file system snapshots and conversation message history (rollout), both stored in JSON format and compatible with any database.

Hands-On Demo: Building an Intelligent Task Tracker

Steve demonstrated the complete development workflow through a meeting planning task tracker. Here are the key steps.

Defining a Sandbox Agent

SandboxAgent is a subclass of Agent, retaining all original parameters while adding sandbox-related configuration. The definition is very intuitive:

# Specify sandbox client and options
client = DockerSandboxClient(image="python:3.12")
# Or switch to cloud
client = ModalSandboxClient(image="python:3.12")

Manifest: Declarative File System

The Manifest defines the file system structure when the agent starts up. It supports multiple data sources:

• Local file copying
• S3/R2 bucket mounting
• GitHub repositories
• Azure Blob Storage

Declarative Configuration is a core paradigm in modern infrastructure management, with the philosophy of "describe what you want, not how to achieve it." Developers only need to declare in the Manifest what files and resources the agent needs, and the SDK handles the specifics of fetching, mounting, and synchronization. This is consistent with Kubernetes Pod Specs and Terraform's HCL configuration, reducing cognitive load on developers while making configurations auditable, versionable, and reproducible.

Mounting external storage is particularly suitable for two scenarios: massive files (hundreds of PDFs) and real-time data (frequently updated data sources). Mounting is faster to start but has network latency for reads; copying is faster to read but slower to start.

Custom Tools and Approval Mechanisms

Python functions can be easily registered as agent tools using the @function_tool decorator:

Tools also support approval mechanisms—for example, marking a task as "complete" requires human confirmation, preventing agents from closing tasks on their own. This is consistent with the "allow this command to run?" interaction pattern in Codex.

Multi-Agent Collaboration

The demo showcased collaboration between two agents: after a program editing agent completes content optimization, it automatically hands off the task to an asset production agent. This is implemented through the Agents SDK's handoff mechanism, providing a clear collaboration paradigm for building complex workflows.

Multi-Agent Systems (MAS) are a classic research direction in distributed artificial intelligence, with the core idea of solving complex problems that are difficult for a single agent through collaboration among multiple specialized agents. In engineering practice, this "division of labor" pattern is similar to microservices architecture—each agent focuses on a specific domain (such as code review, document generation, test verification), passing tasks through explicit communication protocols (like handoff). Compared to a single "omnipotent" agent, multi-agent architectures offer better maintainability, scalability, and fault tolerance, because the failure of a single agent doesn't bring down the entire system.

New Capabilities at the API Level

Beyond the SDK updates, the Responses API has also added several noteworthy features.

Hosted Shell Tool

Use lightweight sandboxes directly in the Responses API: upload files, the model executes code in a container, and returns results. Supports automatic mode (automatically creates and destroys containers) and manual mode, accommodating different levels of control granularity.

Network Access Control

You can configure domain whitelists for containers, or completely block network ingress/egress, enhancing sandbox security at the network layer.

TypeScript Support

After the Python version was released in April, the TypeScript version is now available, meeting strong demand from the frontend and full-stack developer community.

Selection Guide: Agents SDK vs Responses API

Based on Steve and Nish's recommendations, the two have clearly distinct use cases:

• Agents SDK: Suited for complex agent scenarios requiring long-running execution, file operations, and multi-step workflows. The Codex Harness is becoming increasingly coupled with OpenAI models and will provide optimal performance in the future.
• Responses API: Suited for one-off tasks (translation, data structuring), niche programming languages, or scenarios requiring lightweight intelligent loops.

Put simply, if your agent needs to "live in" an environment and work continuously, choose the Agents SDK; if it just needs to "drop in" to complete a single task, the Responses API is more lightweight.

Summary and Outlook

This Agents SDK update marks a key step in agent development moving from "functional" to "user-friendly." The separation of Harness and Compute, out-of-the-box state management, flexible sandbox support, and the skills system dramatically lower the barrier to developing production-grade agents.

Nish also revealed that in the coming weeks to months, more capabilities for the multi-agent framework will be released, making it possible for supervisor agents to coordinate hundreds of specialized agents. Large-scale parallel work will become the default mode for agents.

This vision aligns closely with current industry trends. From Google's A2A (Agent-to-Agent) protocol to Microsoft's AutoGen framework, tech giants are all betting that "agent orchestration" will become the next computing paradigm. The core challenges are: How do you achieve large-scale parallelism while ensuring reliability? How do you design inter-agent communication protocols to prevent "hallucination propagation" (where one agent's erroneous output is treated as fact by others)? How do you implement effective resource scheduling and cost control? The answers to these questions will determine how quickly agents move from "demo-grade" to "enterprise-grade."

For developers, now is the best time to start using the Agents SDK—begin with Docker local development, gradually migrate to cloud sandboxes, and build production-grade agents that can truly work autonomously over extended periods.