부제: Telnyx 전화번호를 모니터링하고, Telnyx AI Inference를 통해 평판 리스크를 분석하며, 번호를 유지, 교체 또는 폐기할 시점을 권장하는 Python 앱을 구축합니다.

아웃바운드 워크플로우 (Outbound workflows)는 대부분의 팀이 인정하고 싶어 하는 것보다 번호의 상태 (number health)에 더 많이 의존합니다.

인벤토리 상으로는 번호가 괜찮아 보일 수 있지만, 실제 환경에서는 성능이 저하될 수 있습니다. 응답률이 떨어지고, 불만 사항이 증가하며, 캠페인 패턴이 노후화됩니다. 지난달에는 잘 작동했던 번호가 오늘은 냉각기 (cooldown), 검토 또는 교체가 필요할 수도 있습니다.

이 예제의 배후에 있는 워크플로우는 다음과 같습니다:

https://github.com/team-telnyx/telnyx-code-examples/tree/main/number-reputation-monitor-auto-rotate-python

이것은 사용자의 Telnyx 전화번호를 나열하고, 번호 상태 컨텍스트를 Telnyx AI Inference로 전송하며, 유지(keep), 교체(rotate) 또는 폐기(retire)에 대한 권장 사항을 기록하는 작은 Python Flask 앱입니다.

앱 구조 (The App Shape)

앱은 세 가지 경로 (routes)를 노출합니다:

• POST /scan: 최대 20개의 번호를 분석합니다.
• GET /health-report: 추적된 번호 상태 및 교체 권장 사항을 검사합니다.
• GET /health: 앱 상태를 확인합니다.

이 앱은 두 개의 Telnyx API를 사용합니다:

GET /v2/phone_numbers
POST /v2/ai/chat/completions

현재 기본 모델은 .env.example에 설정되어 있습니다:

AI_MODEL=MiniMaxAI/MiniMax-M3-MXFP8

패턴은 간단합니다: 번호 인벤토리를 가져오고, 상태 지표 (health metrics)를 첨부한 뒤, 모델에 제한된 권장 사항을 요청하고, 결과를 저장합니다.

스캔 중 발생하는 일

스캔은 다음과 같이 시작합니다:

curl -X POST http://localhost:5000/scan \
  -H "Content-Type: application/json" \
  -d '{}'

앱은 Telnyx를 호출하여 전화번호 목록을 가져온 다음, 처음 20개까지의 번호를 분석합니다.

각 번호에 대해 작은 상태 페이로드 (health payload)를 생성합니다. 샘플에서 기본 지표는 의도적으로 단순하게 설정되어 있습니다:

{
  "calls": 0,
  "complaints": 0,
...

그런 다음 앱은 모델에 다음과 같은 JSON을 반환하도록 요청합니다:

{
  "risk_level": "warning",
  "recommendation": "rotate",
...

만약 권장 사항(recommendation)이 rotate라면, 앱은 이를 순환 로그(rotation log)에 기록합니다.

여기서 중요한 점은 다음과 같습니다: 이 샘플은 실제 사용 중인 번호를 자동으로 교체하지 않습니다. 대신 권장 사항을 기록할 뿐입니다. 실제 아웃바운드 시스템(outbound system)에서 순환(rotation)은 일반적으로 정책 확인(policy checks), 캠페인 상태(campaign state), 라우팅 규칙(routing rules) 및 사람의 승인을 포함해야 합니다.

이것이 유용한 이유

번호 평판(Number reputation)은 단일 플래그(flag)가 아닙니다.

그것은 대개 다음과 같은 신호(signals)들의 집합입니다:

• 응답률 (answer rates)
• 불만 사항 (complaints)
• 수신 거부 (opt-outs)
• 통화량 (call volume)
• 캠페인 이력 (campaign history)
• 통신사 필터링 신호 (carrier filtering signals)
• 최근 라우팅 동작 (recent routing behavior)

모델은 아무것도 없는 상태에서 결정을 만들어내라고 요구받지 않을 때 유용합니다. 모델은 구조화된 운영 컨텍스트(operational context)를 전달받고 제한된 권장 사항을 반환할 때 유용합니다.

이를 통해 출력값을 대시보드(dashboard), 검토 대기열(review queue) 또는 아웃바운드 라우팅 시스템(outbound routing system)으로 더 쉽게 전달할 수 있습니다.

상태 보고서(Health Report) 검사하기

스캔 후에는 현재 상태를 검사할 수 있습니다:

curl http://localhost:5000/health-report

응답에는 추적된 번호와 최근 순환 권장 사항이 포함됩니다:

{
  "numbers": {
    "+12125551234": {
...

이러한 구조는 실제 번호 상태 대시보드(number-health dashboard)를 구축하기 위한 시작점을 제공합니다.

중요한 작은 디테일

프롬프트(prompt)는 모델에게 산문(prose)이나 마크다운 구분 기호(markdown fences) 없이 오직 JSON만 반환하도록 요청합니다.

앱에는 여전히 마크다운 구분 기호를 제거하고 JSON 객체를 파싱(parse)하는 헬퍼(helper)가 포함되어 있습니다. 저는 이 패턴을 선호하는데, AI 앱 코드는 방어적(defensive)이어야 하기 때문입니다. 프롬프트가 도움이 되긴 하지만, 출력을 애플리케이션 상태(application state)로 사용할 수 있게 유지해 주는 것은 바로 검증(validation)입니다.

다음에 추가하고 싶은 것

프로덕션(production) 환경을 위해, 저는 다음과 같은 것들을 추가하겠습니다:

• 전화(calls), 메시지(messages), 수신 거부(opt-outs), 불만 사항(complaints) 및 캠페인 결과(campaign outcomes)로부터 얻은 실제 지표 (Real metrics)
• 번호 이력을 위한 지속적 저장소 (Persistent storage)
• 수동 스캔 대신 예약된 스캔 (Scheduled scans)
• 중요한 번호에 대한 알림 (Alerts)
• 번호 교체(rotation) 또는 폐기(retirement) 전 사람의 승인 (Human approval)
• 위험한 번호를 활성 캠페인에서 제거하는 라우팅 규칙 (Routing rules)
• 웜업(Warmup) 및 쿨다운(cooldown) 정책
• 모든 권장 사항 및 조치에 대한 감사 로그 (Audit logs)

이 리포지토리(repo)는 에이전트가 읽을 수 있도록 구조화되어 있습니다. 여러분의 코딩 에이전트(coding agent)는 README, API 레퍼런스(API reference), 가이드, 환경 파일(environment file), 앱 코드를 검사한 후 이를 확장하는 데 도움을 줄 수 있습니다. 에이전트에게 예약된 스캔, 지속적인 지표, 테스트, 대시보드 또는 실제 라우팅 통합을 추가하도록 요청할 수 있습니다.

직접 시도해보기 (Try It)

코드:
https://github.com/team-telnyx/telnyx-code-examples/tree/main/number-reputation-monitor-auto-rotate-python

Telnyx AI 기술 및 툴킷 (AI skills and toolkits):
https://github.com/team-telnyx/ai

전화번호 목록 조회 API (List Phone Numbers API):
https://developers.telnyx.com/api/numbers/list-phone-numbers

Telnyx AI 추론 문서 (Telnyx AI Inference docs):
https://developers.telnyx.com/docs/inference

채팅 완성 API (Chat Completions API):
https://developers.telnyx.com/api/inference/chat-completions

Telnyx 포털 (Telnyx Portal):
https://portal.telnyx.com/