> ## 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.
# 시나리오 개요
> 정해진 순서대로 정보를 받고 도구를 호출하는 통화 흐름을 시나리오로 만들어요.
## 시나리오란
시나리오는 통화 중 **미리 정한 순서대로 진행되는 대화 흐름**이에요. 프롬프트형 에이전트는
AI가 대화를 알아서 이끌지만, 시나리오는 어떤 정보를 어떤 순서로 받고 마지막에 무엇을
실행할지 저작자가 정해요.
예를 들어 미용실 예약 접수라면 이런 흐름이에요.
```mermaid theme={null}
flowchart LR
A[시작
시술 종류] --> B[수집
날짜와 시간]
B --> C[수집
성함·연락처]
C --> D[Tool 호출
예약 접수 API]
D --> E[완료]
```
고객이 "예약하고 싶어요"라고 말하면 시나리오가 켜지고, 세 가지를 차례로 물어본 뒤
등록해 둔 API를 호출하고 완료를 안내해요.
시나리오는 통화를 **끊지 않아요**. 완료 노드까지 가면 다시 기본 대화 모드로 돌아가
남은 문의를 이어서 받아요.
## 언제 쓰면 좋을까요
| 상황 | 프롬프트형 | 시나리오 |
| ------------------- | ---------- | ---- |
| 단순 문의 응대 | 적합 | 과함 |
| 정해진 항목을 빠짐없이 받아야 함 | 누락 가능 | 적합 |
| 마지막에 외부 시스템에 등록해야 함 | 호출 시점이 불안정 | 적합 |
| 전화 키패드로 번호를 받아야 함 | 불가 | 적합 |
| 1번·2번 같은 갈래 안내(IVR) | 불가 | 적합 |
정보 누락이나 순서가 문제가 되는 통화, 마지막에 반드시 실행해야 하는 작업이 있는 통화일수록
시나리오가 결과를 안정적으로 만들어요.
## 구성 요소
시나리오 하나는 **트리거 키워드**, **연결 Tool**, **노드**, **엣지**로 이루어져요.
### 트리거 키워드
통화 중 고객 발화에서 이 키워드가 감지되면 시나리오로 들어가요. 여러 개를 등록할 수 있고,
실제로 고객이 쓸 만한 말을 넣어야 해요.
```
예약, 예약하고 싶어요, 자리 있나요, 예약 좀
```
키워드는 자동 생성된 것을 그대로 두지 말고 손으로 보강하세요. 도구명 하나만 들어 있으면
고객이 "예약하고 싶어요"라고 말해도 시나리오가 켜지지 않아요.
### 연결 Tool
시나리오가 마지막에 호출할 도구예요. [도구 관리](/agents/tools)에 미리 등록해 둔
**API Request** 도구를 고르면, 그 도구의 요청 스키마에서 수집 항목이 그대로 만들어져요.
시나리오에서 실행할 수 있는 도구는 **API Request 타입만**이에요. MCP·A2A 도구는
시나리오의 Tool 호출 노드에 연결할 수 없어요(에이전트의 다른 경로에서는 쓸 수 있어요).
### 노드
노드는 흐름의 한 단계예요. 다섯 가지 성격이 있어요.
통화가 시나리오로 들어왔을 때 처음 실행되는 노드예요. 시나리오마다 정확히 1개 있어야 해요
항목 하나를 물어보고 답을 받아 두는 노드예요. 받은 값은 끝까지 누적돼요
고객의 말이나 키패드 입력에 따라 여러 갈래 중 하나로 보내는 노드예요
그때까지 모은 값으로 연결 Tool을 실행하는 노드예요
마무리 안내를 하고 기본 대화 모드로 돌아가는 노드예요. 최소 1개 있어야 해요
노드마다 이런 것들을 설정해요.
* **AI 지시문**: 이 단계에서 AI가 할 말과 지켜야 할 규칙이에요.
* **키패드 입력 허용**: 켜면 고객이 말 대신 전화기 숫자 버튼으로 입력할 수 있어요.
* **멘트 보호(barge-in 금지)**: 켜면 이 노드의 안내를 고객이 말해도 끊지 않아요. 상담원 전환 안내처럼
끝까지 들려야 하는 멘트에 써요.
* **액션**: 노드에 들어오거나 나갈 때 실행할 동작이에요.
### 엣지
엣지는 노드와 노드를 잇는 화살표예요. "이 단계가 끝나면 다음은 어디로"를 정해요.
수집 노드는 대개 다음 노드로 하나만 나가고, 분기 노드는 갈래 수만큼 나가요.
## 액션
노드 진입·이탈 시점에 실행할 수 있는 동작이 세 가지 있어요.
| 액션 | 하는 일 |
| --------------- | ------------------------------------ |
| `tts_say` | 고정 멘트를 그대로 읽어요. AI가 문장을 새로 만들지 않아요 |
| `hold_music` | 대기음을 재생하기 시작해요 |
| `transfer_call` | 상담원에게 전환해요. 에이전트 **전환** 탭 설정을 그대로 써요 |
`transfer_call`에는 `wait_sec`(0\~30초)을 줄 수 있어요. 전환을 실행하기 전에 그만큼 기다리는데,
그동안 앞서 시작한 대기음이 재생돼요. 실제 상담 대기열 느낌을 만들 때 써요.
시나리오는 통화를 **종료할 수 없어요**. 인바운드는 봇이 먼저 끊지 않는 것이 정책이라
`end_call` 같은 종료 액션은 아예 제공하지 않아요.
## 키패드(DTMF) 입력
수집 노드에서 **키패드 입력 허용**을 켜면 음성과 키패드를 동시에 받아요.
고객이 말해도 되고 숫자 버튼을 눌러도 돼요.
| 설정 | 설명 |
| ---------- | ------------------------------------------- |
| 입력 안내 멘트 | 노드에 들어오면 이 문구를 그대로 읽어요. 비우면 AI가 알아서 안내해요 |
| 최소·최대 자릿수 | 몇 자리까지 받을지 정해요 |
| 입력 종료키 | `#` 또는 `*`. 없음으로 두면 자릿수와 대기 시간으로만 끝내요 |
| 입력 대기 시간 | 마지막 키 입력 후 몇 초 기다릴지 정해요 |
| 재시도 횟수 | 이 횟수를 넘기면 키패드를 접고 음성 안내로 이어가요 |
| 확인 멘트(리드백) | `{value}`가 입력값으로 바뀌어 되읽어 줘요. 비우면 확인 없이 넘어가요 |
리드백을 켜면 확인 중에 **1번은 맞음, 2번은 재입력**이고, 그 밖의 숫자를 누르면 바로
재입력이 시작돼요. 고객이 `*`를 누르면 그때까지 누른 값을 지우고 처음부터 다시 받아요.
리드백 문구에는 `{value}`가 반드시 들어가야 해요. 없으면 저장할 때 거부돼요.
번호를 되읽지 않는 확인은 의미가 없기 때문이에요.
키패드 메뉴(1번·2번 같은 갈래 선택)를 쓰면 안내 멘트가 고정 발화로 나가고, 숫자 키와
음성 양쪽 모두로 갈래가 결정돼요.
## 저작 방식 두 가지
시나리오 편집기에는 탭이 두 개 있어요. 같은 시나리오를 다른 방식으로 볼 뿐이에요.
Step을 위에서 아래로 나열해 편집해요. 한 줄로 이어지는 단순한 수집 흐름에 빠르고 쉬워요
노드와 화살표를 직접 놓고 이어요. 분기·키패드 메뉴·여러 Tool을 쓰는 흐름은 이쪽이라야 해요
## 저장할 때 확인하는 것들
저장을 누르면 서버가 흐름을 검사해요. 하나라도 걸리면 저장되지 않고 이유를 알려줘요.
* **시작 노드가 정확히 1개**여야 해요.
* **완료 노드가 최소 1개** 있어야 해요.
* 완료가 아닌 노드는 **나가는 화살표가 최소 하나** 있어야 해요. 없으면 대화가 그 자리에서 멈춰요.
* 모든 노드가 **시작 노드에서 도달 가능**해야 해요. 떨어져 있는 노드는 영영 실행되지 않아요.
* 흐름에 **순환(사이클)이 없어야** 해요. 시나리오는 완료로 끝나는 흐름이어야 해요.
검증은 통화 중이 아니라 **저장할 때** 걸려요. 저작 실수를 실통화 전에 잡기 위한 설계예요.
## 다른 방식과 함께 쓰기
한 에이전트에 시나리오를 여러 개 둘 수 있어요. 트리거 키워드가 서로 달라서, 고객이 무엇을
말하느냐에 따라 해당 시나리오로 들어가요. 시나리오에 걸리지 않는 대화는 기본 프롬프트가 받아요.
* **자동 시작**: 통화가 시작되자마자 특정 시나리오로 들어가게 해요. 에이전트당 하나만 지정할 수 있고,
목록 화면에서 켜요.
* **활성/비활성**: 시나리오별 토글로 끄고 켜요. 꺼진 시나리오는 키워드에 걸려도 실행되지 않아요.
* **가져오기/내보내기**: 시나리오를 파일로 주고받아요. 도구까지 함께 담기고, 이름이 겹치면
가져올 때 기존 재사용과 새로 생성 중에 고르게 돼요.
**S2S(실시간 음성) 엔진은 시나리오를 지원하지 않아요.** AI 모델 탭에서 S2S를 고르면 시나리오가
차단돼요. 저장된 시나리오는 그대로 남아 있고, Cascading 모드로 되돌리면 다시 켜져요.
## 다음 단계
도구 등록부터 통화 테스트까지 예약 접수 시나리오를 하나 만들어 봐요
시나리오가 호출할 API·MCP·A2A 도구를 등록해요
시나리오를 붙일 에이전트를 설정하고 배포해요
시나리오가 어떻게 진행됐는지 전사와 녹취로 확인해요