개념

최신 에이전트는 파일 시스템의 실제 파일을 다룰 수 있을 때 가장 효과적으로 작동합니다. 샌드박스 에이전트는 특수 도구와 셸 명령을 사용하여 대규모 문서 집합을 검색하고 조작하며, 파일을 편집하고, 아티팩트를 생성하고, 명령을 실행할 수 있습니다. 샌드박스는 에이전트가 사용자를 대신해 작업하는 데 사용할 수 있는 영구 작업 공간을 모델에 제공합니다. Agents SDK의 샌드박스 에이전트를 사용하면 샌드박스 환경과 연결된 에이전트를 실행할 수 있으므로, 필요한 파일을 파일 시스템에 배치하고 샌드박스를 오케스트레이션하여 대규모 작업을 시작, 중지 및 재개하기가 쉽습니다.

에이전트에 필요한 데이터를 중심으로 작업 공간을 정의합니다. 작업 공간은 GitHub 저장소, 로컬 파일과 디렉터리, 합성 작업 파일, S3 또는 Azure Blob Storage 같은 원격 파일 시스템 및 사용자가 제공하는 기타 샌드박스 입력으로 시작할 수 있습니다.

SandboxAgent는 Agent를 확장하므로 여전히 Agent입니다. instructions, tools, handoffs, mcpServers, modelSettings, 출력 유형, 가드레일, 훅과 같은 일반적인 에이전트 인터페이스를 그대로 유지하며, 일반적인 run() 및 Runner API를 통해 실행됩니다. 달라지는 것은 실행 경계입니다.

SandboxAgent는 에이전트 자체를 정의합니다. 일반적인 에이전트 설정에 defaultManifest, baseInstructions, runAs 같은 샌드박스 전용 기본값과 파일 시스템 도구, 셸 액세스, 스킬, 메모리 또는 압축 같은 기능이 추가됩니다.
Manifest는 새 샌드박스 작업 공간에 필요한 파일, 저장소, 마운트 및 환경을 포함하여 원하는 초기 콘텐츠와 레이아웃을 선언합니다.
샌드박스 세션은 명령이 실행되고 파일이 변경되는 실제 실행 환경입니다.
sandbox 실행 옵션은 실행에서 샌드박스 세션을 가져오는 방식을 결정합니다. 예를 들어 세션을 직접 주입하거나, 직렬화된 샌드박스 세션 상태에서 다시 연결하거나, 샌드박스 클라이언트를 통해 새 샌드박스 세션을 생성할 수 있습니다.
저장된 샌드박스 상태와 스냅샷을 사용하면 이후 실행에서 이전 작업에 다시 연결하거나 저장된 콘텐츠로 새 샌드박스 세션을 초기화할 수 있습니다.

Manifest는 새 샌드박스 작업 공간의 초기 콘텐츠를 정의합니다. 재사용된 세션, 직렬화된 세션 상태 및 스냅샷이 모두 런타임에 작업 공간을 제공하거나 변경할 수 있으므로, 모든 활성 샌드박스의 현재 파일을 설명하지는 않습니다.

이 페이지에서 “샌드박스 세션”은 샌드박스 클라이언트가 관리하는 실제 실행 환경을 의미합니다. 정확한 경계는 클라이언트에 따라 다릅니다. Unix 로컬 세션은 호스트의 로컬 작업 공간에서 실행되는 반면, Docker 및 호스티드 클라이언트는 더 강력한 환경 격리를 제공합니다. 이는 세션에서 설명하는 SDK의 대화형 Session 인터페이스와 다릅니다.

외부 런타임은 여전히 승인, 트레이싱, 핸드오프 및 재개 관련 기록 관리를 담당합니다. 샌드박스 세션은 명령, 파일 변경 및 환경 격리를 담당합니다. 이러한 역할 분리는 모델의 핵심 요소입니다.

구성 요소의 연동 방식

샌드박스 실행은 에이전트 정의와 실행별 샌드박스 설정을 결합합니다. 러너는 에이전트를 준비하고 실제 샌드박스 세션에 바인딩하며, 이후 실행을 위해 상태를 저장할 수 있습니다.

SandboxAgent에이전트와 샌드박스 기본값

러너instructions 준비 및 기능 도구 바인딩

샌드박스 세션명령이 실행되고 파일이 변경되는 작업 공간

저장된 상태나중에 재개하거나 새 작업 공간 초기화

샌드박스 전용 기본값은 SandboxAgent에 유지합니다. 실행별 샌드박스 세션 선택 사항은 sandbox 실행 옵션에 유지합니다.

수명 주기는 다음 세 단계로 구분할 수 있습니다.

SandboxAgent, Manifest 및 기능을 사용해 에이전트와 초기 작업 공간 콘텐츠를 정의합니다.
샌드박스 세션을 주입, 재개 또는 생성하는 sandbox 실행 옵션을 run() 또는 Runner에 제공하여 실행합니다.
러너가 관리하는 RunState, 명시적인 샌드박스 sessionState 또는 저장된 작업 공간 스냅샷에서 나중에 작업을 이어갑니다.

셸 액세스가 가끔 사용하는 도구 중 하나에 불과하다면 도구의 호스티드 셸부터 사용하세요. 작업 공간 격리, 샌드박스 클라이언트 선택 또는 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요.

사용 시점

샌드박스 에이전트는 다음과 같은 작업 공간 중심 워크플로에 적합합니다.

코딩 및 디버깅: GitHub 저장소의 이슈 보고서에 대한 자동 수정 작업을 오케스트레이션하고 대상 테스트를 실행
문서 처리 및 편집: 사용자의 재무 문서에서 정보를 추출하고 작성이 완료된 세금 신고서 초안을 생성
파일 기반 검토 또는 분석: 답변하기 전에 온보딩 문서 묶음, 생성된 보고서 또는 아티팩트 번들을 확인
격리된 멀티 에이전트 패턴: 각 검토자 또는 코딩 하위 에이전트에 별도의 작업 공간을 제공
여러 단계로 구성된 작업 공간 작업: 한 실행에서 버그를 수정하고 나중에 회귀 테스트를 추가하거나, 스냅샷 또는 샌드박스 세션 상태에서 재개

파일이나 지속적으로 변경되는 파일 시스템에 액세스할 필요가 없다면 Agent를 계속 사용하세요. 셸 액세스가 가끔 필요한 기능 중 하나라면 호스티드 셸을 추가하고, 작업 공간 경계 자체가 기능의 일부라면 샌드박스 에이전트를 사용하세요.

샌드박스 클라이언트 선택

macOS 또는 Linux에서 로컬로 개발할 때는 UnixLocalSandboxClient로 시작하세요. Windows에서는 대신 DockerSandboxClient 또는 호스티드 공급자를 사용하세요. 지원되는 모든 플랫폼에서 컨테이너 격리나 이미지 일관성이 필요하면 DockerSandboxClient로 전환하고, 공급자가 관리하는 실행이 필요하면 호스티드 공급자로 전환하세요.

대부분의 경우 SandboxAgent 정의는 그대로 유지하고, sandbox 실행 옵션에서 샌드박스 클라이언트와 해당 옵션만 변경합니다. 로컬, Docker, 호스티드 및 원격 마운트 옵션은 샌드박스 클라이언트를 참조하세요.

핵심 구성 요소

계층	주요 SDK 구성 요소	답변하는 질문
에이전트 정의	`SandboxAgent`, `Manifest`, 기능	어떤 에이전트를 실행하며, 새 세션은 어떤 작업 공간 계약에서 시작해야 하는가?
샌드박스 실행	`sandbox` 실행 옵션, 샌드박스 클라이언트 및 실제 샌드박스 세션	이 실행은 실제 샌드박스 세션을 어떻게 가져오며, 작업은 어디에서 실행되는가?
저장된 샌드박스 상태	`RunState` 샌드박스 페이로드, `sessionState` 및 스냅샷	이 워크플로는 이전 샌드박스 작업에 어떻게 다시 연결하거나 저장된 콘텐츠로 새 샌드박스 세션을 초기화하는가?

주요 SDK 구성 요소는 다음과 같이 각 계층에 대응합니다.

구성 요소	담당 범위	확인할 질문
`SandboxAgent`	에이전트 정의	이 에이전트는 무엇을 해야 하며, 어떤 기본값을 함께 전달해야 하는가?
`Manifest`	새 세션의 작업 공간 파일과 폴더	실행이 시작될 때 파일 시스템에 어떤 파일과 폴더가 있어야 하는가?
`Capability`	샌드박스 네이티브 동작	이 에이전트에 어떤 도구, instructions 조각 또는 런타임 동작을 연결해야 하는가?
`sandbox` 실행 옵션	실행별 샌드박스 클라이언트 및 샌드박스 세션 소스	이 실행에서 샌드박스 세션을 주입, 재개 또는 생성해야 하는가?
`RunState`	러너가 관리하는 저장된 샌드박스 상태	이전에 러너가 관리하던 워크플로를 재개하고 해당 샌드박스 상태를 자동으로 이어가려는가?
`sandbox.sessionState`	명시적으로 직렬화된 샌드박스 세션 상태	`RunState` 외부에서 이미 직렬화한 샌드박스 상태로부터 재개하려는가?
`sandbox.snapshot`	새 샌드박스 세션을 위한 저장된 작업 공간 콘텐츠	새 샌드박스 세션을 저장된 파일과 아티팩트에서 시작해야 하는가?

실용적인 설계 순서는 다음과 같습니다.

Manifest 또는 매니페스트 초기화 객체를 사용하여 새 세션의 작업 공간 계약을 정의합니다.
SandboxAgent를 사용하여 에이전트를 정의합니다.
기본 제공 또는 사용자 지정 기능을 추가합니다.
run(agent, input, { sandbox: ... }) 또는 new Runner({ sandbox: ... })에서 각 실행이 샌드박스 세션을 가져올 방식을 결정합니다.

샌드박스 실행 준비 방식

런타임에 러너는 해당 정의를 구체적인 샌드박스 기반 실행으로 변환합니다.

sandbox 실행 옵션에서 샌드박스 세션을 확인합니다.
실행에 적용할 작업 공간 입력을 결정합니다.
기능이 결과 매니페스트를 처리하도록 합니다.
고정된 순서로 최종 instructions를 구성합니다. SDK의 기본 샌드박스 프롬프트 또는 명시적으로 재정의한 경우 baseInstructions, 그다음 instructions, 기능의 instructions 조각, 원격 마운트 정책 텍스트, 렌더링된 파일 시스템 트리 순입니다.
기능 도구를 실제 샌드박스 세션에 바인딩하고, 준비된 에이전트를 일반적인 run() 및 Runner API를 통해 실행합니다.

샌드박스를 사용해도 턴의 의미는 달라지지 않습니다. 턴은 여전히 단일 셸 명령이나 샌드박스 작업이 아니라 모델 단계입니다. 샌드박스 측 작업과 턴 사이에는 고정된 1:1 대응 관계가 없습니다. 실용적인 기준으로는 샌드박스 작업이 수행된 후 에이전트 런타임에 또 다른 모델 응답이 필요할 때만 추가 턴이 소비됩니다.

`SandboxAgent` 옵션

일반적인 Agent 필드에 추가되는 샌드박스 전용 옵션은 다음과 같습니다.

옵션	주요 용도
`defaultManifest`	러너가 생성하는 새 샌드박스 세션의 기본 작업 공간
`instructions`	SDK 샌드박스 프롬프트 뒤에 추가되는 역할, 워크플로 및 성공 기준
`baseInstructions`	SDK 샌드박스 프롬프트를 대체하는 고급 이스케이프 해치
`capabilities`	이 에이전트와 함께 전달해야 하는 샌드박스 네이티브 도구 및 동작
`runAs`	셸 명령, 파일 읽기 및 패치 같은 모델 대상 샌드박스 도구에서 사용할 사용자 ID

샌드박스 클라이언트 선택, 샌드박스 세션 재사용, 매니페스트 재정의 및 스냅샷 선택은 에이전트가 아니라 sandbox 실행 옵션에 지정합니다.

`defaultManifest`

defaultManifest는 러너가 이 에이전트용 새 샌드박스 세션을 생성할 때 사용하는 기본 작업 공간입니다. Manifest 인스턴스 또는 new Manifest(...)에 전달하는 것과 동일한 초기화 객체를 전달합니다. 에이전트가 일반적으로 시작할 때 필요한 파일, 저장소, 보조 자료, 출력 디렉터리 및 마운트에 사용합니다.

이는 기본값일 뿐입니다. 실행에서 sandbox.manifest를 사용해 재정의할 수 있으며, 재사용하거나 재개한 샌드박스 세션은 기존 작업 공간 상태를 유지합니다.

import { file, gitRepo, Manifest } from '@openai/agents/sandbox';

const manifest = new Manifest({
  root: '/workspace',
  entries: {
    'task.md': file({
      content: 'Fix the failing test and summarize the change.',
    }),
    repo: gitRepo({
      repo: 'openai/openai-agents-js',
      ref: 'main',
    }),
  },
  environment: {
    NODE_ENV: 'test',
  },
});

`instructions` 및 `baseInstructions`

여러 프롬프트에서 유지해야 하는 짧은 규칙에는 instructions를 사용하세요. SandboxAgent에서는 이러한 instructions가 SDK의 샌드박스 기본 프롬프트 뒤에 추가되므로, 기본 제공 샌드박스 지침을 유지하면서 자체 역할, 워크플로 및 성공 기준을 추가할 수 있습니다.

SDK 샌드박스 기본 프롬프트를 대체하려는 경우에만 baseInstructions를 사용하세요. 대부분의 에이전트는 이를 설정할 필요가 없습니다.

배치 위치	용도	예시
`instructions`	에이전트의 안정적인 역할, 워크플로 규칙 및 성공 기준	”온보딩 문서를 검토한 다음 핸드오프하세요.”, “최종 파일을 `output/`에 작성하세요.”
`baseInstructions`	SDK 샌드박스 기본 프롬프트의 완전한 대체 항목	사용자 지정 저수준 샌드박스 래퍼 프롬프트
사용자 프롬프트	이번 실행을 위한 일회성 요청	”이 작업 공간을 요약하세요.”
매니페스트의 작업 공간 파일	더 긴 작업 사양, 저장소 로컬 지침 또는 범위가 제한된 참조 자료	`repo/task.md`, 문서 번들, 샘플 문서 묶음

사용자의 일회성 작업을 instructions에 복사하거나, 매니페스트에 있어야 할 긴 참조 자료를 포함하거나, 기본 제공 기능이 이미 주입하는 도구 문서를 반복하거나, 모델이 런타임에 필요로 하지 않는 로컬 설치 참고 사항을 섞지 마세요.

`capabilities`

기능은 샌드박스 네이티브 동작을 SandboxAgent에 연결합니다. 실행이 시작되기 전에 작업 공간을 구성하고, 샌드박스 전용 instructions를 추가하고, 실제 샌드박스 세션에 바인딩되는 도구를 노출하며, 해당 에이전트의 모델 동작 또는 입력 처리를 조정할 수 있습니다.

기본 제공 기능은 다음과 같습니다.

기능	추가 시점	참고 사항
`shell()`	에이전트에 셸 액세스가 필요한 경우	`exec_command`를 추가하며, 샌드박스 클라이언트가 PTY 상호작용을 지원하면 `write_stdin`도 추가
`filesystem()`	에이전트가 파일을 편집하거나 로컬 이미지를 검사해야 하는 경우	`apply_patch`와 `view_image`를 추가하며, 패치 경로는 작업 공간 루트를 기준으로 한 상대 경로
`skills()`	샌드박스에서 스킬 탐색과 구체화를 사용하려는 경우	샌드박스 로컬 `SKILL.md` 스킬에는 `.agents` 또는 `.agents/skills`를 수동으로 마운트하는 것보다 이 기능을 권장
`memory()`	후속 실행에서 메모리 아티팩트를 읽거나 생성해야 하는 경우	`shell()`이 필요하며, 실시간 업데이트에는 `filesystem()`도 필요
`compaction()`	장기 실행 흐름에서 압축 항목 이후 컨텍스트 축소가 필요한 경우	모델 샘플링 및 입력 처리를 조정

기본적으로 SandboxAgent.capabilities는 filesystem(), shell(), compaction()을 포함하는 Capabilities.default()를 사용합니다. capabilities: [...]를 전달하면 해당 목록이 기본값을 대체하므로, 계속 사용할 기본 기능을 모두 포함해야 합니다.

개념

매니페스트

Manifest는 새 샌드박스 세션의 작업 공간을 설명합니다. 작업 공간 root를 설정하고, 파일과 디렉터리를 선언하고, 로컬 파일을 복사하고, Git 저장소를 복제하고, 원격 스토리지 마운트를 연결하고, 환경 변수를 설정하고, 사용자 또는 그룹을 정의하고, 작업 공간 외부의 특정 절대 경로에 대한 액세스를 허용할 수 있습니다.

매니페스트 환경 값은 기본적으로 유지됩니다. API 키, 액세스 토큰 또는 샌드박스 상태와 함께 저장하면 안 되는 기타 단기 자격 증명에는 { value: "...", ephemeral: true } 같은 임시 항목을 사용하세요.

매니페스트 항목 경로는 작업 공간 기준 상대 경로입니다. 절대 경로이거나 ..을 사용해 작업 공간을 벗어날 수 없으므로, 로컬, Docker 및 호스티드 클라이언트 간에 작업 공간 계약을 이식할 수 있습니다.

작업 시작 전에 에이전트에 필요한 자료에는 매니페스트 항목을 사용하세요.

매니페스트 항목	용도
`file()`, `dir()`	작은 합성 입력, 보조 파일 또는 출력 디렉터리
`localFile()`, `localDir()`	샌드박스에 구체화해야 하는 호스트 파일 또는 디렉터리
`gitRepo()`	작업 공간으로 가져와야 하는 저장소
`s3Mount()`, `gcsMount()`, `r2Mount()`, `azureBlobMount()`, `s3FilesMount()` 같은 마운트	샌드박스 내부에 표시해야 하는 외부 스토리지

로컬 구체화의 경우 localFile() 및 localDir() 소스 경로는 로컬 소스 기본 디렉터리 내부에 있어야 합니다. 기본값은 Node 프로세스의 현재 작업 디렉터리이며, 로컬 샌드박스 클라이언트는 항목을 구체화할 때 클라이언트별 기본 경로를 제공할 수 있습니다. 다른 절대 호스트 디렉터리에서 소스를 가져와야 하는 경우 필요한 최소 범위의 Manifest.extraPathGrants 항목을 추가하세요.

extraPathGrants는 로컬 지연 스킬 탐색에도 사용됩니다. 소스 기본 디렉터리 외부를 가리키는 localDirLazySkillSource()는 매니페스트에서 해당 디렉터리를 허용하지 않으면 무시됩니다. 공유 스킬, 데이터 세트 및 참조 저장소 같은 입력 번들에는 readOnly: true를 권장합니다.

import { Manifest, localDir, skills } from '@openai/agents/sandbox';
import { localDirLazySkillSource } from '@openai/agents/sandbox/local';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const appRoot = dirname(fileURLToPath(import.meta.url));
const repoDir = join(appRoot, 'repo');
const sharedSkillsDir = '/opt/company/agent-skills';

const manifest = new Manifest({
  extraPathGrants: [
    {
      path: sharedSkillsDir,
      readOnly: true,
      description: 'Shared skill bundle.',
    },
  ],
  entries: {
    repo: localDir({ src: repoDir }),
  },
});

const skillCapability = skills({
  lazyFrom: localDirLazySkillSource({
    src: sharedSkillsDir,
  }),
});

마운트 항목은 노출할 스토리지를 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 연결하는 방식을 설명합니다. 마운트 옵션 및 공급자 지원은 샌드박스 클라이언트를 참조하세요.

권한

Permissions는 매니페스트 항목의 파일 시스템 권한을 제어합니다. 이는 샌드박스가 구체화하는 파일에 관한 것이며, 모델 권한, 승인 정책 또는 API 자격 증명에 관한 것이 아닙니다.

사용자는 작업을 실행할 수 있는 샌드박스 ID입니다. 해당 ID가 샌드박스에 존재해야 한다면 사용자를 매니페스트에 추가한 다음, 셸 명령, 파일 읽기 및 패치 같은 모델 대상 샌드박스 도구가 해당 사용자로 실행되어야 할 때 SandboxAgent.runAs를 설정하세요.

파일 수준 공유 규칙도 필요하다면 사용자와 매니페스트 그룹 및 항목의 group 메타데이터를 함께 사용하세요. runAs 사용자는 샌드박스 네이티브 작업을 실행할 주체를 제어하고, Permissions는 샌드박스가 작업 공간을 구체화한 후 해당 사용자가 읽거나 쓰거나 실행할 수 있는 파일을 제어합니다.

SnapshotSpec

SnapshotSpec은 새 샌드박스 세션에서 저장된 작업 공간 콘텐츠를 복원할 위치와 다시 유지할 위치를 지정합니다. 이는 샌드박스 작업 공간의 스냅샷 정책이며, sessionState는 특정 샌드박스 백엔드를 재개하기 위한 직렬화된 연결 상태입니다.

로컬의 영구 스냅샷에는 로컬 스냅샷을 사용하고, 애플리케이션에서 원격 스냅샷 클라이언트를 제공하는 경우에는 원격 스냅샷을 사용하세요. 마운트된 경로와 임시 경로는 영구 작업 공간 콘텐츠로 스냅샷에 복사되지 않습니다.

샌드박스 수명 주기

수명 주기 모드는 SDK 관리형과 개발자 관리형 두 가지입니다.

SDK 관리형러너가 실제 샌드박스를 관리합니다.

sandbox.client를 전달합니다.
러너가 샌드박스 세션을 생성하거나 재개합니다.
에이전트가 실행되고 스냅샷 기반 작업 공간 상태를 유지할 수 있습니다.
러너가 소유한 리소스를 러너가 종료합니다.

개발자 관리형애플리케이션이 실제 샌드박스를 관리합니다.

session을 생성합니다.
실행에 sandbox.session을 전달합니다.
에이전트가 기존 작업 공간을 사용합니다.
세션을 검사하고 재사용한 다음 직접 종료합니다.

샌드박스를 한 번의 실행 동안만 유지하면 되는 경우 SDK 관리형 수명 주기를 사용하세요. client, 선택적 manifest, 선택적 snapshot 및 클라이언트 options를 전달하면 러너가 샌드박스를 생성하거나 재개하고, 에이전트를 실행하고, 스냅샷 기반 작업 공간 상태를 유지하며, 클라이언트가 러너 소유 리소스를 정리하도록 합니다.

import { run } from '@openai/agents';
import { SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const agent = new SandboxAgent({
  name: 'Workspace reviewer',
  model: 'gpt-5.6-sol',
  instructions: 'Inspect the sandbox workspace before answering.',
});

const result = await run(agent, 'Inspect the workspace.', {
  sandbox: {
    client: new UnixLocalSandboxClient(),
  },
});

console.log(result.finalOutput);

샌드박스를 미리 생성하거나, 여러 실행에서 하나의 실제 샌드박스를 재사용하거나, 실행 후 파일을 검사하거나, 직접 생성한 샌드박스에서 스트리밍하거나, 정리 시점을 정확히 결정하려는 경우 개발자 관리형 수명 주기를 사용하세요. session을 전달하면 러너가 해당 실제 샌드박스를 사용하지만 대신 종료하지는 않습니다.

import { run } from '@openai/agents';
import { Manifest, SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const manifest = new Manifest();
const agent = new SandboxAgent({
  name: 'Workspace reviewer',
  model: 'gpt-5.6-sol',
  instructions: 'Inspect the sandbox workspace before answering.',
});

const client = new UnixLocalSandboxClient();
const session = await client.create({ manifest });

try {
  await run(agent, 'First task.', { sandbox: { session } });
  await run(agent, 'Follow-up task.', { sandbox: { session } });
} finally {
  await session.close?.();
}

`sandbox` 실행 옵션

sandbox 실행 옵션에는 샌드박스 세션의 출처와 새 세션의 초기화 방식을 결정하는 실행별 옵션이 포함됩니다.

샌드박스 소스

다음 옵션은 러너가 샌드박스 세션을 재사용, 재개 또는 생성할지 결정합니다.

옵션	사용 시점	참고 사항
`client`	러너가 샌드박스 세션을 생성, 재개 및 정리하도록 하려는 경우	실제 샌드박스 `session`을 제공하지 않으면 필수
`session`	실제 샌드박스 세션을 직접 생성한 경우	호출자가 수명 주기를 관리하며, 러너는 해당 실제 샌드박스 세션을 재사용
`sessionState`	직렬화된 샌드박스 세션 상태는 있지만 실제 샌드박스 세션 객체는 없는 경우	`client`가 필요하며, 러너는 해당 명시적 상태에서 관리 대상 세션으로 재개

새 세션 입력

다음 옵션은 러너가 새 샌드박스 세션을 생성할 때만 적용됩니다.

옵션	사용 시점	참고 사항
`manifest`	새 세션의 작업 공간을 일회성으로 재정의하려는 경우	`Manifest` 또는 매니페스트 초기화 객체를 허용하며, 생략하면 `agent.defaultManifest` 사용
`snapshot`	새 샌드박스 세션을 스냅샷에서 초기화해야 하는 경우	재개와 유사한 흐름 또는 원격 스냅샷 클라이언트에 유용
`options`	샌드박스 클라이언트에 생성 시점 옵션이 필요한 경우	Docker 이미지, 공급자 시간 제한 및 이와 유사한 클라이언트별 설정에 주로 사용

concurrencyLimits는 병렬로 실행할 수 있는 샌드박스 구체화 작업의 양을 제어합니다. 대규모 매니페스트 또는 로컬 디렉터리 복사에 더 엄격한 리소스 제어가 필요하면 manifestEntries와 localDirFiles를 사용하세요.

구체화 제어

구체화 제어는 의도적으로 실행별로 설정됩니다. 동일한 SandboxAgent에서 대규모 로컬 디렉터리 복사에는 보수적인 제한을 사용하고, 작은 매니페스트에는 더 완화된 제한을 사용할 수 있도록 sandbox 실행 옵션 가까이에 유지하세요.

매니페스트에 파일, 디렉터리, 저장소 및 마운트처럼 서로 독립적인 항목이 많은 경우 concurrencyLimits.manifestEntries를 사용하세요. localDir() 항목에 파일이 많아 로컬 복사 부하를 제한해야 하는 경우 concurrencyLimits.localDirFiles를 사용하세요.

전체 예제: 코딩 작업

다음 코딩 스타일 예제는 기본 시작점으로 적합합니다.

import { run } from '@openai/agents';
import {
  Capabilities,
  Manifest,
  SandboxAgent,
  localDir,
  skills,
} from '@openai/agents/sandbox';
import {
  UnixLocalSandboxClient,
  localDirLazySkillSource,
} from '@openai/agents/sandbox/local';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const exampleDir = dirname(fileURLToPath(import.meta.url));
const hostRepoDir = join(exampleDir, 'repo');
const hostSkillsDir = join(exampleDir, 'skills');

const manifest = new Manifest({
  entries: {
    repo: localDir({ src: hostRepoDir }),
  },
});

const agent = new SandboxAgent({
  name: 'Sandbox engineer',
  model: 'gpt-5.6-sol',
  instructions:
    'Read `repo/task.md` before editing files. Load the `$invoice-total-fixer` skill before changing code. Stay grounded in the repository, preserve existing behavior, and mention the exact verification command you ran. If you edit files with apply_patch, paths are relative to the sandbox workspace root.',
  defaultManifest: manifest,
  capabilities: [
    ...Capabilities.default(),
    skills({
      lazyFrom: localDirLazySkillSource({
        src: hostSkillsDir,
      }),
    }),
  ],
});

const result = await run(
  agent,
  'Open `repo/task.md`, fix the issue, run the targeted test, and summarize the change.',
  {
    sandbox: {
      client: new UnixLocalSandboxClient(),
    },
  },
);

console.log(result.finalOutput);

일반적인 패턴

위의 전체 예제에서 시작하세요. 대부분의 경우 동일한 SandboxAgent를 그대로 유지하면서 샌드박스 클라이언트, 샌드박스 세션 소스 또는 작업 공간 소스만 변경할 수 있습니다.

샌드박스 클라이언트 전환

에이전트 정의는 그대로 유지하고 실행 설정만 변경하세요. 컨테이너 격리나 이미지 일관성이 필요하면 Docker를 사용하고, 공급자가 관리하는 실행이 필요하면 호스티드 공급자를 사용하세요. 예제와 공급자 옵션은 샌드박스 클라이언트를 참조하세요.

작업 공간 재정의

에이전트 정의는 그대로 유지하고 sandbox: { client, manifest }를 사용해 새 세션의 매니페스트만 교체하세요. 에이전트를 다시 만들지 않고 동일한 에이전트 역할을 서로 다른 저장소, 문서 묶음 또는 작업 번들에 적용해야 할 때 사용합니다.

샌드박스 세션 주입

명시적인 수명 주기 제어, 실행 후 검사 또는 출력 복사가 필요하면 실제 샌드박스 세션을 주입하세요. 해당 실행에 sandbox: { session }을 사용하고 애플리케이션 코드에서 세션을 종료합니다.

세션 상태에서 재개

RunState 외부에서 이미 샌드박스 상태를 직렬화했다면 sandbox: { client, sessionState }를 사용해 러너가 해당 상태에서 다시 연결하도록 하세요. 샌드박스 상태를 자체 스토리지나 작업 시스템에 저장하고 Runner가 해당 상태에서 직접 재개하도록 하려는 경우 사용합니다.

스냅샷에서 시작

sandbox: { client, snapshot }을 사용해 저장된 파일과 아티팩트로 새 샌드박스를 초기화하세요. 새 실행이 agent.defaultManifest만 사용하는 대신 저장된 작업 공간 콘텐츠에서 시작해야 할 때 사용합니다.

Git에서 스킬 로드

skills({ from: gitRepo(...) })를 사용해 로컬 스킬 소스를 저장소 기반 소스로 교체하세요. 스킬 번들에 자체 릴리스 주기가 있거나 여러 샌드박스에서 공유해야 할 때 사용합니다.

도구로 노출

도구 에이전트는 자체 샌드박스 경계를 사용하거나 상위 실행의 실제 샌드박스를 재사용할 수 있습니다. 재사용은 빠른 읽기 전용 탐색 에이전트에 유용합니다. 다른 샌드박스를 생성하거나, 콘텐츠를 채우거나, 스냅샷을 생성하는 비용 없이 상위 에이전트가 사용하는 정확한 작업 공간을 검사할 수 있습니다.

도구 에이전트에 실제 격리가 필요하면 sandboxAgent.asTool(...)을 통해 자체 runConfig를 제공하세요. 도구 에이전트가 자유롭게 변경 작업을 수행하거나, 신뢰할 수 없는 명령을 실행하거나, 다른 백엔드 또는 이미지를 사용해야 한다면 별도의 샌드박스를 사용하세요.

로컬 도구 및 MCP와의 결합

동일한 에이전트에서 일반 도구를 계속 사용하면서 샌드박스 작업 공간을 유지하세요. 샌드박스 기능은 tools, mcpServers, 핸드오프, 모델 설정 및 출력 설정과 함께 사용할 수 있습니다.

메모리

향후 샌드박스 에이전트 실행에서 이전 실행으로부터 학습해야 한다면 memory() 기능을 사용하세요. 메모리는 SDK의 대화형 Session 메모리와 별개입니다. 학습 내용을 샌드박스 작업 공간 내부의 파일로 정제한 후 이후 실행에서 해당 파일을 읽을 수 있습니다.

설정, 읽기/생성 동작, 멀티턴 대화 및 레이아웃 격리에 관한 자세한 내용은 에이전트 메모리를 참조하세요.

구성 패턴

단일 에이전트 패턴을 이해한 다음에는 더 큰 시스템에서 샌드박스 경계를 어디에 둘지 결정해야 합니다.

샌드박스 에이전트는 SDK의 다른 기능과 계속 조합할 수 있습니다.

핸드오프: 샌드박스를 사용하지 않는 접수 에이전트에서 문서 중심 작업을 샌드박스 검토 에이전트로 전달
Agents as tools: 여러 샌드박스 에이전트를 도구로 노출하며, 일반적으로 각 asTool(...) 호출에 샌드박스 실행 설정을 전달하여 각 도구에 자체 샌드박스 경계를 제공
모델 컨텍스트 프로토콜 (MCP) 및 일반 함수 도구: 샌드박스 기능을 mcpServers 및 일반 도구와 함께 사용
에이전트 실행: 샌드박스 실행에서도 일반적인 run() 및 Runner API 사용

핸드오프를 사용해도 최상위 실행과 최상위 턴 루프는 각각 하나씩 유지됩니다. 활성 에이전트는 변경되지만 실행이 중첩되지는 않습니다.

asTool(...)에서는 관계가 다릅니다. 외부 오케스트레이터는 하나의 외부 턴을 사용해 도구 호출을 결정하며, 해당 도구 호출은 샌드박스 에이전트의 중첩 실행을 시작합니다. 중첩 실행에는 자체 턴 루프, maxTurns, 승인 및 일반적으로 자체 샌드박스 실행 설정이 있습니다. 외부 오케스트레이터의 관점에서는 이 모든 작업이 하나의 도구 호출 뒤에서 수행되므로, 중첩된 턴은 외부 실행의 턴 카운터를 증가시키지 않습니다.

추가 자료

빠른 시작: 샌드박스 에이전트 하나 실행
샌드박스 클라이언트: 로컬, Docker, 호스티드 및 마운트 옵션 선택
에이전트 메모리: 이전 샌드박스 실행에서 얻은 학습 내용 보존 및 재사용