Sandbox Agents Quickstart

Sandbox Agents Quickstart (샌드박스 에이전트 퀵스타트)

베타 기능: 샌드박스 에이전트는 베타 상태예요. GA 전에 API·기본값·지원 기능의 세부 사항이 바뀔 수 있고, 시간이 지나 더 많은 고급 기능이 추가될 거예요.

현대 에이전트는 파일시스템의 실제 파일 위에서 동작할 때 가장 잘 일해요. Agents SDK의 샌드박스 에이전트는 모델에게 영속 작업 공간을 줘서, 대형 문서 집합을 검색하고 파일을 편집하고 명령을 실행하고 산출물(artifact)을 생성하며 저장된 샌드박스 상태에서 작업을 다시 집어 들 수 있게 해요.

SDK가 그 실행 하네스(harness)를 제공하므로, 파일 스테이징·파일시스템 도구·shell 접근·샌드박스 lifecycle·스냅샷·프로바이더별 접착 코드를 직접 엮지 않아도 돼요. 일반 Agent와 Runner 흐름을 유지한 채, 작업 공간용 Manifest, 샌드박스 네이티브 도구용 capabilities, 어디서 실행할지 정하는 SandboxRunConfig를 추가하면 돼요.

출처: 문서

본문

사전 요구사항

  • Python 3.10 이상
  • OpenAI Agents SDK에 대한 기본적인 익숙함
  • 샌드박스 클라이언트. 신뢰하는 로컬 개발에서는 UnixLocalSandboxClient로 시작하세요.

설치

아직 SDK를 설치하지 않았다면:

pip install openai-agents

Docker 기반 샌드박스:

pip install "openai-agents[docker]"

로컬 샌드박스 에이전트 만들기

이 예제는 로컬 저장소를 repo/ 아래에 스테이징하고, 로컬 skills를 지연 로드하며, 러너가 실행을 위해 Unix-로컬 샌드박스 세션을 만들게 해요.

로컬 명령은 호스트 권한을 사용해요: Linux에서 UnixLocalSandboxClient는 명령에 OS 수준 격리를 추가하지 않아요. macOS에서는 sandbox-exec를 통해 파일시스템 제한을 적용하지만 네트워크 격리는 제공하지 않아요. 이 예제는 신뢰하는 로컬 개발이나 외부 격리 환경 안에서 쓰세요. 신뢰할 수 없는 명령(신뢰할 수 없는 입력의 영향을 받는 명령 포함)에는 적절히 구성된 Docker나 호스팅 샌드박스를 고르거나 외부 격리를 제공하세요. Unix-local 실행 한계를 참고하세요.

import asyncio
from pathlib import Path

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.capabilities import Capabilities, LocalDirLazySkillSource, Skills
from agents.sandbox.entries import LocalDir
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

EXAMPLE_DIR = Path(__file__).resolve().parent
HOST_REPO_DIR = EXAMPLE_DIR / "repo"
HOST_SKILLS_DIR = EXAMPLE_DIR / "skills"

def build_agent(model: str) -> SandboxAgent[None]:
    return SandboxAgent(
        name="Sandbox engineer",
        model=model,
        instructions=(
            "Read `repo/task.md` before editing files. Stay grounded in the repository, preserve "
            "existing behavior, and mention the exact verification command you ran. "
            "If you edit files with apply_patch, paths are relative to the sandbox workspace root."
        ),
        default_manifest=Manifest(
            entries={
                "repo": LocalDir(src=HOST_REPO_DIR),
            }
        ),
        capabilities=Capabilities.default() + [
            Skills(
                lazy_from=LocalDirLazySkillSource(
                    # This is a host path read by the SDK process.
                    # Requested skills are copied into `skills_path` in the sandbox.
                    source=LocalDir(src=HOST_SKILLS_DIR),
                )
            ),
        ],
    )

async def main() -> None:
    result = await Runner.run(
        build_agent("gpt-5.6-sol"),
        "Open `repo/task.md`, fix the issue, run the targeted test, and summarize the change.",
        run_config=RunConfig(
            sandbox=SandboxRunConfig(client=UnixLocalSandboxClient()),
            workflow_name="Sandbox coding example",
        ),
    )
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

examples/sandbox/docs/coding_task.py를 참고하세요. 작은 shell 기반 저장소를 사용해서 Unix-로컬 실행에서 결정론적으로 검증할 수 있게 해요.

핵심 선택

기본 실행이 동작하면, 그다음 대부분의 사람들이 손대는 선택은 이쪽이에요.

  • default_manifest — 새 샌드박스 세션의 파일·저장소·디렉터리·마운트
  • instructions — 프롬프트 전반에 적용돼야 하는 짧은 워크플로 규칙
  • base_instructions — SDK 샌드박스 프롬프트를 교체하는 고급 탈출구
  • capabilities — 파일시스템 편집/이미지 검사·shell·skills·memory, 그리고 SDK의 압축 메커니즘 같은 샌드박스 네이티브 도구
  • run_as — 모델 지향 도구가 실행되는 샌드박스 사용자 계정
  • SandboxRunConfig.client — 샌드박스 백엔드
  • SandboxRunConfig.session, session_state, snapshot — 이후 실행이 이전 작업에 다시 연결하는 방법

다음으로 갈 곳

  • Concepts — 매니페스트·capabilities·권한·스냅샷·런 구성·구성 패턴 이해
  • Sandbox clients — Unix-로컬·Docker·호스팅 프로바이더·마운트 전략 선택
  • Agent memory — 이전 샌드박스 실행의 교훈 보존·재사용

shell 접근이 가끔 쓰는 도구 하나뿐이라면 tools 가이드의 hosted shell로 시작하세요. 작업 공간 격리·샌드박스 클라이언트 선택·샌드박스 세션 재개 동작이 설계의 일부일 때 샌드박스 에이전트를 쓰세요.

더 알아보기 (Learn more)