에이전트의 실행을 격리 환경으로 내보내는 OpenAI의 Sandbox Agents

에이전트에게 셸(Shell) 권한을 부여하면, 대개 두 가지 불안감이 동시에 찾아온다. 하나는 "rm -rf를 입력하면 어떡하지"라는 보안 측면이다. 다른 하나는 "20분 동안 패키지를 설치하고 중간 파일을 만든 작업이 프로세스가 종료되는 순간 사라진다"는 지속성 문제다. 도구 호출(Tool calling)을 나열하기만 한 에이전트는 이 두 가지 모두에 취약하다.

OpenAI의 Agents SDK에 도입된 Sandbox Agents는 이 문제를 정면으로 재설계한 기능이다. JavaScript/TypeScript 버전(@openai/agents)은 6월 24일에 v0.12.0으로 업데이트되었으며, Python 버전과 함께 샌드박스 실행 주변 환경이 상당히 갖춰졌다. 무엇이 새로워졌고, 현직 엔지니어로서 어떻게 활용할 수 있는지 1차 자료를 통해 분석해 본다.

일반적인 에이전트는 모델이 "이 도구를 호출하라"고 말하면, 사용자의 프로세스가 그 자리에서 실행한다. 파일 쓰기도 셸 실행도 사용자의 환경에서 일어난다. Sandbox Agents는 이 실행을 격리된 Unix 라이크(Unix-like) 환경으로 내보낸다. 공식 문서에서는 이 환경을 파일 시스템, 셸, 설치된 패키지, 마운트된 데이터, 공개 포트, 스냅샷(Snapshot), 재개 가능한 상태를 가진 것으로 설명한다.

즉, 에이전트에게 전달하는 것은 단발성 함수가 아니라 작업 공간 그 자체다. 문서 뭉치를 읽게 하거나, 검증용 파일을 작성하거나, pip install을 통해 무언가를 실행하거나, 결과물을 생성하거나, 서비스를 구축하거나, 사람의 리뷰 후에 재개하는 작업 등이 가능하다. 이러한 "한 번의 프롬프트로 끝나지 않는 업무"를 호스트 환경을 더럽히지 않고 수행할 수 있다. 에이전트가 폭주하더라도 피해는 상자(Box) 안에 갇힌다.

로컬 Unix 샌드박스에서 구동하는 최소 예제는 공식 가이드의 퀵스타트(Quickstart)와 동일하다.

npm install @openai/agents zod

import { run } from "@openai/agents";
import { Manifest, SandboxAgent, file, shell } from "@openai/agents/sandbox";
import { UnixLocalSandboxClient } from "@openai/agents/sandbox/local";
...

Manifest는 상자를 실행한 직후의 파일 배치를 선언하는 것으로, 에이전트는 이를 기점으로 움직인다. capabilities를 통해 무엇을 허용할지 추가해 나간다. 일반적인 Agent를 SandboxAgent로 바꾸고, run에 sandbox.client를 전달하기만 하면 되는 낮은 진입 장벽은 솔직히 호감이 간다.

개인적으로 가장 효과적이라고 생각하는 점은 장시간의 작업을 중간에 멈추고 사람이 리뷰한 뒤, 그대로 이어서 재개할 수 있다는 점이다. 이는 상태(State)를 세 가지로 나누어 관리하는 설계로 구현되어 있다.

상태	보유 항목
RunState	모델의 이력, 도구의 상태, 승인, 현재 어떤 에이전트가 동작 중인지
Session state	재연결 가능한, 직렬화(Serialized)된 샌드박스 세션
snapshot	새로운 세션을 시작할 때의 씨앗이 되는, 저장된 워크스페이스의 내용

러너(Runner)는 먼저 살아있는 세션을 찾고, 없으면 저장된 RunState로부터 복구하며, 그것도 없으면 명시적인 샌드박스 상태를 사용한 뒤 마지막으로 신규 세션을 생성한다. 대화의 문맥(RunState)과 실행 환경의 내용(snapshot)을 별개로 취급하는 것이 핵심이다. 따라서 "위험한 조작 직전에 승인 대기 상태로 만들고, 사람이 OK를 누르면 상자를 다시 세워 계속 진행"하는 것과 같이 사람을 개입시킨 워크플로(Workflow)가 깨지지 않는다. 에이전트를 장시간 구동할 때 매번 걸림돌이 되는 것이 바로 이 상태 관리이므로, SDK 측에서 이를 담당해 주는 것은 큰 이점이다.

능력(capabilities)에는 Shell이나 Filesystem 외에도 Skills와 Memory가 있다. 이 두 가지는 지금까지 각자가 수동으로 구축해 왔던 "에이전트의 주변 기능"을 SDK가 표준화하려 한다는 성격이 짙다.

Skills는 작업을 시작하기 전에 필요한 지시, 스크립트, 참조, 소재를 가져오는 메커니즘으로, 로컬 디렉토리나 Git 리포지토리(Repository)에서 읽어올 수 있다. 모델에게 먼저 인덱스(Index)를 보여주고, 필요한 것만 전개(Expand)하게 한다. Memory...

는 대화 이력(Conversation History)과는 별개의 것으로, 여러 실행(Execution)을 가로질러 재사용할 수 있는 학습 내용을 남긴다. 요약을 추출하여 마크다운(Markdown)으로 고정하고, 나중에 다시 읽는다. 읽기 전용(Read-only), 생성 전용(Write-only), 양방향(Bidirectional) 모드를 선택할 수 있다. 과거 작업에서 얻은 지식을 이력을 통째로 재생하지 않고도 계승할 수 있는 것이다.

이 부분은 Claude 주변에서 언급되는 "SKILL.md"나 에이전트 메모리(Agent Memory)의 발상과 명확하게 겹친다. 각 기업이 서로 다른 이름으로 동일한 부품으로 수렴하고 있다는 것을 알 수 있다.

샌드박스(Sandbox)의 실체를 어디서 구동할지는 run에 전달하는 클라이언트(Client)에 의해 결정된다. 로컬에서 테스트하려면 UnixLocalSandboxClient를, 운영 환경에서 확장(Scale)하고 싶다면 다른 프로바이더(Provider)로 교체한다. 문서에 따르면 지원 대상은 로컬을 포함하여 Blaxel, Cloudflare, Daytona, Docker, E2B, Modal, Runloop, Vercel, 그리고 자체 구현을 포함하여 총 10개 계통이다. 각각 격리 방식(Isolation method), 스토리지(Storage), 인증 정보(Credentials) 처리 방식이 다르다.

이 점이 은근히 중요한데, 에이전트의 코드는 거의 바꾸지 않고 실행 기반(Execution Infrastructure)만 교체할 수 있다. "로컬에서 만들고, 그대로 클라우드 격리 환경으로"가 한 줄로 해결된다. 샌드박스가 이미 이만큼의 벤더(Vendor)를 끌어들이고 있다는 사실은, 에이전트의 주전장이 모델의 지능에서 "어디서, 어떻게 안전하게 코드를 실행할 것인가"로 옮겨가고 있다는 반증이기도 하다.

도구로서 가벼운 질의나 단발적인 도구 호출(Tool Call)이라면 일반적인 Agent로 충분하다. Sandbox Agents가 빛을 발하는 때는 파일을 묶음으로 다루거나, 명령(Command)이나 패키지(Package)를 실행하거나, 결과물을 만들거나, 사람의 리뷰를 거쳐 재개하는 등의 "환경을 가진 작업"을 할 때다. 반대로 그 부분을 자체적인 Docker와 큐(Queue), 상태 DB(State DB)로 구축하고 있다면, 해당 계층을 SDK로 옮길 수 있을지 한 번 비교해 볼 가치가 있다. TypeScript와 Python 모두에서 동일한 개념을 사용할 수 있으므로, 우선 UnixLocalSandboxClient로 로컬의 작은 태스크를 하나 통과시켜 보는 것이 감을 잡는 지름길이라고 생각한다.