- Add SandboxPathGrant manifest support for explicit access to absolute
paths outside sandbox workspace.
- Centralize path handling in WorkspacePathPolicy.normalize_path(...),
including extra grant matching, symlink-aware host validation, and
most-specific grant selection.
- Harden access boundaries by rejecting filesystem-root grants, // root
aliases, and grants that resolve to /.
- Preserve nested grant semantics, including writable parent + read-only
child cases through remote symlink targets and macOS exec confinement.
- Update sandbox provider integrations to use shared path policy across
Docker, Unix-local, Runloop, Vercel, Cloudflare, E2B, Modal, Daytona,
and Blaxel.
### Summary
This pull request fixes sandbox compaction defaults so Azure/custom
deployment names do not fail before the model request is sent. It makes
compaction model-window lookup separator-insensitive for known
OpenAI-style names like `gpt-5-2`, adds a non-throwing lookup path, and
falls back to the static compaction threshold when the model window
cannot be inferred.
### Test plan
- `make format`
- `make lint`
- `uv run pytest tests/sandbox/test_compaction.py
tests/sandbox/capabilities/test_compaction_capability.py
tests/test_sandbox_runtime_agent_preparation.py -q`
- `uv run mypy src/agents/sandbox/capabilities/compaction.py
tests/sandbox/test_compaction.py
tests/sandbox/capabilities/test_compaction_capability.py`
- `uv run pyright src/agents/sandbox/capabilities/compaction.py
tests/sandbox/test_compaction.py
tests/sandbox/capabilities/test_compaction_capability.py`
Full `make tests` / `make typecheck` are currently blocked in this
workspace by missing optional dependencies and unrelated existing
failures (`numpy`, `litellm`, `sqlalchemy`, `temporalio`, `boto3`,
runloop extra, and one PTY timing assertion).
### Issue number
Refs #2927
### Checks
- [x] I've added new tests (if relevant)
- [ ] I've added/updated the relevant documentation
- [x] I've run `make lint` and `make format`
- [ ] I've made sure tests pass
### Summary
Updates the OpenAI tracing exporter to align usage metadata with the
trace ingest payload shape.
For the default OpenAI tracing endpoint, usage metadata is now only
included on generation spans, where it is normalized to the supported
token-count shape. Other tracing endpoints continue to receive the raw
SDK payload.
Adds regression coverage for OpenAI endpoint sanitization and custom
endpoint behavior.
### Test plan
- `make format`
- `make lint`
- `make sync && make typecheck`
- `uv run pytest
tests/test_openai_responses.py::test_get_response_span_exports_usage
tests/test_trace_processor.py` (46 passed)
- Manual tracing repro: `Runner.run(...)` completed, `flush_traces()`
completed, and no tracing client errors were emitted.
- `make tests` reached 3858 passed, 10 failed locally in sandbox tests
because `sandbox-exec` returned `sandbox_apply: Operation not
permitted`.
### Issue number
N/A
### Checks
- [x] I've added new tests (if relevant)
- [ ] I've added/updated the relevant documentation
- [x] I've run `make lint` and `make format`
- [ ] I've made sure tests pass
### Sandbox Agents
This release adds **Sandbox Agents**, a beta SDK surface for running
agents with a persistent, isolated workspace. Sandbox agents keep the
normal `Agent` and `Runner` flow, but add workspace manifests,
sandbox-native capabilities, sandbox clients, snapshots, and resume
support so agents can work over real files, run commands, edit
repositories, generate artifacts, and continue work across runs.
Key pieces:
- `SandboxAgent`: an `Agent` with sandbox defaults such as
`default_manifest`, sandbox instructions, capabilities, and `run_as`.
- `Manifest`: a fresh-workspace contract for files, directories, local
files, local directories, Git repos, environment, users, groups, and
mounts.
- `SandboxRunConfig`: per-run sandbox wiring for client creation, live
session injection, serialized session resume, manifest overrides,
snapshots, and materialization concurrency limits.
- Built-in capabilities for shell access, filesystem editing and image
inspection, skills, memory, and compaction.
- Workspace snapshots and serialized sandbox session state for
reconnecting to existing work or seeding a fresh sandbox from saved
contents.
### Sandbox clients and hosted providers
Sandbox agents now support local, containerized, and hosted execution
backends:
- `UnixLocalSandboxClient` for fast local development.
- `DockerSandboxClient` for container isolation and image parity.
- Hosted sandbox clients for Blaxel, Cloudflare, Daytona, E2B, Modal,
Runloop, and Vercel through optional extras.
The release also adds provider-specific examples and mount strategies
for common storage backends, including S3, Cloudflare R2, Google Cloud
Storage, Azure Blob Storage, and S3 Files where supported by the
selected backend.
### Sandbox memory
Adds a sandbox memory capability that lets future sandbox-agent runs
learn from prior runs. Memory stores extracted lessons in the sandbox
workspace, injects a concise summary into later runs, and uses
progressive disclosure so agents can search deeper rollout summaries
only when useful.
Memory supports:
- Read-only or generate-only modes.
- Live updates when the agent discovers stale memory.
- Multi-turn grouping through `conversation_id`, SDK `Session`,
`RunConfig.group_id`, or generated run IDs.
- Separate memory layouts for isolating memory across agents or
workflows.
- S3-backed examples for persisted memory across runs.
### Workspace mounts, snapshots, and resume
This release adds a full workspace entry and mount model for sandbox
sessions:
- Local files and directories.
- Synthetic files and directories.
- Git repository entries.
- Remote storage mounts for S3, R2, GCS, Azure Blob Storage, and S3
Files.
- Provider-specific mount strategies across Docker, Modal, Cloudflare,
Blaxel, Daytona, E2B, and Runloop.
- Portable snapshots with path normalization, symlink preservation,
mount-safe snapshotting, and remote snapshot support.
- Resume paths through runner-managed `RunState`, explicit
`SandboxSessionState`, or saved snapshots.
### Examples and tutorials
Adds a large `examples/sandbox/` suite covering:
- Local Unix and Docker sandbox runners.
- Docker mount smoke tests for S3, GCS, Azure Blob Storage, and S3
Files.
- Sandbox coding tasks with skills.
- Sandbox agents as tools and handoff patterns.
- Memory examples, including multi-agent/multi-turn memory and S3-backed
memory.
- Tax-prep and healthcare-support workflows.
- Dataroom QA and metric extraction tutorials.
- Repository code review tutorial.
- Vision website clone tutorial.
- Provider examples for Blaxel, Cloudflare, Daytona, E2B, Modal,
Runloop, Temporal, and Vercel.
### Runtime, tracing, and model plumbing
The release includes the runtime plumbing needed to make sandbox agents
work naturally inside the existing SDK:
- Runner-managed sandbox preparation, capability binding, session
lifecycle, state serialization, and resume behavior.
- Sandbox-aware `RunState` serialization.
- Unified sandbox tracing with SDK spans.
- Token usage on tracing spans.
- Runner-managed prompt cache key defaults.
- OpenAI agent registration and harness ID configuration.
- Safer redaction of sensitive MCP tool outputs when sensitive tracing
is disabled.
- Additional OpenAI client/model utilities and Chat Completions
coverage.
## Documentation & Other Changes
- docs: add Asqav to external tracing processors list.
- docs: update translated document pages.
Co-authored-by: Abdulrahman Alfozan <alfozan@openai.com>
Co-authored-by: Aditya Singh <60082699+adityasingh2400@users.noreply.github.com>
Co-authored-by: Andi Liu <andi@openai.com>
Co-authored-by: Aron <263346377+aron-cf@users.noreply.github.com>
Co-authored-by: ashwinnathan-openai <ashwinnathan@openai.com>
Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: cploujoux <cploujoux@blaxel.ai>
Co-authored-by: elainegan-openai <168589666+elainegan-openai@users.noreply.github.com>
Co-authored-by: Elias Freider <freider@users.noreply.github.com>
Co-authored-by: Erik Dunteman <erik@erikds-macbook-air.local>
Co-authored-by: Jason Liu <jasonliu@openai.com>
Co-authored-by: Jason Steving <32336750+jasonsteving99@users.noreply.github.com>
Co-authored-by: Kazuhiro Sera <seratch@openai.com>
Co-authored-by: Lovre Pešut <lovre.pesut@gmail.com>
Co-authored-by: Lucas Wang <lucas_wang@lucas-futures.com>
Co-authored-by: Matt Brockman <matt.brockman@e2b.dev>
Co-authored-by: Mish Ushakov <mishushakov@users.noreply.github.com>
Co-authored-by: Naresh <ghostwriternr@gmail.com>
Co-authored-by: nicholasclark-openai <nicholasclark@openai.com>
Co-authored-by: qiyaoq-oai <qiyaoq@openai.com>
Co-authored-by: Scott Trinh <scott@scotttrinh.com>
Co-authored-by: tode-rl <tony@runloop.ai>
Co-authored-by: Wendy Jiao <wendyjiao@openai.com>
Matthew.K