빠른 시작

최신 에이전트는 파일시스템의 실제 파일을 다룰 수 있을 때 가장 효과적으로 작동합니다. Agents SDK의 샌드박스 에이전트는 모델에 영속적인 작업 공간을 제공하여 대규모 문서 모음을 검색하고, 파일을 편집하고, 명령을 실행하고, 산출물을 생성하고, 저장된 샌드박스 상태에서 작업을 재개할 수 있게 합니다.

SDK는 파일 스테이징, 파일시스템 도구, 셸 접근, 샌드박스 수명 주기, 스냅샷, 제공자별 연동 코드를 직접 연결할 필요 없이 이러한 실행 환경을 제공합니다. 기존 Agent와 Runner 흐름을 그대로 유지하면서 작업 공간을 위한 Manifest, 샌드박스 네이티브 도구를 위한 기능, 작업 실행 위치를 지정하는 sandbox 실행 옵션을 추가하면 됩니다.

사전 요구 사항

Node.js 22 이상
OpenAI Agents SDK에 대한 기본적인 이해
샌드박스 클라이언트. macOS 또는 Linux에서 신뢰할 수 있는 로컬 개발 작업을 할 때는 UnixLocalSandboxClient로 시작하세요. Windows에서는 대신 DockerSandboxClient나 호스팅 샌드박스 클라이언트를 사용하세요.

이 빠른 시작에서는 Node.js와 npm 명령을 사용하지만, SDK가 Node.js에만 한정되는 것은 아닙니다. 프로젝트에서 호환되는 패키지 해석 방식과 런타임 API를 사용한다면 샌드박스 에이전트를 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/ 아래에 스테이징하고, 로컬 스킬을 지연 로드하며, 러너가 이번 실행을 위한 Unix 로컬 샌드박스 세션을 생성하도록 합니다. 에이전트 정의에 매니페스트와 기능을 지정하고, 실행 설정에서는 이번 실행에 사용할 샌드박스 클라이언트만 선택합니다.

UnixLocalSandboxClient는 macOS와 Linux 모두에서 명령을 호스트 프로세스로 실행합니다. 이 클라이언트는 OS 수준의 파일시스템 또는 네트워크 격리를 추가하지 않습니다. 이 예제는 신뢰할 수 있는 로컬 개발 작업이나 외부에서 격리된 환경 내에서 사용하세요. 신뢰할 수 없는 입력의 영향을 받는 명령을 비롯하여 신뢰할 수 없는 명령을 실행할 때는 적절히 구성된 Docker 또는 호스팅 백엔드를 선택하거나 외부 격리를 제공하세요. Unix 로컬 실행 제한을 참고하세요.

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);

주요 선택 사항

기본 실행이 정상적으로 작동하면 일반적으로 다음 사항을 선택하게 됩니다:

defaultManifest: 새 샌드박스 세션에 사용할 파일, 저장소, 디렉터리, 마운트
instructions: 여러 프롬프트에 걸쳐 적용할 간단한 워크플로 규칙
baseInstructions: SDK 샌드박스 프롬프트를 대체하기 위한 고급 재정의 수단
capabilities: 파일시스템 편집/이미지 검사, 셸, 스킬, 메모리, 압축 등의 샌드박스 네이티브 도구
runAs: 모델에 제공되는 도구에 사용할 샌드박스 사용자 ID
sandbox.client: 샌드박스 백엔드
sandbox.session, sandbox.sessionState 또는 sandbox.snapshot: 이후 실행에서 이전 작업에 다시 연결하는 방식

다음 단계

개념: 매니페스트, 기능, 권한, 스냅샷, 실행 설정, 구성 패턴을 이해합니다.
샌드박스 클라이언트: Unix 로컬, Docker, 호스팅 제공자, 마운트 전략을 선택합니다.
에이전트 메모리: 이전 샌드박스 실행에서 얻은 교훈을 보존하고 재사용합니다.

셸 접근이 가끔 사용하는 도구 중 하나일 뿐이라면 도구 가이드의 호스팅 셸로 시작하세요. 작업 공간 관리, 샌드박스 클라이언트 선택, 샌드박스 세션 재개 동작이 설계의 일부라면 샌드박스 에이전트를 사용하세요.