빠른 시작

현대적인 에이전트는 파일시스템의 실제 파일을 대상으로 작업할 수 있을 때 가장 잘 동작합니다. Agents SDK 의 Sandbox Agents 는 모델에 지속적인 작업 공간을 제공하여, 대규모 문서 집합 검색, 파일 편집, 명령 실행, 아티팩트 생성, 그리고 저장된 샌드박스 상태에서 작업 재개를 가능하게 합니다.

SDK 는 파일 스테이징, 파일시스템 도구, 셸 접근, 샌드박스 수명 주기, 스냅샷, 공급자별 연결 코드를 직접 조합하지 않아도 이 실행 하네스를 제공합니다. 일반적인 Agent 및 Runner 흐름은 그대로 유지하면서, 작업 공간용 Manifest, 샌드박스 네이티브 도구용 capabilities, 그리고 작업 실행 위치를 지정하는 sandbox 실행 옵션만 추가하면 됩니다.

사전 요구 사항

Node.js 22 이상
OpenAI Agents SDK 에 대한 기본적인 이해
샌드박스 클라이언트. 로컬 개발에서는 UnixLocalSandboxClient 로 시작하세요

이 quickstart 는 Node.js 와 npm 명령을 사용하지만, SDK 가 Node.js 에만 한정되는 것은 아닙니다. 프로젝트에서 호환되는 패키지 해석과 런타임 API 를 사용한다면 Sandbox agent 는 Deno 와 Bun 에서도 실행할 수 있습니다.

설치

아직 SDK 를 설치하지 않았다면 다음을 실행하세요:

npm install @openai/agents

Docker 기반 샌드박스의 경우, 로컬에 Docker 를 설치하고 @openai/agents/sandbox/local 의 DockerSandboxClient 를 사용하세요.

tty: true 로 대화형 로컬 PTY 세션을 사용하는 경우, SDK 를 실행하는 프로세스에서도 python3 또는 OPENAI_AGENTS_PYTHON 을 통해 Python 3 를 사용할 수 있어야 합니다. PTY 가 아닌 셸 명령에는 Python 이 필요하지 않습니다.

로컬 샌드박스 에이전트 생성

이 예제는 로컬 리포지토리를 repo/ 아래에 스테이징하고, 로컬 skills 를 지연 로드하며, 실행 시 runner 가 Unix-local 샌드박스 세션을 생성하도록 합니다. 에이전트 정의는 manifest 와 capabilities 를 소유하고, 실행 구성은 이번 실행에 사용할 샌드박스 클라이언트만 선택합니다.

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.5',
  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(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);

핵심 선택 사항

기본 실행이 동작하면, 대부분의 사용자가 다음으로 고려하는 선택 사항은 다음과 같습니다:

defaultManifest: 새 샌드박스 세션에 사용할 파일, 리포지토리, 디렉터리, 마운트
instructions: 프롬프트 전반에 공통으로 적용할 짧은 워크플로 규칙
baseInstructions: SDK 샌드박스 프롬프트를 대체하기 위한 고급 escape hatch
capabilities: 파일시스템 편집/이미지 검사, 셸, skills, 메모리, compaction 과 같은 샌드박스 네이티브 도구
runAs: 모델 대상 도구에 사용할 샌드박스 사용자 신원
sandbox.client: 샌드박스 백엔드
sandbox.session, sandbox.sessionState, 또는 sandbox.snapshot: 이후 실행이 이전 작업에 다시 연결하는 방식

다음 단계

개념: manifest, capabilities, 권한, 스냅샷, 실행 구성, 구성 패턴을 이해합니다
샌드박스 클라이언트: Unix-local, Docker, 호스티드 공급자, 마운트 전략 중에서 선택합니다
에이전트 메모리: 이전 샌드박스 실행의 학습 내용을 보존하고 재사용합니다

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