인바운드 상담사 — 개발 가이드

1A는 무엇을 하고, 무엇을 하지 않나

2A의 내부 상태 머신

A는 다음 6개 상태만 가진다. 빨간 점선은 바지-인 인터럽트 전이다.

구현 힌트 — gateway.py의 현재 ai_busy 플래그는 THINKING+SPEAKING을 합친 것. 바지-인을 구현하려면 SPEAKING 상태를 별도로 분리하고, send_queue에 쌓인 오디오 청크를 drop 할 수 있게 큐를 재설계해야 한다.

3바지-인 (barge-in) 처리 — A의 가장 어려운 요구사항

핵심 의사 코드

# 재생 중(SPEAKING)에도 수신 미디어를 읽는다 — ai_busy 아님에 주의
async def on_media_chunk(mulaw: bytes):
    if state == "SPEAKING":
        rms = audioop.rms(audioop.ulaw2lin(mulaw, 2), 2)
        if rms > BARGE_IN_THRESHOLD:        # ex) 500
            barge_counter += 1
            if barge_counter >= 3:           # ~60ms 연속 감지
                await abort_tts()             # 1) send_queue.clear() + Twilio clear
                offset_ms = compute_offset()    # 2) 지금까지 송신한 ms
                start_listening(prev_offset=offset_ms)
                state = "LISTENING"
    elif state == "LISTENING":
        buffer.extend(mulaw)
        if vad_detected_end(buffer):      # ≥0.8s 무음
            utter = bytes(buffer); buffer.clear()
            text = await stt(utter)
            reply = await B.chat(text,
                                  utterance_offset=prev_offset,
                                  caller_phone=caller_phone)
            await speak(reply)

4B와의 인터페이스 계약

A → B 로 보내는 것

B → A 로 받는 것

B는 내부적으로 DB 저장·네이버 조회 등을 하지만, A의 관심사는 아니다. A는 reply_text만 받아서 읽으면 된다.

5시나리오별 시퀀스

6A 주변 데이터 흐름 (한 장 요약)

7구현 현황 — 무엇이 있고, 무엇을 더 만들어야 하나

8PR 전 셀프 체크리스트

• ✅ A가 새로 추가한 코드 안에 import google.genai, naver, db 같은 import가 없는가? (있다면 경계 침범)
• ✅ 응답 텍스트를 A 자체가 만들지 않는가? (TTS 인풋은 오직 B가 준 reply_text)
• ✅ 바지-인 발생 시 utterance_offset 이 B로 전달되는가?
• ✅ caller_phone 이 매 턴 B에 전달되는가?
• ✅ 통화 종료 시 텍스트/음성 파일이 남는가?
• ✅ 예외/타임아웃 시 통화가 hang 걸리지 않고 END 상태로 수렴하는가?