본문 바로가기 메뉴 바로가기

Kakao i Agent::구현 시나리오::대표 명령어

페이지 이동경로

대표 명령어

대표 명령어는 특정 명령어에 실행되는 명령어 그룹으로서, 사용자가 사전에 정의한 명령어를 발화하면 정의된 명령어들이 순차로 실행되는 기능입니다. 명령어 그룹에 포함될 수 있는 명령어의 개수는 최소 한 개부터 최대 10개까지이며, 음악형 콘텐츠에 해당하는 명령어는 한 개만 설정할 수 있습니다. 대표 명령어를 사용하기 위해서는 Recognizer.Text 인터페이스의 triggerType 파라미터를 WORKFLOW로 설정해야 합니다.

다음 시나리오는 사용자가 “나 졸려"라는 대표 명령어 그룹(나 졸려)에 명령어 1(잠온다), 명령어 2(내일 일정 알려줘), 명령어 3(조용한 노래 틀어줘)를 등록하여 해당 명령어에 해당하는 음성 답변 또는 동작이 순차적으로 처리되는 과정을 설명합니다.

안내
대표 명령어는 카카오톡에서 “헤이카카오” 친구 추가를 한 후에 설정 챗봇 > [나만의 맞춤 설정] > [내 명령어 설정]에서 설정할 수 있습니다.

Wake-up

Wake-up 시나리오 그림Wake-up 시나리오

  1. 사용자가 Wake-up 버튼을 누릅니다.

  2. Service Agent는 발화 효과음 “띠링”과 함께 발화가 시작되었음을 인식하는 Recognizer.Speech Event를 KVS(Kakao i agent Virtual Service)에 전송합니다.

    표Recognizer.Speech
    구분 설명
    Interface Recognizer.Speech: Service Agent에서 발생한 사용자 발화를 KVS에 전달
    메시지 타입: Event
    인터페이스 타입: Recognizer
    인터페이스: Speech
    Body type으로 구성됨
    type: BUTTON_TAP
    안내
    Service Agent에서 발화 인식 기준이 미달되었지만 KVS에서 인식 기준을 충족했을 경우, Service Agent는 KVS로부터 전달받은 Recognizer.InformRecognized Instruction의 데이터를 기준으로 발화를 인식합니다.

음성 명령

음성 명령 시나리오 그림음성 명령 시나리오

음성 명령 인식 시작

  1. 사용자가 “나 졸려”라는 음성 명령을 합니다.

  2. KVS가 음성 명령이 시작되었음을 인식하고 Recognizer.InformRecognized Instruction을 Service Agent에 전송합니다.

    • Recognizer.InformRecognized Instruction은 음성 인식 진행 중간 결과와 최종 결과를 Service Agent에 전달해주는 인터페이스이며, 각 단계별 인식 결과를 전송할 때 type을 특정하여 전송합니다.
    표Recognizer.InformRecognized
    구분 설명
    Interface Recognizer.InformRecognized: KVS가 음성 인식 진행 중간/최종 결과를 Service Agent에 전달
    메시지 타입: Instruction
    인터페이스 타입: Recognizer
    인터페이스: InformRecognized
    Body type, text로 구성됨
    type: BPD(인식 시작)
    text: BPD
    type: PARTIAL(인식 중)
    text: 나, 나 졸려
    type: EPD(인식 종료)
    text: EPD
    안내
    Recognizer.InformRecognized의 Body 타입에 사용되는 약자와 의미는 다음과 같습니다.
    - BPD(Begin Point Detection): 사용자가 발화를 시작하는 것으로 판단
    - PARTIAL(Partial Result) :사용자가 발화를 끝내기 전의 중간 인식 결과
    - EPD(End Point Detection): 사용자가 발화를 종료한 것으로 판단
    - FINAL(Final Result): 사용자가 발화한 음성의 최종 결과

음성 명령 캡처 중지

  1. KVS가 전달받은 음성을 통해 완전한 명령어를 인식하면, Service Agent에 음성 캡처 중지를 요청하는 Recognizer.StopCapture Instruction을 전송합니다.

    • Service Agent는 Recognizer.StopCapture Instruction을 전달받으면 즉시 마이크를 닫습니다.
    표Recognizer.StopCapture
    구분 설명
    Interface Recognizer.StopCapture: KVS가 사용자의 의도를 파악했거나 명령어 인식을 종료할 때 사용자의 음성 캡처를 중지하도록 Service Agent에 지시
    메시지 타입: Instruction
    인터페이스 타입: Recognizer
    인터페이스: StopCapture

음성 명령 인식 완료

KVS는 음성 명령어 인식을 완료하면 최종 인식 결과를 Recognizer.InformRecognized(type: FINAL) Instruction을 통해 Service Agent에 전달합니다.

표Recognizer.InformRecognized
구분 설명
Interface Recognizer.InformRecognized: KVS가 음성 인식 진행 중간 결과와 최종 결과를 Service Agent에 전달하는 Instruction
메시지 타입: Instruction
인터페이스 타입: Recognizer
인터페이스: InformRecognized
Body type, text로 구성됨
type: FINAL(인식 완료)
text: 나 졸려

명령어 1(잠 온다)

명령어 1(잠 온다) 시나리오 그림명령어 1(잠 온다) 시나리오

  1. KVS는 “나 졸려” 대표 명령어에 설정된 명령어를 순차적으로 실행 시키기 위해 Recognizer.RequestText Instruction을 전송합니다.

    표Recognizer.RequestText
    구분 설명
    Interface Recognizer.RequestText: KVS가 Service Agent에 Text Event를 보내도록 지시
    메시지 타입: Instruction
    인터페이스 타입: Recognizer
    인터페이스: RequestText
    Body utternace, triggerType으로 구성됨
    utternace: 잠 온다
    triggerType: WORKFLOW

  2. 해당 명령어의 실행 여부를 판단하기 위해, KVS는 대기 상태를 요청하는 System.SubscribeNextIdle Instruction을 전송합니다. 이에 대한 응답으로 Service Agent는 System.Idle Event를 전송하고, 다음 명령어를 실행합니다.

    표System.SubscribeNextIdle
    구분 설명
    Interface System.SubscribeNextIdle: Service Agent의 유휴 상태가 일정 시간 이상 지속될 때 KVS가 Service Agent에 전송
    메시지 타입: Instruction
    인터페이스 타입: Recognizer
    인터페이스: RequestText
    Body utternace, triggerType으로 구성됨
    utternace: 잠 온다
    triggerType: WORKFLOW

  3. KVS는 음성 응답을 지시하기 위해 Synthesizer.Speak Instruction과 데이터를 Service Agent에 전달합니다.

    표System.SubscribeNextIdle
    구분 설명
    Interface Synthesizer.Speak: Service Agent에 음성 응답이 필요할 때마다 KVS가 Service Agent에 전송
    메시지 타입: Instruction
    인터페이스 타입: System
    인터페이스: RequestText
    Body url, text로 구성됨
    url: 음성 URL
    text: 토닥토닥 콩콩

  4. Service Agent가 음성 답변(“토닥토닥 콩콩”)을 재생하고, Synthesizer.SpeakStarted Event를 전송합니다.

    표Synthesizer.SpeakStarted
    구분 설명
    Interface Synthesizer.SpeakStarted: Service Agent가 Speak Instruction을 처리하고 합성된 음성의 재생을 시작한 후에 KVS에 전송
    메시지 타입: Event
    인터페이스 타입: Synthesizer
    인터페이스: SpeakStarted

  5. 음성 답변 출력이 완전히 종료되면, Service Agent는 KVS에 Synthesizer.SpeakFinished Event를 전송합니다. 표Synthesizer.SpeakFinished

    구분 설명
    Interface Synthesizer.SpeakFinished: Service Agent가 Speak Instruction을 처리하고 합성된 음성의 재생을 마친 후에 KVS에 전송
    메시지 타입: Event
    인터페이스 타입: Synthesizer
    인터페이스: SpeakFinished
    안내
    수신된 음성 응답은 Speak 채널의 Player Queue에 추가되어 우선순위에 맞게 순차적으로 출력됩니다.

  6. System.SubscribeNextIdle Instruction에 대한 응답으로, Service Agent는 KVS에 System.Idle Event를 전송하고 다음 명령어의 실행을 준비합니다.

    • Service Agent가 System.Idle Event를 전송하면, KVS는 다음 명령어의 실행을 요청하기 위해 Recognizer.RequestText Instruction을 Service Agent에 전송합니다.
    표System.idle
    구분 설명
    Interface Sytem.idle: System.SubscribeNextIdle Instruction에서 주어진 interval 동안 Service Agent의 유휴 상태가 지속될 경우 Service Agent가 KVS에 전송
    메시지 타입: Event
    인터페이스 타입: System
    인터페이스: Idle
    안내
    대기(Idle) 상태란 Service Agent가 아무 기능을 하지 않는 대기 상태로, 음성 인식 및 처리 중이 아니며 스피커가 소리를 내지 않는 상태를 의미합니다.

명령어 2(내일 일정 알려줘)

명령어 2(내일 일정 알려줘) 시나리오 그림명령어 2(내일 일정 알려줘) 시나리오

  1. KVS는 명령어 2(내일 일정 알려줘)의 실행을 요청하기 위해 Service Agent에 Recognizer.RequestText Instruction을 전송합니다.

    표Recognizer.RequestText
    구분 설명
    Interface Recognizer.RequestText: KVS가 Service Agent에 Text Event를 보내도록 지시
    메시지 타입: Instruction
    인터페이스 타입: System
    인터페이스: SubscribeNextIdle
    Body utterance, triggerType으로 구성됨
    utterance: 내일 일정 알려줘
    triggerType: WORKFLOW

  2. 명령어의 실행 종료 여부를 판단하기 위해, KVS는 대기 상태를 요청하는 System.SubscribeNextIdle Instruction을 전송합니다. 이에 대한 응답으로 Service Agent는 System.Idle Event를 전송하고, 다음 명령어를 실행합니다.

    표System.SubscribeNextIdle
    구분 설명
    Interface System.SubscribeNextIdle: Service Agent의 유휴 상태가 일정 시간 이상 지속될 때 KVS가 Service Agent에 전송
    메시지 타입: Instruction
    인터페이스 타입: System
    인터페이스: SubscribeNextIdle

  3. 지정된 텍스트 명령어를 KVS에 요청하기 위해 Service Agent는 Recognizer.Text Event를 전송합니다.

    표Recognizer.Text
    구분 설명
    Interface Recognizer.Text: 음성이 아닌 텍스트 발화 입력 시, 지정된 텍스트 명령어를 KVS에 전달
    메시지 타입: Event
    인터페이스 타입: Recognizer
    인터페이스: Text
    Body utterance, triggerType으로 구성됨
    utterance: 내일 일정 알려줘
    triggerType: WORKFLOW

  4. KVS는 음성 응답을 전달하기 위해, Service Agent에 Synthesizer.Speak Instruction을 전달합니다.

    표Synthesizer.Speak
    구분 설명
    Interface Synthesizer.Speak: Service Agent에 음성 응답이 필요할 때마다 KVS가 Service Agent에 전달
    메시지 타입: Instruction
    인터페이스 타입: Recognizer
    인터페이스: Text
    Body url, text로 구성됨
    url: 음성 URL
    text: 내일은 일정이 없어요

  5. Service Agent가 음성 답변(“내일은 일정이 없어요”)을 재생하고, Synthesizer.SpeakStarted Event를 전송합니다.

    표Synthesizer.SpeakStarted
    구분 설명
    Interface Synthesizer.SpeakStarted: Service Agent가 Speak Instruction을 처리하고 합성된 음성의 재생을 시작한 후에 KVS에 전송
    메시지 타입: Event
    인터페이스 타입: Synthesizer
    인터페이스: SpeakStarted

  6. 음성 답변 출력이 완전히 종료되면, Service Agent는 KVS에 Synthesizer.SpeakFinished Event를 전송합니다.

    표Synthesizer.SpeakFinished
    구분 설명
    Interface Synthesizer.SpeakStarted: Service Agent가 Speak Instruction을 처리하고 합성된 음성의 재생을 마친 후에 KVS에 전달
    메시지 타입: Event
    인터페이스 타입: Synthesizer
    인터페이스: SpeakFinished

  7. System.SubscribeNextIdle Instruction에 대한 응답으로, Service Agent는 KVS에 System.idle Event를 전달하고 다음 명령어의 실행을 준비합니다.

    • System.idle에 대한 응답으로 KVS는 Recognizer.RequestText Instruction을 전송합니다.
    표Sytem.idle
    구분 설명
    Interface Sytem.idle: System.SubscribeNextIdle Instruction에서 주어진 interval 동안 Service Agent의 유휴 상태가 지속될 경우 Service Agent가 KVS에 전달
    메시지 타입: Event
    인터페이스 타입: System
    인터페이스: Idle
    안내
    idle(대기)는 Service Agent가 아무 기능을 하지 않는 대기 상태로, 음성 인식 및 처리 중이 아니며 스피커가 소리를 내지 않는 상태를 의미합니다.

명령어 3(조용한 노래 틀어줘)

명령어 3(조용한 노래 틀어줘) 시나리오 그림명령어 3(조용한 노래 틀어줘) 시나리오

  1. KVS는 명령어 3(조용한 노래 틀어줘)의 실행을 요청하기 위해 Recognizer.RequestText Instruction을 전달합니다.

    표Recognizer.RequestText
    구분 설명
    Interface Recognizer.RequestText: KVS가 Service Agent에 Text Event를 보내도록 지시
    메시지 타입: Instruction
    인터페이스 타입: Recognizer
    인터페이스: RequestText
    Body utternace, triggerType으로 구성됨
    utternace: 조용한 노래 틀어줘
    triggerType: WORKFLOW

  2. 해당 명령어의 실행 종료 여부를 판단하기 위해, KVS는 대기 상태를 요청하는 System.SubscribeNextIdle Instruction을 전달합니다. 이에 대한 응답으로 Service Agent는 Sytem.idle Event를 KVS에 전달하고, 다음 명령어를 실행합니다.

    표System.SubscribeNextIdle
    구분 설명
    Interface System.SubscribeNextIdle: Service Agent의 유휴 상태가 일정 시간 이상 지속될 때 KVS가 Service Agent에 전달
    메시지 타입: Instruction
    인터페이스 타입: System
    인터페이스: SubscribeNextIdle

  3. 지정된 텍스트 명령어를 KVS에 요청하기 위해 Service Agent는 Recognizer.Text Event를 전송합니다.

    표Recognizer.Text
    구분 설명
    Interface Recognizer.Text: 음성이 아닌 텍스트 발화 입력 시, 지정된 텍스트 명령어를 KVS에 전달
    메시지 타입: Event
    인터페이스 타입: Recognizer
    인터페이스: Text

  4. KVS는 음성 응답을 전달하기 위해, Service Agent에 Synthesizer.Speak Instruction을 전달합니다.

    표Synthesizer.Speak
    구분 설명
    Interface Synthesizer.Speak: Service Agent에 음성 응답이 필요할 때마다 KVS가 Service Agent에 전달
    메시지 타입: Instruction
    인터페이스 타입: Synthesizer
    인터페이스: Speak
    Body url, text로 구성됨
    url: 음성 URL
    text: 조용한 음악 들려줄게요

  5. Service Agent가 음성 답변(“조용한 음악 들려줄게요”)을 재생하고, Synthesizer.SpeakStarted Event를 전송합니다.

    표Synthesizer.SpeakStarted
    구분 설명
    Interface Synthesizer.SpeakStarted: Service Agent가 Speak Instruction을 처리하고 합성된 음성의 재생을 시작한 후에 KVS에 전송
    메시지 타입: Event
    인터페이스 타입: Synthesizer
    인터페이스: Speak.Started

  6. 음성 답변 출력이 완전히 종료되면, Service Agent는 KVS에 Synthesizer.SpeakFinished Event를 전송합니다.

    표음성 응답 재생 종료 메시지
    구분 설명
    Interface Synthesizer.SpeakFinished: Service Agent가 Speak Instruction을 처리하고 합성된 음성의 재생을 마친 후에 KVS에 전달
    메시지 타입: Event
    인터페이스 타입: Synthesizer
    인터페이스: Speak.Finished

  7. 다음 곡의 재생을 위해, Service Agent는 KVS에 AudioPlayer.Started Event를 전송합니다.

    표AudioPlayer.Started
    구분 설명
    Interface AudioPlayer.Started: Service Agent가 오디오 스트림의 재생이 시작했음을 KVS에 전달
    메시지 타입: Event
    인터페이스 타입: AudioPlayer
    인터페이스: Started
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 contact.dkt@kakaocorp.com 으로 제보해주세요.