샌드박스 클라이언트
이 페이지를 사용하여 샌드박스 작업을 어디에서 실행할지 선택하세요. 대부분의 경우 SandboxAgent 정의는 그대로 유지되고, 샌드박스 클라이언트와 클라이언트별 옵션만 SandboxRunConfig에서 변경됩니다.
베타 기능
샌드박스 에이전트는 베타입니다. 정식 출시 전에는 API의 세부 사항, 기본값, 지원 기능이 변경될 수 있으며, 시간이 지나면서 더 고급 기능이 추가될 수 있습니다.
선택 가이드
| 목표 | 시작 대상 | 이유 |
|---|---|---|
| macOS 또는 Linux에서 가장 빠른 로컬 반복 작업 | UnixLocalSandboxClient |
추가 설치가 필요 없고, 로컬 파일시스템 개발이 단순합니다 |
| 기본적인 컨테이너 격리 | DockerSandboxClient |
특정 이미지로 Docker 내부에서 작업을 실행합니다 |
| 호스티드 실행 또는 프로덕션 수준 격리 | 호스티드 샌드박스 클라이언트 | 작업공간 경계를 제공업체가 관리하는 환경으로 옮깁니다 |
로컬 클라이언트
대부분의 사용자는 다음 두 샌드박스 클라이언트 중 하나로 시작하면 됩니다.
| 클라이언트 | 설치 | 이 경우 선택 | 예제 |
|---|---|---|---|
UnixLocalSandboxClient |
없음 | macOS 또는 Linux에서 가장 빠른 로컬 반복 작업이 필요할 때. 로컬 개발의 좋은 기본값입니다 | Unix-local 시작 예제 |
DockerSandboxClient |
openai-agents[docker] |
로컬 환경 일치를 위해 컨테이너 격리나 특정 이미지가 필요할 때 | Docker 시작 예제 |
Unix-local은 로컬 파일시스템을 대상으로 개발을 시작하는 가장 쉬운 방법입니다. 더 강한 환경 격리나 프로덕션 수준의 환경 일치가 필요하면 Docker 또는 호스티드 제공업체로 이동하세요.
Unix-local에서 Docker로 전환하려면 에이전트 정의는 그대로 두고 실행 구성만 변경하면 됩니다.
from docker import from_env as docker_from_env
from agents.run import RunConfig
from agents.sandbox import SandboxRunConfig
from agents.sandbox.sandboxes.docker import DockerSandboxClient, DockerSandboxClientOptions
run_config = RunConfig(
sandbox=SandboxRunConfig(
client=DockerSandboxClient(docker_from_env()),
options=DockerSandboxClientOptions(image="python:3.14-slim"),
),
)
컨테이너 격리 또는 이미지 일치가 필요할 때 이 방식을 사용하세요. examples/sandbox/docker/docker_runner.py를 참고하세요.
마운트와 원격 스토리지
마운트 항목은 어떤 스토리지를 노출할지 설명하고, 마운트 전략은 샌드박스 백엔드가 해당 스토리지를 어떻게 연결할지 설명합니다. 내장 마운트 항목과 일반 전략은 agents.sandbox.entries에서 import하세요. 호스티드 제공업체 전략은 agents.extensions.sandbox 또는 제공업체별 확장 패키지에서 사용할 수 있습니다.
일반적인 마운트 옵션:
mount_path: 스토리지가 샌드박스 내에서 표시되는 위치입니다. 상대 경로는 매니페스트 루트 아래에서 해석되고, 절대 경로는 그대로 사용됩니다read_only: 기본값은True입니다. 샌드박스가 마운트된 스토리지에 다시 써야 하는 경우에만False로 설정하세요mount_strategy: 필수입니다. 마운트 항목과 샌드박스 백엔드 둘 다에 맞는 전략을 사용하세요
마운트는 임시 작업공간 항목으로 처리됩니다. 스냅샷 및 영속성 흐름에서는 저장된 작업공간에 마운트된 원격 스토리지를 복사하는 대신, 마운트된 경로를 분리하거나 건너뜁니다.
일반 로컬/컨테이너 전략:
| 전략 또는 패턴 | 이 경우 사용 | 참고 |
|---|---|---|
InContainerMountStrategy(pattern=RcloneMountPattern(...)) |
샌드박스 이미지에서 rclone을 실행할 수 있을 때 |
S3, GCS, R2, Azure Blob을 지원합니다. RcloneMountPattern은 fuse 모드 또는 nfs 모드로 실행할 수 있습니다 |
InContainerMountStrategy(pattern=MountpointMountPattern(...)) |
이미지에 mount-s3가 있고 Mountpoint 스타일의 S3 또는 S3 호환 액세스가 필요할 때 |
S3Mount 및 GCSMount를 지원합니다 |
InContainerMountStrategy(pattern=FuseMountPattern(...)) |
이미지에 blobfuse2와 FUSE 지원이 있을 때 |
AzureBlobMount를 지원합니다 |
InContainerMountStrategy(pattern=S3FilesMountPattern(...)) |
이미지에 mount.s3files가 있고 기존 S3 Files 마운트 대상에 연결할 수 있을 때 |
S3FilesMount를 지원합니다 |
DockerVolumeMountStrategy(driver=...) |
컨테이너 시작 전에 Docker가 볼륨 드라이버 기반 마운트를 연결해야 할 때 | Docker 전용입니다. S3, GCS, R2, Azure Blob은 rclone을 지원하고, S3와 GCS는 mountpoint도 지원합니다 |
지원되는 호스티드 플랫폼
호스티드 환경이 필요할 때도 일반적으로 동일한 SandboxAgent 정의를 그대로 사용할 수 있으며, SandboxRunConfig에서 샌드박스 클라이언트만 변경하면 됩니다.
이 저장소 체크아웃 대신 공개된 SDK를 사용 중이라면, 일치하는 패키지 extra를 통해 샌드박스 클라이언트 의존성을 설치하세요.
제공업체별 설정 참고 사항과 저장소에 포함된 확장 예제 링크는 examples/sandbox/extensions/README.md를 참고하세요.
| 클라이언트 | 설치 | 예제 |
|---|---|---|
BlaxelSandboxClient |
openai-agents[blaxel] |
Blaxel 실행기 |
CloudflareSandboxClient |
openai-agents[cloudflare] |
Cloudflare 실행기 |
DaytonaSandboxClient |
openai-agents[daytona] |
Daytona 실행기 |
E2BSandboxClient |
openai-agents[e2b] |
E2B 실행기 |
ModalSandboxClient |
openai-agents[modal] |
Modal 실행기 |
RunloopSandboxClient |
openai-agents[runloop] |
Runloop 실행기 |
VercelSandboxClient |
openai-agents[vercel] |
Vercel 실행기 |
호스티드 샌드박스 클라이언트는 제공업체별 마운트 전략을 제공합니다. 스토리지 제공업체에 가장 적합한 백엔드와 마운트 전략을 선택하세요.
| 백엔드 | 마운트 참고 사항 |
|---|---|
| Docker | InContainerMountStrategy 및 DockerVolumeMountStrategy와 같은 로컬 전략으로 S3Mount, GCSMount, R2Mount, AzureBlobMount, S3FilesMount를 지원합니다 |
ModalSandboxClient |
S3Mount, R2Mount, HMAC 인증 GCSMount에 대해 ModalCloudBucketMountStrategy를 사용한 Modal 클라우드 버킷 마운트를 지원합니다. 인라인 자격 증명 또는 이름이 지정된 Modal Secret을 사용할 수 있습니다 |
CloudflareSandboxClient |
S3Mount, R2Mount, HMAC 인증 GCSMount에 대해 CloudflareBucketMountStrategy를 사용한 Cloudflare 버킷 마운트를 지원합니다 |
BlaxelSandboxClient |
S3Mount, R2Mount, GCSMount에 대해 BlaxelCloudBucketMountStrategy를 사용한 클라우드 버킷 마운트를 지원합니다. 또한 agents.extensions.sandbox.blaxel의 BlaxelDriveMount와 BlaxelDriveMountStrategy를 사용한 영구 Blaxel Drive도 지원합니다 |
DaytonaSandboxClient |
DaytonaCloudBucketMountStrategy를 사용한 클라우드 버킷 마운트를 지원합니다. S3Mount, GCSMount, R2Mount, AzureBlobMount와 함께 사용하세요 |
E2BSandboxClient |
E2BCloudBucketMountStrategy를 사용한 클라우드 버킷 마운트를 지원합니다. S3Mount, GCSMount, R2Mount, AzureBlobMount와 함께 사용하세요 |
RunloopSandboxClient |
RunloopCloudBucketMountStrategy를 사용한 클라우드 버킷 마운트를 지원합니다. S3Mount, GCSMount, R2Mount, AzureBlobMount와 함께 사용하세요 |
VercelSandboxClient |
현재 호스티드 전용 마운트 전략이 노출되어 있지 않습니다. 대신 매니페스트 파일, 저장소, 또는 다른 작업공간 입력을 사용하세요 |
아래 표는 각 백엔드가 어떤 원격 스토리지 항목을 직접 마운트할 수 있는지 요약합니다.
| 백엔드 | AWS S3 | Cloudflare R2 | GCS | Azure Blob Storage | S3 Files |
|---|---|---|---|---|---|
| Docker | ✓ | ✓ | ✓ | ✓ | ✓ |
ModalSandboxClient |
✓ | ✓ | ✓ | - | - |
CloudflareSandboxClient |
✓ | ✓ | ✓ | - | - |
BlaxelSandboxClient |
✓ | ✓ | ✓ | - | - |
DaytonaSandboxClient |
✓ | ✓ | ✓ | ✓ | - |
E2BSandboxClient |
✓ | ✓ | ✓ | ✓ | - |
RunloopSandboxClient |
✓ | ✓ | ✓ | ✓ | - |
VercelSandboxClient |
- | - | - | - | - |
더 많은 실행 가능한 예제는 로컬, 코딩, 메모리, 핸드오프, 에이전트 구성 패턴에 대해서는 examples/sandbox/을, 호스티드 샌드박스 클라이언트에 대해서는 examples/sandbox/extensions/를 살펴보세요.