개발자가 Async 래퍼로 SSE 스트림을 .jsonl 파일에 녹화하여 프로덕션 AI 에이전트 디버깅을 가능하게 했다

Context

AI 에이전트 스트림은 SSE 연결이 상태 저장이고 일시적이다. REST API는 요청/응답을 로그로 남길 수 있지만, 스트림 이벤트는 버퍼에서 소비되자마자 사라진다. 프로덕션에서 UI가 잘못된 상태로 멈추면 스크린샷과 메모리로만 디버깅해야 했다.

Technical Solution

• AgentStreamRecorder → Async 제너레이터를 래핑하여 각 SSE 이벤트를 .jsonl 파일에 저장하고 원본을 그대로 전달
• 세션 헤더 → UUID, 시작 시간, t=0-baseline 포함하여 머신 간 이식성 보장
• 상대 타임스탬프(t 필드) → 'tool_result가 tool_use 842ms 후 도착'과 같이 디버깅에 유용한 정보 제공
• 매 쓰기 후 flush → 프로세스 충돌 시에도 마지막 이벤트까지 기록 유지
• agent-stream CLI로 --speed 옵션을 사용한 배속/슬로우 재생 지원

Impact

프로덕션에서 3주간 재발생하던 버그를 녹화/재생으로 15분 만에 해결했다.

Key Takeaway

AI 에이전트 디버깅의 핵심은 개별 에러 코드가 아닌 이벤트 시퀀스이며, 스트림을 녹화 가능하게 만드는 것만으로 디버깅 방식이 근본적으로 달라진다.