Telnyx Decision Models를 사용한 자동화된 통화 후 QA 점수 산출 방법

지원팀은 수학적 문제를 안고 있습니다.

매주 수천 건의 고객 통화가 발생하지만, 관리자들은 그중 극히 일부만을 수동으로 검토할 수 있습니다. 설령 통화에 대한 점수가 매겨지더라도, 그 점수는 종종 스프레드시트 속에 고립되어 존재합니다. 이 점수만으로는 에이전트가 어려운 대화를 한 건인지, 아니면 특정 패턴을 발전시키고 있는지를 알려줄 수 없습니다.

이는 두 가지 뚜렷한 엔지니어링 문제를 야기합니다:

커버리지(Coverage): 각 녹취록을 직접 듣지 않고도 더 많은 완료된 통화를 평가하는 것.
메모리(Memory): 에이전트의 결과를 충분히 오래 보존하여 트렌드를 식별하고 더 나은 코칭 결정을 내릴 수 있도록 하는 것.

오픈 소스 post-call-qa-scoring 예제는 이 두 가지 문제를 모두 해결합니다. 이는 Telnyx Decision Models를 사용하여 스크립트를 채점하고, 내구성 있는 QAAgent 액터(actor)를 이용해 각 지원 에이전트의 품질 기록을 유지합니다.

결과는 자율적인 징계 시스템이 아닙니다. 인간의 주의가 필요한 통화와 트렌드를 표면화하는 방법입니다.

애플리케이션의 작동 방식

지원 통화가 종료되면, 이 애플리케이션은 다음 작업을 수행합니다:

call-conversation-ended 웹훅(webhook)으로부터 스크립트를 수신합니다.
스크립트가 임베드되지 않은 경우 transcription-saved를 폴백(fallback)으로 사용합니다.
지원 에이전트 ID로 키 지정된 내구성 있는 액터(actor)로 스크립트를 라우팅합니다.
Telnyx Decision Model에 세 가지 구조화된 채점 신호(structured grading signals)를 요청합니다.
결과를 개별 액터별 SQL에 저장합니다.
5회 통화 로링 평균(rolling average)을 재계산합니다.
해당 트렌드를 기반으로 코칭 권장 사항을 플래그 지정하거나 해제합니다.
잠재적인 규정 준수 위반(compliance breaches)은 관리자에게 SMS를 통해 에스컬레이션(escalate)합니다.
팀 리드에게 일일 에이전트별 요약본(digest)을 전송합니다.

각 통화 ID는 채점 스케줄링 전에 SQL 기본 키(primary key)로 저장됩니다. 또한, 스케줄된 작업은 안정적인 ID인 grade:<callId>를 사용하므로 웹훅 재시도 시 중복 점수가 생성되지 않습니다.

지원 에이전트당 액터 하나를 사용하는 이유?

핵심 설계 결정은 다음과 같습니다:

액터(actor)는 에이전트의 품질 프로필입니다.

작업자(worker)는 idFromName(agentId)를 사용하여 액터(actor)를 해결합니다. 해당 지원 에이전트의 이후 모든 통화 기록은 동일한 내구성 있는 액터에 도달합니다.

const actorId = env.QA_AGENT.idFromName(agentId);
const qaAgent = env.QA_AGENT.get(actorId);

...

이 액터는 점수 기록(score history), 이동 평균(rolling average), 코칭 상태(coaching state), 위반 기록(breach records), 그리고 요약 일정(digest schedule)을 소유합니다. 따라서 애플리케이션은 다른 호출이 끝날 때마다 캐시에서 에이전트의 이력을 재구성할 필요가 없습니다.

구조화된 필드로 통화 기록 평가하기

자유 형식 모델 출력(Free-text model output)은 QA 자동화에 적합하지 않습니다. 만약 모델이 단락을 반환한다면, 다운스트림 코드(downstream code)는 평균을 계산하거나 에스컬레이션 임계값(escalation threshold)을 적용하기 전에 그 산문을 해석해야 합니다.

대신 이 예제는 Telnyx Decision Models 엔드포인트를 호출합니다:

POST /v2/ai/typesafe/v1/systemone

하나의 요청으로 세 가지 유형의 질문에 대해 통화 기록을 평가합니다:

choice: 합격 또는 특정 실패 카테고리
noul: 0–1 범위의 규정 준수 위반 신호(compliance-breach signal)
score: 0–5점의 전반적인 품질 점수

애플리케이션은 이후 타입화된 값에 일반 프로그램 논리를 적용할 수 있습니다:

interface DecisionResult {
  choice: string;
  noul: number;
...
}

한 호출이 전반적인 품질 평가를 통과했더라도 심각한 규정 준수 신호를 포함할 수 있습니다. 따라서 샘플은 이러한 필드들을 독립적으로 처리합니다. noul 값이 0.8을 초과하면, 합격/실패 여부와 관계없이 해당 호출을 breaches 테이블에 기록하고 즉시 관리자 검토 알림(manager-review alert)을 보냅니다.

Decision Models는 여기서 검토자를 대체하지 않습니다. 그들은 누구 앞에 어떤 증거를 제시해야 할지 결정합니다.

개별 점수를 추세로 만들기

성공적인 평가가 끝날 때마다, 액터는 SQL 기록을 쿼리하고 5회 호출 이동 평균을 재계산합니다.

SELECT ts, choice, noul, score, status, last_error
FROM scores
WHERE status = 'graded'
...

평균 점수가 QA_COACHING_FLOOR 아래로 떨어지면, 액터가 해당 상담원에게 코칭이 필요하다고 플래그를 지정합니다. 이후 통화에서 평균 점수가 다시 임계치 위로 올라오면, 이 플래그는 자동으로 해제됩니다.

이러한 구분은 중요합니다. 낮은 점수는 단발성 통화일 수 있습니다. 하지만 하락하는 이동 평균(rolling average)은 근본적인 대화를 조사하거나 코칭하거나 검토해야 할 더 강력한 이유가 됩니다.

실패 사례를 가시적으로 유지하기

이 채점 작업은 무한히 재시도하는 대신 제한된 재시도를 사용합니다. 일시적 오류(Transient failures)는 10초, 30초, 60초 간격으로 백오프(back off)합니다. 만약 여전히 채점이 완료되지 않으면, 해당 통화는 status="ungraded"와 last_error 값을 가지고 저장됩니다.

따라서 일일 요약본은 낮은 점수와 성공적으로 채점되지 않은 녹취록을 구분할 수 있습니다. 실패한 AI 작업이 보고 파이프라인에서 조용히 사라지지 않습니다.

통화를 연결하지 않고 전체 파이프라인 테스트하기

해당 리포지토리에는 합성 데모 엔드포인트가 포함되어 있습니다. 예제를 배포한 후 다음 명령을 호출하세요:

curl -X POST https://<edge-function-url>/demo/trigger \
  -H "Content-Type: application/json" \
  -d '{ 
...

이 엔드포인트는 웹훅 흐름에서 사용되는 것과 동일한 액터, Decision Models 요청, SQL 히스토리, 트렌드 계산 및 에스컬레이션 로직을 통해 녹취록을 라우팅합니다. 이는 시연 및 테스트를 위한 것이므로, 라이브 통화 애플리케이션을 연결하기 전에 아키텍처를 검사할 수 있습니다.

예제 실행하기

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/post-call-qa-scoring

...

실시간 Decision Models 호출 및 SMS 알림을 위해서는 Telnyx API 키, 메시징이 활성화된 Telnyx 번호, 그리고 팀 리드의 E.164 번호를 Edge 비밀(Edge secrets)로 구성해야 합니다. 해당 리포지토리의 README에는 코칭 플로어와 요약본 시간(digest hour)을 포함하여 지원되는 모든 설정에 대한 내용이 문서화되어 있습니다.

이 패턴을 다음에 적용할 곳

샘플은 지역 은행 지원 시나리오를 사용하지만, 이 아키텍처는 대화가 시간이 지남에 따라 일관된 검토가 필요한 모든 곳에서 유용합니다:

컨택센터 코칭
헬스케어 커뮤니케이션 감사(audits)
보험 고지 의무 확인(disclosure checks)
영업 통화 품질 모니터링
고객 서비스 에스컬레이션 검토

여기서 중요한 패턴은 단순히 통화 점수 산출을 넘어섭니다. 구조화된 결정(structured decisions)을 생성하고, 측정 대상 엔티티 주변에 지속적인 기록(durable history)을 유지하며, 높은 위험도의 결과는 사람에게 전달하는 것입니다.

Telnyx Decision Models를 사용한 자동화된 통화 후 QA 점수 산출 방법

요약

핵심 포인트