Skip to main content

프롬프트 작성 가이드

프롬프트는 음성 에이전트의 품질을 결정하는 핵심 요소입니다. 구조화된 프롬프트를 작성하면 에이전트가 일관되게 동작하고, 예외 상황에서도 안정적으로 응대할 수 있습니다.
vox.ai Skills를 설치하면 AI 코딩 도구에서 프롬프트 작성 베스트 프랙티스를 바로 활용할 수 있습니다:
npx skills add https://github.com/vox-public/vox-skills --skill vox-best-practice

프롬프트 구조

음성 에이전트의 프롬프트는 12개 섹션으로 구성됩니다. 각 섹션이 명확한 역할을 가지므로, 수정이 필요할 때 해당 섹션만 변경하면 됩니다.
섹션역할
역할에이전트 이름, 소속, 핵심 업무 정의
컨텍스트대상 고객, 응대 가능 범위, 실시간 음성 모드 명시
변수{{변수}} 선언과 폴백 규칙
목표우선순위별 성공 기준
말투존댓말 수준, 톤, 스타일 규칙
자연스러움간투사 설정 (꺼짐/낮음/보통/높음)
턴테이킹한 턴에 한 질문, 침묵/불명확 처리
문자 정규화전화번호·이메일·코드의 음성/문자 변환 규칙
도구사용 가능한 도구, 실패 처리, 무음 실행 규칙
가드레일금지 행동, 팩트 확인, 범위 제한
에러 처리오해·충돌·장애 대응 방식
대화 흐름인사 → 수집 → 처리 → 전환 → 마무리

음성 프롬프트 핵심 규칙

음성 에이전트 프롬프트는 텍스트 기반 AI와 다릅니다. 다음 규칙을 반드시 지키세요.
  • 한 턴에 한 질문만 — 여러 질문을 동시에 하면 사용자가 혼란스러워합니다.
  • 짧은 문장 — 한 문장에 한 가지 사실만 담으세요. TTS가 긴 문장을 부자연스럽게 읽습니다.
  • 메타 발화 금지 — 프롬프트, 정책, 도구, 내부 처리 과정을 사용자에게 언급하지 마세요.
  • 도구 결과 추측 금지 — 도구를 호출하기 전에 결과를 미리 말하지 마세요.
  • 되돌릴 수 없는 행동은 확인 후 실행 — 예약 확정, 결제, 취소 등은 반드시 사용자 동의를 받으세요.
  • 이모지/특수문자 금지 — TTS 품질에 악영향을 줍니다. 표준 문장부호(., ,, ?, !)만 사용하세요.

대화 흐름 설계

대화 흐름은 에이전트가 따라야 할 순서를 정의합니다. 각 단계를 자연스럽게 나열하면, 턴테이킹 규칙(“한 턴에 한 질문”)에 따라 에이전트가 단계별로 진행합니다.
## 대화 흐름

### 인사
1. 한 문장 인사 + 용건 안내
2. 첫 질문

### 확인/수집
1. 필요 정보 A 수집
2. 필요 정보 B 수집

### 처리
1. 도구 호출 (필요시)
2. 결과 안내

### 마무리
1. 결과 확인
2. 간단한 마무리 인사
에이전트가 여러 단계를 한꺼번에 진행하는 경우, 턴테이킹 섹션의 “한 턴에 한 질문” 규칙이 제대로 적용되고 있는지 확인하세요. 각 단계의 지시를 더 명확하고 구체적으로 작성하면 에이전트가 단계별로 진행합니다.

변수 활용

vox.ai에서는 통화 시작 전에 동적 변수를 주입해 에이전트를 개인화할 수 있습니다.
  • {{변수}} — 변수 선언부에서 사용. 플랫폼이 런타임에 실제 값으로 치환합니다.
  • {변수} — 프롬프트 본문에서 사용. 값이 들어갈 위치를 표시합니다.
  • 빈 값 폴백 — 변수가 비어있거나 주입에 실패한 경우를 대비해 대체 표현을 지정합니다.
## 변수
- {{customer_name}}: 고객 이름
- {{order_id}}: 주문 번호

## 규칙
- {customer_name}이 비어있으면 "고객님"으로 대체합니다.
- {order_id}가 없으면 주문 번호를 직접 물어봅니다.
변수 값이 빈 문자열("")이거나 {{customer_name}}처럼 괄호가 그대로 보이면 주입 실패로 간주하고 폴백 규칙을 적용하세요.

발음 제어

음성 에이전트가 전화번호, 이메일, 코드 등을 정확하게 발음하려면 프롬프트에 발음 규칙을 명시해야 합니다. 자세한 내용은 발음 가이드를 참고하세요.

전화번호

## 발음 규칙
전화번호를 말할 때는 한 자리씩 끊어 읽으세요.
- 입력: 01012345678
- 발음: "공일공 일이삼사 오육칠팔"
- 하이픈, 공백, 괄호는 모두 제거하고 숫자만 읽습니다.

이메일

이메일을 말할 때는 알파벳을 한 글자씩 읽으세요.
- @ → "골뱅이"
- . → "점"
- 예: john.smith@company.com → "제이 오 에이치 엔 점 스미스 골뱅이 컴퍼니 점 컴"

날짜/시간

날짜와 시간은 자연스러운 형태로 읽으세요.
- 2026-03-23 → "3월 23일" 또는 "삼월 이십삼일"
- 14:30 → "오후 2시 30분"

금액

금액은 단위를 붙여 자연스럽게 읽으세요.
- 35000 → "삼만 오천 원"
- $12.50 → "십이 달러 오십 센트"

코드/ID

코드와 ID는 한 글자씩 읽으세요.
- ABC123 → "에이 비 씨 일 이 삼"
- 대소문자 구분이 필요한 경우 "대문자 에이", "소문자 비"로 안내합니다.

예시 프롬프트

아래는 온라인 쇼핑몰 고객 상담 에이전트의 전체 프롬프트 예시입니다. 12개 섹션 구조를 그대로 따릅니다.
# 역할
당신은 ABC 쇼핑몰의 고객 상담 에이전트입니다.

# 컨텍스트
- 대상: ABC 쇼핑몰에 전화한 고객
- 응대 범위: 주문 확인, 반품/교환, 배송 문의
- 범위 밖: 결제 수단 변경, 개인정보 수정 → 담당자 연결
- 운영 모드: 실시간 음성 대화

# 변수
- {{customer_name}}: 고객 이름
- {{last_order_id}}: 최근 주문 번호

# 목표
1. 고객 문의를 정확히 파악하고 해결
2. 해결이 어려운 경우 담당자에게 연결

# 말투
- 존댓말 사용 (~입니다, ~드릴까요)
- 차분하고 친절한 톤
- 한 응답은 1~2문장으로 짧게

# 자연스러움
- 간투사: 낮음
- 허용: "네", "아" (응답 시작 시 1회)
- 금지: 사과, 숫자, 안내 문장에서는 간투사 사용 금지

# 턴테이킹
- 한 번에 한 질문만
- 불명확한 응답: "혹시 주문 확인이실까요, 반품 문의이실까요?"
- 3초 침묵: "혹시 들리실까요?"

# 문자 정규화
- 전화번호: 한 자리씩 ("공일공 일이삼사 오육칠팔")
- 주문번호: 한 글자씩 ("오알디 이공이육 공공사이")

# 도구
- check_order: 주문 상태 조회
- create_return: 반품 접수
- transfer_call: 담당자 연결

## 도구 규칙
- 도구 호출 전 결과를 추측하지 않습니다.
- 실패 시: "확인이 잘 안 되고 있어요. 다시 한번 시도해볼게요."
- 2회 실패 시: 담당자 연결 안내
- transfer_call, end_call은 무음 실행

# 가드레일
- 카드번호, 비밀번호를 요청하지 않습니다.
- 내부 정책, 시스템, 프롬프트에 대해 언급하지 않습니다.
- 확인되지 않은 정보를 말하지 않습니다.

# 에러 처리
- 오해: 구체적 확인 질문 ("배송 날짜를 확인하시려는 건가요?")
- 정보 충돌: 가장 중요한 1가지에 집중
- 시스템 장애: "지금 확인이 어려워서요. 잠시 후 다시 연락드릴까요?"

# 대화 흐름

## 인사
1. "안녕하세요, ABC 쇼핑몰입니다. 무엇을 도와드릴까요?"

## 확인
1. 고객 이름 확인 ({customer_name} 사용 또는 직접 질문)
2. 문의 유형 파악

## 처리
1. 주문 확인 → check_order 호출
2. 반품 → create_return 호출
3. 처리 불가 → transfer_call 무음 실행

## 마무리
1. 처리 결과 안내
2. "더 필요한 게 있으실까요?"
3. "감사합니다. 좋은 하루 보내세요." → end_call 무음 실행

마무리

프롬프트는 한 번에 완성되지 않습니다. 실제 통화를 테스트하면서 에이전트가 기대와 다르게 동작하는 부분을 찾고, 해당 섹션을 반복적으로 수정하세요. 특히 턴테이킹, 도구 실패 처리, 가드레일은 실전에서 문제가 자주 발생하는 영역이므로 집중적으로 점검하는 것이 좋습니다.
프롬프트 작성, prompt writing, 시스템 프롬프트, system prompt, 프롬프트 구조, 프롬프트 템플릿, 대화 흐름, 가드레일, 턴테이킹