OpenAI Agents API를 사용하면 세션 생성 호출 한 번으로 지속형 클라우드 에이전트를 시작할 수 있으며, OpenAI는 클라우드에서 에이전트 하네스를 실행합니다. Novita Sandbox는 Agents API나 OpenAI 관리형 하네스를 대체하지 않습니다. 대신 OpenAI가 문서화한 자체 호스팅 실행 경로를 위한 격리된 상태 저장 런타임을 제공합니다. 즉, 애플리케이션이 샌드박스를 세션에 연결하고, 에이전트는 해당 런타임 내에서 명령을 실행하고 파일을 편집하며, 애플리케이션이 샌드박스 라이프사이클을 소유합니다. 이러한 분할은 OpenAI 호스팅 에이전트 워크플로우를 원하지만 코드, 파일, 브라우저, 컴퓨터 사용 및 장기 실행 작업을 위해 별도의 재사용 가능한 환경이 필요할 때 중요합니다.
이 가이드에서는 API의 주요 개념, 하네스와 환경의 책임 분담 방식, Novita Sandbox를 자체 호스팅 경로에 연결하는 방법, 프로토타입에서 프로덕션으로 전환하기 전에 확인해야 할 사항을 설명합니다. 제품 페이지만 필요하다면 Novita Sandbox에서 시작하는 것이 가장 좋습니다.
Agents API, Agents SDK, Responses API
OpenAI의 에이전트 런타임 비교는 세 가지 통합 모델을 구분합니다:
| 원하는 것 | 사용할 것 | 상태 관리 주체 |
|---|---|---|
| OpenAI 관리형 Codex 하네스를 통해 장기 실행 작업 수행 | Agents API | 저장된 세션 구성, 턴, 항목 |
| 애플리케이션 내에서 에이전트 루프 유지 | Agents SDK | 애플리케이션 상태, SDK 세션 또는 Responses 대화 |
| 모델을 직접 호출하고 모든 것을 직접 조율 | Responses API | 애플리케이션 기록 또는 Responses 대화 |
Agents API는 가장 높은 수준의 옵션입니다. OpenAI는 이를 OpenAI 관리형 API를 통한 Codex 하네스 액세스라고 설명합니다. 세션, 오케스트레이션, 컨텍스트 압축, 복구를 처리합니다. Agents SDK는 애플리케이션 내에서 실행되며 배포, 스토리지, 승인, 런타임 통합에 대한 더 많은 제어권을 제공합니다. Responses API는 모델 계층에 가장 가깝습니다. 이 구분은 "에이전트"가 재사용 가능한 모델/도구 구성 또는 지속형 실행 에이전트를 의미할 수 있고, API 문서가 각 런타임에서 해당 용어를 다르게 사용하기 때문에 유용합니다.
에이전트 하네스란 무엇인가?
에이전트 하네스는 에이전트 턴을 중심으로 한 클라우드 서비스입니다. 명령과 컨텍스트를 모델에 보내고, 도구를 호출하며, 진행 상황을 추적하고, 중단 및 재개를 처리하며, 작업을 검사 가능한 스트림으로 구성합니다. Agents API에서 이 하네스는 관리형 Codex 하네스입니다.
관리형 하네스는 다음을 지원합니다:
- 환경이 연결되었을 때 명령 및 코드 실행.
- 관련 기술 및 지침 적용.
- 도구 또는 MCP를 통해 외부 데이터에 연결.
- 에이전트가 작업하는 동안 방향 제시.
- 컨텍스트 창 관리를 위한 이전 작업 요약.
- 작업을 하위 작업으로 나누고 하위 에이전트에 위임.
- 중단된 지점에서 세션 재개.
그렇다고 애플리케이션이 사라지는 것은 아닙니다. 애플리케이션은 여전히 세션을 생성하고, 입력을 제출하며, 이벤트를 수신하고, 승인 또는 함수 호출을 처리하며, ID와 아티팩트를 저장할 방법을 결정합니다. 하네스는 오케스트레이션 작업을 줄여줄 뿐, 제품 정책을 없애지는 않습니다.
에이전트가 여전히 샌드박스를 필요로 하는 이유
일부 에이전트는 파일 시스템에 접근하지 않고 질문에 답하거나 원격 API를 호출합니다. 다른 에이전트는 파일을 생성하고, 의존성을 설치하고, 스크립트를 실행하고, 브라우저를 검사하고, 데스크톱을 제어하거나, 사용자가 없는 동안 다단계 작업을 유지해야 합니다. 샌드박스는 이러한 작업에 제품 서버나 로컬 머신을 건드리지 않는 대체 가능한 실행 환경을 제공합니다.
Agents API는 환경을 선택 사항으로 취급합니다. OpenAI의 아키텍처 문서는 세 가지 실행 선택을 지원합니다:
none— 하네스에 셸이나 파일 시스템이 없습니다. 함수 도구는 결과를 하네스에 반환합니다.openai_hosted— OpenAI가 샌드박스를 프로비저닝하고 관리합니다.self_hosted— 애플리케이션이 환경을 시작하고 연결하므로 자체 컴퓨팅, 프라이빗 네트워크 또는 사용자 정의 소프트웨어를 사용할 수 있습니다.
이것이 두 시스템 간의 경계가 가장 명확한 지점입니다. Agents API와 OpenAI는 하네스를 호스팅할 수 있지만, 자체 호스팅 환경을 사용하면 팀이 실행 플랫폼을 선택할 수 있습니다. 이 선택은 격리, 파일 시스템 형태, 네트워킹, SDK, 일시 중지/재개 동작, 요금 청구 및 유지 관리해야 하는 인프라 양에 영향을 미칩니다.
이 아키텍처에서의 Novita Sandbox
Novita Sandbox는 AI 에이전트를 위한 관리형 실행 환경입니다. 공식 개요는 인프라 관리 없이 코드 실행, 의존성 설치, 파일 액세스, 브라우저 사용, 세션 간 상태 유지를 위한 격리된 상태 저장 런타임을 설명합니다. 직접적인 Novita 전용 에이전트 스택에서 애플리케이션은 샌드박스를 생성하고, 모델 또는 에이전트 프레임워크는 도구 호출을 선택하며, 샌드박스는 이를 실행하고, 애플리케이션은 런타임 외부에서 정책, 승인 및 스토리지를 유지합니다.
Agents API와 함께 사용할 때 권장되는 정확한 프레이밍은 네이티브가 아닌 보완적입니다. OpenAI의 현재 자체 호스팅 샌드박스 가이드는 Cloudflare, Daytona, DigitalOcean, E2B, Blaxel, Modal, Runloop, OCI, Vercel을 문서화된 제공업체로 나열합니다. Novita Sandbox는 현재 해당 제공업체 목록에 없습니다. 따라서 실용적인 경로는 Novita를 애플리케이션 관리형 실행 환경으로 사용하고 OpenAI의 자체 호스팅 환경 계약을 통해 Agents API 세션에 연결하는 것입니다. 이는 유용한 분리(OpenAI가 지속형 하네스를 실행하고 Novita Sandbox가 런타임을 제공)를 유지하면서 현재 문서에서 지원하지 않는 공식 제공업체 통합을 주장하지 않습니다.
Novita Sandbox는 다섯 가지 개념을 중심으로 구축되었습니다:
| 개념 | 에이전트에 제공하는 것 |
|---|---|
| Sandbox | 자체 파일 시스템과 프로세스 공간을 갖춘 격리된 런타임 |
| Template | 재현 가능한 시작 이미지, 의존성, 구성 및 설정 |
| Snapshot | 반복 설정을 피하기 위해 재사용할 수 있는 저장된 샌드박스 상태 |
| Secret | 팀 범위의 암호화된 값으로, 자격 증명을 하드코딩하지 않도록 함 |
| Region | 현재 US v1/v2 엔드포인트의 위치 |
런타임은 코딩 에이전트, 브라우저 에이전트, 데이터 분석, 연구 및 RL 스타일 워크로드를 지원합니다. Novita Sandbox 개요는 현재 리전과 라이프사이클 동작에 대한 소스입니다.
라이프사이클, 지속성, 장기 실행 작업
Novita Sandbox에는 세 가지 라이프사이클 상태(실행 중, 일시 중지, 종료)가 있습니다. 실행 중인 샌드박스는 명령을 실행하고 연결을 제공할 수 있습니다. 일시 중지된 샌드박스는 파일 시스템과 인메모리 상태(실행 중인 프로세스 및 변수 포함)를 보존하는 반면, CPU 및 RAM 요금 청구는 중지됩니다. 네트워크 연결은 재개될 때까지 중단됩니다. 종료된 샌드박스는 종료되어 복원할 수 없습니다.
두 가지 시간 제한 컨트롤이 전환을 주도합니다. 샌드박스 시간 제한은 생성 시점부터 카운트다운되고, 유휴 시간 제한은 구성된 기간 동안 클라이언트가 연결되지 않았을 때 발생합니다. 두 이벤트 모두에서 종료 대신 일시 중지를 선택할 수 있으며, 선택적으로 자동 재개를 활성화할 수 있습니다. 이는 검토를 기다리는 코드 편집 작업, 단계 사이에 일시 중지되는 브라우저 세션, 또는 나중에 의존성과 변수가 그대로 유지된 상태로 재개되는 데이터 분석 노트북에 유용합니다.
스냅샷은 일시 중지와 다릅니다. 일시 중지는 해당 인스턴스에 대한 현재 샌드박스 상태를 유지합니다. 스냅샷은 상태를 재사용 가능한 환경으로 캡처하므로 새 샌드박스가 이미 설치된 의존성, 구성 및 파일로 시작할 수 있습니다. 프로덕션에서는 반복 가능한 기본 이미지에 템플릿을, 재사용 가능한 작업 상태에 스냅샷을, 템플릿이나 스냅샷에 자격 증명을 포함하는 대신 비밀에 자격 증명을 사용하세요.
Novita를 자체 호스팅 경로에 연결
OpenAI의 자체 호스팅 샌드박스 가이드는 연결 형태를 정의합니다. 애플리케이션은 environment.type: "self_hosted"로 세션을 생성하고, 환경 ID와 원격 URL을 수신하고, 런타임 내에서 실행기를 시작한 다음 세션을 연결된 것으로 보고합니다. 공식 실행기 명령은 다음과 같습니다:
codex exec-server \
--remote "<session.environment.remote_url>" \
--environment-id "<session.environment.id>"
세션 이벤트 스트림은 agent.session.environment.pending, connected 또는 failed를 보고합니다. 에이전트가 작업하는 동안 실행기가 계속 실행되어야 하며, 컴퓨팅을 중지하기 전에 종료를 조정해야 합니다.
다음 스케치는 공식 Novita SDK를 사용한 해당 흐름의 Novita 측을 보여줍니다. 샌드박스를 생성하고, 소스 코드에 시크릿을 넣지 않고 인증을 준비하며, OpenAI 실행기를 시작할 위치를 제공합니다. 실행기 키를 주입하고 이벤트 스트림을 기다리는 정확한 방법은 애플리케이션과 OpenAI SDK 버전에 따라 다릅니다.
import os
from novita_sandbox import Novita
def create_agent_runtime() -> str:
novita = Novita(api_key=os.environ["NOVITA_API_KEY"])
sandbox = novita.sandbox.create(
"codex",
timeout=3600,
envs={"CODEX_API_KEY": os.environ["CODEX_EXECUTOR_KEY"]},
)
try:
sandbox.git.clone(
"https://github.com/your-org/your-repo.git",
path="/home/user/repo",
username="x-access-token",
password=os.environ["GITHUB_TOKEN"],
depth=1,
)
print(
"Create the Agents API session with environment.type=self_hosted, "
"then start codex exec-server here."
)
except Exception:
sandbox.kill()
raise
return sandbox.sandbox_id
프로덕션에서 이 경로를 사용하기 전에 현재 OpenAI SDK 객체, 환경 키 이름, 원격 URL 동작 및 라이프사이클 요구 사항을 OpenAI의 자체 호스팅 샌드박스 가이드와 비교하여 확인하세요. 세션 API가 샌드박스를 대신 관리한다고 가정하지 마세요. self_hosted의 경우 그 책임은 명시적으로 귀하에게 있습니다.
더 간단한 Agents API가 아닌 워크플로우의 경우 Novita의 Codex 에이전트 가이드는 codex 템플릿에서 Codex CLI를 직접 실행하고, 출력을 스트리밍하고, 완료되면 샌드박스를 종료하는 방법을 보여줍니다.
보안 및 자격 증명
하네스, 샌드박스 및 애플리케이션 서버를 별도의 신뢰 도메인으로 취급하세요.
- OpenAI API 키, Novita API 키, Git 토큰 및 데이터베이스 자격 증명을 프롬프트 및 소스 파일 외부에 보관하세요.
- 샌드박스 내부에서 사용되는 팀 범위의 민감한 값에는 Novita Sandbox 시크릿을 사용하세요.
- OpenAI의 지침에 따라 샌드박스 외부에 속하는 자격 증명에는 OpenAI 볼트를 사용하세요.
- 보안 샌드박스 액세스를 선호하세요. Novita 문서에 따르면 SDK 버전 2.0.0 이상으로 생성된 샌드박스에 대해 보안 액세스가 자동으로 활성화됩니다. 이전 사용자 정의 템플릿은 재구축이 필요할 수 있습니다.
- 명시적 네트워크 정책을 설정하고 작업에 필요한 경우에만 확장하세요.
- 생성된 코드와 아티팩트는 더 넓은 권한을 받거나 프로덕션 시스템에 도달하기 전에 검토하세요.
이러한 컨트롤은 함께 작동합니다. 샌드박스는 생성된 코드의 폭발 반경을 줄이지만, 에이전트를 인증하거나, 의도를 검증하거나, 어떤 아티팩트가 런타임을 떠날 수 있는지 결정하지는 않습니다.
비용 및 제한
OpenAI는 선택한 모델의 API 요금으로 Agents API 모델 사용량을 청구하고, OpenAI 도구는 표준 요금으로 청구합니다. OpenAI 호스팅 환경의 경우 컨테이너 요금이 적용됩니다. 자체 호스팅 경로의 경우 실행 리소스는 제공업체 비용입니다.
Novita Sandbox 요금 청구는 샌드박스가 실행되는 동안 CPU 및 RAM에 대해 초 단위로 이루어집니다. 일시 중지하면 CPU 및 RAM 요금이 중지됩니다. 일시 중지된 데이터는 영구 스토리지로 유지되며, 각 계정에는 60GB의 무료 영구 스토리지가 포함되며 추가 스토리지는 시간당 청구됩니다. 각 실행 중인 샌드박스에는 20GB의 임시 스토리지가 포함됩니다. 공식 Sandbox 크레딧 및 가격은 변경될 수 있으므로 현재 값을 Novita Sandbox 가격 페이지에서 확인하세요.
Novita의 할당량 제한도 병렬 워크로드에 중요합니다. 작성 시점 기준으로 무료 계정은 기본적으로 5개의 동시 샌드박스로 제한되고, 유료 계정은 100개입니다. 최대 단일 샌드박스 vCPU 및 메모리는 등급에 따라 다릅니다. 엔터프라이즈 한도는 조정 가능합니다. 마케팅 페이지의 예제에 의존하기보다 할당량 제한 가이드 및 Sandbox.get_quota()를 확인하세요.
이 아키텍처가 적합한 경우
자체 호스팅 Novita 런타임은 다음과 같은 경우에 적합합니다:
- 에이전트가 코드를 실행하고, 파일을 수정하고, 의존성을 설치하고, 테스트를 실행하고, 웹을 탐색하거나 데스크톱과 상호 작용해야 하는 경우.
- 애플리케이션이 인간의 지연, 재시도 또는 다단계 검토에 걸쳐 상태 저장 세션이 필요한 경우.
- 제품 서버와 별도로 격리된 실행을 원하는 경우.
- 워크로드가 템플릿, 스냅샷, 일시 중지/재개 또는 재현 가능한 환경의 이점을 활용하는 경우.
다음과 같은 경우에는 적합하지 않습니다:
- 작업에 원격 함수 호출만 필요하고 파일 시스템이나 셸이 필요하지 않은 경우.
- OpenAI 관리형 환경이 필요하고 환경 라이프사이클을 소유하고 싶지 않은 경우.
- OpenAI의 현재 직접 샌드박스 제공업체 가이드에 나열된 제공업체가 필요한 경우.
- 규정 준수 모델에 Novita가 배포에 대해 문서화하지 않은 제공업체 관리형 격리 컨트롤이 필요한 경우.
가장 안전한 평가는 실제 저장소, 명령, 네트워크 정책, 비밀 처리 및 실패 경로를 사용한 소규모 개념 증명입니다. 그런 다음 시작, 일시 중지/재개, 작업 완료 및 대표적인 실행의 총 비용을 측정하세요.
FAQ
Novita Sandbox가 OpenAI Agents API와 기본적으로 통합되나요?
OpenAI의 현재 환경 제공업체 가이드에 따르면 그렇지 않습니다. 정확한 아키텍처는 Agents API의 자체 호스팅 환경 경로를 사용하고, Novita Sandbox를 애플리케이션 관리형 런타임으로 시작한 다음, 문서화된 실행기를 그 안에서 실행하는 것입니다. 제공업체 통합은 변경될 수 있으므로 릴리스 전에 현재 가이드를 확인하세요.
OpenAI가 호스팅 샌드박스를 제공하는데도 Novita가 필요한가요?
요구 사항에 따라 다릅니다. OpenAI의 호스팅 샌드박스는 운영이 적은 경로입니다. Novita Sandbox는 사용자 정의 이미지, 템플릿, 스냅샷, 브라우저 또는 컴퓨터 사용 워크플로우, 상태 저장 일시 중지/재개 또는 리소스에 대한 제공업체 수준 제어를 위한 별도의 런타임 선택이 필요할 때 유용합니다.
에이전트가 일시 중지 상태에서도 프로세스와 파일을 유지할 수 있나요?
네. Novita의 일시 중지/재개 문서에 따르면 파일 시스템 및 인메모리 상태(실행 중인 프로세스 및 변수 포함)가 보존됩니다. 네트워크 연결은 샌드박스가 재개될 때까지 중단됩니다.
이것이 OpenAI Agents SDK와 동일한가요?
아니요. Agents SDK는 애플리케이션 내에서 실행되며 에이전트 루프에 대한 더 많은 제어권을 제공합니다. Agents API는 OpenAI의 관리형 Codex 하네스를 사용합니다. Novita Sandbox는 두 패턴 모두에 실행을 호스팅할 수 있지만 세션 및 오케스트레이션 동작이 다릅니다.
어디서부터 시작해야 하나요?
OpenAI Agents API 퀵스타트를 시도하여 하네스 세션 및 이벤트를 이해하세요. 그런 다음 Novita Sandbox를 만들고 해당 런타임, 라이프사이클, 보안 및 비용 모델이 프로덕션 요구 사항과 일치하는지 결정하세요.
