openai-agents-js

What's Changed

Sandbox Agents

This release adds Sandbox Agents, a beta SDK surface for running agents with persistent workspaces and sandbox-backed capabilities in JavaScript.

Sandbox agents build on the existing Agent, Runner, and run flow, while adding workspace manifests, sandbox sessions, capabilities, snapshots, memory, and resume support. They let agents inspect files, run commands, edit repositories, apply patches, generate artifacts, and continue work across runs.

Refer to the Sandbox Agents guide and examples/sandbox/ for more details.

Key additions include:

• SandboxAgent, exported from @openai/agents/sandbox, with sandbox defaults such as defaultManifest, baseInstructions, capabilities, and runAs.
• Manifest, a workspace contract for synthetic files and directories, local files and directories, Git repositories, environment, users, groups, permissions, and mounts.
• SandboxRunConfig, which wires sandbox clients, live sessions, serialized session resume, manifest overrides, snapshots, and materialization limits into each run.
• Built-in capabilities for filesystem access, shell access, patching and editing, image inspection, lazy skills, memory, and compaction.
• Sandbox-aware RunState serialization for resuming runner-managed sandbox sessions.

Sandbox Clients and Hosted Providers

Sandbox agents support local, containerized, and hosted execution backends:

• UnixLocalSandboxClient for local development.
• DockerSandboxClient for container isolation and image parity.
• Hosted sandbox clients for Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, and Vercel through @openai/agents-extensions/sandbox/* subpath exports.

Provider-specific examples are available under examples/sandbox/extensions/.

Workspaces, Snapshots, Resume, and Memory

This release adds a workspace model for sandbox sessions, including synthetic files and directories, local files and directories, Git repositories, local bind mounts, Docker volume strategies, and typed remote mounts where supported by the selected backend.

It also adds local and remote snapshot store interfaces for carrying workspace contents across runs, plus runner-managed resume through serialized sandbox session state.

Sandbox memory lets future sandbox-agent runs learn from prior runs by storing extracted lessons in the workspace, injecting concise summaries into later runs, and supporting progressive disclosure through deeper rollout summaries. Memory supports read-only and generate-enabled modes, live updates, automatic generation when sessions are flushed, multi-turn grouping, separate memory layouts, and pluggable MemoryStore implementations.

Examples

A new examples/sandbox/ suite demonstrates:

• Basic SandboxAgent execution with a manifest.
• Unix-local and Docker sandbox runners.
• Interactive Unix-local PTY usage.
• Sandbox handoffs and sandbox agents as tools.
• Host-defined tools combined with sandbox agents.
• Filesystem, shell, image, patch, compaction, lazy skill, and memory capabilities.
• Snapshot-based resume and multi-agent or multi-turn memory.
• Hosted provider runners for Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, and Vercel.

Runtime, Tracing, and Model Plumbing

The release includes the runtime plumbing needed for sandbox agents to work naturally inside the JavaScript SDK:

• Runner-managed sandbox preparation, capability binding, lifecycle handling, cleanup, and resume.
• Per-agent sandbox session tracking for handoffs and agents-as-tools flows.
• Public sandbox agent identity preservation across model filters and runtime hooks.
• Sandbox operation spans for session startup, command execution, filesystem work, snapshots, memory, and provider operations.
• runAs support for compatible shell and filesystem operations.
• Remote sandbox concurrency limits for manifest and local directory materialization.

What's Changed

• feat: add sandbox agents (#1199) by @seratch in https://github.com/openai/openai-agents-js/pull/1210
  • fix: keep public sandbox agent identity in filters by @seratch in https://github.com/openai/openai-agents-js/pull/1226
  • fix: support remote sandbox concurrency limits by @seratch in https://github.com/openai/openai-agents-js/pull/1225
  • fix: reject symlink ancestors in remote local sources by @seratch in https://github.com/openai/openai-agents-js/pull/1223
  • fix: support sandbox filesystem runAs across providers by @seratch in https://github.com/openai/openai-agents-js/pull/1224
  • fix: align sandbox mounts with Python and protect rclone credentials by @seratch in https://github.com/openai/openai-agents-js/pull/1228
  • fix: narrow sandbox public entrypoint by @seratch in https://github.com/openai/openai-agents-js/pull/1230
• feat: expose Responses WebSocket keepalive options by @seratch in https://github.com/openai/openai-agents-js/pull/1219
• feat: add context management model settings by @seratch in https://github.com/openai/openai-agents-js/pull/1233
• feat: add tool item convenience accessors by @seratch in https://github.com/openai/openai-agents-js/pull/1195
• fix: #1212 add code interpreter output include option by @seratch in https://github.com/openai/openai-agents-js/pull/1213
• fix: surface model refusals during run resolution by @seratch in https://github.com/openai/openai-agents-js/pull/1216

Documentation & Other Changes

• docs: use locked MCP filesystem server in examples by @mcgrew-oai in https://github.com/openai/openai-agents-js/pull/1193
• docs: update readme for npm packages by @seratch in https://github.com/openai/openai-agents-js/pull/1227
• ci: improve the automation to set milestone for a PR by @seratch in https://github.com/openai/openai-agents-js/pull/1214
• test: add optional sandbox storage mount integrations by @seratch in https://github.com/openai/openai-agents-js/pull/1229
• chore: upgrade pnpm to 10.33.2 by @seratch in https://github.com/openai/openai-agents-js/pull/1211
• chore: upgrade pnpm to 10.33.3 by @seratch in https://github.com/openai/openai-agents-js/pull/1231
• chore: bump the npm_and_yarn group across 1 directory with 4 updates by @dependabot[bot] in https://github.com/openai/openai-agents-js/pull/1194
• chore: update versions by @github-actions[bot] in https://github.com/openai/openai-agents-js/pull/1196

Full Changelog: https://github.com/openai/openai-agents-js/compare/v0.8.5...v0.9.0