에이전트 세션은 환경이 종료된 후에도 유지될 수 있습니다. self_hosted 환경에서 사용하는 컴퓨팅 리소스와 파일은 애플리케이션이 관리합니다.
환경 시작
애플리케이션은 세션을 생성한 후 컴퓨팅 리소스를 시작할 수 있습니다. 공급자의 SDK 또는 API를 사용해 리소스를 시작한 다음, 세션의 환경 ID와 환경 키로 실행기를 연결하세요.
OpenAI Cookbook의 애플리케이션에서 샌드박스를 관리하는 예제를 참고하세요.
각 세션의 환경은 하나의 컴포넌트가 관리하도록 하세요. 세션과 공급자의 컴퓨팅 리소스 간 매핑을 저장하세요. 요청이 반복되거나 동시에 들어와도 환경이 중복 생성되지 않도록 해야 합니다.
웹훅으로 컴퓨팅 리소스 시작
입력을 처리하는 데 환경 연결이 필요할 때까지 기다릴 수도 있습니다. API는 실행기가 연결되기를 기다리기 전에 agent.session.action_required 이벤트를 보내며, 이 이벤트에는 required_action.type: "environment_connection"이 포함됩니다. 웹훅 핸들러는 환경을 시작하거나 다시 연결합니다.
OpenAI Cookbook의 웹훅으로 샌드박스를 관리하는 예제를 참고하세요.
웹훅 설정 안내에 따라 agent.session.action_required 및 agent.session.failed 이벤트를 처리할 핸들러를 등록하세요. 핸들러의 서명 비밀 키와 세션 읽기용 자격 증명은 실행기의 환경 키와 분리해 관리하세요. 여러 공급자의 핸들러가 한 프로젝트를 공유하는 경우 해당 세션을 담당하는 핸들러로 이벤트를 전달하세요.
핸들러와 워커는 각각 다음 작업을 담당합니다.
- 서명 검증 및 큐 등록. 핸들러에서 웹훅 서명을 검증하세요.
data.required_action.type값이environment_connection일 때만 연결 요청을 큐에 넣으세요. 세션 실패 이벤트도 큐에 넣으세요. 큐 등록에 성공한 후에만 HTTP 성공 응답을 반환하세요. - 현재 상태 확인. 워커는 세션을 조회합니다. 삭제된 세션과 이미 해결된 작업은 무시하세요. 자체 호스팅 세션에 여전히 연결이 필요하면
session.environment.id와session.environment.remote_url을 사용해 실행기를 시작하거나 다시 연결하세요. 세션이 여전히 실패 상태라면 해당 세션의 컴퓨팅 리소스를 해제하세요.
세션 스트림은 같은 요청을 agent.session.requires_action 이벤트로 알립니다. 필요한 작업이 function_call이면 환경을 시작하는 대신 함수 실행 결과를 제공해야 합니다. 턴 생성 이벤트와 agent.session.in_progress 이벤트가 도착하는 시점에는 오프라인 실행기를 시작하기에 이미 늦습니다.
핸들러를 배포한 후 자체 호스팅 세션을 생성하고 입력을 보내세요. 작업 디렉터리는 핸들러 설정과 일치해야 하며, 핸들러에 에이전트 필터가 설정되어 있다면 그 조건도 충족해야 합니다. 제한 시간 내에 실행기가 연결되면 처음 제출한 요청이 계속 처리됩니다.
환경 유지 또는 중지
다음 턴에서 재사용할 수 있도록 턴 사이에도 컴퓨팅 리소스를 계속 실행하거나, 턴이 끝난 후 일정 시간 기다렸다가 중지하세요. 새로 들어오는 작업과 충돌하지 않도록 종료 시점을 조정하세요. 연결 요청이 들어오거나 실행이 시작되면 예정된 종료를 취소하세요. 컴퓨팅 리소스를 중지하기 전에 상태를 다시 확인하세요.
유휴 이벤트만으로는 환경을 안전하게 종료할 수 있는지 판단할 수 없습니다. 연결 요청이 해소된 후 대기 중인 입력의 턴이 시작되기 전에 유휴 이벤트가 도착할 수 있습니다. 애플리케이션에서 새로 들어오는 작업에 맞춰 종료 시점을 조정할 수 없다면 환경을 계속 실행하세요.
연결이 끊긴 후 다시 연결
연결 이벤트는 연결 상태를 알려 줍니다. agent.session.environment.connected 및 agent.session.environment.disconnected 이벤트로 연결 상태를 확인하세요. 설정 과정에서는 agent.session.environment.pending 또는 agent.session.environment.failed 이벤트도 발생할 수 있습니다. 이러한 이벤트는 컴퓨팅 리소스를 요청하지 않습니다. environment_connection 작업이 요청되면 컴퓨팅 리소스를 시작하고, 공급자의 서비스 상태는 별도로 확인하세요.
턴 도중 연결이 끊기면 턴이 완료되더라도 도구 실행은 실패할 수 있습니다. 도구 실행 결과와 에이전트의 최종 응답을 확인하세요. 연결이 끊겨도 웹훅으로 재연결 요청이 자동 전송되거나 강제 종료된 명령어가 다시 실행되지는 않습니다. 이후 입력이 들어오면 재연결 요청이 발생할 수 있습니다.
입력 시점에 연결이 필요하면 API는 최대 5분까지 기다립니다. 이 대기 시간을 고려해 클라이언트와 프록시의 타임아웃을 설정하세요. 제한 시간 내에 연결되지 않으면 제출한 요청이 실패합니다. 첫 입력은 비동기적으로 실패할 수 있으며, 이 경우 세션이 failed 상태로 남을 수 있습니다.
프로세스가 비정상 종료된 후에는 API가 대기 중이던 입력의 복구를 보장하지 않습니다. 재시도하기 전에 요청이나 세션의 처리 결과를 확인하세요. 원래 요청이 대기 중인 동안에는 입력을 다시 제출하지 마세요. 제한 시간이 지난 뒤 연결되더라도 시간이 초과된 입력은 다시 처리되지 않습니다.
환경 ID를 재사용해도 새 컴퓨팅 리소스에 기존 파일이 복원되지는 않습니다. 파일을 보존하려면 공급자의 스토리지나 스냅샷을 사용하세요.
리소스 정리
새 입력을 더 이상 받지 않도록 하세요. 정리가 끝난 뒤에도 컴퓨팅 리소스가 계속 실행되는 일이 없도록 이미 진행 중인 시작 작업과 정리 작업의 실행 시점을 조정하세요.
세션을 삭제하고 공급자의 컴퓨팅 리소스는 별도로 중지하세요. 세션을 삭제해도 환경은 중지되지 않으며 삭제 웹훅도 전송되지 않습니다.