LLM WikiAccess-protected knowledge portal

WIKI

OpenAI Agents SDK Sandbox & Harness: 에이전트를 신뢰 경계 기준으로 제어면과 실행면으로 분리한 방법

왜 이 업데이트를 지금 봐야 하나 2026년 4월 15일 공개된 OpenAI Agents SDK 업데이트는 에이전트 아키텍처를 신뢰 경계 기준으로 두 층으로 분리 한 것이 핵심이다. 릴리스에서 눈에 띄는 변화는 세 가지다. 샌드박스 Sandbox 장기 실행 에이전트를 위한 격리된 실행 환경. 파일, 도구, 의존성에 접근하면서도 시스템 전체를 보호한다. 하네스 컴퓨트 분리 제어면 harness 과 실행면 compute 을 나눠

경로human/study/content/ai-frontier/19-openai-agents-sdk-sandbox-harness-manifest.md
카테고리Study
태그#agents #ai-review #harness #manifest #sandbox #sdk #study

왜 이 업데이트를 지금 봐야 하나

2026년 4월 15일 공개된 OpenAI Agents SDK 업데이트는 에이전트 아키텍처를 신뢰 경계 기준으로 두 층으로 분리한 것이 핵심이다. 릴리스에서 눈에 띄는 변화는 세 가지다.

이 세 가지는 서로 다른 문제를 푼다.

  1. 보안: 모델이 생성한 셸 명령이 루프 자격 증명을 읽을 수 없다. 하네스와 샌드박스를 분리해 폭발 반경(blast radius)을 가둔다.
  2. 내결함성: 샌드박스 컨테이너가 죽거나 만료돼도 스냅샷과 재수화(rehydrate)로 마지막 체크포인트에서 이어받는다.
  3. 이식성: E2B, Modal, Runloop 같은 여러 제공자 중 어느 것을 써도 같은 Manifest로 에이전트 환경을 기술한다.

이 업데이트는 "새 기능 추가"보다 에이전트 시스템을 두 신뢰 도메인으로 나누는 설계 원칙의 공식화에 가깝다. 이전 SDK가 루프 오케스트레이션만 다뤘다면, 이번부터는 실행 환경 보안과 상태 내구성까지 SDK가 책임진다.

전체 구조: 두 층과 그 경계

OpenAI Agents SDK — Harness / Sandbox 신뢰 경계 신뢰 도메인: Harness (영속, 제어면) 비신뢰 도메인: Sandbox (일시적, 실행면) Harness (제어면 — 신뢰됨) LLM 루프 모델 호출 (100+ LLM 지원) Chat Completions 호환 API OpenAI·Anthropic·Gemini·Llama 등 메모리 (2종) ① 세션 메모리: 대화 이력 SQLite / SQLAlchemy / Redis ② 샌드박스 메모리: 파일→교훈 증류 Manifest (워크스페이스 정의) 로컬 파일 마운트 · 출력 디렉터리 정의 · 스토리지 연동 AWS S3 · GCS · Azure Blob Storage · Cloudflare R2 스냅샷 & 재수화 (State Persistence) 샌드박스 실패 시 마지막 체크포인트에서 새 컨테이너로 복원 자격 증명은 하네스에 유지 — 모델 생성 코드 접근 불가 서브에이전트 오케스트레이션 병렬 샌드박스 · 작업별 격리 환경 · 다중 컨테이너 조율 신뢰 경계 Sandbox (실행면 — 비신뢰됨) 샌드박스 제공자 (선택) Blaxel Cloudflare Daytona E2B Modal Runloop Vercel 자체 구축 가능 Manifest로 이식 가능 — 제공자 교체 시 에이전트 코드 수정 불필요 Codex 파일시스템 도구 read_file · write_file · run_command · edit_file git_* (commit, diff, push) · 기타 컨테이너 도구 실행은 컨테이너 내부 — 하네스 자격 증명과 격리됨 격리 실행 컨테이너 Git, 스냅샷, 의존성, 파일시스템 접근 컨테이너 만료/실패 → 하네스가 스냅샷에서 신규 컨테이너 복원 보안 강화 (v0.x+) 워크스페이스 수화 시 심볼릭 링크 탈출 아카이브 거부 (symlink escape 방지) 도구 호출 결과 반환 스냅샷 핵심 보안 원칙: 하네스는 영속적·신뢰됨 / 샌드박스는 일시적·비신뢰됨 자격 증명은 하네스에 보관 — 모델이 생성한 코드가 루프 비밀에 접근하는 경로가 없다. 샌드박스 실패는 실행의 손실이지 상태의 손실이 아니다.
OpenAI Agents SDK — Harness·Sandbox·Manifest 아키텍처

1. 하네스-샌드박스 분리: 왜 두 층인가

이번 업데이트 이전의 에이전트 SDK는 모델 루프(harness)를 잘 다뤘지만, 실행 환경 보안은 개발자 책임이었다. 에이전트가 파일을 읽고 코드를 실행하려면 직접 파일시스템에 접근하거나, 별도 샌드박스를 구성하고 연결해야 했다.

이 구조에서 가장 위험한 지점은 하나다. 모델이 생성한 셸 명령이 API 키, 데이터베이스 비밀, 클라우드 토큰 같은 루프 자격 증명에 접근할 수 있다는 점이다. 프롬프트 인젝션이나 악의적인 데이터가 에이전트 루프에 들어오면, 자격 증명이 같은 실행 공간에 있으면 폭발 반경이 크다.

업데이트는 이 문제를 구조적으로 푼다.

하네스는 샌드박스를 호출하지만 공유 메모리 공간에서 돌지 않는다. 두 층의 경계가 신뢰 경계이기도 하다.

샌드박스 실패는 실행의 손실이지 상태의 손실이 아니다

SDK의 스냅샷-재수화 메커니즘이 이 원칙을 실행 가능하게 만든다.

  1. 하네스가 주기적으로 에이전트 상태를 스냅샷으로 저장한다.
  2. 샌드박스 컨테이너가 만료되거나 실패하면 하네스가 감지한다.
  3. 하네스는 새 컨테이너를 프로비저닝하고 마지막 스냅샷에서 워크스페이스를 복원한다.
  4. 에이전트는 마지막 체크포인트에서 이어받는다.

개발자가 별도의 복구 로직을 작성하지 않아도 된다. 이 로직이 SDK 안으로 들어왔다.

2. Manifest 추상화: 샌드박스 환경의 이식성

샌드박스 환경마다 API가 다르면 코드가 제공자에 종속된다. 이 문제를 풀기 위해 SDK는 Manifest 추상화를 도입한다.

Manifest는 에이전트가 어떤 환경에서 실행돼야 하는지를 선언적으로 기술하는 구조체다.

manifest = Manifest(
    inputs=["src/", "data/input.csv"],           # 마운트할 로컬 파일/디렉터리
    outputs=["reports/", "artifacts/"],           # 에이전트가 생성할 출력 디렉터리
    storage={
        "s3": S3Config(bucket="my-bucket", prefix="agent-runs/"),
    },
)

같은 Manifest로 E2B, Modal, Runloop, 또는 자체 구축 샌드박스 중 어느 것에서도 에이전트를 실행할 수 있다. 샌드박스 제공자를 교체해도 에이전트 코드는 바뀌지 않는다.

지원 스토리지 제공자

Manifest는 로컬 파일 마운트 외에 다음 클라우드 스토리지를 연동한다.

제공자용도
AWS S3대규모 데이터셋 입력, 결과 아카이빙
Google Cloud StorageGCP 환경 통합
Azure Blob StorageAzure 환경 통합
Cloudflare R2엣지 가까운 스토리지

스토리지 제공자 연결도 Manifest 수준에서 선언된다. 에이전트 코드 안에 클라우드 SDK 연결 코드를 직접 작성하지 않아도 된다.

3. 메모리 시스템: 세션 메모리와 샌드박스 메모리

SDK는 메모리를 두 층으로 나눈다.

세션 메모리

대화 이력과 에이전트 컨텍스트를 저장하는 메모리다. 하네스에 속하며 신뢰된 공간에 있다.

지원 백엔드:

세션 메모리는 하네스 컨테이너가 재시작돼도 유지된다.

샌드박스 메모리

장기 실행 에이전트가 여러 실행에 걸쳐 학습한 내용을 축적하는 메모리다. 파일시스템에서 추출한 교훈을 구조화해 저장한다. 한 번 실행에서 발견한 유용한 패턴이 다음 실행에 영향을 줄 수 있다.

두 메모리의 역할 분담이 명확하다.

4. 100개 이상의 LLM 지원: Chat Completions 호환 인터페이스

이전 Agents SDK는 사실상 OpenAI 모델에 최적화돼 있었다. 이번 업데이트에서 하네스가 Chat Completions API 호환 인터페이스를 표준으로 채택하면서, 같은 형식을 지원하는 100개 이상의 LLM을 쓸 수 있게 됐다.

agent = Agent(
    model="claude-sonnet-5",       # Anthropic
    # model="gemini-2-5-pro",      # Google
    # model="llama-4-scout",       # Meta (via 호환 엔드포인트)
    instructions="코드 리뷰 에이전트입니다.",
    tools=[read_file, write_file, run_command],
)

이 변화는 팀의 LLM 선택지를 SDK 수준에서 잠그지 않는다는 점에서 중요하다. 특정 작업에 맞는 모델을 고르거나, 비용과 성능 기준으로 제공자를 교체할 때 에이전트 아키텍처를 다시 짤 필요가 없다.

다만 주의할 점이 있다. 모델마다 도구 호출(tool call) 포맷과 멀티턴 처리 방식에 세부 차이가 있다. 호환 인터페이스로 통일했다고 해서 모든 모델이 동일하게 동작하지는 않는다. 특히 긴 컨텍스트나 복잡한 도구 체인을 쓸 때는 대상 모델로 별도 검증이 필요하다.

5. Codex 파일시스템 도구와 샌드박스 보안

샌드박스 안에서 에이전트가 쓸 수 있는 도구는 Codex 스타일 파일시스템 도구 세트다.

도구동작
read_file(path)컨테이너 내 파일 내용 반환
write_file(path, content)컨테이너 내 파일 쓰기
edit_file(path, old, new)파일 특정 부분 교체
run_command(cmd)셸 명령 실행 (컨테이너 내부)
git_*git commit, diff, push 등 VCS 조작

이 도구들은 모두 샌드박스 컨테이너 내부에서만 실행된다. 하네스 영역의 파일이나 환경 변수에 직접 접근하는 경로가 없다.

심볼릭 링크 탈출 방지

이번 업데이트에는 보안 픽스도 포함됐다. 워크스페이스를 수화(hydrate)할 때, 샌드박스 아카이브 루트 외부를 가리키는 심볼릭 링크를 포함한 tar 아카이브를 거부한다. 절대 경로 심볼릭 링크 타깃도 마찬가지로 거부한다.

로컬, Docker, 제공자 기반 샌드박스 구현 전체에 이 검증이 적용된다.

이 변경은 작아 보이지만, 공급망 공격(supply chain attack)이나 악의적인 아카이브가 컨테이너 루트 밖으로 탈출하는 경로를 차단한다는 점에서 프로덕션 배포에서 의미 있다.

6. 서브에이전트와 병렬 샌드박스

하네스는 하나의 샌드박스만 관리하는 게 아니다. SDK는 여러 서브에이전트를 각각 격리된 샌드박스에서 병렬로 실행하는 패턴을 지원한다.

실용적으로 이런 패턴이 유용하다.

한 서브에이전트의 샌드박스가 실패해도 하네스가 그 서브에이전트만 재수화한다. 나머지 서브에이전트 실행은 영향을 받지 않는다.

운영자 관점 체크리스트

어디까지를 기대하고, 어디부터는 아직 이른가

이번 업데이트는 에이전트 설계에 필요한 보안 격리, 상태 내구성, 워크스페이스 이식성이라는 세 가지 생산성 기반을 SDK 수준으로 내렸다는 점에서 중요하다.

그러나 과대평가를 피해야 할 지점도 있다.

Open question

References