OpenAI Agents API: A Session Is Not Its Sandbox

The production verdict

Do not wire agent.session.created to “start a VM” and agent.session.idle to “stop the VM.” That shortcut confuses events with authority.

For a self-hosted Agents API environment, put one application-owned lifecycle controller between signed OpenAI events and the compute provider. It should:

• retrieve current session state before provisioning or stopping anything;
• keep exactly one session-to-environment-to-compute mapping;
• start or reconnect compute only for a current environment_connection requirement;
• treat idle as a hint, never a shutdown command;
• reconcile tool effects and saved state after a disconnect or timeout;
• close the Agents API session and provider compute as separate operations.

This is not a generic reaction to the Agents API launch. The useful new boundary is in the current lifecycle documentation. OpenAI manages the Codex harness and durable session. Your application still owns self-hosted compute, executor connectivity, files and cleanup.

One agent run now has three state owners

The Agents API architecture separates the managed harness, the optional execution environment and the application server. With environment.type: "self_hosted", the application provisions compute and connects an executor to the environment assigned to the session.

Those parts can disagree:

The Agents API overview calls a session durable and says the service retains its state across turns. The sandbox lifecycle guide is equally explicit that a session can outlive its environment. Reusing the environment ID does not restore files in replacement compute.

Treat this as a join, not a mirror. A durable session does not make compute durable. A running VM does not make a turn active. A connected executor does not prove that a tool effect was accepted.

Start from a current requirement, not a historical event

OpenAI documents agent.session.action_required with required_action.type: "environment_connection" as the signal that a self-hosted session needs its executor. That is more precise than starting compute for every created session.

The safe path is deliberately two-stage:

1. Verify the webhook signature and place the event on a durable queue.
2. Let one worker retrieve the session and inspect its current required actions.
3. Ignore deleted sessions and already-resolved connection requests.
4. Acquire a lock on the session-to-compute mapping.
5. Reuse or reconnect the one owned instance when it exists. Create one only when it does not.
6. Record the provider instance ID before releasing the lock.

OpenAI's lifecycle guide says repeated or concurrent requests must not create duplicate environments and recommends one component to manage each session's environment. That makes idempotency a provider-control concern, not only a webhook concern.

Use a stable effect key such as:

agents-api:environment:{environment_id}:compute

The mapping record should retain session_id, environment_id, provider instance ID, executor generation, connection state, workspace snapshot reference and last reconciled event ID. A webhook delivery can repeat. A worker can crash after provider creation and before acknowledgement. The effect key lets the next worker discover and adopt the same compute instead of creating a second billable machine.

Idle is not shutdown authority

The dangerous event is the one with the friendliest name.

The session webhook guide defines agent.session.idle as ready for more input. The lifecycle guide warns that an idle event may arrive when a connection request clears, before waiting input starts its turn. Stopping compute immediately can therefore tear down the environment beneath work that is about to begin.

Use a shutdown lease:

{
  "sessionId": "sess_17",
  "environmentId": "env_17",
  "providerInstanceId": "vm_17",
  "idleObservedAt": "2026-09-30T06:20:00Z",
  "notBefore": "2026-09-30T06:25:00Z",
  "expectedSessionStatus": "idle",
  "expectedExecutorGeneration": 4
}

The five-minute grace period above is an illustrative DVNC pilot setting, not an OpenAI limit. The control is the recheck:

• cancel the pending stop if new input, an active turn or an environment connection request appears;
• retrieve the session again after the grace period;
• confirm no turn or required action is pending;
• stop the exact provider instance and executor generation in the lease;
• record provider read-back that compute is no longer running.

If the application cannot coordinate shutdown with incoming work, OpenAI's guidance is to keep compute running. That costs more than an eager stop, but it is cheaper than corrupting an active workflow while the lifecycle controller is still immature.

A completed turn can still contain a failed tool

A self-hosted executor can disconnect mid-turn. The lifecycle docs say that the turn may still complete while a tool fails, and that the disconnect does not automatically reconnect the executor or restart a killed command.

Do not map turn completed to workflow completed. Reconcile at least four layers:

1. Turn: Did the managed harness reach a terminal state?
2. Tool: Did each intended command or application tool produce a terminal result?
3. Workspace: Are required files present in the current compute or an external snapshot?
4. Business effect: Does the authoritative system show the intended change once?

This matters most when the command crossed a mutable boundary. A deployment call, ticket update or repository write may have succeeded just before the executor disconnected. Blindly asking the agent to repeat “unfinished work” can apply the effect twice.

The Agents API recovery guide says a failed turn may already have changed files or called external tools. It tells operators to inspect saved work and completed effects before retrying. The same rule applies when the client saw a timeout: an absent response is unknown, not failed.

The lifecycle guide adds two sharper constraints. The API can wait up to five minutes for an input-time environment connection, and it does not guarantee recovery of pending input after a process crash. Do not resubmit while the original request is still waiting. After a timeout, retrieve the session, turn and tool items before deciding whether to continue, compensate or hold for an owner.

Cleanup is a two-resource transaction

Deleting an Agents API session removes it from the API, with physical cleanup potentially continuing asynchronously. For a self-hosted environment, OpenAI says deletion neither stops provider compute nor emits a deletion webhook.

That means cleanup needs an application-owned terminal record:

{
  "sessionId": "sess_17",
  "sessionDeleted": true,
  "providerInstanceId": "vm_17",
  "computeStopped": true,
  "executorRevoked": true,
  "workspaceDisposition": "snapshot-retained",
  "effectReconciliation": "observed"
}

Order the operation around your recovery requirements. Stop accepting new input, coordinate with any startup already in progress, reconcile mutable effects, preserve the files or artifacts you need, delete the session, stop compute and revoke the environment credential. If either deletion or provider stop is ambiguous, retain cleanup_required and reconcile instead of issuing the same destructive call in a loop.

Provider read-back is the terminal evidence. A successful stop request is only acceptance by the provider. The controller should observe the instance in a stopped or absent state and record which snapshot, volume or artifact set remains.

The reference controller passes 19 lifecycle cases

I built a dependency-free controller for the release decision and ran 19 synthetic cases. It is reference code, not a test of OpenAI's beta service or a cloud provider.

The controller returns separate statuses for the states teams are tempted to collapse:

The core call is intentionally plain:

import { decideSandboxLifecycle } from "./lifecycle-controller.mjs";

const decision = decideSandboxLifecycle(observed);

if (decision.status === "start_or_reconnect") {
  return ensureOneComputeInstance(observed.environmentId);
}

if (decision.status === "stop_ready") {
  return stopAndReadBack(observed.computeInstances[0]);
}

if (["reconcile", "uncertain", "divergent"].includes(decision.status)) {
  return routeToPlatformOwner(decision);
}

The cases cover duplicate compute, deleted or failed sessions with live compute, environment connection requests, mid-turn disconnect, input timeout, idle before and after a recheck, and an active turn with no compute. Adapt the provider adapter, not the evidence states.

Release gate for a self-hosted environment

Run this gate before moving a real workflow onto self-hosted Agents API compute.

The buyer decision is not whether the Agents API can manage a long-running harness. It can. The decision is whether your platform team is prepared to operate the remaining distributed system around a self-hosted environment. If the answer is no, start with the OpenAI-hosted environment or environment.type: "none", and earn the self-hosted path through lifecycle tests.

Frequently asked questions