### 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>
78 lines
3 KiB
Python
78 lines
3 KiB
Python
from __future__ import annotations
|
|
|
|
import io
|
|
from pathlib import Path
|
|
|
|
from agents import ApplyPatchTool, apply_diff
|
|
from agents.editor import ApplyPatchOperation, ApplyPatchResult
|
|
from agents.sandbox import Capability, Manifest
|
|
from agents.sandbox.session.base_sandbox_session import BaseSandboxSession
|
|
from agents.tool import Tool
|
|
|
|
|
|
def _read_text(handle: io.IOBase) -> str:
|
|
payload = handle.read()
|
|
if isinstance(payload, str):
|
|
return payload
|
|
if isinstance(payload, bytes | bytearray):
|
|
return bytes(payload).decode("utf-8", errors="replace")
|
|
return str(payload)
|
|
|
|
|
|
class _SandboxWorkspaceEditor:
|
|
def __init__(self, session: BaseSandboxSession) -> None:
|
|
self._session = session
|
|
|
|
async def create_file(self, operation: ApplyPatchOperation) -> ApplyPatchResult:
|
|
target = self._resolve_path(operation.path)
|
|
content = apply_diff("", operation.diff or "", mode="create")
|
|
await self._session.mkdir(target.parent, parents=True)
|
|
await self._session.write(target, io.BytesIO(content.encode("utf-8")))
|
|
return ApplyPatchResult(output=f"Created {self._display_path(target)}")
|
|
|
|
async def update_file(self, operation: ApplyPatchOperation) -> ApplyPatchResult:
|
|
target = self._resolve_path(operation.path)
|
|
handle = await self._session.read(target)
|
|
try:
|
|
original = _read_text(handle)
|
|
finally:
|
|
handle.close()
|
|
updated = apply_diff(original, operation.diff or "")
|
|
await self._session.write(target, io.BytesIO(updated.encode("utf-8")))
|
|
return ApplyPatchResult(output=f"Updated {self._display_path(target)}")
|
|
|
|
async def delete_file(self, operation: ApplyPatchOperation) -> ApplyPatchResult:
|
|
target = self._resolve_path(operation.path)
|
|
await self._session.rm(target)
|
|
return ApplyPatchResult(output=f"Deleted {self._display_path(target)}")
|
|
|
|
def _resolve_path(self, raw_path: str) -> Path:
|
|
return self._session.normalize_path(raw_path)
|
|
|
|
def _display_path(self, path: Path) -> str:
|
|
root = Path(self._session.state.manifest.root)
|
|
return path.relative_to(root).as_posix()
|
|
|
|
|
|
class WorkspaceApplyPatchCapability(Capability):
|
|
"""Expose the hosted apply_patch tool against the active sandbox workspace."""
|
|
|
|
def __init__(self) -> None:
|
|
super().__init__(type="workspace_apply_patch")
|
|
self._session: BaseSandboxSession | None = None
|
|
|
|
def bind(self, session: BaseSandboxSession) -> None:
|
|
self._session = session
|
|
|
|
def tools(self) -> list[Tool]:
|
|
if self._session is None:
|
|
return []
|
|
return [ApplyPatchTool(editor=_SandboxWorkspaceEditor(self._session))]
|
|
|
|
async def instructions(self, manifest: Manifest) -> str | None:
|
|
_ = manifest
|
|
return (
|
|
"Use the `apply_patch` tool for workspace text edits when you need to create or "
|
|
"update files inside the sandbox. Prefer saving final outputs in the requested "
|
|
"workspace directories instead of describing edits without writing them."
|
|
)
|