> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 프롬프트 작성

> 효과적인 AI 음성 에이전트 프롬프트 작성 방법을 안내합니다.

# 프롬프트 작성 가이드

프롬프트는 음성 에이전트의 품질을 결정하는 핵심 요소입니다. 구조화된 프롬프트를 작성하면 에이전트가 일관되게 동작하고, 예외 상황에서도 안정적으로 응대할 수 있습니다.

<Tip>
  [vox CLI](/docs/ai/cli)를 연동하면 Claude Code, Codex 같은 코딩 에이전트가 프롬프트 작성 가이드를 참고해 대화만으로 프롬프트를 만들고 다듬어 줍니다.
</Tip>

## 프롬프트 구조

음성 에이전트의 프롬프트는 12개 섹션으로 구성됩니다. 각 섹션이 명확한 역할을 가지므로, 수정이 필요할 때 해당 섹션만 변경하면 됩니다.

| 섹션                                            | 역할                            |
| --------------------------------------------- | ----------------------------- |
| 역할                                            | 에이전트 이름, 소속, 핵심 업무 정의         |
| 컨텍스트                                          | 대상 고객, 응대 가능 범위, 실시간 음성 모드 명시 |
| [변수](/docs/build/variables/dynamic-variables) | `{{변수}}` 선언과 폴백 규칙            |
| 목표                                            | 우선순위별 성공 기준                   |
| 말투                                            | 존댓말 수준, 톤, 스타일 규칙             |
| 자연스러움                                         | 간투사 설정 (꺼짐/낮음/보통/높음)          |
| 턴테이킹                                          | 한 턴에 한 질문, 침묵/불명확 처리          |
| 문자 정규화                                        | 전화번호·이메일·코드의 음성/문자 변환 규칙      |
| [도구](/docs/build/tools/overview)              | 사용 가능한 도구, 실패 처리, 무음 실행 규칙    |
| 가드레일                                          | 금지 행동, 팩트 확인, 범위 제한           |
| 에러 처리                                         | 오해·충돌·장애 대응 방식                |
| 대화 흐름                                         | 인사 → 수집 → 처리 → 전환 → 마무리       |

## 음성 프롬프트 핵심 규칙

<Warning>
  음성 에이전트 프롬프트는 텍스트 기반 AI와 다릅니다. 다음 규칙을 반드시 지키세요.
</Warning>

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

## 대화 흐름 설계

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

```text theme={null}
## 대화 흐름

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

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

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

### 마무리
1. 결과 확인
2. 간단한 마무리 인사
```

<Warning>
  에이전트가 여러 단계를 한꺼번에 진행하는 경우, 턴테이킹 섹션의 "한 턴에 한 질문" 규칙이 제대로 적용되고 있는지 확인하세요. 각 단계의 지시를 더 명확하고 구체적으로 작성하면 에이전트가 단계별로 진행합니다.
</Warning>

## 변수 활용

vox.ai에서는 통화 시작 전에 [동적 변수](/docs/build/variables/dynamic-variables)를 주입해 에이전트를 개인화할 수 있습니다.

* `{{변수}}` — 프롬프트 본문에서 실제 값으로 치환되는 변수 표기입니다.
* `{변수}` — 규칙이나 설명 문장에서 변수 이름을 가리킬 때만 사용할 수 있습니다. 실제 값으로 치환되지는 않습니다.
* 빈 값 폴백 — 변수가 비어있거나 주입에 실패한 경우를 대비해 대체 표현을 지정합니다.

```text theme={null}
## 변수
- 고객 이름: {{customer_name}}
- 주문 번호: {{order_id}}

## 규칙
- {customer_name}이 비어있으면 "고객님"으로 대체합니다.
- {order_id}가 없으면 주문 번호를 직접 물어봅니다.
```

<Note>
  변수 값이 빈 문자열(`""`)이거나 `{{customer_name}}`처럼 괄호가 그대로 보이면 주입 실패로 간주하고 폴백 규칙을 적용하세요.
</Note>

## 발음 제어

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

### 전화번호

<Accordion title="전화번호 발음 규칙 예시">
  ```text theme={null}
  ## 발음 규칙
  전화번호를 말할 때는 한 자리씩 끊어 읽으세요.
  - 입력: 01012345678
  - 발음: "공일공 일이삼사 오육칠팔"
  - 하이픈, 공백, 괄호는 모두 제거하고 숫자만 읽습니다.
  ```
</Accordion>

### 이메일

<Accordion title="이메일 발음 규칙 예시">
  ```text theme={null}
  이메일을 말할 때는 알파벳을 한 글자씩 읽으세요.
  - @ → "골뱅이"
  - . → "점"
  - 예: john.smith@company.com → "제이 오 에이치 엔 점 스미스 골뱅이 컴퍼니 점 컴"
  ```
</Accordion>

### 날짜/시간

<Accordion title="날짜·시간 발음 규칙 예시">
  ```text theme={null}
  날짜와 시간은 자연스러운 형태로 읽으세요.
  - 2026-03-23 → "3월 23일" 또는 "삼월 이십삼일"
  - 14:30 → "오후 2시 30분"
  ```
</Accordion>

### 금액

<Accordion title="금액 발음 규칙 예시">
  ```text theme={null}
  금액은 단위를 붙여 자연스럽게 읽으세요.
  - 35000 → "삼만 오천 원"
  - $12.50 → "십이 달러 오십 센트"
  ```
</Accordion>

### 코드/ID

<Accordion title="코드·ID 발음 규칙 예시">
  ```text theme={null}
  코드와 ID는 한 글자씩 읽으세요.
  - ABC123 → "에이 비 씨 일 이 삼"
  - 대소문자 구분이 필요한 경우 "대문자 에이", "소문자 비"로 안내합니다.
  ```
</Accordion>

## 예시 프롬프트

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

```text theme={null}
# 역할
당신은 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. 고객 이름 확인
2. 문의 유형 파악

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

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

## 마무리

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

***

<Accordion title="연관 검색어">
  프롬프트 작성, prompt writing, 시스템 프롬프트, system prompt, 프롬프트 구조, 프롬프트 템플릿, 대화 흐름, 가드레일, 턴테이킹
</Accordion>