Kakao i Agent::Service Agent Interface

페이지 이동경로

Service Agent Interface

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

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

  • 필드별 포맷에 오류가 있는 경우에는 KVS에서 경고를 발생시킵니다.
  • Body 필드는 null을 입력할 경우 에러가 발생할 수 있으니, 빈 값인 경우에는 반드시 empty로 입력해야 합니다.

Message 구조

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

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

Message Syntax

코드예제Message Syntax

{
	"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

{
	"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

	"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

{
		"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
- 3rd Party: 각 Maker의 ID
BotId Chappie bot ID
DaCustom 주요 구분자인 /를 제외하고, Domain Agent에서 원하는대로 구성

인터페이스 목록

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

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

  • System.SubscribeNextIdle: 1.1 버전부터 지원
  • System.UnsubscribeIdle: 1.2 버전부터 지원
인터페이스 목록

관련 문서

AI Service Agent Kakao i Agent Service Agent 등록 Kakao i Agent Service Agent Interface Kakao i Agent 구현 시나리오 Kakao i Agent Troubleshooting Kakao i Agent

이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.