docs: add sandbox agents guides (#1200)

Author: seratch

README.md

@@ -1,18 +1,17 @@
 # OpenAI Agents SDK (JavaScript/TypeScript)
 
-[![npm version](https://badge.fury.io/js/@openai%2Fagents.svg)](https://badge.fury.io/js/@openai%2Fagents)
-[![CI](https://github.com/openai/openai-agents-js/actions/workflows/test.yml/badge.svg)](https://github.com/openai/openai-agents-js/actions/workflows/test.yml)
+[![npm version](https://badge.fury.io/js/@openai%2Fagents.svg)](https://badge.fury.io/js/@openai%2Fagents) [![CI](https://github.com/openai/openai-agents-js/actions/workflows/test.yml/badge.svg)](https://github.com/openai/openai-agents-js/actions/workflows/test.yml)
 
 The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows in JavaScript/TypeScript. It is provider-agnostic, supporting OpenAI APIs and more.
 
 <img src="https://cdn.openai.com/API/docs/images/orchestration.png" alt="Image of the Agents Tracing UI" style="max-height: 803px;">
 
-> [!NOTE]
-> Looking for the Python version? Check out [OpenAI Agents SDK Python](https://github.com/openai/openai-agents-python).
+> [!NOTE] Looking for the Python version? Check out [OpenAI Agents SDK Python](https://github.com/openai/openai-agents-python).
 
 ## Core concepts
 
 1. [**Agents**](https://openai.github.io/openai-agents-js/guides/agents): LLMs configured with instructions, tools, guardrails, and handoffs
+1. [**Sandbox Agents**](https://openai.github.io/openai-agents-js/guides/sandbox-agents): Agents paired with a filesystem workspace and sandbox environment for longer-running work
 1. **[Agents as tools](https://openai.github.io/openai-agents-js/guides/tools/#4-agents-as-tools) / [Handoffs](https://openai.github.io/openai-agents-js/guides/handoffs/)**: Delegating to other agents for specific tasks
 1. [**Tools**](https://openai.github.io/openai-agents-js/guides/tools/): Various Tools let agents take actions (functions, MCP, hosted tools)
 1. [**Guardrails**](https://openai.github.io/openai-agents-js/guides/guardrails/): Configurable safety checks for input and output validation
@@ -43,7 +42,47 @@ Explore the [`examples/`](https://github.com/openai/openai-agents-js/tree/main/e
 npm install @openai/agents zod
 ```
 
-### Run your first agent
+### Run your first Sandbox Agent
+
+[Sandbox Agents](https://openai.github.io/openai-agents-js/guides/sandbox-agents) are in beta. A sandbox agent can inspect files, run commands, apply patches, and carry workspace state across longer tasks.
+
+```js
+import { run } from '@openai/agents';
+import { gitRepo, Manifest, SandboxAgent } from '@openai/agents/sandbox';
+import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';
+
+const agent = new SandboxAgent({
+  name: 'Workspace Assistant',
+  instructions: 'Inspect the sandbox workspace before answering.',
+  defaultManifest: new Manifest({
+    entries: {
+      repo: gitRepo({
+        repo: 'openai/openai-agents-js',
+        ref: 'main',
+      }),
+    },
+  }),
+});
+
+const result = await run(
+  agent,
+  'Inspect repo/README.md and summarize what this project does.',
+  {
+    sandbox: {
+      client: new UnixLocalSandboxClient(),
+    },
+  },
+);
+
+console.log(result.finalOutput);
+// This project provides a JavaScript/TypeScript SDK for building agent workflows.
+```
+
+(_If running this, ensure you set the `OPENAI_API_KEY` environment variable_)
+
+### Run an agent without a sandbox
+
+You can still use a regular `Agent` when your workflow does not need a filesystem workspace or sandbox lifecycle.
 
 ```js
 import { Agent, run } from '@openai/agents';
@@ -63,8 +102,6 @@ console.log(result.finalOutput);
 // Infinite loop's dance.
 ```
 
-(_If running this, ensure you set the `OPENAI_API_KEY` environment variable_)
-
 Explore the [`examples/`](https://github.com/openai/openai-agents-js/tree/main/examples) directory to see the SDK in action.
 
 ## Acknowledgements

docs/astro.config.mjs

@@ -136,6 +136,27 @@ const sidebar = [
           ko: '에이전트',
         },
       },
+      {
+        label: 'Sandbox agents',
+        items: [
+          {
+            label: 'Quickstart',
+            link: '/guides/sandbox-agents',
+          },
+          {
+            label: 'Concepts',
+            link: '/guides/sandbox-agents/concepts',
+          },
+          {
+            label: 'Sandbox clients',
+            link: '/guides/sandbox-agents/clients',
+          },
+          {
+            label: 'Agent memory',
+            link: '/guides/sandbox-agents/memory',
+          },
+        ],
+      },
       {
         label: 'Models',
         link: '/guides/models',

docs/src/assets/images/harness_with_compute.png

@@ -1,5 +1,6 @@
 ---
 import { Code, TabItem, Tabs } from '@astrojs/starlight/components';
+import helloWorldSandboxExample from '../../../examples/docs/toppage/sandboxAgent.ts?raw';
 import helloWorldExample from '../../../examples/docs/toppage/textAgent.ts?raw';
 import helloWorldVoiceExample from '../../../examples/docs/toppage/voiceAgent.ts?raw';
 const path = Astro.url.pathname;
@@ -22,6 +23,9 @@ const pathPrefix =
     </div>
     <div class="openai-hero-code flex-1 overflow-x-scroll">
       <Tabs>
+        <TabItem label="Sandbox Agent">
+          <Code lang="typescript" code={helloWorldSandboxExample} />
+        </TabItem>
         <TabItem label="Text Agent">
           <Code lang="typescript" code={helloWorldExample} />
         </TabItem>

docs/src/components/Hero.astro

@@ -34,6 +34,7 @@ Use this page as the hub for agent definition. Jump out to the adjacent guide th
 | --- | --- |
 | Choose a model or configure stored prompts | [Models](/openai-agents-js/guides/models) |
 | Add capabilities to the agent | [Tools](/openai-agents-js/guides/tools) |
+| Give the agent an isolated filesystem workspace | [Sandbox agents](/openai-agents-js/guides/sandbox-agents/concepts) |
 | Decide between managers and handoffs | [Agent orchestration](/openai-agents-js/guides/multi-agent) |
 | Configure handoff behavior | [Handoffs](/openai-agents-js/guides/handoffs) |
 | Run turns, stream events, or manage state | [Running agents](/openai-agents-js/guides/running-agents) |

docs/src/content/docs/guides/agents.mdx

@@ -69,6 +69,7 @@ The additional options are:
 | `toolErrorFormatter` | – | Hook to customize tool approval rejection messages returned to the model. See [Tool error formatter](#tool-error-formatter). |
 | `reasoningItemIdPolicy` | – | Controls whether reasoning-item `id`s are preserved or omitted when prior run items are turned back into model input. See [Reasoning item ID policy](#reasoning-item-id-policy). |
 | `tracing` | – | Per-run tracing configuration overrides (for example, export API key). |
+| `sandbox` | – | Sandbox client, live session, session state, snapshot, manifest override, or concurrency limits for `SandboxAgent` runs. See [Sandbox agents](/openai-agents-js/guides/sandbox-agents/concepts). |
 | `errorHandlers` | – | Handlers for supported runtime errors (currently `maxTurns`). See [Error handlers](#error-handlers). |
 | `conversationId` | – | Reuse a server-side conversation (OpenAI Responses API + Conversations API only). |
 | `previousResponseId` | – | Continue from the previous Responses API call without creating a conversation (OpenAI Responses API only). |
@@ -99,6 +100,7 @@ If you are creating your own `Runner` instance, you can pass in a `RunConfig` ob
 | `callModelInputFilter` | `CallModelInputFilter` | Global hook to edit model inputs before each model call. |
 | `toolErrorFormatter` | `ToolErrorFormatter` | Global hook to customize tool approval rejection messages returned to the model. |
 | `reasoningItemIdPolicy` | `ReasoningItemIdPolicy` | Default policy for preserving or omitting reasoning-item `id`s when replaying generated items into later model calls. |
+| `sandbox` | `SandboxRunConfig` | Default sandbox runtime configuration for `SandboxAgent` runs. |
 
 ## State and conversation management
 
@@ -115,6 +117,8 @@ There are four common ways to carry state into the next turn:
 
 `result.history` and `session` are client-managed. `conversationId` and `previousResponseId` are OpenAI-managed and only apply when you are using the OpenAI Responses API. In most applications, pick one persistence strategy per conversation. Mixing client-managed history with server-managed state can duplicate context unless you are deliberately reconciling both layers.
 
+Sandbox agents add another state layer: the live sandbox workspace. Use the regular SDK `session`, `conversationId`, or `previousResponseId` for conversation history, and use `sandbox.session`, `sandbox.sessionState`, `RunState`, or snapshots for sandbox filesystem state. See [Sandbox agents](/openai-agents-js/guides/sandbox-agents/concepts) for the workspace lifecycle.
+
 ### Conversations / chat threads
 
 Each call to `runner.run()` (or `run()` utility) represents one **turn** in your application-level conversation. You choose how much of the `RunResult` you show the end‑user – sometimes only `finalOutput`, other times every generated item.

docs/src/content/docs/guides/running-agents.mdx

@@ -0,0 +1,67 @@
+---
+title: Quickstart
+description: Create your first sandbox agent with an isolated workspace, filesystem tools, shell commands, and sandbox session state.
+---
+
+import { Aside, Code } from '@astrojs/starlight/components';
+import basicExample from '../../../../../examples/docs/sandbox-agents/basic.ts?raw';
+
+<Aside type="caution" title="Beta feature">
+  Sandbox agents are in beta. API details, defaults, and supported capabilities
+  may change before general availability, and more advanced features are
+  expected over time.
+</Aside>
+
+Modern agents work best when they can operate on real files in a filesystem. **Sandbox Agents** in the Agents SDK give the model a persistent workspace where it can search large document sets, edit files, run commands, generate artifacts, and pick work back up from saved sandbox state.
+
+The SDK gives you that execution harness without making you wire together file staging, filesystem tools, shell access, sandbox lifecycle, snapshots, and provider-specific glue yourself. You keep the normal `Agent` and `Runner` flow, then add a `Manifest` for the workspace, capabilities for sandbox-native tools, and the `sandbox` run option for where the work runs.
+
+## Prerequisites
+
+- Node.js 22 or higher.
+- Basic familiarity with the OpenAI Agents SDK.
+- A sandbox client. For local development, start with `UnixLocalSandboxClient`.
+
+## Installation
+
+If you have not already installed the SDK:
+
+```bash
+npm install @openai/agents
+```
+
+For Docker-backed sandboxes, install Docker locally and use `DockerSandboxClient` from `@openai/agents/sandbox/local`.
+
+If you use interactive local PTY sessions with `tty: true`, the process running the SDK also needs Python 3 available as `python3`, or through `OPENAI_AGENTS_PYTHON`. Non-PTY shell commands do not require Python.
+
+## Create a local sandbox agent
+
+This example stages a local repo under `repo/`, loads local skills lazily, and lets the runner create a Unix-local sandbox session for the run.
+
+<Code
+  lang="typescript"
+  code={basicExample}
+  title="Create a local sandbox agent"
+/>
+
+The example is intentionally shaped like the Python SDK quickstart: the agent definition owns the manifest and capabilities, while the run config only chooses the sandbox client for this run.
+
+## Key choices
+
+Once the basic run works, the choices most people reach for next are:
+
+- `defaultManifest`: the files, repos, directories, and mounts for fresh sandbox sessions.
+- `instructions`: short workflow rules that should apply across prompts.
+- `baseInstructions`: an advanced escape hatch for replacing the SDK sandbox prompt.
+- `capabilities`: sandbox-native tools such as filesystem editing/image inspection, shell, skills, memory, and compaction.
+- `runAs`: the sandbox user identity for model-facing tools.
+- `sandbox.client`: the sandbox backend.
+- `sandbox.session`, `sandbox.sessionState`, or `sandbox.snapshot`: how later runs reconnect to prior work.
+
+## Where to go next
+
+- [Concepts](/openai-agents-js/guides/sandbox-agents/concepts): understand manifests, capabilities, permissions, snapshots, run config, and composition patterns.
+- [Sandbox clients](/openai-agents-js/guides/sandbox-agents/clients): choose Unix-local, Docker, hosted providers, and mount strategies.
+- [Agent memory](/openai-agents-js/guides/sandbox-agents/memory): preserve and reuse lessons from previous sandbox runs.
+
+If shell access is only one occasional tool, start with hosted shell in the [Tools guide](/openai-agents-js/guides/tools). Reach for sandbox agents when workspace isolation, sandbox client choice, or sandbox-session resume behavior are part of the design.