LiveKit Agent job 시작 실패
configRef를 가진 참가자 부재

마지막 업데이트 2026-10-28

대상: 2026-10-27 13:30~21:30 KST prod agent WARNING/ERROR 로그분석: 2026-10-28 · 갱신: 2026-10-28 (LiveKit 서버 로그 대조 + 수정 적용) · 이슈 ID 미발급코드 확인: develop 31af4ffe · 배포 SHA 미확인

1. 코드 경로

PPI 저장소 상대 경로역할
apps/livekit-agent/agent.py · ppi_agent (L5506~)job entrypoint. 가장 먼저 _fetch_model_config(ctx.room.name)을 호출. 예외 시 job 전체 종료.
apps/livekit-agent/agent.py · _fetch_model_config (L412~466)list_participants로 room 참가자를 조회하고, metadata의 configRef로 Valkey 설정 스냅샷을 읽음. 못 찾으면 RuntimeError("LiveKit valkey model config metadata was not found").
apps/livekit-agent/agent.py · ModelConfigParticipantMissingError (L400~) · ppi_agent except (L5513~)수정(로컬): metadata 보유 참가자가 없으면 전용 예외를 올리고, entrypoint가 WARN 로그 후 request_shutdown("model_config_participant_missing")으로 정상 종료.
apps/web/lib/voice-agent/livekit-token.ts · createLiveKitParticipantToken (L90~123)같은 metadata(configRef)를 참가자 토큰 metadata와 RoomAgentDispatch metadata 두 곳에 넣음.

2. 판정 요약

확정(코드+Agent 로그+LiveKit 서버 로그): job 시작 실패 5건은 모두 아동이 한 번도 들어오지 않은 빈 room에 배정된 job이다. 아동 PC 연결이 끊긴 뒤 20초 departure timeout으로 room이 닫혔고, 아동 클라이언트의 늦은 재연결(resume)이 같은 이름의 room을 다시 만들었다. join 자체는 could not restart participant로 거부됐지만, 토큰의 RoomAgentDispatch로 job만 배정됐다. configRef 형식 오류나 Valkey 조회 실패는 아니다.
정정: 초판의 "아동이 들어왔다 곧 나간 race" 추정은 틀렸다. 5개 room 모두 starting RTC session이 0건이며, 4건은 5분 뒤 empty timeout, 1건은 40초 뒤 Web의 DeleteRoom으로 닫혔다. 따라서 job 실패 자체의 수업 영향은 없다. 실제 영향은 그 앞의 아동 연결 끊김이고, 아동 앱의 새 join으로 회복됐다.

로그 전체(162,986행, 1,120 job)에서 수업 진행에 직접 영향을 줄 수 있는 문제는 3종이며 모두 드물다. 반복적인 수업 장애 패턴은 없다.

#증상건수영향
1job 시작 실패 model config metadata was not found5해당 dispatch에서 AI 미기동. 4건은 같은 room 새 job으로 회복
2Typecast TTS 502 Bad Gateway9발화 1회 누락. 외부 공급자 오류, 15:06~21:14 산발
3OpenAI Realtime server_error2응답 1회 실패 (17:36, 19:18)

3. 입출력 흐름 — job 시작 실패의 인과

Web /api/livekit/call
  → 토큰 발급: 참가자 metadata = configRef, RoomAgentDispatch.metadata = configRef (같은 값)
  → 아동 join → room 생성 → job 시작 → 정상 수업
  → 아동 PC 연결 끊김 (participant closing: PEER_CONNECTION_DISCONNECTED)
  → 20초 뒤 LiveKit이 room 종료 (closing idle room: departure timeout)
  → 아동 클라이언트가 늦게 resume 시도 (room 종료 1초~9.5분 뒤)
  → LiveKit: 같은 이름으로 새 room 생성 (selected node for room)
      + 토큰 roomConfig의 RoomAgentDispatch → assigned job to worker
      + 아동 join 거부 (could not handle new participant: could not restart participant)
  → job: list_participants = 0명 → RuntimeError → unhandled exception
  → 빈 room은 5분 뒤 empty timeout으로 종료 (#5만 40초 뒤 Web DeleteRoom)
  → 아동 앱이 새로 join → 새 room·새 job → 회복

LiveKit 서버 로그 대조 (Loki service_name="ppi-livekit")

#이전 room 종료resume 실패 + job 배정간격빈 room 종료
118:03:2118:03:221초18:08:22 empty timeout
218:37:0118:37:1211초18:42:12 empty timeout
319:27:5119:31:35약 4분19:36:35 empty timeout
419:50:0219:50:031초19:55:03 empty timeout
519:59:5420:09:23약 9.5분20:10:03 API_DELETE

같은 시간대 could not restart participant는 6건이다. 6번째(18:18:08, 0af1c571)는 이전 room이 닫히기 2초 전에 들어와 새 room이 생기지 않았고 job도 없었다.

배제 근거

4. 세부 — 실패 job과 회복

실패 KSTroom (앞 8자) · 활동실패 job같은 room 다음 job
18:03:229b548454 · lesson-23 tiki_basicAJ_NSdRH6Vk9N3D18:03:57 (+35초)
18:37:1280fa9fdf · lesson-9 newpp08AJ_M3butGDbpmyX18:38:11 (+1분)
19:31:35353524ae · lesson-10 newpp10AJ_MEozpcPcrbpx19:31:56 (+21초)
19:50:03125c6e7c · lesson-13 newpp11AJ_m9efznRB5B6j19:54:57 (+5분)
20:09:23c03875fb · lesson-20 tiki_basicAJ_sm8xWMbGHBrq없음 — 40초 뒤 Web이 room을 DeleteRoom (세션 정리 경로)

로그가 WARNING 이상만 담고 있으나, 거의 모든 job이 시작 시 turn_detection is deprecated 경고를 남기므로 "다음 job 없음"은 의미 있는 신호로 본다.

무해로 분류한 경고

메시지규모판단
livekit-nc noise cancellation not authorized / unavailable≈100k행LiveKit Cloud 전용 기능. self-hosted에서 상시 발생
event loop blocked — ai_coustics/_ffi.pyjob당 1~2회p50 213ms, p99 255ms, 최대 541ms. 세션 초기화 시점. 1초 이상 차단 0건
VAD inference is slower than realtime37 jobjob당 1~4회, 최대 1.0초. 9/15 좀비 job 같은 연속 누적 없음
skipping reply … cannot be interruptedjob당 ≤17AI 발화 중 아동 발화. 정상 동작
voice_lifecycle_publish_failed / PublishDataError세션당 2건세션 종료 시점 room close 후 발행
turn_detection deprecated · drop unknown FFI handle · ASR continuation RPC unsupported매 job상시 경고

같은 메시지가 두 가지 JSON 형식으로 중복 기록되어 실제 건수는 원시 행 수의 약 1/3이다.

5. 적용한 수정과 주의사항

적용(로컬·미커밋): 참가자 부재를 전용 예외 ModelConfigParticipantMissingError로 분리하고, entrypoint가 unhandled exception 대신 WARN 로그(model config participant missing; shutting down job, jobId·participantCount)를 남긴 뒤 request_shutdown("model_config_participant_missing")으로 정상 종료한다. ctx.connect() 전에 종료하므로 빈 room에 AI가 들어가지 않는다.
try:
    config, config_snapshot = await _fetch_model_config(ctx.room.name)
except ModelConfigParticipantMissingError as exc:
    logger.warning("model config participant missing; shutting down job", ...)
    request_shutdown("model_config_participant_missing")
    return
기각한 초판 개선안: ctx.job.metadata 우선 사용은 적용하지 않았다. 원인이 "아무도 들어오지 않을 room"으로 확정됐기 때문에, 이를 적용하면 빈 room에서 AI 세션이 기동되어 job max duration(45분)까지 슬롯을 점유한다(9/15 좀비 job과 같은 위험).
남은 축(별도 이슈): 실제 장애는 아동 PC 연결 끊김 뒤 resume이 departure timeout(20초)을 넘겨 실패하는 것이다. 클라이언트가 resume 실패 시 즉시 새 join으로 전환하는지는 이번 범위에서 다루지 않았다. 관련: readiness·dispatch 흐름.

6. 인수인계용 요약

자료: ppi-livekit-agent-prod-20261027_1330-2130-warning-error.log (45MB, 162,986행) + Loki ppi-livekit 10/27 18:00~20:30 (43,139행). 수업 영향 후보: job 시작 실패 5건(RuntimeError LiveKit valkey model config metadata was not found, agent.py _fetch_model_config), Typecast 502 9건, OpenAI Realtime server_error 2건. job 실패 원인 확정: 아동 PEER_CONNECTION_DISCONNECTED → 20초 departure timeout으로 room 종료 → 늦은 resume이 같은 이름 room 재생성 + RoomAgentDispatch로 job 배정, join은 could not restart participant로 거부 → list_participants 0명. 5개 room 모두 참가자 0, 4건 empty timeout·1건 API_DELETE. job 실패 자체는 수업 영향 없음. 수정(로컬·미커밋): ModelConfigParticipantMissingError + ppi_agent에서 WARN 후 request_shutdown("model_config_participant_missing"), connect 전 종료. ctx.job.metadata 우선안은 빈 room AI 기동·슬롯 점유 위험으로 기각. 남은 축: 클라이언트 resume 실패 처리(별도 이슈).