Service Agent Interface

Service Agent Interface의 Message에 대한 설명과 카카오 i(KVS)에서 제공하는 인터페이스 목록은 다음과 같습니다.

주의
인터페이스 구현 시, 해당 필드 포맷을 반드시 준수하시기 바랍니다.

필드별 포맷에 오류가 있는 경우에는 KVS에서 경고를 발생시킵니다.

Body 필드는 null을 입력할 경우 에러가 발생할 수 있으니, 빈 값인 경우에는 반드시 empty로 입력하시기 바랍니다.

Message 구조

Message는 Service Agent와 KVS 간의 데이터 전송과 수신에 사용되는 JSON 객체 혹은 미디어 스트림을 의미합니다. 모든 Message는 다음과 같이 header와 body로 구성됩니다.

표Message 구조

필드	타입	필수 여부	설명
	Object	`필수`	Message의 Header 부분 - `type`과 `messageId`로 구성
type	String	`필수`	해당 인터페이스 이름 - 온점(`.`)을 기준으로 Interface 구분자와 하위 구분자로 표현 ex) Recognizer.Speech: `Recognizer`는 Interface 구분자, `Speech`는 하위 구분자를 나타냄
messageId	String	`필수`	특정 메시지의 고유 ID - 해당 메시지의 생성 주체가 임의의 UUID로 정의
body	Object	`필수`	Message의 Body 부분 - 전송하고자 하는 내용을 JSON 포맷으로 입력

Message Syntax

코드예제Message Syntax

JSON

{
        "header": {
                "type": "{STRING}",
                "messageId": "{STRING}"
        },
        "body": {
          		{
          			{OBJECT}
		          }
        }
}

Message 타입

Agent Interface는 요청과 응답을 주고받기 위해 Message를 데이터 포맷으로 사용합니다. Message는 KVS와 Agent 간에 통신을 위한 데이터 자료 구조로서 JSON 포맷으로 구성되며, 타입은 Event, State, Instruction으로 구분됩니다. 각 메시지 타입을 전송할 때 특정 인터페이스 목적에 맞게 Scheme을 구성해야 하며, 정의된 필드들을 정확하게 넣어야 정상적으로 동작합니다.

Event는 Service Agent에서 발생한 요청 사항(일반적으로 음성 요청)을 KVS에알리는 Message입니다. 사용자 발화나 특정 해당 Event에 대한 응답으로 KVS는 Instruction Message를 전송하여 답변 재생을 하거나 Service Agent 제어, 볼륨 조정, 알람 설정 등과 같은 액션을 지시하며, 실제 서비스 로직에서 PUSH를 통해서 전송되기도 합니다. State는 Event와 함께 전송되는 정보이며, 경우에 따라 전송되지 않을 수도 있습니다.

표Message 포맷

구분	설명
Event(이벤트)	Service Agent에서 발생한 일련의 사건을 KVS로 전송하는 Message 포맷 - Event 메시지에는 State 메시지가 함께 전송될 수 있음
State(상태)	Service Agent의 상태 정보를 포함한 Message 포맷 - 대부분 Event 메시지와 함께 전송되며, 경우에 따라 전송이 안 될 수도 있음
Instruction(지시)	전송받은 Event 메시지에 대한 응답 - KVS가 Service Agent에 전송하는 Message 포맷

Event

Event는 Service Agent가 KVS로 전송하는 Message 포맷입니다. Event 메시지에는 상태(State)를 리스트로 추가할 수 있으며, 해당 State 정보는 KVS에서 Event에 대한 로그를 확인할 때 사용됩니다.

안내
고객사가 인터페이스를 직접 정의하는 Vendor 인터페이스의 Event 포맷은 다음과 같습니다.

Event 포맷: Vendor.{Vendor Name}.{Interface Name}.{Event Name}

Event Header

표Event Header

파라미터	타입	필수 여부	설명
type	String	`필수`	해당 인터페이스 이름
messageId	String	`필수`	특정 메시지를 나타내는 고유 ID - 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId	String	`선택`	Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID - 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Event Syntax

코드예제Event Syntax

JSON

{
  "event": {
    "header": {
      "type": "[INTERFACE TYPE]",
      "messageId": "[MESSAGE ID]",
      "dialogRequestId": "[DIALOG REQUEST ID]"
    },
    "body": {}
  }
}

State

State는 기본적으로 Event가 전송될 때 선택적(Optional)으로 전송되며, {Interface Name}.{State Name} 형태를 따릅니다.

안내
고객사가 인터페이스를 직접 정의하는 Vendor 인터페이스의 State 포맷은 다음과 같습니다.

State 포맷: Vendor.{Vendor Name}.{Interface Name}.{State Name}

표Body Parameters

파라미터	타입	필수 여부	설명
data	Object	`필수`	커스텀 데이터 영역

State Syntax

코드예제State Syntax

JSON

{
  "state": [
    {
      "header": {
        "type": "[INTERFACE TYPE]"
      },
      "body": {
        "wuw": "[WAKE-UP WORD]"
      }
    }
  ]
}

Instruction

Instruction(인스트럭션)은 Service Agent에서 발생한 Event에 대한 응답으로 KVS가 Service Agent로 전송하는 Message로, 시스템 설정값 변경, 노래 재생, 알람 재생 지시 등과 같이 Service Agent에서 처리해야 하는 지시 사항을 전달합니다. Service Agent가 Instruction을 수행하면 Resource의 State가 변경되며, 이에 따른 Event가 발생합니다.

안내
고객사가 인터페이스를 직접 정의하는 Vendor 인터페이스의 Instruction 포맷은 다음과 같습니다.

Instruction 포맷: Vendor.{Vendor Name}.{Interface Name}.{Instruction Name}

Instruction Header

표Instruction Header

파라미터	타입	필수 여부	설명
type	String	`필수`	해당 인터페이스 이름
messageId	String	`필수`	특정 메시지를 나타내는 고유 ID - 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId	String	`선택`	Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID - 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Instruction Syntax

코드예제Instruction Syntax

JSON

{
  "instruction": {
    "header": {
      "type": "[INTERFACE TYPE]",
      "messageId": "[MESSAGE ID]",
      "dialogRequestId": "[DIALOG REQUEST ID]"
    },
    "body": {}
  }
}

Message 구성

Token

카카오 i에서는 Bot의 Skill 서버가 Service Agent로 전달하는 Instruction 메시지에 토큰을 지정하는 것을 권장하며, 이 경우 Service Agent는 Instruction 메시지를 수행한 결과로 발생한 Event 메시지에 동일 토큰을 그대로 전달해야 합니다.

이렇게 Instruction과 Event 메시지가 동일 토큰을 교환함으로써, Bot의 Skill 서버는 Event 메시지를 전달받았을 때 Event 메시지에 포함된 토큰이 어떤 Instruction에 대한 결과인지 식별할 수 있습니다. 특히 Event 메시지의 경우에는 Bot의 ID가 포맷에 맞게 토큰에 명시되어야 해당 Bot의 Skill Request로 Event 메시지가 전달됩니다.

토큰 생성 규칙은 {벤더 이름}/{봇 아이디}/{uuid}이며, 주요 구분자는 슬래시(/)를 사용합니다.

표Token Parameters

파라미터	설명
MarkerId	- Chappie maker ID - Inhouse DA - 3^rd Party: 각 Maker의 ID
BotId	Chappie bot ID
DaCustom	주요 구분자인 `/`를 제외하고, Domain Agent에서 원하는대로 구성

인터페이스 목록

인터페이스는 Service Agent와 KVS간 데이터를 주고받는 Message의 스펙을 의미하며, 제공 목록은 다음과 같습니다.

안내
현재 인터페이스는 대부분 1.0 버전이며, 아래의 인터페이스에 한해 업데이트 버전을 지원하고 있습니다.

System.SubscribeNextIdle: 1.1 버전부터 지원

System.UnsubscribeIdle: 1.2 버전부터 지원

Recognizer.RequestText: 1.1 버전부터 지원

Synthesizer.Stop: 1.1 버전부터 지원

AudioPlayer.SuggestPlaylist: 1.1 버전부터 지원

표인터페이스 목록

인터페이스	설명	Event	Instruction	State
Recognizer	음성 인식	Speech Text Canceled	StopCapture InformRecognized ExpectSpeech RequestText	RecognizerState
MusicRecognizer	음악 인식	Recognize	StopCapture	-
Synthesizer	음성 답변	SpeakReceived SpeakStarted SpeakFinished SpeakStopped TextToSpeech	Speak Stop	SpeakState
AudioPlayer	오디오 콘텐츠 재생	Started NearlyFinished ProgressReport ProgressReportIntervalElapsed Finished Failed Stopped Paused Resumed	Play Stop SuggestPlaylist	PlayState ContentState
PlaybackController	오디오 재생 컨트롤	PlayCommanded PauseCommanded NextCommanded PreviousCommanded StopCommanded ResumeCommanded	-	-
Template	View Template 디스플레이	ElementSelected Rendered Closed	Render Close	RenderState
System	시스템 공통	SynchronizeState Bootup Exception Idle RequestCanceled RequestCompleted	RequestSynchronizeState ClearCache Close Heartbeat SubscribeNextIdle UnsubscribeIdle	SystemState
Speaker	볼륨 컨트롤	VolumeChanged MuteChanged	SetVolume AdjustVolume SetMute	VolumeState

kakaoIdocumentation

Kakao i Agent::Service Agent Interface

페이지 이동경로

Service Agent Interface

Message 구조

Message Syntax

Message 타입

Event

Event Header

Event Syntax

State

State Syntax

Instruction

Instruction Header

Instruction Syntax

Message 구성

Token

인터페이스 목록

관련 문서