OpenAI Agents SDK Sandbox and Harness Guide

Direct answer

OpenAI’s updated Agents SDK gives Python developers a model-native harness for long-running agents that inspect files, run commands, edit code, and use tools inside controlled sandbox environments. The important architectural change is not simply “agents can execute code.” It is the separation of the agent harness from the compute environment: the harness coordinates state, tools, memory, and recovery while a sandbox provides an isolated workspace for model-generated work.

That separation makes the SDK relevant for document analysis, repository maintenance, data-room research, and other workflows where an agent needs more than a chat completion but should not receive unrestricted access to the host system. OpenAI says the release is generally available through the API with standard token-and-tool-use pricing. The new harness and sandbox capabilities launch in Python first; TypeScript support is planned.

Key takeaways

• The SDK adds native sandbox execution for files, commands, dependencies, and outputs.
• A Manifest describes the workspace consistently across sandbox providers and storage systems.
• The harness includes configurable memory, filesystem tools, MCP, skills, AGENTS.md, shell execution, and patch-based file edits.
• Separating orchestration from compute helps reduce credential exposure and supports snapshotting, rehydration, and parallel sandboxes.
• The release is not a permission system by itself. Developers still need least-privilege credentials, network controls, approval gates, logging, and prompt-injection defenses.

What OpenAI changed in the Agents SDK

The April 15, 2026 announcement describes an updated Agents SDK built around two connected capabilities: a more capable harness and native sandbox execution. The harness is the control layer around the model. It coordinates the agent loop, workspace conventions, tools, memory, and long-running execution. The sandbox is the controlled environment where the agent can read inputs, run commands, install or use dependencies, and write outputs.

This is a different emphasis from a minimal function-calling demo. A function tool can invoke a carefully bounded operation, but many useful engineering agents need to inspect a directory, compare several files, run a test, apply a patch, and continue after an intermediate failure. Treating that sequence as a first-class runtime problem is the practical value of the update.

The official announcement names several primitives that can participate in the harness:

• MCP for tool and data integrations.
• Skills for progressive disclosure of specialized instructions.
• AGENTS.md for repository or workspace guidance.
• Shell execution for code and command-line work.
• apply_patch-style edits for controlled file changes.
• Configurable memory and sandbox-aware orchestration.

The release also introduces a Manifest abstraction. Instead of hard-coding one provider’s workspace API, an application can describe mounted inputs, output directories, and other workspace entries in a portable form. OpenAI lists support for providers including Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, and Vercel, as well as storage systems such as Amazon S3, Google Cloud Storage, Azure Blob Storage, and Cloudflare R2.

Architecture: harness outside, compute inside

The central design can be represented as a control plane and an execution plane:

The model should not be treated as the security boundary. The harness should decide what tools are available, what files are mounted, which actions require approval, and where outputs may go. The sandbox then limits the blast radius if generated code behaves incorrectly or an untrusted instruction attempts to redirect the task.

This architecture also explains why harness and compute separation matters operationally. If a sandbox expires or fails, externalized state can allow the run to resume in a fresh environment. If several independent tasks are safe to parallelize, the harness can route them to separate sandboxes rather than giving one process broad access to every dataset.

A verified Python starting point

The official example uses the Python package and the sandbox interfaces exposed by the SDK. The following pattern follows that example’s structure while keeping the task intentionally narrow: mount a temporary data room and ask the agent to compare known files.

Install the SDK first with pip install "openai-agents>=0.14.0".

1import asyncio
2import tempfile
3from pathlib import Path
4
5from agents import Runner
6from agents.run import RunConfig
7from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
8from agents.sandbox.entries import LocalDir
9from agents.sandbox.sandboxes import UnixLocalSandboxClient
10
11
12async def main() -> None:
13    with tempfile.TemporaryDirectory() as tmp:
14        data_room = Path(tmp) / "data"
15        data_room.mkdir()
16        (data_room / "metrics.md").write_text(
17            "FY2025 revenue: $124.3M\nFY2024 revenue: $98.7M\n",
18            encoding="utf-8",
19        )
20
21        agent = SandboxAgent(
22            name="Dataroom analyst",
23            model="gpt-5.4",
24            instructions=(
25                "Use only files mounted under data/. "
26                "Cite the source filename in your answer."
27            ),
28            default_manifest=Manifest(
29                entries={"data": LocalDir(src=data_room)}
30            ),
31        )
32
33        result = await Runner.run(
34            agent,
35            "Compare FY2025 and FY2024 revenue.",
36            run_config=RunConfig(
37                sandbox=SandboxRunConfig(
38                    client=UnixLocalSandboxClient()
39                )
40            ),
41        )
42        print(result.final_output)
43
44
45if __name__ == "__main__":
46    asyncio.run(main())

This example is useful because it makes the workspace contract explicit. The agent is told where evidence lives, the manifest mounts only the required directory, and the prompt requires a source filename. In production, replace the local client with a provider-backed sandbox, pin compatible package versions, and add tests around mounts, outputs, timeouts, and failure recovery before allowing the agent to modify real repositories.

Security model and production controls

Sandboxing reduces risk; it does not make arbitrary agent execution safe by default. OpenAI’s announcement explicitly recommends designing agent systems with prompt-injection and exfiltration attempts in mind. The practical controls should sit around the SDK:

Keep credentials out of generated execution

Do not place long-lived cloud keys, production database passwords, or broad Git tokens in the workspace. Prefer short-lived credentials issued by the harness or a broker, scoped to one task and one destination. If the agent only needs to read a bucket prefix, do not grant account-wide object access.

Separate read, write, and publish permissions

A research agent may need read access to source files but no write access. A coding agent may write to a temporary branch but require human approval before merging. A publishing agent should not be able to alter application infrastructure. Model these as separate tools and roles instead of relying on natural-language instructions.

Restrict network egress

A sandbox with unrestricted outbound networking can turn a prompt injection into data exfiltration. Use an allowlist or an egress proxy, log requests, and make external fetches explicit. MCP servers deserve the same scrutiny as any other integration: validate inputs, authenticate connections, and avoid exposing internal metadata through tool results.

For broader threat-modeling patterns, see this MCP tool-server threat-modeling guide and the StepSecurity Dev Machine Guard guide.

Treat files as untrusted instructions

A repository’s AGENTS.md, README, issue, or downloaded document can contain instructions that conflict with the task. The harness should distinguish policy from content and require approval for sensitive actions. Give the model a clear evidence boundary, just as the example limits analysis to data/.

Record tool calls and state transitions

Long-running agents are difficult to debug from final answers alone. Capture model requests, tool arguments, command exit codes, file diffs, sandbox identity, approvals, and checkpoint events. Redact secrets before storing traces. If your team already uses a harness-oriented workflow, the harness engineering guide for AI coding agents provides useful context for this separation of concerns.

When this architecture is a good fit

The updated SDK is a strong fit when a workflow has all or most of these properties:

It is less suitable for a simple FAQ bot, a deterministic ETL job, or a latency-critical request that does not need file or command execution. A sandbox adds startup, orchestration, observability, and security-management costs. Do not adopt it merely because “agent” is on the roadmap.

Common implementation mistakes

Assuming the sandbox replaces authorization

It does not. A sandbox boundary does not decide whether a user is allowed to export a customer record or deploy a change. Keep authorization in the application and expose only approved capabilities to the agent.

Mounting too much data

A convenient project-root mount can silently include secrets, build artifacts, customer data, or unrelated repositories. Build manifests from an allowlist and test the resulting directory tree in CI.

Letting tool output become unlimited context

Large logs and repository scans can increase cost and reduce accuracy. Use progressive disclosure, bounded output, summaries with source references, and explicit file-selection tools. Tool search and skills are useful only when their boundaries are clear.

Treating retries as harmless

A retry may repeat a write, payment, deployment, or external API call. Add idempotency keys, action receipts, and approval checkpoints. Distinguish retryable infrastructure failures from a tool action that already succeeded.

Skipping failure recovery tests

Terminate the sandbox during a long task. Verify that the harness can identify the last durable checkpoint, recreate the environment, and continue without duplicating side effects. Recovery is a design requirement, not a happy-path feature.

Cost, latency, and operational trade-offs

OpenAI says these capabilities use standard API pricing based on tokens and tool use, but the total cost is broader than model tokens. Budget for sandbox startup, storage, network transfer, tracing, retries, snapshots, and human review. A task that reads a few files may be cheaper with a direct tool call; a task that needs repeated inspection and testing may justify a persistent or resumable environment.

Latency also changes shape. A local sandbox can start quickly, while a remote provider may add provisioning time. Parallel sandboxes can reduce wall-clock time for independent work but increase peak spend and coordination complexity. Measure time to first useful tool call, total runtime, failed-run recovery time, and cost per completed task—not just model latency.

FAQ

Is the updated Agents SDK available in TypeScript?

The announced harness and sandbox capabilities launch first in Python. OpenAI says TypeScript support is planned for a future release, so TypeScript teams should avoid assuming parity until the relevant SDK and documentation are available.

Can I use my own sandbox provider?

Yes. OpenAI describes built-in support for several providers and says developers can bring their own sandbox. The manifest abstraction is intended to make workspace definitions portable, but provider-specific limits, networking, persistence, and pricing still need validation.

Does this prevent prompt injection?

No. It can reduce the consequences by isolating compute and limiting mounts, credentials, tools, and network access. Prompt-injection defense still requires an explicit trust model, untrusted-content handling, approvals, monitoring, and testing.

Should every coding agent run in a sandbox?

Any agent that executes generated code, handles sensitive files, or makes multi-step system changes should have an isolation strategy. A sandbox is one part of that strategy. For a read-only assistant, simpler constrained tools may be more efficient.

Conclusion

The updated OpenAI Agents SDK is best understood as a runtime architecture for serious agent workflows, not just another model wrapper. Its model-native harness coordinates the loop while sandbox compute contains files, commands, dependencies, and outputs. The Manifest abstraction offers a useful portability layer, and snapshotting plus rehydration address a real weakness of long-running agents: the execution environment can fail without necessarily losing the work state.

The safest adoption path is incremental. Start with a read-only task and a tiny manifest, log every tool call, add egress and credential controls, test interruption and recovery, and only then grant narrowly scoped write capabilities. Teams that make those boundaries explicit will get more value from agent execution without confusing an SDK feature with a complete security architecture.

Sources and visual credits

• OpenAI: The next evolution of the Agents SDK — primary announcement and official example.
• OpenAI Agents SDK documentation — official developer documentation.
• TechCrunch: OpenAI updates its Agents SDK — independent reporting and interview context.
• Help Net Security: OpenAI updates Agents SDK — independent security-focused reporting.
• The Mermaid architecture diagram is original and created for this article; no external image is used.

Visual: Security control path

This original threat-to-control diagram turns the security guidance in this article into a concrete sequence of gates.

Visual reading: security is layered. Blocking unsafe actions before execution is important, but allowed actions still need sandboxing, logging, and output validation.