> ## 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.

# 실행 대기음

> 도구가 실행되는 동안 대기음을 재생해 통화의 무음 구간을 채웁니다.

# 실행 대기음

도구가 결과를 반환할 때까지 통화는 무음 상태가 됩니다. 이 구간이 길어지면 사용자는 전화가 끊겼다고 느끼고 먼저 말을 걸거나 통화를 종료합니다. 실행 대기음을 설정하면 도구가 실행되는 동안 소리가 재생되어, 응답을 기다리는 중이라는 신호가 사용자에게 전달됩니다.

## 사용 시점

* **응답이 느린 API 호출**: 외부 서비스에서 데이터를 가져오는 동안 무음 구간을 소리로 대체
* **오래 걸리는 작업**: 조회·예약 처리·외부 시스템 연동처럼 몇 초 이상 걸리는 작업에 오디오 피드백 제공
* **자연스러운 대화 흐름**: 대화 중간의 어색한 침묵 방지
* **처리 중 신호**: 장애가 아니라 요청을 처리하는 중임을 사용자에게 전달

<Note>
  실행 대기음은 선택 사항입니다. 무음으로 두려면 기본값인 **사용 안 함**을 유지하세요.
</Note>

## 선택할 수 있는 대기음

**실행 대기음**에서 하나를 선택합니다. 기본값은 **사용 안 함**입니다.

| 대기음              | API 값                        | 설명                          | 적합한 상황            |
| ---------------- | ---------------------------- | --------------------------- | ----------------- |
| **사용 안 함**       | `none`                       | 아무 소리도 재생하지 않습니다.           | 빠르게 끝나는 작업, 무음 유지 |
| **타이핑**          | `typing`                     | 키보드 입력 소리를 재생합니다.           | 검색·조회처럼 "찾아보는" 동작 |
| **대기 음악 1 \~ 4** | `elevator_1` \~ `elevator_4` | 배경 음악 4종 가운데 선택한 하나를 재생합니다. | 몇 초 이상 걸리는 작업     |

## 동작 방식

대기음은 도구 실행 구간에서만 재생되고, 통화 상황에 따라 자동으로 멈춥니다. 별도로 조절할 설정은 없습니다.

* 에이전트가 말하는 동안에는 음소거됩니다. [실행 중 발화](/docs/build/tools/builtin/end-call#실행-중-발화)와 대기음이 겹쳐 들리지 않습니다.
* 사용자가 말을 시작하면 즉시 정지합니다.
* 도구 결과를 바탕으로 한 발화가 시작되면 종료됩니다.

```mermaid theme={null}
flowchart TD
    A[도구 호출] --> B[대기음 재생]
    B --> C{통화 상황}
    C -- 에이전트 발화 --> D[음소거]
    D --> B
    C -- 사용자 발화 --> E[정지]
    C -- 결과 발화 시작 --> F[종료]
```

대화 예시:

```
사용자: "제 주문 언제 도착하나요?"
에이전트: "주문 내역을 확인해 드릴게요." [발화가 끝난 뒤 타이핑음 재생]
에이전트: "어제 발송되어 내일 도착 예정입니다."
```

<Note>
  실행이 500밀리초 안에 끝나는 도구에서는 대기음이 사용자에게 거의 들리지 않습니다.
</Note>

## 설정 위치

커스텀 API 도구와 Flow 노드에서 설정합니다.

| 위치               | 대상                                                                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 워크스페이스의 도구 편집 화면 | [API 도구](/docs/build/tools/api)                                                                                                      |
| 플로우 빌더의 노드 설정    | [API 노드](/docs/build/flow/nodes/api-node), [도구 노드](/docs/build/flow/nodes/tool-node), [SMS 노드](/docs/build/flow/nodes/send-sms-node) |

같은 에이전트 안에서도 도구마다 다른 대기음을 선택할 수 있습니다.

## API와 CLI에서 설정하기

v3 API의 커스텀 API 도구에서는 `tool_call_sound` 필드를 사용합니다. 값은 `none`, `typing`, `elevator_1` \~ `elevator_4` 중 하나이며, 필드를 생략하면 소리를 재생하지 않습니다.

```json theme={null}
{
  "tool_call_sound": "typing"
}
```

v3 API의 Flow 노드에서는 `data` 안에 `tool_call_sound`를 사용합니다. 지원 노드는 `api`, `tool`, `sendSms`뿐입니다.

```json theme={null}
{
  "data": {
    "tool_call_sound": "elevator_1"
  }
}
```

vox CLI로 관리하는 Flow 프로젝트 파일에서는 `toolCallSound`를 쓰고, push할 때 `tool_call_sound`로 변환합니다. 자세한 내용은 [CLI](/docs/ai/cli)를 참고하세요.

## 모범 사례

### 실행 시간에 맞는 대기음

1초 안에 끝나는 도구는 **사용 안 함**이나 **타이핑**으로 충분합니다. 3초 이상 걸리는 도구에는 **대기 음악**이 더 자연스럽습니다. 모든 도구에 설정할 필요는 없습니다. 실행이 오래 걸리는 도구부터 설정하세요.

### 실행 중 발화와의 조합

실행 중 발화가 켜져 있으면 발화가 먼저 나가고, 발화가 끝난 뒤 남은 대기 구간을 대기음이 채웁니다. 반대로 실행 중 발화가 없는 도구는 호출 직후부터 대기음이 재생되므로, 무음이 가장 길게 느껴지는 도구일수록 대기음의 효과가 큽니다.

### 실제 지연으로 테스트

테스트 통화에서 실제 API를 호출해 들어보세요. 네트워크 왕복과 API 처리 시간에 따라 대기음이 들리는 길이가 달라지므로, 모의 응답으로는 실제 체감을 확인할 수 없습니다.

## 예시 구성

### 조회형 도구

외부 API에서 정보를 조회하는 작업에는 **타이핑**이 어울립니다. 상담원이 키보드로 검색하는 인상을 주어 짧은 대기를 자연스럽게 만듭니다.

### 외부 시스템을 조회하는 상담 에이전트

주문 조회, 예약 확인처럼 외부 시스템 응답에 2\~5초 걸리는 도구에는 **대기 음악**을 선택하세요. 무음보다 배경 음악이 있는 쪽이 대기 시간을 짧게 느끼게 합니다.

### 여러 단계를 거치는 플로우

대기음은 노드 단위로 설정하므로 단계마다 다르게 구성할 수 있습니다. 예를 들어 첫 조회 노드는 **타이핑**, 이후 처리가 긴 노드는 **대기 음악**으로 설정해 단계 전환을 소리로도 구분합니다.

## 문제 해결

### 대기음이 들리지 않을 때

1. **도구가 너무 빨리 끝났습니다**: 실행이 500밀리초 안에 끝나면 대기음이 재생될 시간이 없습니다. 정상 동작입니다.
2. **실행 중 발화가 실행 구간을 전부 덮었습니다**: 에이전트가 말하는 동안 대기음은 음소거되므로, 발화가 도구 실행보다 길면 대기음이 들리지 않습니다.
3. **지원되지 않는 위치에 설정했습니다**: 커스텀 API 도구와 Flow `api`·`tool`·`sendSms` 노드에서만 설정할 수 있습니다.

## 관련 문서

* [도구 개요](/docs/build/tools/overview)
* [API 도구](/docs/build/tools/api)
* [도구 노드](/docs/build/flow/nodes/tool-node)

***

<Accordion title="연관 검색어">
  실행 대기음, 대기음, tool call sound, toolCallSound, tool\_call\_sound, 타이핑음, 대기 음악, elevator, hold music, 도구 실행 소리, 무음 구간, API 도구, Flow 노드
</Accordion>