OpenAI Agents SDK 네이티브 샌드박스 및 Manifest 가이드

OpenAI는 2026년 4월 15일 중요한 Agents SDK 업데이트를 출시했고, 출시 글의 설치 명령이 그 신호였습니다. pip install "openai-agents>=0.14.0" (OpenAI). 이 버전 라인은 중요합니다. 이는 새 프롬프트 템플릿이나 또 다른 함수 호출 래퍼가 아니었습니다. OpenAI가 파일 작업, 셸 작업, 패치 적용, 샌드박스 생명주기, 워크스페이스 설명을 SDK 수준의 프리미티브로 옮긴 것이었습니다.

코딩 에이전트, 문서 에이전트, 데이터 정리 에이전트, 저장소 유지보수 봇을 만드는 개발자에게 이 설계 변화는 단순합니다. 모든 팀이 Docker, 임시 디렉터리, 도구 스키마, 파일 스테이징, 재시도 로직을 둘러싼 취약한 하네스를 매번 다시 만들지 않아도 된다는 뜻입니다. 이제 SDK는 모델 네이티브 하네스, 샌드박스 네이티브 실행, 파일시스템 도구, MCP, AGENTS.md, 셸 접근, apply_patch, 그리고 이식 가능한 워크스페이스를 설명하기 위한 Manifest 추상화를 제공합니다.

변화: 도구 호출에서 실제 워크스페이스로

기존 Agents SDK도 이미 오케스트레이션에는 유용했습니다. 에이전트, 도구, 핸드오프, 가드레일, 트레이싱을 제공했기 때문입니다. 4월 업데이트는 시간이 지남에 따라 파일을 다뤄야 하는 에이전트에 부족했던 런타임 형태를 추가합니다.

OpenAI는 업데이트된 SDK가 개발자가 제어된 샌드박스 환경 안에서 파일을 검사하고, 명령을 실행하고, 코드를 수정하고, 장기 작업을 수행할 수 있는 에이전트를 구축하도록 돕는다고 설명합니다 (OpenAI). 여기서 핵심은 “제어된 워크스페이스”라는 표현입니다. 진지하게 파일을 다루는 에이전트에는 도구 목록 이상의 것이 필요합니다. 루트 디렉터리, 마운트된 입력, 출력 위치, 셸, 권한, 스냅샷, 컨테이너가 죽었을 때 재개할 방법이 필요합니다.

이 업데이트 전의 일반적인 프로덕션 구성은 다음과 같았습니다.

• 임시 워크스페이스 생성
• 그 안으로 파일 복사
• 읽기, 쓰기, 셸, 패치 도구 노출
• 경로 수동 검증
• 샌드박스 또는 컨테이너 시작
• 아티팩트 수집
• 작업이 길어지면 상태 스냅샷 저장
• 이 모든 것을 모델이 이해할 수 있는 지시문으로 변환

많은 에이전트 프로젝트가 조용히 지저분해지는 지점이 바로 이 글루 코드입니다. 새 SDK는 그중 많은 부분을 일급 구성으로 바꿉니다.

OpenAI의 출시 글은 Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel을 샌드박스 제공자로 기본 지원하며, “직접 샌드박스 가져오기” 경로도 제공한다고 밝혔습니다 (OpenAI). 출시 시점에 호스팅 제공자 7곳과 로컬 개발 경로가 함께 제공된 것입니다.

Manifest는 이식성 계층입니다

Manifest 추상화는 이번 릴리스에서 가장 실용적인 부분입니다. 모델이 작업을 시작하기 전에 샌드박스 워크스페이스에 무엇이 들어 있어야 하는지를 설명합니다.

Python 문서에서 Sandbox Agents는 베타로 표시되어 있으며, Python 3.10 이상이 필요하고, 모델에 문서 세트를 검색하고, 파일을 편집하고, 명령을 실행하고, 아티팩트를 생성하고, 저장된 샌드박스 상태에서 재개할 수 있는 영속 워크스페이스를 제공하는 방법으로 소개됩니다 (OpenAI Agents SDK Python 문서).

간단한 Python 형태는 다음과 같습니다.

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import LocalDir
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

agent = SandboxAgent(
    name="Repo maintainer",
    model="gpt-5.5",
    instructions="Read repo/task.md, edit with apply_patch, then run the targeted test.",
    default_manifest=Manifest(entries={"repo": LocalDir(src="./repo")}),
)

result = await Runner.run(
    agent,
    "Fix the failing test and summarize the change.",
    run_config=RunConfig(
        sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())
    ),
)

중요한 것은 문법이 아닙니다. 계약입니다. Manifest는 로컬 파일, 디렉터리, Git 저장소, 합성 파일, 환경 변수, 사용자, 그룹, 출력 디렉터리, 원격 스토리지 마운트를 설명할 수 있습니다. JavaScript 문서에 따르면 Manifest 엔트리 경로는 워크스페이스 기준 상대 경로여야 하며, 절대 경로가 될 수 없고, ..로 워크스페이스를 벗어날 수 없습니다. 이는 모든 프롬프트에서 기억해야 하는 대신 런타임이 강제해 주길 바라는, 바로 그런 지루하지만 중요한 제약입니다 (OpenAI Agents SDK JS 문서).

기능: 셸, 파일시스템, 스킬, 메모리, 컴팩션

SandboxAgent는 임시 폴더가 붙은 일반 에이전트에 그치지 않습니다. 샌드박스 전용 기능을 함께 갖습니다.

JS 개념 문서는 기본 제공 기능으로 shell(), filesystem(), skills(), memory(), compaction()을 나열합니다 (OpenAI Agents SDK JS 문서). 여기서는 기본값이 중요합니다. 문서에 따르면 Capabilities.default()에는 파일시스템, 셸, 컴팩션이 포함됩니다. 즉 일반적인 코딩 에이전트 루프가 더 이상 맞춤 도구 정의 더미가 아니라는 뜻입니다.

파일시스템 기능은 패치 스타일의 파일 편집을 노출합니다. 셸 기능은 샌드박스 세션 안에서 명령 실행을 노출합니다. 스킬은 특화된 지시나 절차를 점진적으로 공개할 수 있게 합니다. 메모리와 컴팩션은 긴 실행에서 유용한 상태를 유지하면서도 이전 모든 토큰을 다음 턴에 다시 밀어 넣지 않도록 돕습니다.

이는 강력한 코딩 에이전트가 실제로 작동하는 방식과 맞습니다. 에이전트는 검사합니다. 명령을 실행합니다. 파일을 수정합니다. 더 작은 명령을 실행합니다. diff를 확인합니다. 변경 내용을 요약합니다. 하네스가 각 단계를 서로 무관한 API 호출로 취급하면 모델은 자신의 세계를 재구성하는 데 너무 많은 주의를 씁니다. 샌드박스 세션은 모델이 딛고 설 자리를 제공합니다.

AGENTS.md도 이 모델에 자연스럽게 들어맞습니다. 공개 AGENTS.md 사이트는 이를 코딩 에이전트를 안내하기 위한 Markdown 형식으로 설명하며, 60,000개 이상의 오픈소스 프로젝트에서 사용된다고 말합니다 (AGENTS.md). 이 파일에는 빌드 명령, 테스트 지침, 스타일 규칙, 저장소별 주의사항이 들어가야 합니다. 샌드박스 세계에서 AGENTS.md는 모든 작업에 붙여 넣는 거대한 프롬프트가 아니라 워크스페이스 로컬 운영 컨텍스트가 됩니다.

Python 우선, TypeScript는 따라오는 중

출시 당시에는 Python 우선이었습니다. TechCrunch는 4월 15일 새 하네스와 샌드박스 기능이 Python에서 먼저 출시되고, TypeScript 지원은 이후 계획되어 있다고 보도했습니다 (TechCrunch). PyPI도 그 날짜를 뒷받침합니다. openai-agents 버전 0.14.0과 0.14.1이 2026년 4월 15일 업로드되었습니다 (PyPI).

2026년 6월 16일 기준으로, 실무적인 그림은 더 균형 잡혀 있습니다. 공식 JS 문서에는 이제 베타 Sandbox Agents가 포함되어 있고, Node.js 22 이상을 요구하며, Manifest, SandboxAgent, UnixLocalSandboxClient, Docker 지원, 그리고 @openai/agents-extensions를 통한 호스팅 제공자 클라이언트를 보여 줍니다 (OpenAI Agents SDK JS 퀵스타트). JS 문서는 또한 패키지 해석과 런타임 API가 호환될 때 Deno와 Bun도 작동할 수 있다고 언급합니다.

영역	Python	TypeScript / JavaScript
4월 15일 출시 상태	최초 지원 경로	이후 계획
현재 샌드박스 문서	베타, Python 3.10+	베타, Node.js 22+
로컬 샌드박스	UnixLocalSandboxClient	UnixLocalSandboxClient
Docker 샌드박스	openai-agents[docker]	DockerSandboxClient
호스팅 제공자	SDK 통합을 통해 지원	@openai/agents-extensions 제공자 경로

그렇다고 두 생태계가 동일하다는 뜻은 아닙니다. Python은 최초 출시 표면이었고, 많은 예제가 여전히 Python에 먼저 도착합니다. TypeScript도 이제 실제 샌드박스 에이전트를 프로토타이핑할 만큼 공식 표면적을 갖췄지만, 호스팅 제공자 세부사항, PTY 동작, 마운트, 생명주기 지원은 여전히 백엔드별로 주의 깊게 읽어야 합니다.

지금 파일 작업 에이전트를 구성한다면

실수는 샌드박스를 마법 같은 안전 상자로 취급하는 것입니다. 샌드박스는 런타임 경계이지 제품 명세가 아닙니다. 여전히 워크스페이스를 설계해야 합니다.

깔끔한 구조는 다음과 같습니다.

• repo/: 작업 트리 또는 마운트된 저장소
• task.md: 모델이 가장 먼저 읽어야 하는 작업 명세
• inputs/: 읽기 전용 문서, 데이터셋, 스크린샷 또는 로그
• output/: 최종 생성 아티팩트가 위치해야 하는 유일한 장소
• AGENTS.md: 빌드, 테스트, 스타일, 안전 지침
• 샌드박스 사용자: 백엔드가 지원하는 경우 non-root ID
• Manifest env: 기본적으로 유지되는 비밀이 아닌 설정, ephemeral로 표시된 시크릿

Manifest는 입력을 설명해야 합니다. 에이전트 지시문은 워크플로를 설명해야 합니다. 사용자 프롬프트는 일회성 작업을 설명해야 합니다. 이들을 분리해 두세요. JS 문서는 긴 참고 자료가 Manifest에 들어가야 할 때 instructions에 우겨 넣지 말라고 명시적으로 경고합니다 (OpenAI Agents SDK JS 문서).

프로덕션에서는 데모 경로가 아니라 폭발 반경을 기준으로 백엔드를 선택하세요. Unix-local은 개발용으로 괜찮습니다. 반복 가능성이 필요할 때는 Docker가 더 나은 기본값입니다. 실행마다 깨끗한 격리, 원격 실행, 확장, 또는 제공자별 스냅샷 동작이 필요할 때는 호스팅 제공자가 적합합니다. JS 클라이언트 문서는 호스팅 제공자 지원이 다양하며, 개발자가 환경 변수, 포트, PTY, 스냅샷, 정리 동작에 대해 제공자 문서를 확인해야 한다고 말합니다 (OpenAI Agents SDK JS 클라이언트).

생태계 관점

이 업데이트가 중요한 이유는 파일 작업 에이전트의 형태를 표준화하기 때문입니다. 업계는 이미 몇 가지 프리미티브로 수렴했습니다. 외부 도구를 위한 MCP, 저장소 지침을 위한 AGENTS.md, 실제 검사를 위한 셸, 검토 가능한 수정을 위한 패치, 격리를 위한 샌드박스입니다. OpenAI의 Agents SDK는 이제 개발자가 실제로 조합할 수 있는 런타임 안에 이 조각들을 패키징합니다.

여전히 날카로운 모서리는 권한입니다. 넓은 네트워크, 쓰기 가능한 마운트, 장기 자격 증명, 모호한 지시를 가진 샌드박스 에이전트는 여전히 피해를 줄 수 있습니다. Manifest는 워크스페이스 입력과 권한 부여를 가시화하기 때문에 도움이 됩니다. 하지만 승인 정책, 시크릿 위생, 의존성 고정, 아티팩트 검토의 필요성을 없애지는 않습니다.

오늘날 가장 좋은 사용 사례는 “에이전트가 모든 것을 한다”가 아닙니다. 더 좁고 더 가치 있는 방식입니다. 모델에 제한된 워크스페이스, 명확한 작업 파일, 저장소 로컬 지침, 셸과 패치 도구, 하나의 명시적 검증 경로를 제공하세요. 폐기 가능한 환경에서 주니어 엔지니어처럼 작업하게 하세요. 그런 다음 diff를 검토하세요.

이는 채팅 루프 주변에 또 다른 반쪽짜리 샌드박스를 직접 만드는 것보다 훨씬 건강한 추상화입니다.

이 모델들을 직접 사용해 보고 싶은 독자는 base_url 하나만 바꿔 OpenAI 호환 API로 onehop을 통해 호출할 수 있습니다. 퍼스트파티보다 저렴하고, 신규 계정은 카드 없이 $10 무료 크레딧을 받을 수 있습니다. onehop에서 Claude 및 기타 모델 호출하기, 또는 $10 무료 크레딧으로 가입하기.