OpenAI Agents SDK Sandbox 2026: 출시 전 어떻게 검수할까?

예제 실행은 성공했지만 실제 환경에서는 다른 폴더를 읽고 작업 중단 뒤 복구도 되지 않습니다.

가장 안전한 선택은 여섯 단계 검수를 순서대로 통과시키는 것입니다. 작업 공간 계약, 결정성 테스트, 실제 샌드박스 통합, 권한 격리, 상태 복구, 실패 시 롤백을 모두 확인한 뒤 출시해야 합니다. 맥 전용 도구나 병렬 테스트가 있을 때만 독립된 클라우드 맥을 추가합니다.

이 글은 이미 SandboxAgent 예제를 실행했지만 출시 기준이 없는 개발자를 위한 글입니다. 파일과 명령 권한을 검증해야 하는 플랫폼 엔지니어, 로컬과 컨테이너와 클라우드 맥 사이에서 테스트 환경을 정해야 하는 기술 책임자에게도 적합합니다.

마지막 업데이트: 2026년 8월 26일. 아래의 최신 검수 기준은 Sandbox Agents 공식 개념 문서와 공식 빠른 시작 문서를 기준으로 확인했습니다. Sandbox Agents는 현재 베타이므로 정식 출시 전 API와 기본 설정, 지원 기능이 바뀔 수 있습니다.

시작 시점에는 작업 공간 계약부터 고정합니다

검수의 첫 단계는 코드를 실행하는 일이 아닙니다. 에이전트의 활동 범위를 문서로 고정하는 일입니다.

다음 항목을 하나의 기준 문서로 남깁니다.

• 읽을 수 있는 파일과 디렉터리
• 수정하거나 새로 만들 수 있는 위치
• 접근이 금지된 경로
• 사용할 명령과 사용할 수 없는 명령
• 실행 계정과 필요한 권한
• 네트워크 접근 범위
• 환경 변수와 외부 저장소 자격 증명
• Manifest와 SandboxRunConfig의 예상 설정
• 세션 상태, 스냅샷, 작업 공간 정리 방식

이 계약이 없으면 테스트가 성공해도 무엇을 증명했는지 설명하기 어렵습니다. 개발자 컴퓨터에만 있는 설정 파일이나 이미 설치된 명령을 전제로 삼아도 안 됩니다. 매번 같은 방식으로 새 작업 공간을 만들 수 있어야 합니다.

SandboxRunConfig의 실제 필드와 동작은 공식 실행 설정 참조에서 확인합니다. 문서에 없는 옵션을 내부 약속처럼 사용하면 베타 변경 때 검수 기준도 함께 무너집니다.

주의: 작업 공간의 전체 경로를 허용하는 방식은 빠르지만 검수 증거로는 약합니다. 필요한 하위 경로와 읽기 전용 여부를 각각 기록해야 합니다.

다음 단계에서는 모델을 빼고 편성 로직을 검증합니다

두 번째 단계는 실제 모델이나 실제 샌드박스의 성능을 확인하는 단계가 아닙니다. 도구 호출과 흐름 제어가 예상대로 움직이는지 보는 단계입니다.

공식 테스트 도구와 scripted_sandbox_session을 사용하면 정해진 응답과 명령 결과를 주입할 수 있습니다. 이 방식으로 다음 경로를 나눠 확인합니다.

• 정상적인 도구 호출
• 잘못된 도구 인자
• 명령 실패
• 대상 파일이 없는 경우
• 권한 거부
• 재시도 뒤에도 실패하는 경우
• 중간 단계에서 흐름이 끝나는 경우
• 최종 출력이 비어 있거나 형식에 맞지 않는 경우

각 테스트에는 예상 도구 이름, 인자, 호출 순서, 최종 출력, 오류 처리 결과를 함께 저장합니다. Agents SDK 테스트 안내와 스크립트 기반 샌드박스 세션 참조가 이 단계의 기준입니다.

이 테스트가 증명하는 범위는 분명합니다. SDK의 편성 로직, 도구 라우팅, 오류 분기는 검증할 수 있습니다. 실제 파일 권한, 프로세스 격리, 운영 체제 명령, 네트워크 경계까지 증명하지는 못합니다. 결정성 테스트를 통과했다는 이유로 실제 샌드박스 통합 테스트를 생략하면 안 됩니다.

실제 환경에서는 일관성과 격리를 따로 확인합니다

세 번째 단계부터는 출시 대상과 같은 방식으로 환경을 만듭니다. 의존성 목록, 디렉터리 구조, 실행 방식, 작업 계정이 달라지면 별도 테스트로 취급합니다.

대표 작업을 새 작업 공간에서 실행하면서 다음 증거를 남깁니다.

• 시작 시점의 환경과 의존성 목록
• 현재 작업 디렉터리
• 생성된 파일의 경로와 내용
• 파일 소유자와 권한
• 실행한 명령과 종료 결과
• 예상 밖으로 접근한 경로
• 작업 중단과 정리 결과

로컬에서만 통과하는 경우에는 먼저 의심해야 할 원인이 있습니다. 개발자 계정의 넓은 권한, 전역으로 설치된 도구, 이전 작업의 잔여 파일, 운영 체제별 경로 차이입니다. 이 문제는 샌드박스가 불안정해서가 아니라 테스트 환경의 계약이 재현되지 않아서 생깁니다.

맥 전용 도구 체인, 시스템 구성 요소, 서명 과정이 작업에 포함되면 실제 맥에서 다시 실행합니다. 다른 운영 체제의 컨테이너 결과는 파일 생성과 일반 명령 검증에는 쓸 수 있지만 맥 전용 통합 검증을 대신하지 못합니다. 세션 추적이 필요하다면 Agents SDK 추적 문서에 맞춰 호출과 오류 기록을 연결합니다.

로컬 실행과 독립 환경의 역할을 나누는 기준

독립된 클라우드 맥은 모든 테스트의 기본값이 아닙니다. 맥 의존성이 없고 결정성 테스트와 관리형 샌드박스 통합 검증으로 충분하다면 추가 환경이 과합니다. 반대로 서명, 시스템 도구, 병렬 회귀가 핵심이면 개발자 맥 하나에 의존하는 편이 더 큰 위험입니다.

높은 권한을 열기 전에는 거부 경로를 먼저 봅니다

네 번째 단계는 정상 작업보다 실패 작업을 먼저 실행하는 단계입니다. 에이전트가 필요한 권한만 갖는지 확인해야 합니다.

다음 시도를 각각 수행하고 결과를 기록합니다.

• 읽기 전용 디렉터리에 파일을 덮어쓰기
• 허용 목록 밖의 경로 읽기
• 작업 공간 밖으로 파일 복사
• 비밀값 환경 변수 출력
• 승인 없는 외부 전송
• 삭제와 대량 덮어쓰기
• 허용되지 않은 명령 실행

거부되어야 할 작업이 조용히 성공하면 즉시 차단 항목입니다. 승인 절차가 필요한 작업이 사용자 확인 없이 진행되어도 출시할 수 없습니다. 자격 증명이 작업 환경에 존재한다는 사실만으로 사용을 허용해서는 안 됩니다. 필요한 명령에만 제한적으로 전달하고, 로그에는 비밀값이 남지 않는지 확인합니다.

로컬 클라이언트에서 명령이 거부되었다고 해서 생산형 격리가 확보된 것은 아닙니다. 클라이언트 설정과 실제 컨테이너 또는 관리형 실행 경계를 나눠 검증해야 합니다.

경험상 놓치기 쉬운 지점: 파일 권한 검사는 성공한 파일만 보는 방식으로 끝내면 안 됩니다. 존재하지 않는 파일, 심볼릭 링크, 작업 공간 밖의 상대 경로처럼 경계가 흔들리는 입력을 함께 넣어야 합니다.

긴 작업은 중단 뒤 상태를 검수합니다

다섯 번째 단계는 완주한 성공 사례가 아니라 중간 실패를 대상으로 합니다. 긴 작업을 실행하고 도구 호출 사이에서 의도적으로 중단합니다.

확인할 순서는 다음과 같습니다.

1. 중단 시점까지 완료된 단계와 미완료 단계를 저장합니다.
2. 세션 상태나 스냅샷이 실제 작업 공간과 연결되는지 확인합니다.
3. 중단된 작업을 같은 상태에서 재개합니다.
4. 완료된 삭제, 덮어쓰기, 외부 전송이 반복되지 않는지 확인합니다.
5. 새 세션에서 이전 작업의 파일과 상태가 나타나지 않는지 확인합니다.
6. 복구가 불완전하거나 정리되지 않으면 작업 공간을 폐기하고 새로 생성합니다.

복구 결과가 매번 다르면 재시도 횟수를 늘리는 것으로 해결하지 않습니다. 어떤 상태를 신뢰할 수 있는지 정의되지 않았기 때문입니다. 복구 불가, 상태 불일치, 정리 실패는 보완 관찰 항목이 아니라 출시 차단 항목으로 분류하는 편이 안전합니다.

마지막에는 방출 기준과 재검수 조건을 나눕니다

검수 결과는 통과, 보완 테스트, 차단의 세 가지로 나눕니다. 한 번의 성공 시연만 저장하지 말고 구성 버전, 테스트 입력, 실행 기록, 이상 동작, 담당자를 함께 보관합니다.

• 통과: 작업 공간이 재현되고, 허용된 작업만 성공하며, 거부와 복구 결과가 예상과 일치합니다.
• 보완 테스트: 기능은 맞지만 특정 운영 체제, 병렬 실행, 중단 시점의 증거가 부족합니다.
• 차단: 권한 초과, 민감 정보 노출, 재현 불가 환경, 복구 불일치, 롤백 경로 부재가 발견되었습니다.

다음 체크리스트에서 차단 항목이 하나라도 남으면 출시를 미룹니다.

• [ ] 작업 공간 계약과 Manifest를 버전으로 저장했습니다.
• [ ] SandboxRunConfig의 예상값과 실제 실행값을 비교했습니다.
• [ ] 정상 호출과 명령 실패를 결정성 테스트로 분리했습니다.
• [ ] 파일 없음, 권한 거부, 조기 종료를 각각 재현했습니다.
• [ ] 출시 대상과 같은 의존성과 디렉터리 구조에서 실행했습니다.
• [ ] 작업 공간 밖 경로와 읽기 전용 경로를 차단했습니다.
• [ ] 환경 변수와 외부 저장소 자격 증명의 노출을 확인했습니다.
• [ ] 삭제, 덮어쓰기, 외부 전송에 거부 또는 승인 경로가 있습니다.
• [ ] 작업을 중단한 뒤 상태와 스냅샷을 복구했습니다.
• [ ] 복구 후 완료된 위험 작업이 중복 실행되지 않았습니다.
• [ ] 복구 실패 시 작업 공간을 폐기하고 다시 만드는 규칙이 있습니다.
• [ ] 맥 전용 도구와 병렬 실행을 실제 대상 환경에서 확인했습니다.
• [ ] 통과, 보완, 차단 판정과 책임자를 기록했습니다.

독립된 맥 환경을 추가하는 시점

맥 전용 도구가 없고 단일 작업만 검증한다면 로컬과 관리형 샌드박스 조합으로 충분할 수 있습니다. 하지만 서명 과정, 시스템 도구, 여러 작업의 동시 실행, 짧은 기간의 반복 회귀가 포함되면 독립된 클라우드 맥을 고려합니다.

이때 환경을 단순히 빌리는 데서 끝내면 안 됩니다. 작업 공간 생성, 의존성 설치, 대표 작업 실행, 중단과 재개, 정리 실패 확인을 같은 체크리스트로 반복해야 합니다. ProxyMac의 콘솔 안내에서 접속과 실행 절차를 확인하고, 계정 운영이 필요한 경우 도움말 페이지를 기준으로 전달 기록을 남기는 방식이 적합합니다.

FAQ

OpenAI Agents SDK Sandbox를 출시하기 전에 무엇을 먼저 테스트해야 하나요?

먼저 에이전트가 읽고 쓰는 파일과 접근하지 않아야 할 경로를 문서로 고정해야 합니다. 그다음 결정성 테스트로 도구 인자와 오류 분기를 확인하고, 실제 샌드박스에서 파일 시스템과 프로세스를 검증합니다. 마지막으로 권한 격리, 중단 뒤 복구, 실패 시 작업 공간 재생성까지 통과해야 출시 후보가 됩니다.

SandboxAgent의 파일 권한과 명령 권한은 어떤 방식으로 확인하나요?

정상 파일 읽기와 쓰기만 확인해서는 부족합니다. 읽기 전용 경로에 쓰기를 시도하고, 허용되지 않은 경로와 비밀값 환경 변수, 외부 전송 명령을 각각 거부하는지 확인해야 합니다. 거부 기록과 승인 절차가 남아야 하며, 로컬 클라이언트에서 막혔다는 사실만으로 격리를 입증해서는 안 됩니다.

로컬에서 통과한 에이전트 샌드박스가 출시 환경에서 실패하는 이유는 무엇인가요?

개발자 컴퓨터에는 우연히 설치된 의존성, 다른 작업에서 남은 파일, 넓은 사용자 권한이 있을 수 있습니다. 반면 출시 환경은 작업 경로와 실행 계정이 다릅니다. 따라서 같은 의존성 목록과 디렉터리 구조를 새로 만든 환경에서 재실행해야 합니다. 맥 전용 명령이나 서명 과정은 실제 맥에서 다시 확인해야 합니다.

에이전트 샌드박스의 스냅샷 복구와 작업 재개는 어떻게 검증하나요?

긴 작업을 실행한 뒤 중간에 의도적으로 중단하고 저장된 상태를 이용해 재개합니다. 이미 끝난 삭제나 외부 전송 같은 위험 작업이 다시 실행되지 않는지 확인해야 합니다. 이전 작업의 파일이 새 세션에 섞이지 않는지도 봅니다. 복구가 불완전하면 계속 실행하지 말고 작업 공간을 폐기한 뒤 새로 만들어야 합니다.

어떤 샌드박스 테스트에 독립된 맥 환경이 필요한가요?

맥 전용 개발 도구, 시스템 구성 요소, 서명 과정, 여러 작업의 동시 실행을 검증할 때 독립된 맥 환경이 적합합니다. 일반적인 도구 인자와 오류 분기는 결정성 테스트로 먼저 확인할 수 있습니다. 따라서 모든 테스트를 맥에서 할 필요는 없지만, 출시 대상이 맥이라면 마지막 통합 검증을 다른 운영 체제로 대신해서는 안 됩니다.

현재 방식이 개발자 개인 맥에만 의존한다면 환경마다 설치된 도구가 다르고, 작업 잔여 파일이 섞이며, 병렬 검증을 위한 독립 공간도 부족합니다. 컨테이너만 사용하는 방식도 맥 전용 명령과 서명 과정을 재현하지 못할 수 있습니다. 이런 문제가 검수를 막는다면 작업 기간에 맞춰 ProxyMac의 격리된 클라우드 맥을 검증 환경으로 마련하는 편이 낫습니다. 다만 개발 환경을 그대로 생산에 옮기지 말고, 이 글의 계약, 권한, 복구, 롤백 항목을 새 환경에서 다시 통과시켜야 합니다. 자세한 이용 조건은 ProxyMac 요금 안내에서 확인할 수 있습니다.

FAQ