저는 한 번에 하나의 기여를 통해 오픈 소스 포트폴리오를 키워오고 있으며, 이번 주에는 livekit/agents (11k+ stars, 수많은 실시간 음성 AI 에이전트의 기반이 되는 프레임워크)에서 정말 흥미로운 것을 발견했습니다.

버그 (The bug)

만약 여러분이 실시간 모델(OpenAI Realtime, xAI, Gemini Live)을 사용하여 음성 에이전트를 구축하고 있다면, 모델은 전사(transcription) 내용을 청크(chunks) 단위로 스트리밍하여 다시 보냅니다. 단일 발화(utterance)는 최종 확정되기 전에 많은 user_input_transcribed 이벤트를 발생시킬 수 있습니다. OpenAI/xAI의 경우 토큰(token) 단위로, Gemini의 경우 하나의 큰 중간 블롭(interim blob) 형태로 발생합니다.

만약 발화당 정확히 한 번만 반응하고 싶다면(예를 들어, RPC를 통해 프론트엔드에 "사용자가 입력 중" 표시를 보여주는 경우), 이러한 모든 중간 이벤트들을 서로 연관시킬 수 있는 안정적인 키(key)가 필요합니다.

해당 키는 이미 내부적으로 존재했습니다 — InputTranscriptionCompleted는 item_id를 포함하고 있습니다. 하지만 프레임워크가 이를 상위 계층으로 공개 UserInputTranscribedEvent로서 다시 방출할 때, item_id가 조용히 누락되었습니다. 이로 인해 소비자(consumers)들은 제공자(providers) 간에 중복을 제거(dedupe)할 수 있는 신뢰할 수 있는 방법을 잃게 되었습니다.

수정 사항 (The fix)

발견하고 나니 간단했습니다: 필드를 추가하고, 이를 전달(forward)하면 됩니다.

class UserInputTranscribedEvent(BaseModel):
    transcript: str
    is_final: bool
...

두 개의 파일, 실제 변경 사항은 약 10줄 정도입니다. 실제 작업은 실시간 모델 계층에서 AgentActivity를 거쳐 AgentSession까지 이벤트를 추적하여, 정확히 어느 지점에서 필드가 삼켜졌는지(swallowed) 찾아내는 과정이었습니다.

교훈 (The takeaway)

이 기여를 하기 위해 livekit-agents의 모든 것을 이해할 필요는 없었습니다 — 단지 하나의 이벤트의 라이프사이클(lifecycle)을 처음부터 끝까지 이해하기만 하면 되었습니다. 작고 범위가 명확한 이슈들은 거대한 코드베이스에 진입할 수 있는 가장 달성 가능한 방법이며, 특히 누군가가 이슈 자체에서 이미 영역을 매핑해 두었을 때는 더욱 그렇습니다.

PR이 올라갔고, CI는 통과(green)되었으며, 리뷰를 기다리고 있습니다: github.com/livekit/agents/pull/6172