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

# 시나리오 예제

> 키패드 수집, 갈래 메뉴, 조회 후 분기까지 실제로 쓰이는 시나리오 세 가지를 뜯어봐요.

[빠른 시작](/start/scenario-quickstart)에서 만든 예약 접수는 **한 줄로 이어지는 가장 단순한 형태**예요.
실제 통화는 그것보다 복잡해요. 여기서는 성격이 다른 세 가지를 하나씩 뜯어봐요.

| 예제                               | 핵심                            | 노드 수 | 도구 수 |
| -------------------------------- | ----------------------------- | ---- | ---- |
| [택배 배송 조회](#예제-1-택배-배송-조회)       | 키패드로 긴 번호 받기 · 리드백 확인         | 3    | 1    |
| [통신사 고객센터](#예제-2-통신사-고객센터)       | 키패드 메뉴로 갈래 나누기 · 멀티툴 · 상담원 전환 | 10   | 3    |
| [병원 진료 예약 변경](#예제-3-병원-진료-예약-변경) | 본인 확인 후 조회 · 결과 보고 분기         | 8    | 3    |

<Note>
  셋 다 **인바운드** 시나리오예요. 시나리오는 전화를 받는 통화에서 동작해요.
</Note>

***

## 자동 생성이 만들어 주는 것, 손으로 그려야 하는 것

시나리오 편집기의 `AI 시나리오 자동 생성`은 **연결 Tool의 요청 스키마를 읽어** 수집 Step을
파라미터 수만큼 만들어요. 트리거 키워드와 안내 멘트도 함께 만들어져요.

<img src="https://mintcdn.com/tello-cc85f660/GpavOctsiNNZNXdD/images/scenario/ex-00-autogen.webp?fit=max&auto=format&n=GpavOctsiNNZNXdD&q=85&s=de63dbb9161c0a736e1cda1b4e9a1e77" alt="AI 시나리오 자동 생성 결과, 트리거 키워드 5개와 Step 1개" width="1220" height="414" data-path="images/scenario/ex-00-autogen.webp" />

자동 생성이 만드는 흐름은 **항상 한 줄**이에요.

```
시작 → 수집 → 수집 → … → Tool 호출 → 완료
```

그래서 이렇게 나눠 쓰면 돼요.

| 만들려는 것                          | 방법                  |
| ------------------------------- | ------------------- |
| 수집 Step, 트리거 키워드, 안내 멘트 초안      | **자동 생성**           |
| 키패드(DTMF) 설정                    | 폼 편집에서 Step별로 켜기    |
| 갈래(분기), 키패드 메뉴, 여러 Tool, 상담원 전환 | **GUI 다이어그램에서 손으로** |

<Tip>
  아래 예제 ①은 자동 생성으로 뼈대를 만들고 키패드만 켜면 돼요.
  예제 ②③은 갈래가 있어서 다이어그램 탭에서 노드를 추가하고 화살표를 이어야 해요.
</Tip>

***

## 예제 1 · 택배 배송 조회

**상황.** 고객이 "제 물건 어디쯤 왔어요?"라고 물어요. 운송장 번호를 받아 조회해 알려줘야 해요.

**왜 키패드인가.** 운송장 번호는 10\~14자리 숫자예요. 음성 인식으로 받으면 한 자리만 틀려도
조회가 실패해요. 키패드로 받으면 정확하고, 시끄러운 곳에서도 됩니다.

### 흐름

```mermaid theme={null}
flowchart LR
  A["시작<br/>운송장 번호<br/>(키패드 + 리드백)"] --> B["Tool 호출<br/>배송 조회 API"]
  B --> C["완료<br/>결과 안내"]
```

### 도구

| 항목    | 값                                                  |
| ----- | -------------------------------------------------- |
| 도구명   | 배송 조회 API                                          |
| 타입    | API Request                                        |
| 엔드포인트 | `POST https://api.example.com/delivery/track`      |
| 설명    | 운송장 번호로 배송 상태를 조회한다. 고객이 배송 위치나 도착 예정일을 물을 때 사용한다. |

```json 요청 스키마 theme={null}
{
  "parameters": [
    { "name": "tracking_number", "type": "string", "required": true, "description": "운송장 번호" }
  ]
}
```

### 트리거 키워드

```
배송 조회, 배송 상태, 어디쯤 왔나요, 도착 예정일, 운송장 번호
```

### 키패드 설정

Step의 **키패드 입력 허용**을 켜고 이렇게 채워요.

| 항목       | 값                                                            | 이유                      |
| -------- | ------------------------------------------------------------ | ----------------------- |
| 입력 안내 멘트 | 운송장 번호 열두 자리를 누르신 후 우물정(#)자를 눌러주세요. 다시 입력하시려면 별표(\*)를 눌러주세요. | 종료키와 재입력 방법을 함께 알려줘야 해요 |
| 최소 자릿수   | 10                                                           | 택배사마다 자릿수가 달라요          |
| 최대 자릿수   | 14                                                           | 〃                       |
| 입력 종료키   | `#`                                                          | 자릿수가 가변이라 종료키가 꼭 필요해요   |
| 입력 대기 시간 | 6초                                                           | 긴 번호는 누르는 데 시간이 걸려요     |
| 재시도 횟수   | 2                                                            |                         |
| 확인 멘트    | 입력하신 운송장 번호 `{value}` 맞으신가요?                                 | 조회 전에 한 번 걸러 줘요         |

<Warning>
  자릿수가 **가변이면 종료키를 반드시 두세요.** 최대 자릿수만 믿으면 짧은 번호를 넣은 고객이
  대기 시간만큼 기다려야 해요.
</Warning>

### 만드는 순서

<Steps>
  <Step title="도구 등록">
    [도구 관리](/agents/tools)에서 위 스키마로 `배송 조회 API`를 만들어요.
  </Step>

  <Step title="시나리오 자동 생성">
    에이전트 › 도구 › AI 시나리오 › `수정` › `+ 시나리오 추가`.
    Tool을 고르고 `AI 시나리오 자동 생성`을 누르면 Step 1개가 만들어져요.
  </Step>

  <Step title="키패드 켜기">
    Step 1의 **키패드 입력 허용**을 켜고 위 표대로 채워요. 다이어그램 탭에서 보면 이렇게 생겼어요.

    <img src="https://mintcdn.com/tello-cc85f660/GpavOctsiNNZNXdD/images/scenario/ex-01-delivery-canvas.webp?fit=max&auto=format&n=GpavOctsiNNZNXdD&q=85&s=f1132dd2e6e32006f8f1a8d8ebd29ae8" alt="택배 배송 조회 시나리오, 시작(키패드) · Tool 호출 · 완료 3노드" width="1400" height="766" data-path="images/scenario/ex-01-delivery-canvas.webp" />
  </Step>

  <Step title="저장·활성화·배포">
    저장하고 목록에서 토글을 켠 뒤 `배포하기 →`를 눌러요.
  </Step>
</Steps>

### 통화 예시

```
봇  운송장 번호 열두 자리를 누르신 후 우물정자를 눌러주세요.
고객 (1234-5678-9012 입력 후 #)
봇  입력하신 운송장 번호 일이삼사 오육칠팔 구공일이 맞으신가요?
고객 (1)
봇  조회 중입니다. 잠시만 기다려주세요.
봇  현재 동서울 물류센터에 있고, 내일 오전 중 도착 예정입니다. 더 궁금한 점 있으실까요?
```

***

## 예제 2 · 통신사 고객센터

**상황.** 문의 종류가 여러 가지고 처리 방법도 각각 달라요. 처음에 갈래를 나누고, 갈래마다
다른 정보를 받아 **다른 API**를 불러야 해요. 사람이 필요한 건은 상담원에게 넘겨야 해요.

**왜 키패드 메뉴인가.** "요금 조회요"라고 말해도 되지만, 대기 중이거나 시끄러운 곳이면
번호를 누르는 쪽이 빨라요. 키패드 메뉴는 **음성과 번호를 동시에 받아요.**

### 흐름

```mermaid theme={null}
flowchart TD
  M["시작 · 키패드 메뉴<br/>1 / 2 / 3 / 0"]
  M -->|1| B1["수집<br/>생년월일 (키패드)"]
  B1 --> B2["Tool 호출<br/>요금 조회 API"]
  M -->|2| T1["수집<br/>현재·변경 명의자, 관계"]
  T1 --> T2["Tool 호출<br/>명의변경 접수 API"]
  M -->|3| C1["수집<br/>해지 사유, 희망 시간"]
  C1 --> C2["Tool 호출<br/>해지상담 접수 API"]
  M -->|0| A1["안내 · 멘트 보호<br/>대기음 → 상담원 전환"]
  B2 --> E["완료"]
  T2 --> E
  C2 --> E
  A1 --> E
```

### 도구 세 가지

| 도구명         | 엔드포인트                               | 파라미터                                         |
| ----------- | ----------------------------------- | -------------------------------------------- |
| 요금 조회 API   | `POST /billing/inquiry`             | `birth_date`                                 |
| 명의변경 접수 API | `POST /subscription/transfer`       | `current_owner`, `new_owner`, `relationship` |
| 해지상담 접수 API | `POST /subscription/cancel-request` | `reason`, `callback_time`                    |

<Note>
  시나리오 하나가 **도구를 여러 개** 쓸 수 있어요. Tool 호출 노드마다 `호출할 Tool`을 따로
  고르면 돼요. 고르지 않으면 시나리오 기본 Tool이 쓰여요.
</Note>

### 시작 노드 · 키패드 메뉴

키패드 메뉴는 **숫자 키를 갈래에 연결**해요. 수집 노드와 달리 값을 받는 게 아니라 어디로 갈지를 정해요.

| 키 | 가는 곳   |
| - | ------ |
| 1 | 요금 조회  |
| 2 | 명의변경   |
| 3 | 해지상담   |
| 0 | 상담원 연결 |

안내 멘트는 노드에 들어오는 순간 **그대로 읽혀요.**

```
안녕하세요. 요금 조회는 1번, 명의변경은 2번, 해지상담은 3번, 상담원 연결은 0번을 눌러주세요.
```

다이어그램에서 보면 갈래마다 노드 줄기가 하나씩 뻗어 나가요.

<img src="https://mintcdn.com/tello-cc85f660/GpavOctsiNNZNXdD/images/scenario/ex-02-callcenter-canvas.webp?fit=max&auto=format&n=GpavOctsiNNZNXdD&q=85&s=6cefe17280fb42a8962082fd5271e76f" alt="통신사 고객센터 시나리오, 갈래별 수집 노드와 Tool 호출 노드" width="1400" height="669" data-path="images/scenario/ex-02-callcenter-canvas.webp" />

<Warning>
  메뉴 노드는 **멘트 보호(barge-in 금지)를 켜세요.** 안 그러면 주변 소음이나 고객의 "여보세요"에
  안내가 끊겨서 선택지를 다 못 들어요.
</Warning>

<Tip>
  번호를 안 눌러도 "요금이 왜 이렇게 많이 나왔어요"라고 말하면 1번 갈래로 가요. 각 갈래 함수의
  설명이 판단 근거가 되므로 **고객이 실제로 할 법한 말**로 적어요.
</Tip>

### 상담원 전환 갈래 (0번)

이 갈래는 수집도 Tool 호출도 없어요. **액션 세 개를 순서대로** 실행해요.

| 순서 | 액션                              | 하는 일                           |
| -- | ------------------------------- | ------------------------------ |
| 1  | `tts_say`                       | "상담원에게 연결해드리겠습니다. 잠시만 기다려주세요." |
| 2  | `hold_music`                    | 대기음 재생 시작                      |
| 3  | `transfer_call` (`wait_sec: 5`) | 5초 기다린 뒤 전환 실행                 |

`wait_sec`은 상담 대기열을 흉내내요. 그동안 앞서 시작한 대기음이 재생돼요.

노드에 붙은 액션은 다이어그램에서 배지로 보여요. **멘트 보호**도 함께 켜 두었어요.

<img src="https://mintcdn.com/tello-cc85f660/GpavOctsiNNZNXdD/images/scenario/ex-02b-transfer-node.webp?fit=max&auto=format&n=GpavOctsiNNZNXdD&q=85&s=a3ebc6fa19a518f77e5f857f507096c6" alt="상담원 전환 노드, 대기음 시작·상담원 전환 대기 5초 배지와 멘트 보호" width="590" height="770" data-path="images/scenario/ex-02b-transfer-node.webp" />

<Warning>
  `transfer_call`은 에이전트 **전환** 탭 설정을 그대로 써요. 전환 탭이 꺼져 있으면 전환되지
  않고 봇이 계속 응대해요. 전환 번호를 먼저 설정하세요.
</Warning>

<Note>
  전환에 실패해도 통화는 끊기지 않아요. 대기음을 끄고 "지금은 연결이 어렵습니다" 안내 후
  봇이 이어받아요. 시나리오는 통화를 종료할 수 없기 때문이에요.
</Note>

### 만드는 순서

<Steps>
  <Step title="도구 3개 등록">
    표대로 API Request 도구 세 개를 만들어요.
  </Step>

  <Step title="시나리오 만들고 GUI 다이어그램 열기">
    시나리오를 추가한 뒤 **GUI 다이어그램** 탭으로 가요. 갈래가 있어서 폼 편집으로는 못 만들어요.
  </Step>

  <Step title="시작 노드에 메뉴 붙이기">
    시작 노드에 키패드 메뉴를 설정하고, 갈래마다 함수를 하나씩 만들어요.
    함수의 `다음 노드`가 그 갈래의 첫 노드가 돼요.
  </Step>

  <Step title="갈래별 노드 잇기">
    갈래마다 수집 노드 › Tool 호출 노드 › 완료 노드로 이어요. Tool 호출 노드에서
    `호출할 Tool`을 각각 골라요.
  </Step>

  <Step title="0번 갈래에 액션 넣기">
    안내 노드의 진입 액션에 `tts_say` › `hold_music` › `transfer_call`을 순서대로 넣어요.
  </Step>

  <Step title="저장">
    저장하면 서버가 흐름을 검사해요. 모든 갈래가 완료 노드에 도달해야 통과해요.
  </Step>
</Steps>

### 통화 예시

```
봇  안녕하세요. 요금 조회는 1번, 명의변경은 2번, 해지상담은 3번, 상담원 연결은 0번을 눌러주세요.
고객 (2)
봇  현재 명의자 성함을 말씀해주세요.
고객 김철수요. 아들 김민수로 바꾸려고요.
봇  두 분 관계가 어떻게 되실까요?
고객 부자지간이요.
봇  명의변경을 접수하겠습니다.
봇  접수가 완료됐습니다. 더 도와드릴 것이 있으실까요?
```

두 번째 답변에서 고객이 **두 가지를 한 번에** 말했어요. 이미 받은 건 그대로 두고 빠진
항목만 이어서 물어봐요.

***

## 예제 3 · 병원 진료 예약 변경

**상황.** 예약을 바꾸려면 먼저 누구인지 확인하고 **기존 예약을 조회**해야 해요. 그다음
변경인지 취소인지에 따라 다른 처리를 해요.

**앞선 두 예제와 다른 점.** 갈래가 **조회 결과 뒤에** 있어요. 예제 ②는 통화 시작 시점에
갈래를 나눴지만, 여기서는 먼저 조회한 결과를 알려주고 나서 고객이 결정해요.

### 흐름

```mermaid theme={null}
flowchart TD
  V["시작<br/>생년월일 (키패드)"]
  V --> L["Tool 호출<br/>예약 조회 API"]
  L --> Q["예약 안내 후<br/>변경? 취소?"]
  Q -->|변경| R1["수집<br/>희망 날짜·시간"]
  R1 --> R2["Tool 호출<br/>예약 변경 API"]
  Q -->|취소| C1["재확인<br/>멘트 보호"]
  C1 --> C2["Tool 호출<br/>예약 취소 API"]
  R2 --> E["완료"]
  C2 --> E
```

### 도구 세 가지

| 도구명         | 엔드포인트                                    | 파라미터           |
| ----------- | ---------------------------------------- | -------------- |
| 진료예약 조회 API | `POST /hospital/appointments`            | `birth_date`   |
| 진료예약 변경 API | `POST /hospital/appointments/reschedule` | `new_datetime` |
| 진료예약 취소 API | `POST /hospital/appointments/cancel`     | `confirm`      |

### 본인 확인 (생년월일 키패드)

| 항목        | 값                                                  |
| --------- | -------------------------------------------------- |
| 입력 안내 멘트  | 예약 확인을 도와드리겠습니다. 생년월일 여섯 자리를 누르신 후 우물정(#)자를 눌러주세요. |
| 최소·최대 자릿수 | 6 · 6                                              |
| 입력 종료키    | `#`                                                |
| 확인 멘트     | `{value}` 맞으신가요?                                   |

<Note>
  자릿수가 \*\*고정(6자리)\*\*이라 종료키 없이도 자동으로 끝나요. 그래도 종료키를 두면 고객이
  바로 넘어갈 수 있어 응답이 빨라져요.
</Note>

### 조회 결과 뒤 분기

조회 노드 다음에 **갈래 노드**를 둬요. 이 노드는 값을 받지 않고 어디로 갈지만 정해요.

| 함수                 | 설명(판단 근거)           | 가는 곳     |
| ------------------ | ------------------- | -------- |
| `route_reschedule` | 날짜를 바꾸거나 미루고 싶다고 하면 | 희망 일시 수집 |
| `route_cancel`     | 예약을 취소하겠다고 하면       | 취소 재확인   |

AI 지시문에는 조회 결과를 먼저 알려주라고 적어요.

```
조회된 예약 일정을 안내한 뒤, 날짜를 변경하실지 취소하실지 물어보세요.
```

다이어그램에서 보면 조회 노드 아래에서 두 줄기로 갈라져요.

<img src="https://mintcdn.com/tello-cc85f660/GpavOctsiNNZNXdD/images/scenario/ex-03-hospital-canvas.webp?fit=max&auto=format&n=GpavOctsiNNZNXdD&q=85&s=d725630fef35eaab97c21ee9de06c010" alt="병원 진료 예약 변경 시나리오, 인증·조회 후 변경/취소 2갈래" width="768" height="1188" data-path="images/scenario/ex-03-hospital-canvas.webp" />

### 취소 전 재확인

취소는 되돌리기 어려워요. 확인 노드를 하나 더 두고 **멘트 보호를 켜요.**

```
정말 취소하실지 한 번 더 확인하세요. 취소하면 같은 시간대 재예약이 어려울 수 있다고 안내하세요.
```

<Tip>
  되돌릴 수 없는 처리 앞에는 확인 단계를 넣으세요. 음성은 오인식이 있어서 "취소"가 잘못
  들릴 수 있어요.
</Tip>

### 통화 예시

```
봇  예약 확인을 도와드리겠습니다. 생년월일 여섯 자리를 누르신 후 우물정자를 눌러주세요.
고객 (900101#)
봇  구공공일공일 맞으신가요?
고객 (1)
봇  예약 내역을 확인하고 있습니다.
봇  3월 14일 목요일 오후 2시 내과 진료로 예약되어 있습니다. 날짜를 변경하시겠어요, 취소하시겠어요?
고객 다음 주로 미룰 수 있을까요?
봇  희망하시는 날짜와 시간을 말씀해주세요.
고객 3월 21일 같은 시간이요.
봇  예약을 변경하겠습니다.
봇  3월 21일 목요일 오후 2시로 변경됐습니다. 더 도와드릴 것이 있으실까요?
```

***

***

## 한 에이전트에 여러 시나리오

세 예제를 같은 에이전트에 함께 둘 수 있어요. 트리거 키워드가 서로 달라서 고객이 무엇을
말하느냐에 따라 해당 시나리오로 들어가요.

<img src="https://mintcdn.com/tello-cc85f660/GpavOctsiNNZNXdD/images/scenario/ex-04-list.webp?fit=max&auto=format&n=GpavOctsiNNZNXdD&q=85&s=feb8b749db6ef03af54ab7d08fed7f46" alt="한 에이전트에 등록된 시나리오 네 개" width="1090" height="225" data-path="images/scenario/ex-04-list.webp" />

<Tip>
  쓰지 않는 시나리오는 토글을 꺼 두세요. 키워드가 겹치면 어느 쪽이 걸릴지 예측하기 어려워져요.
</Tip>

## 세 예제에서 가져갈 것

<CardGroup cols={2}>
  <Card title="숫자는 키패드로">
    운송장·주문번호·생년월일·전화번호는 키패드가 정확해요. 리드백까지 켜면 오류가 거의 없어요
  </Card>

  <Card title="갈래는 다이어그램에서">
    자동 생성은 한 줄만 만들어요. 분기·메뉴·멀티툴은 GUI 다이어그램에서 손으로 그려요
  </Card>

  <Card title="끊기면 안 되는 멘트는 보호">
    메뉴 안내, 전환 안내, 취소 재확인은 멘트 보호를 켜요
  </Card>

  <Card title="되돌릴 수 없는 일 앞엔 확인">
    취소·삭제·결제 전에는 확인 노드를 하나 더 둬요
  </Card>
</CardGroup>

## 자주 겪는 문제

<Warning>
  * **메뉴를 눌렀는데 반응이 없어요**: 시작 노드에 키패드 메뉴가 설정돼 있나요? 안내 멘트만
    넣고 메뉴 연결을 안 하면 숫자를 눌러도 갈래로 가지 않아요.
  * **긴 번호를 중간에 끊어 받아요**: 입력 대기 시간을 늘리고 종료키를 두세요. 12자리를 5초 안에
    다 누르지 못하는 고객이 많아요.
  * **안내가 자꾸 끊겨요**: 멘트 보호(barge-in 금지)를 켜세요.
  * **상담원 전환이 안 돼요**: 에이전트 **전환** 탭에서 전환 번호를 설정했는지 확인하세요.
  * **저장이 안 돼요**: 갈래 중 하나가 완료 노드에 닿지 않았을 수 있어요. 모든 길이 완료로
    끝나야 하고, 순환이 있으면 안 돼요.
  * **Tool이 안 불려요**: Tool 호출 노드에서 `호출할 Tool`을 골랐는지, 그 도구가 **API Request**
    타입인지 확인하세요.
</Warning>

## 관련 문서

* [시나리오 개요](/scenarios/overview)
* [시나리오 빠른 시작](/start/scenario-quickstart)
* [도구 관리](/agents/tools)