> ## 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.
# 메뉴얼 작성
> 메뉴얼의 트리거와 본문을 쓰고, 도구와 다른 메뉴얼을 참조하고, 템플릿이나 문서로 초안을 시작할 수 있어요.
메뉴얼은 에이전트 편집 화면에서 만들고 프롬프트 옆 탭에서 써요. 제목, **언제**, 본문 세 칸만 채우면 에이전트가 통화 중 그 절차를 따라요.
메뉴얼이 통화에서 언제 불려 오는지와 프롬프트, 플로우 가운데 무엇을 고를지는 [메뉴얼 개요](/docs/build/manuals/overview)에 있어요.
## 메뉴얼 만들기
에이전트 편집 화면 설정 패널의 **메뉴얼**을 펼치고 **메뉴얼 만들기**를 누르세요. `새 메뉴얼`이라는 이름으로 만들어지고 프롬프트 옆에 탭으로 열려요.
제목은 목록과 탭에서 메뉴얼을 알아보는 라벨이에요. **언제**에는 이 절차를 꺼낼 대화 상황을 쓰세요.
에이전트가 따를 절차를 쓰세요. 빈 메뉴얼이면 템플릿이나 가지고 있는 문서로 초안을 채울 수 있어요.
편집 내용은 현재 편집본에 자동으로 저장돼요. 실제 통화에 쓰려면 에이전트를 [배포](/docs/build/versioning)하세요.
메뉴얼을 쓸 때 알아 둘 한도예요.
| 항목 | 값 |
| - | - |
| 제목 | 최대 128자 |
| 본문 | 최대 8,096자, 공백 포함 |
| 쓸 수 있는 에이전트 | 프롬프트 에이전트 |
| 참조 범위 | 워크스페이스의 API 도구, 이 메뉴얼의 빌트인 도구, 같은 에이전트의 메뉴얼 |
## 트리거 쓰기
**언제**에는 이 메뉴얼을 꺼낼 대화 상황을 쓰세요. 에이전트는 통화 중 대화와 트리거를 대조해 메뉴얼을 불러올지 판단해요. 예: `고객이 주문한 상품의 환불이나 교환을 요청할 때`
* **발화 상황 담기**: "환불 처리"처럼 업무 이름만 쓰지 말고 실제 대화 상황을 쓰세요. "고객이 환불을 요청하거나 결제 취소를 문의할 때"처럼 구체적일수록 정확하게 불러와요.
* **다른 메뉴얼과 경계 나누기**: 같은 에이전트의 메뉴얼끼리 트리거가 겹치면 엉뚱한 절차를 불러올 수 있어요.
* **참조 전용이면 비워 두기**: 목록 카드에 **시작 조건 없음**으로 표시되고, 다른 메뉴얼이 참조할 때만 불러와요.
## 본문 쓰기
순서가 있는 절차는 번호 목록으로, 단계 안의 조건은 글머리표로 쓰세요. 본문에서 `/`를 누르면 제목과 **단계** 서식을 넣을 수 있어요.
```markdown theme={null}
1. 주문번호를 물어봅니다.
2. 주문 조회 도구로 주문을 확인합니다.
- 주문이 없으면 번호를 다시 확인합니다.
3. 환불 사유를 확인하고 접수를 안내합니다.
```
에이전트는 지시를 해석해 상황에 맞게 말과 순서를 조절해요. 매번 똑같은 실행을 강제해야 한다면 [플로우 에이전트](/docs/build/flow/overview)를 쓰세요.
## 도구와 다른 메뉴얼 참조하기
본문에서 `/`를 누르고 **도구**나 **메뉴얼**을 고르면 참조할 대상을 검색할 수 있어요. `@tool:`이나 `@manual:`을 직접 입력해도 같은 목록이 열려요. 고른 참조는 본문에 태그로 표시돼요.
| 참조 | 고를 수 있는 대상 | 메뉴얼을 불러오면 |
| - | - | - |
| API 도구 | 워크스페이스에 만든 [API 도구](/docs/build/tools/api) | 에이전트가 그 도구를 함께 쓸 수 있어요 |
| 빌트인 도구 | 이 메뉴얼 안에서 만든 빌트인 도구 | 에이전트가 그 도구를 함께 쓸 수 있어요 |
| 메뉴얼 | 같은 에이전트의 다른 메뉴얼 | 에이전트가 이어서 그 메뉴얼을 불러올 수 있어요 |
메뉴얼이 쓰는 도구는 본문의 참조가 정해요. 에이전트의 도구 목록에 따로 연결하지 않아도 돼요.
상담사 연결처럼 여러 절차가 공유하는 단계는 트리거가 빈 메뉴얼로 따로 만들고, 환불과 해지 메뉴얼 양쪽에서 참조하세요. 태그로 표시된 메뉴얼 참조를 누르면 그 메뉴얼이 탭으로 열려요.
## 빌트인 도구 추가하기
통화 종료, 통화 전환, 에이전트 전환, 문자 발신, DTMF 전송, 주소 검색, [변수 추출](/docs/build/tools/builtin/extract-variables)은 메뉴얼마다 따로 만들어요. `/`에서 **도구**를 고른 뒤 빌트인 도구 종류를 고르면 설정 창이 열리고, 저장하면 본문에 참조가 들어가요.
문자 발신은 문자를 보낼 수 있는 번호가 있어야 목록에 나와요. 번호 상세에서 [문자 발신](/docs/operate/deploy/phone/sms)을 신청해 승인받은 뒤 쓰세요.
만든 빌트인 도구는 메뉴얼 탭 아래쪽에 배지로 모여요. 배지를 누르면 설정을 고치고, **제거**를 누르면 메뉴얼에서 빼요. 도구 이름을 바꾸면 본문의 참조도 함께 바뀌어요. 도구별 설정은 [통화 종료](/docs/build/tools/builtin/end-call), [통화 전환](/docs/build/tools/builtin/transfer-call), [에이전트 전환](/docs/build/tools/builtin/transfer-agent) 같은 빌트인 도구 문서에 있어요.
## 템플릿이나 문서로 시작하기
새로 만든 메뉴얼처럼 내용이 빈 메뉴얼에는 본문 아래쪽에 초안을 채우는 버튼 세 개가 나와요.
* **템플릿에서 시작**: vox.ai가 준비한 템플릿을 골라 지금 메뉴얼에 채워요. 자주 쓰는 절차를 고쳐 쓸 때 고르세요.
* **문서로 초안 만들기**: 업무 문서를 올리면 제목, 트리거, 본문 초안을 만들어 줘요. `.md`, `.txt` 파일을 올릴 수 있어요.
* **마크다운 가져오기**: `.md` 파일 내용을 그대로 본문에 넣어요. 이미 정리된 절차가 있을 때 고르세요.
초안은 열어서 다듬은 뒤 쓰세요. 내용이 이미 있는 메뉴얼에는 초안을 덮어쓰지 않아요.
## 실행 대기음 고르기
메뉴얼을 불러온 직후 재생할 소리는 메뉴얼 탭 오른쪽 위의 **메뉴얼 설정**에서 고르세요. 대기음 종류와 동작은 [실행 대기음](/docs/build/tools/tool-call-sound)과 같아요.
## 메뉴얼 삭제하기
삭제할 메뉴얼의 탭을 열고 오른쪽 위 **삭제** 버튼을 누르세요. 다른 메뉴얼이 이 메뉴얼을 참조하고 있으면 확인 창에 참조하는 메뉴얼 수가 나와요. 삭제하면 그 참조가 끊어지니 참조한 메뉴얼도 함께 고치세요.
삭제도 편집과 같이 현재 편집본에만 적용돼요. 이미 배포한 버전의 메뉴얼은 다음 배포 전까지 그대로 통화에 쓰여요.
## API로 설정하기
v3 API는 메뉴얼을 에이전트 소유 리소스로 저장해요. 에이전트 설정의 `data.manuals`는 UUID 키를 쓰는 전체 맵이에요.
* **PATCH에 `manuals`를 넣으면**: 맵 전체를 교체해요. 일부 항목만 보내면 빠진 항목이 제거돼요.
* **`manuals`를 생략하면**: 현재 맵을 유지해요.
* **개별 메뉴얼을 다룰 때**: `/agents/{agent_id}/manuals` 하위 경로로 조회하고, 만들고, 고치고, 지우세요. 전역 `/manuals` 경로는 제공하지 않아요.
```json theme={null}
{
"expected_head_revision": 12,
"data": {
"manuals": {
"11111111-1111-4111-8111-111111111111": {
"name": "환불 안내",
"trigger": "고객이 환불이나 결제 취소를 요청할 때",
"content": "환불 사유와 주문 정보를 확인합니다.",
"built_in_tools": [],
"config": { "tool_call_sound": "typing" }
}
}
}
}
```
예시의 `12`는 설명용 값이에요. 요청을 보내기 전에 `GET /agents/{agent_id}?version=current` 응답에서 확인한 `head_revision`으로 바꾸세요. 쓰기 요청에는 마지막으로 읽은 값을 `expected_head_revision`으로 보내세요. `REVISION_CONFLICT`가 나면 최신 상태를 자동으로 다시 읽어 덮어쓰지 말고, 바뀐 내용을 확인해 직접 병합하세요.
## 문제가 생겼을 때
탭을 열고 탭 아래쪽에 표시된 항목을 고치세요. 제목이 없거나, 참조 형식이 올바르지 않거나, 만들지 않은 빌트인 도구를 참조하면 표시돼요. 고치지 않으면 배포가 막힐 수 있어요.
빈 메뉴얼에서 다시 시도하세요. 작성 중인 내용을 덮어쓰지 않도록, 내용이 있는 메뉴얼에는 템플릿과 초안을 넣지 않아요.
파일 크기와 형식을 확인하세요. 문서로 초안 만들기는 100,000자까지 읽어요. 마크다운 가져오기는 본문 한도인 8,096자를 넘는 파일을 가져올 수 없어요.
## 관련 문서
* [메뉴얼 개요](/docs/build/manuals/overview): 메뉴얼을 불러오는 방식과 관리 방법
* [에이전트 버전 관리](/docs/build/versioning): 메뉴얼을 포함한 설정을 배포하고 되돌리기
* [API 도구](/docs/build/tools/api): 메뉴얼에서 참조할 도구 만들기
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.