OpenAI Node SDK, 에이전트 세션 오류를 스트림으로 전달

오류 뒤의 세션 알림을 놓치지 않도록 합니다

OpenAI Node SDK 7.53.0은 한국시간 2026년 11월 6일 공개됐습니다. Beta Agents 스트림 안에서 전달되는 오류를 예외로 던져 즉시 닫는 대신 이벤트로 전달하도록 변경합니다. 일반적인 모든 스트림 API의 오류 처리가 바뀐 것은 아닙니다.

PR #3120은 세션 수명 알림보다 오류 이벤트가 먼저 도착할 수 있다고 설명합니다. 이전에는 그 오류에서 스트림이 닫혀 앱이 뒤따르는 이벤트를 놓쳤습니다. 수정 대상은 beta.agents.sessions.events.stream()과 스트리밍 방식의 beta.agents.sessions.create()입니다.

이벤트 처리와 예외 처리가 모두 필요합니다

이 두 경로는 해석된 JSON 페이로드를 오류를 포함해 전달합니다. 앱은 반복문 안에서 이벤트 종류를 구분해야 합니다. 정상 출력만 이어 붙이는 코드라면 세션 오류가 도착했을 때 화면 상태와 저장 상태를 어떻게 바꿀지 추가로 확인해야 합니다.

반면 HTTP 오류, 네트워크 실패, 잘못된 JSON은 여전히 예외를 발생시킵니다. 오류가 전부 이벤트로 바뀌었다고 이해하고 예외 처리를 제거하면 다른 실패를 놓치게 됩니다. 스트림 내부의 서비스 오류와 스트림을 전달하는 통신 자체의 실패를 나누는 변경입니다.

EOF를 성공으로 해석하지 마세요

원문은 오류 뒤에 EOF가 왔다고 성공한 finalResult가 만들어지는 것은 아니라고 명시합니다. 연결이 끝났다는 사실과 작업이 정상 완료됐다는 사실은 다릅니다. 이미 일부 출력이 화면에 나타났더라도 세션 결과가 실패일 수 있습니다.

부분 응답을 저장하는 앱이라면 완료·중단·오류 상태를 별도로 남겨 보세요. 다음 화면에서 이전 출력을 다시 보여줄 때도 사용자가 그 내용을 최종 결과로 오해하지 않도록 구분할 수 있습니다. 이는 변경을 적용하는 설계 제안이며 SDK가 자동으로 제공하는 화면 기능은 아닙니다.

재시도 전에 실행 결과를 확인합니다

실패가 보였다고 이전 도구 작업까지 취소됐다고 가정할 수는 없습니다. 파일이나 외부 시스템을 바꾸는 흐름에서는 실행 식별자와 완료된 작업을 보존하고 결과가 불명확한 부분부터 확인하는 편이 좋습니다. 같은 요청을 무조건 처음부터 보내면 부작용이 중복될 수 있습니다.

PR의 검증은 로컬 HTTP 서버의 합성 SSE를 사용해 두 메서드와 여러 모듈 형식을 비교한 결과입니다. 이를 실제 서비스의 모든 오류 순서가 검증됐다는 뜻으로 확대하지 않았습니다. 프로젝트에서는 정상 출력 후 오류, 오류 후 상태 알림, 네트워크 단절을 나누어 시험해 보세요. 이 글은 원문 검토이며 직접 SDK 스트림을 실행한 테스트 결과는 아닙니다.

출처

• Node SDK 7.53.0 공식 릴리스
• PR #3120 · 이벤트 전달과 예외 처리 경계