샌드박스 수명 주기

샌드박스 수명 주기 (Sandbox lifecycle)

에이전트 세션은 환경보다 오래 살 수 있어요. 여러분의 애플리케이션이 self_hosted 환경이 사용하는 컴퓨팅과 파일을 관리해요. 환경 시작, 유지, 재연결, 정리를 다루는 가이드예요.

출처: 문서

본문

에이전트 세션은 환경보다 오래 살 수 있어요. 여러분의 애플리케이션이 self_hosted 환경이 사용하는 컴퓨팅과 파일을 관리해요.

환경 시작하기

여러분의 애플리케이션은 세션을 만든 뒤 컴퓨팅을 시작할 수 있어요. 제공자의 SDK 또는 API를 사용한 뒤, 세션의 환경 ID와 환경 키로 executor를 연결하세요.

OpenAI Cookbook의 application-managed sandbox examples를 참고하세요.

각 세션의 환경을 관리할 구성 요소 하나를 사용하세요. 세션과 제공자 컴퓨팅 사이의 매핑을 저장하세요. 반복되거나 동시에 오는 요청이 중복 환경을 만들어서는 안 돼요.

웹훅에서 컴퓨팅 시작하기

입력이 환경 연결을 필요로 할 때까지 기다릴 수도 있어요. API는 executor를 기다리기 전에 required_action.type: "environment_connection"과 함께 agent.session.action_required를 발행해요. 여러분의 웹훅 핸들러가 환경을 시작하거나 다시 연결해요.

OpenAI Cookbook의 webhook-managed sandbox examples를 참고하세요.

agent.session.action_required와 agent.session.failed에 대한 핸들러를 등록하려면 webhook setup을 따르세요. 서명 비밀과 세션 읽기 자격 증명을 executor의 environment key와 분리해서 유지하세요. 여러 제공자 핸들러가 프로젝트를 공유하면, 세션을 소유한 핸들러로 이벤트를 라우팅하세요.

핸들러와 워커는 별개의 작업을 가져요:

1. 검증 및 대기열에 넣기(Verify and queue). 웹훅 서명을 검증해요. data.required_action.type이 environment_connection일 때만 연결 요청을 대기열에 넣어요. 세션 실패도 대기열에 넣어요. 대기열에 넣는 데 성공한 뒤에만 성공적인 HTTP 응답을 반환해요.
2. 현재 상태 확인(Check current state). 워커가 세션을 검색해요. 삭제된 세션과 해결된 액션은 무시해요. 여전히 연결이 필요한 자체 호스팅 세션의 경우 session.environment.id와 session.environment.remote_url을 사용해 executor를 시작하거나 다시 연결해요. 여전히 실패한 세션의 경우 컴퓨팅을 해제해요.

세션 스트림은 같은 요청을 agent.session.requires_action로 보고해요. function_call required action은 환경 시작이 아니라 함수 결과가 필요해요. 턴 생성과 agent.session.in_progress 이벤트는 오프라인 executor를 시작하기에는 너무 늦게 도착해요.

핸들러를 배포한 뒤 self-hosted session을 만들고 입력을 보내세요. 핸들러에 설정한 작업 디렉토리와 에이전트 필터를 일치시키세요. executor가 마감 전에 연결되면 원래 제출이 계속돼요.

환경을 유지하거나 멈추기

턴 사이에 컴퓨팅을 계속 실행해 재사용하거나, 턴이 끝난 뒤 멈추기 전에 유예 기간(grace period)을 허용하세요. 들어오는 작업과 종료를 조정하세요. 연결이 요청되거나 실행이 시작되면 보류 중인 종료를 취소하세요. 컴퓨팅을 멈추기 전에 상태를 다시 확인하세요.

유휴(idle) 이벤트만으로는 안전한 종료 신호가 아니에요. 연결 요청이 해소될 때, 대기 중인 입력이 턴을 시작하기 전에 도착할 수 있거든요. 애플리케이션이 들어오는 작업과 종료를 조정할 수 없다면 환경을 계속 실행 상태로 두세요.

연결 해제 후 재연결하기

연결 이벤트는 상태를 보고해요. agent.session.environment.connected와 agent.session.environment.disconnected를 사용해 연결을 관찰하세요. 설정 과정에서 agent.session.environment.pending 또는 agent.session.environment.failed도 발행될 수 있어요. 이 이벤트들은 컴퓨팅을 요청하지 않아요. 시작을 트리거하려면 environment_connection required action을 사용하고, 제공자 상태는 별도로 확인하세요.

턴 중간의 연결 해제는 턴이 완료되더라도 도구를 실패시킬 수 있어요. 도구 결과와 에이전트의 최종 응답을 검사하세요. 연결 해제는 웹훅을 통한 재연결을 자동으로 요청하거나 죽은 명령을 재시작하지 않아요. 이후 입력이 재연결을 요청할 수 있어요.

API는 입력 시 연결을 최대 5분 동안 기다려요. 이 대기를 위해 클라이언트와 프록시 타임아웃을 설정하세요. 만료되면 제출이 실패해요. 초기 입력은 비동기적으로 실패하고 세션을 failed로 남길 수 있어요.

API는 프로세스 크래시 후 보류 중인 입력의 복구를 보장하지 않아요. 재시도 전에 요청 또는 세션 결과를 확인하세요. 원래 요청이 대기 중일 때는 재제출하지 마세요. 늦은 연결은 타임아웃된 입력을 재생하지 않아요.

환경 ID를 재사용해도 교체된 컴퓨팅의 파일은 복원되지 않아요. 보존하려면 제공자 저장소 또는 스냅샷을 사용하세요.

정리하기

새 입력을 받는 것을 중지하세요. 컴퓨팅이 떠 있는 채로 남지 않도록 이미 진행 중인 시작 작업과 정리를 조정하세요.

세션을 삭제하고 제공자 컴퓨팅을 별도로 중지하세요. 세션을 삭제해도 환경이 중지되거나 삭제 웹훅이 발생하지 않아요.

더 알아보기 (Learn more)

관련 문서: 파일과 아티팩트와 OpenAI 호스팅 환경을 참고하세요.