미로
OpenAI Python SDK, 에이전트 환경 중지·만료 이벤트 지원
제어 API가 아니라 상태 이벤트 지원입니다
OpenAI Python SDK 3.28.0은 한국시간 2026년 10월 10일 공개됐습니다. 에이전트 환경이 중지되거나 만료됐음을 나타내는 스트림·웹훅 이벤트 타입이 추가됩니다. 기존 글의 ‘환경 중지와 만료 설정 추가’라는 표현과 달리, 이번 변경의 확인된 범위는 상태를 받아 해석하는 클라이언트 지원입니다.
PR #4046은 suspended와 expired 이벤트를 추가하고 기존 ready·failed 변형을 유지한다고 설명합니다. 릴리스 제목만 보고 환경을 중지시키는 새 메서드나 만료 시간을 설정하는 기능이 생겼다고 단정해서는 안 됩니다.
중지와 만료는 복원 가능성이 다릅니다
변경 코드의 상태 설명에서 suspended는 환경이 멈췄지만 비공개 체크포인트에서 재개할 수 있는 상태입니다. expired는 환경과 체크포인트가 만료된 상태로 설명됩니다. 둘 다 현재 연결되지 않았다는 이유로 같은 상태로 처리하면 사용자에게 잘못된 재개 가능성을 안내할 수 있습니다.
세션 스트림의 새 이벤트에는 환경 상태와 이벤트·세션 식별자가 있으며, 해당하는 경우 turn_id도 포함됩니다. 웹훅은 수명이 바뀐 환경의 식별자를 전달합니다. 서로 다른 전달 경로가 같은 형태라고 가정하지 말고 각각의 타입을 확인해야 합니다.
웹훅 구독 이름도 추가됩니다
SDK는 웹훅 구독 생성·수정·테스트 매개변수에 agent.environment.suspended와 agent.environment.expired를 허용합니다. 이는 앱이 해당 이벤트를 구독하고 처리할 수 있도록 이름과 타입을 지원하는 변화입니다. SDK 업데이트 자체가 운영 서버의 구독을 자동으로 바꾸지는 않습니다.
원문은 공개 SDK 배포와 백엔드 활성화가 별도 단계라고 밝힙니다. 따라서 클라이언트에 타입이 있다는 사실만으로 모든 프로젝트에서 즉시 이벤트가 발생한다고 보장할 수 없습니다. 실제 서비스 지원 여부와 현재 구독 구성을 함께 확인해야 합니다.
화면과 재개 판단을 분리해 보세요
앱에서는 ‘연결이 끊김’, ‘재개 가능한 중지’, ‘체크포인트 만료’를 다른 상태로 표현하는 방식을 검토할 수 있습니다. 만료 알림을 받은 뒤 예전 실행을 그대로 다시 보내는 대신, 보존한 결과와 새로 시작할 작업을 구분하는 흐름이 필요할 수 있습니다. 이는 앱 설계 제안이지 새 제어 API의 사용 예가 아닙니다.
PR은 동기·비동기 수명 이벤트와 서명 웹훅 집중 테스트를 보고했습니다. 이 글에서 실제 환경을 중지하거나 만료시킨 것은 아닙니다. 변경된 타입을 수신 코드에 반영하고, 알 수 없는 상태를 만났을 때도 전체 처리 흐름이 멈추지 않는지 작은 테스트부터 확인하시면 좋겠습니다.
댓글
이 글에 대한 생각을 남겨 주세요.