Skip to main content
샌드박스를 사용하면 에이전트에게 Linux 데스크톱을 제공하고, 에이전트가 스크린샷, 마우스 클릭, 키보드 입력으로 이를 조작하게 할 수 있습니다. 이 튜토리얼에서는 일회용 서버리스 샌드박스에서 Chromium을 실행합니다. 로컬 머신의 Python 컨트롤러가 데스크톱 스크린샷을 OpenAI의 컴퓨터 도구로 보내고, 도구가 반환한 액션을 샌드박스에서 실행한 다음 결과를 조회합니다. 에이전트에게 샘플 브라우저 양식을 작성하게 해 보세요. 양식 서버가 제출 내용을 별도로 검증하므로, 성공 여부를 모델의 완료 보고에만 의존하지 않아도 됩니다.

사전 요구 사항

시작하기 전에 다음 항목을 준비하세요.
  • Python 3.11, 3.12 또는 3.13과 uv
  • 샌드박스 액세스 권한이 있는 Forge API 키. 시작하기를 참조하세요.
  • gpt-5.6-sol 및 컴퓨터 도구에 액세스할 수 있는 OpenAI API 키
  • 컨트롤러에서 샌드박스 서비스와 OpenAI API로 나가는 아웃바운드 액세스. 샌드박스는 Debian 저장소에서 패키지를 설치합니다.
이 예시에서는 CPU 2개와 메모리 4기비바이트(GiB)를 요청하고, 샌드박스 최대 수명을 30분으로 설정합니다. 서버리스 배치를 명시적으로 선택하므로 러너를 따로 배포하지 않아도 됩니다.

사용자 인증 정보 설정

작업 디렉터리를 만들고, 입력 내용이 화면에 표시되지 않는 프롬프트를 사용할 수 있도록 Bash를 실행하세요:
해당 셸에서 Forge 및 OpenAI 사용자 인증 정보를 입력하세요.
두 키는 모두 로컬 컨트롤러 환경에만 저장되며, 스크립트는 이 키를 샌드박스에 전달하지 않습니다. 컨트롤러는 데스크톱 스크린샷과 작업 프롬프트를 모델 API로 전송합니다.

데스크톱 컨트롤러 만들기

작업 디렉터리에 다음 전체 예제를 computer_use.py 파일로 저장하세요. 이 예제는 세 가지 컴포넌트로 구성됩니다. Chromium은 브라우저 샌드박스가 활성화된 상태로 desktop 사용자 권한으로 실행됩니다. 양식 서버는 샌드박스 내부의 루프백 주소에서 수신 대기합니다. 이 예제는 공개 엔드포인트를 만들지 않으며, 로컬 머신에서 브라우저를 열지도 않습니다. 어댑터는 좌표와 키 조합을 검증하고, 입력할 텍스트는 리터럴 인수로 전달합니다. 루프는 지원되지 않는 액션이 나오거나 안전 검토가 요청되면 중지됩니다. 모델 턴은 최대 20회까지 허용되며, 턴 사이마다 10분 제한 시간을 초과했는지 확인합니다.
computer_use.py

작업 실행 및 확인

같은 셸에서 의존성과 함께 컨트롤러를 실행하세요.
컨트롤러는 샌드박스를 생성하고 데스크톱 패키지를 설치한 다음, Chromium이 양식을 로드할 때까지 기다립니다. 이어서 모델이 페이지를 읽고 화면에 표시된 문구를 입력한 후 Verify를 선택합니다. 패키지 설치에는 몇 분 정도 걸릴 수 있으며, 모델 턴 수는 실행마다 다를 수 있습니다. 각 run은 computer-use-results/ 아래에 새 디렉터리를 만들어 결과를 저장합니다. run이 성공하면 result.json 파일에 "status": "passed", "verified": true, "cleanup": "stopped"가 포함됩니다. 양식에 PASS가 표시되었는지 확인하려면 agent/final.png 파일을 여세요. 컨트롤러는 성공으로 판정하기 전에 양식 서버의 확인 파일을 검사합니다. 컨트롤러는 작업이 실패한 경우에도 finally 블록에서 샌드박스 중지를 시도합니다. 정리 작업 결과가 "failed"이거나 정리 작업이 끝나기 전에 컨트롤러를 종료했다면 sandbox-id.txt 파일의 ID를 사용해 샌드박스를 중지하세요. [SANDBOX-ID]를 해당 ID로 바꾼 다음, 같은 셸에서 샌드박스를 중지하세요.
작업이 실패하면 저장된 전사본과 최신 agent/turn-*.png 파일(있는 경우)을 확인하세요. API 오류, 데스크톱 설치 실패, 브라우저 시작 실패는 두 파일 중 하나 또는 둘 다 생성되기 전에 발생할 수 있습니다. 샌드박스 연결 오류와 실행 오류는 샌드박스 지원 아티클을 참조하세요.

다음 단계

이 예시를 응용하려면 샘플 양식과 작업을 직접 제어할 수 있는 애플리케이션으로 바꾸세요. 스크린샷/액션 루프는 그대로 두고 애플리케이션별 성공 확인 로직을 추가하세요. 반복해서 실행하는 경우에는 시작할 때마다 데스크톱 패키지를 설치하지 않도록 패키지를 컨테이너 이미지에 미리 포함해 빌드하세요. 자세한 내용은 샌드박스 구성을 참조하세요. 다른 애플리케이션에서 에이전트를 사용하기 전에 허용할 대상과 작업을 정의하고, 민감한 오퍼레이션에는 사람의 승인을 거치도록 하세요. 샘플 프롬프트와 입력 검증만으로는 Chromium이 이동할 수 있는 위치가 강제로 제한되지 않습니다. 컨트롤러를 확장할 때는 OpenAI의 컴퓨터 사용 가이드를 검토하세요. 에이전트를 샌드박스에 연결하는 다른 방법은 에이전트를 참조하세요. 라이프사이클 관리에 대해서는 정리 패턴을 참조하세요.
마지막 수정일 2026년 10월 15일