OpenAI’s Evolving Agents SDK: Why Agent Workspaces, Sandboxes, and Durable State Matter

An agent that only works until the container restarts is not an agent. It is a demo with a heartbeat.

The Demo-to-Runtime Gap

The first version of any agent looks impressive. You wire a model to a few tools, give it a system prompt, and watch it summarize documents or write code. Then you hand it a real task: clone a repository, run the test suite, apply a patch, generate a report, and leave the artifacts somewhere a human can review them.

The agent stalls. Not because the model is weak, but because the task needs something the prompt cannot provide: a filesystem, a shell, installed dependencies, and a place to put output. Prompt context is not a workspace. It is a description of a workspace, and descriptions do not compile.

Three failure symptoms show up when the runtime underneath the agent loop is incomplete:

• Lost run state. The container dies, the process restarts, and the agent has no memory of what it was doing. The conversation history may survive in a database, but the half-finished file edit does not.
• Credential exposure. Model-generated code runs in the same environment as your API keys. One prompt-injection attempt and the keys are gone.
• No resumable filesystem. The agent writes a file, the session ends, and the next run starts from scratch. Long-horizon work becomes a sequence of unrelated short-horizon attempts.

These are not model problems. They are runtime problems, and they persist regardless of how good the underlying model becomes.

The OpenAI Agents SDK's recent direction—native sandbox execution, workspace manifests, and resumable sessions—is best understood as an attempt to close this gap. But the SDK name is not the point. The point is whether any given agent runtime provides three things: a declared workspace, a real isolation boundary, and durable state. I use those three axes to evaluate agent runtimes because they survive rebranding, version bumps, and vendor marketing.

Harness vs. Compute: The Boundary That Defines Everything

Every agent system has two planes, whether or not the documentation names them.

The harness is the control plane. It owns the agent loop, model calls, tool routing, handoffs, approvals, tracing, recovery, and run state. When you read about "agent orchestration," you are reading about the harness.

Compute is the execution plane. It owns the filesystem, shell, installed packages, mounted data, exposed ports, and snapshots. When the model decides to run pytest or write a file, that work happens in compute.

The boundary between these two planes is the single most consequential architectural decision in an agent system. Draw it in the wrong place and you get three problems at once: credentials leak into untrusted execution, state dies with the container, and scaling means duplicating the entire agent rather than adding execution capacity.

OpenAI's own framing puts it directly: separating harness from compute keeps credentials out of environments where model-generated code executes, enables durable execution because externalized state survives container loss, and makes agents more scalable because runs can use one sandbox or many. Those are not three separate features. They are three consequences of one boundary decision.

The observable test is simple. Kill the container mid-task. If the run survives—if the harness can rehydrate state in a fresh container and continue from the last checkpoint—the boundary is clean. If the run dies with the container, the boundary is not clean, no matter what the SDK documentation claims.

The harness/compute split is a conceptual model, not a specific API. Exact surfaces, defaults, and supported capabilities are version-dependent, and sandbox agents are currently in beta. Treat the boundary as a design principle, not a guarantee about any particular release.

Workspace Contracts: Manifests, Files, and What Starts the Run

A workspace is not "wherever the agent happens to run." It is a declared contract about what exists before the agent takes its first action.

In the Agents SDK, that contract is a manifest. The manifest owns files, directories, repositories, mounts, environment variables, users and groups, and output locations. It answers a question that most agent frameworks leave implicit: what is the starting state?

That question is a security decision and a reproducibility decision, not a setup convenience. If the agent silently depends on host state the manifest never declared—a cached credential, a pre-installed package, a file in the home directory—then the run is not reproducible and the isolation boundary is fictional.

The SDK's own documentation draws a useful line here. If shell access is only an occasional tool, start with a hosted shell tool. Use sandbox agents when workspace isolation, sandbox provider choice, or resumable filesystem state is part of the product design. That distinction matters because it prevents the common failure of reaching for a full sandbox when a single shell call would do.

The pieces fit together like this:

The failure mode to watch for: an agent that works in development because the developer's machine happens to have the right files, and fails in production because the manifest never declared them. If you cannot reconstruct the workspace from the manifest alone, the manifest is incomplete.

Two Sandbox Integration Patterns and Their Tradeoffs

There are two ways to connect an agent to a sandbox, and the choice determines your iteration speed, your secret exposure, and your state model.

Pattern 1: Agent inside the sandbox. The agent process runs in the same container as the execution environment. It has direct filesystem access and can modify its own environment. This mirrors local development closely—if you run the agent in your terminal, you run the same command in the sandbox. The cost is a communication layer across the boundary: WebSocket or HTTP, session management, error handling. If your provider does not handle that layer, you build it.

Pattern 2: Sandbox as a tool. The agent runs in trusted infrastructure and calls the sandbox remotely for execution. Agent code updates instantly without rebuilding container images. API keys stay outside the sandbox. Agent state—conversation history, reasoning chains, memory—lives where the agent runs, separate from the execution environment. You pay for sandboxes only when executing code, and you can run tasks in multiple remote sandboxes in parallel.

The decision boundary is not subtle. Choose Pattern 1 when the agent and execution environment are tightly coupled—when the agent needs persistent access to specific libraries or complex environment state, and when production should mirror local development. Choose Pattern 2 when you need fast iteration on agent logic, when secret isolation is non-negotiable, or when you want to parallelize across remote sandboxes.

Provider abstraction sits on top of both patterns. The Agents SDK supports bring-your-own-sandbox and built-in integrations with providers including Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, and Vercel. Switching backends should not change agent logic. If it does, the abstraction is leaking.

These are architecture patterns, not a single API. The same harness can route, pause, resume, and trace the workflow while each sandbox keeps execution close to the files, tools, and ports it needs.

Durable State: Snapshots, Rehydration, and Resume Semantics

"We save conversation history" is not durability. Durability means the run survives infrastructure failure.

The mechanism is snapshot and rehydration. The harness checkpoints agent state, and when the original environment fails or expires, it restores that state in a fresh container and continues from the last checkpoint. For this to be meaningful, four things must be externalized:

1. Run state — where the agent is in its task, what it has decided, what remains.
2. Tool results — the outputs of commands and file operations the agent has already executed.
3. Workspace filesystem — the files the agent has created or modified.
4. Pending approvals — any human-in-the-loop gates that have not yet been resolved.

Miss any one of these and resume becomes a partial reconstruction that may silently diverge from the original run.

It helps to separate three recovery semantics that are often conflated:

• Retry re-executes a failed step. It assumes the step is idempotent. If the step charged a credit card, retry charges it twice.
• Replay re-executes from the beginning, reproducing the original sequence. It assumes determinism. Model calls are not deterministic.
• Resume continues from the last checkpoint. It assumes the checkpoint captured enough state to reconstruct the run's position and pending work.

Resume is the strongest guarantee and the hardest to implement correctly. The failure path is worth walking through explicitly. A container expires mid-task. The harness preserves run state, tool results, and pending approvals. The workspace filesystem is restored from the last snapshot. What the harness must reconstruct is everything between the last checkpoint and the moment of failure—and if the agent executed a side-effecting tool in that window, the reconstruction may duplicate or lose that effect.

Checkpoint granularity and idempotency of side-effecting tools are where durability claims get tested. A system that checkpoints after every tool call has different correctness properties than one that checkpoints every thirty seconds. Neither is universally right, but the difference matters when money, external APIs, or irreversible operations are involved.

Security and Isolation Boundaries

Design agent systems assuming prompt-injection and exfiltration attempts. That is not paranoia; it is the correct default when model-generated code executes in an environment that touches real systems.

The harness/compute split is the first line of defense. Credentials live in the harness. Model-directed code executes in compute. The model cannot leak what it cannot reach.

But a sandbox boundary is not a force field. It contains filesystem isolation, network policy, and resource limits. It does not automatically contain mounted data or exposed ports. Mount a data room and the agent can read everything in it. Expose a port and the blast radius widens beyond the intended task.

Policy enforcement belongs at the tool gateway, before commands or file edits execute. The gateway is where you decide whether a given shell command, file write, or network call is allowed—not after the fact in a log.

The decision rule I use: if the agent only needs occasional shell access, a hosted shell tool is the smaller, safer surface. Reach for a full sandbox session when isolation or resumable filesystem state is part of the product design, not when it is a convenience.

Evaluating Runtime Completeness Without the Brand

The three axes generalize. They work on the OpenAI Agents SDK, on plugin-oriented harnesses, on protocol-server architectures, and on agent-to-agent delegation systems. Feature lists do not generalize; these do.

Axis 1 — Workspace. Is the starting state declared, reproducible, and inspectable? Can you reconstruct the workspace from the manifest alone? If not, the workspace is implicit and the run is not reproducible.

Axis 2 — Isolation. Where does model-directed code execute, and what can it reach? Are credentials outside that boundary? What does the sandbox contain, and what does it merely appear to contain?

Axis 3 — Durability. What survives container death, and what are the resume semantics? Is the recovery model retry, replay, or resume? What happens to side-effecting tools that executed between checkpoints?

Apply these axes to any agent runtime and you get a comparable answer. A plugin-oriented harness, a protocol-server architecture, and a CLI-plus-skills system will each answer them differently—but the axes stay constant.

The honest limits: sandbox agents are in beta. API details, defaults, and supported capabilities may change. Provider-specific behavior varies. Any evaluation is a snapshot, not a permanent verdict. The axes outlast the snapshot.

What to Do Next

Pick one long-running agent task—something that touches files, runs commands, and takes more than a few minutes. Write down three things before you run it:

1. Its workspace contract: what files, mounts, and environment must exist before the first action.
2. Its isolation boundary: where model-directed code executes, and what it can reach.
3. Its resume semantics: what survives container death, and how the harness reconstructs the run.

Then run it and kill the container mid-task. Watch what actually survives. The gap between what you wrote down and what you observed is the real state of your runtime, independent of any SDK's branding.

Once durability is real—once the run genuinely survives infrastructure failure—the next question is what the agent can safely modify about its own harness. That is a harder problem, and it only becomes worth asking after the substrate underneath it holds.