메뉴얼은 프롬프트 에이전트에서만 쓸 수 있어요. 플로우 에이전트에는 메뉴얼을 만들 수 없어요.
절차를 담을 방식 고르기
시스템 프롬프트
가장 빠르게 만들고 고칠 수 있어요. 절차가 한두 개뿐인 단순한 에이전트일 때 고르세요.
메뉴얼
업무마다 절차를 나눠 두고 필요한 순간에만 불러와요. 업무가 여러 개이고 에이전트가 말과 순서를 조절해도 될 때 고르세요.
플로우 에이전트
그래프로 설계한 경로를 그대로 따라요. 정해진 분기와 단계를 매번 똑같이 강제해야 할 때 고르세요.
작동 방식
프롬프트 에이전트의 시스템 프롬프트는 매 턴 대화 컨텍스트에 통째로 들어가요. 절차가 쌓일수록 지금 대화와 무관한 내용까지 토큰을 쓰고 응답이 늦어져요. 메뉴얼은 평소에 제목과 트리거만 대화에 올라가 있어요. 대화가 트리거와 맞는 순간 본문을 불러오고, 그 통화가 끝날 때까지 유지해요.
- 트리거가 있는 메뉴얼: 대화 상황이 트리거와 맞으면 에이전트가 직접 불러와요.
- 트리거가 빈 메뉴얼: 다른 메뉴얼이 본문에서 참조할 때만 이어서 불러와요. 여러 절차가 공유하는 공통 단계를 따로 둘 때 써요.
- 메뉴얼이 참조한 도구: 메뉴얼을 불러오는 순간 함께 쓸 수 있어요. 에이전트에 따로 연결하지 않아도 돼요.
에이전트와 함께 관리하기
메뉴얼은 그 메뉴얼을 쓰는 에이전트 안에 있어요. 에이전트 편집 화면 설정 패널의 메뉴얼에서 만들고, 카드를 누르면 프롬프트 옆에 탭으로 열려요.- 수정할 때: 편집 내용은 현재 편집본에 자동으로 저장돼요. 실제 통화에 반영하려면 에이전트를 배포하세요.
- 배포할 때: 메뉴얼은 프롬프트, 도구와 함께 같은 버전에 담겨요. 변경사항 검토 화면의 메뉴얼 항목에서 바뀐 내용을 확인하세요.
- 되돌릴 때: 이전 버전을 복원하면 그 버전의 메뉴얼도 함께 돌아와요.
- 다른 에이전트에서 쓸 때: 에이전트를 복제하면 메뉴얼도 함께 복사돼요. 원본을 고쳐도 복사본은 바뀌지 않아요.
API로 설정하기
API에서는 메뉴얼이 에이전트 설정의data.manuals에 담겨요. 키는 메뉴얼 UUID예요. 메뉴얼을 한 건씩 다룰 때는 /agents/{agent_id}/manuals 엔드포인트를 쓰고, 쓰기 요청마다 마지막으로 조회한 head_revision을 expected_head_revision으로 보내세요. 요청과 응답 형식은 API 참조의 메뉴얼 항목에 있어요.
data.manuals를 보낼 때: 전체 맵을 교체해요. 일부 항목만 보내면 나머지는 제거돼요.data.manuals를 생략한 PATCH: 현재 맵을 유지해요.- 전역
/manuals경로: 제공하지 않아요. 메뉴얼은 에이전트 하위 경로로만 다뤄요. - revision:
GET /agents/{agent_id}?version=current에서 읽으세요.REVISION_CONFLICT가 나면 자동으로 다시 시도하지 마세요.
문제가 생겼을 때
예전 메뉴얼 목록 화면이 보이지 않아요
예전 메뉴얼 목록 화면이 보이지 않아요
에이전트 편집 화면 설정 패널의 메뉴얼에서 찾으세요. 2026년 9월 22일부터 메뉴얼은 워크스페이스 목록이 아니라 각 에이전트 안에서 관리해요. 그전에 에이전트에 연결해 두었던 메뉴얼은 연결된 에이전트마다 사본으로 옮겨졌어요.
메뉴얼 때문에 배포가 막혀요
메뉴얼 때문에 배포가 막혀요
빨간 점이 붙은 메뉴얼 탭을 열고 탭 아래쪽에 표시된 항목을 고치세요. 제목이 없거나, 없는 메뉴얼이나 도구를 참조하면 배포할 수 없어요. 통화에서 불러올 수 있는 메뉴얼이 대상이에요.
과거 버전의 메뉴얼이 당시 내용과 달라요
과거 버전의 메뉴얼이 당시 내용과 달라요
버전을 열고 메뉴얼 목록 아래에 표시된 이관 날짜를 확인하세요. 2026년 9월 22일 이전에 배포한 버전은 메뉴얼을 버전에 담지 않아서, 메뉴얼을 쓰던 과거 버전에는 이관 시점의 메뉴얼 내용이 들어 있어요.
관련 문서
- 메뉴얼 작성: 트리거와 본문을 쓰고 도구 참조하기
- 에이전트 버전 관리: 메뉴얼을 포함한 설정을 배포하고 되돌리기
- 실행 대기음: 메뉴얼을 불러온 직후 재생할 소리 고르기