AI Service Agent

카카오 i 플랫폼에서는 다양한 분야에서 AI 음성 서비스를 연동하고 활용할 수 있도록 서버, Agent, 인터페이스 등과 같은 구성 요소들을 제공하고 있습니다. 이러한 구성 요소들을 활용하면 특정 비즈니스 목적에 맞는 AI 음성 서비스를 만들 수 있습니다. 본 가이드는 카카오 i SDK를 탑재하지 않고 직접 Service Agent와 Agent Interface를 스펙에 맞춰 구현하여 카카오 i(KVS)와 연동하는 상세 개발 프로세스를 제공합니다.

그림카카오 i 시스템 아키텍처

Service Agent는 사용자 발화를 인식하고 이해할 수 있는 스마트 스피커와 같은 IoT 디바이스에 탑재되어 있으며, 카카오 i 플랫폼과 HTTP/2(Hypertext Transfer Protocol Version 2) 프로토콜을 기반으로 Connection을 맺고 상시 연결되어 있습니다. 데이터 전송에는 Agent Interface가 사용되며, 데이터 전송 프로토콜은 Message 데이터 형식을 사용합니다.

Agent Interface는 문자 그대로 Agent와 통신을 위해 제공되는 인터페이스를 의미합니다. 카카오 i 플랫폼의 인터페이스는 크게 KVS(Kakao i agent Virtual Service)를 기준으로 Service Agent와 통신하는 Service Agent Interface와 사용자 발화 데이터를 분석하여 사용자에게 적절한 답변을 돌려주기 위해 Bot과 Domain Agent(Skill)가 통신하는 Domain Agent(Skill) Interface로 구분됩니다.

카카오 i 플랫폼은 KVS를 탑재한 카카오 i 서버와 Domain Agent(Skill)가 탑재된 Skill 서버를 포함합니다. Skill(스킬)은 사용자가 발화한 정보를 분석하여 Bot에게 적절한 답변을 돌려주는 기능을 의미하며, Bot과 Skill 서버의 연동과 인터페이스에 대한 자세한 설명은 Kakao i Skill 문서를 참고하시기 바랍니다.

표카카오 i 플랫폼 구성 요소

구분	항목	설명
Agent	Service Agent	사용자와 인터랙션을 위한 Agent ex) 카카오 미니 음성 인식 스피커, HeyKakao 애플리케이션 및 내비게이션 등
Agent	Domain Agent	도메인별(날씨, 알람 등) 비즈니스 로직이 구현된 Agent - Skill 서버에 구현되어 있음
서버	카카오 i 서버	AI 음성 인식 서비스를 제공하는 서버 - Kakao i agent Virtual Service(KVS) 탑재
서버	Skill 서버	비즈니스 로직이 구현된 서버 - Service Agent에서 발생한 Event를 처리 - 각 도메인(날씨, 알림 등)별로 구분된 Domain Agent(Skill)로 구성
Interface	Service Agent Interface	Service Agent와 카카오 i 사이에 인터랙션(Interaction) 하는 인터페이스
Interface	Domain Agent Interface	해당 Bot과 Domain Agent(Skill)사이에 인터랙션을 하는 인터페이스

카카오 i 플랫폼의 AI 음성 서비스 동작 시퀀스는 다음과 같이 요약할 수 있습니다.

IoT 디바이스(Service Agent)는 사용자 발화, 디바이스의 버튼 제어 또는 다른 센싱을 통해 Event를 감지합니다.

Service Agent는 감지된 Event와 사용자 발화 데이터를 KVS에 전달합니다.

음성 발화일 경우에는 자연어 처리를 통하여 사용자 의도를 분석합니다.

해당 발화를 특정 Bot으로 분류하고, 해당 Bot은 Instruction 메시지를 통해 적절한 답변을 전송하거나 디바이스를 제어합니다.

Service Agent Interaction

Service Agent와 Domain Agent(Skill) 간의 데이터 전송에는 Message 포맷이 사용됩니다. 각 인터페이스의 Message 포맷은 동일하지만, 포함되는 값들은 인터페이스 종류에 따라 다릅니다.

그림Agent Interface 구분

표Agent Interface 종류

구분	설명
Service Agent Interface	Service Agent가 KVS와 인터랙션을 하는 인터페이스 - Kakao i Agent 참고
Domain Agent(Skill) Interface	Domain Agent(Skill)가 해당 Bot과 인터랙션을 하는 인터페이스 - Kakao i Skill 참고

안내
본 가이드에서 설명하는 Channel, Multipart, Capability 항목은 Service Agent Interaction에 한해 적용됩니다.

Channel

Agent Interface에는 Event, State, Instruction 메시지를 논리적으로 연결해 주는 Event Channel과 Down Channel이 존재합니다. Event Channel과 Down Channel은 HTTP/2를 통해 하나의 물리적 연결을 맺으며, 한 개의 통신 채널을 통해서 둘 이상의 데이터를 전송하는데 사용되는 기술인 Multiplexing(멀티플렉싱)을 이용합니다.

Event Channel

Event Channel(이벤트 채널)은 Service Agent에서 발생한 Event Request를 KVS로 전송하는 Channel입니다. Event 메시지는 Event Channel URL을 통해 전송되며, 주로 단일 Event 형태로 전송됩니다.

그림Event Channel

만약 KVS가 즉시 처리할 수 있는 Event 메시지가 요청된 경우에는 이에 대한 응답으로 하나 또는 그 이상의 Instruction 메시지가 전송될 수 있으며, 경우에 따라 메시지가 전송되지 않을 수도 있습니다. KVS에서 즉시 처리할 수 없는 Event 메시지는 Down Channel을 통해 전송되며, 이 경우에도 Instruction Message 포맷을 사용합니다.

Event Channel은 다음의 특성을 가집니다.

Event 메시지는 Queueing(큐잉) 방식을 기반으로 순차적으로 전송되며, 최대한 신속하게 큐(Queue)를 소비하여 지연을 최소화해야 합니다.

Recognizer.Speech Event 메시지와 같이 음성 바이너리 파일을 함께 전송하는 경우에는 <The First Part>에 Recognizer.Speech Event를 전송하고, <The Second Part>에는 octet-stream 형태의 바이너리 스트림을 전송합니다.

단, Recognizer.Speech Event는 다른 Event와 동시에 전달되어야 하며 동시간대에 하나만 존재해야 합니다.

Event Request Syntax

Event는 Event Message와 Event Message를 포함한 Event Request(Event Channel로 전달되는 Request)로 구분할 수 있습니다. Event Request는 Service Agent에서 발생한 Event Message를 전달하는 Request를 의미하며 State, Event Capability로 구성됩니다.

Event 영역은 현재 발생한 Event의 상세 정보를 담고, Service 영역은 현재 Service Agent에서 사용 가능한 서비스들의 Capabilities를 담습니다. State 영역은 현재 Service Agent의 런타임 상태를 담습니다.

코드예제Event Request Syntax

JSON

{
        "event": {
                "header": {
                        "type": "Recognizer.Speech",
                        "messageId": "...",
                        "dialogRequestId": "..."
                }
        },
        "service": {
                "capabilities": [
                        {
                                "interface": "ExternalSpeaker",
                                "version": "1.0",
                                ...
                        }
                ]
        },
        "state": [
                {
                        "header": {
                                "type": "Recognizer.RecognizerState"
                        },
                        "body": {
                                "wuw": "헤이 카카오"
                        }
                }
        ]
}

Down Channel

Down Channel(다운 채널)은 KVS에서 Service Agent로 Instruction 메시지를 전송할 때 사용하는 채널로서, Event Channel에서 즉시 처리할 수 없는 이벤트 처리 결과나 KVS에서 발생한 푸시 등을 전달합니다. 발화의 중간 인식 결과를 알려주는 Recognizer.InformRecognized과 녹음 중단을 지시하는 Recognizer.StopCapture 등은 Down Channel을 통해 전달되는 대표적인 Instruction 메시지입니다.

그림Down Channel

일반적으로 발화는 라이브 스트리밍으로 전달되기 때문에 KVS가 발화 완료 지점을 감지할 수 없을 경우 적당한 시점에 요청을 완료할 수 없습니다. 따라서 Down Channel은 Half-closed 상태(단방향 통신)로 운영되며, Service Agent가 Request를 보내면 Response를 닫지 않고 항상 열린 상태를 유지합니다.

예를 들어 Service Agent가 발화 Event인 Recognizer.Speech Event를 발생시킨 경우, Instance Agent는 지속적으로 음성 버퍼를 계속 생성하기 때문에 Event Channel은 약 15초간 Request 상태로 열린 상태를 유지합니다. HTTP 프로토콜 상 Service Agent만 Request를 종료할 수 있고, Request를 종료해야만 Response를 받을 수 있습니다. 이 경우, Event Channel을 통해 Event 메시지가 전송 중이더라도 상시 열려있는 Down Channel을 통해 음성 버퍼가 전송 중일 때도 추가 발화 정보를 획득할 수 있습니다.

안내
Down Channel은 영속적인 연결 상태를 유지해야 하며, 네트워크 단절 및 서버에서 종료 등과 같이 연결이 끊어지면 즉시 새로운 연결을 생성해야 합니다.

Multipart

Service Agent와 KVS가 HTTP/2를 통해 Event와 Instruction 메시지를 송수신할 때, 하나 이상의 Event 또는 Instruction 메시지(JSON 형식)들을 <The First Part>에 배치하고, 바이너리 오디오 파일이 존재할 경우에는 <The Second Part> 및 <The Third Part>에 배치하는 Multipart(멀티파트) 형식을 사용합니다.
예를 들어 Recognizer.Speech Event 메시지와 같이 음성 바이너리를 함께 전송하는 경우, <The First Part>에 Recognizer.Speech Event를 전송하고, <The Second Part>에는 octet-stream 형태의 바이너리 스트림을 전송합니다.

안내
대부분 인터페이스는 <The First Part> 로만 이루어지며, 음성 인식 또는 음성 합성 등의 오디오 바이너리를 추가로 전달하는 일부 인터페이스의 경우에는 <The Second Part> 또는 <The Third Part> 까지 활용합니다.

Capability

Capability는 Service Agent에서 구현하여 사용할 인터페이스를 전달하는 역할을 하며, 현재 Agent Interface에는 Service.Capabilities로 명시합니다. Capability에 인터페이스 목록을 보내지 않으면 KVS는 Agent Interface의 모든 인터페이스를 사용한다는 의미로 판단하므로, 사용할 인터페이스 목록을 반드시 전송해야 합니다.

안내
Capabilities에 인터페이스를 명시하지 않은 경우, 해당 인터페이스에 포함된 Instruction 메시지는 전송되지 않습니다.

표Capability

파라미터	타입	필수 여부	설명
interface	String	`필수`	Service Agent에서 사용할 인터페이스 - Vendor 인터페이스를 사용할 경우 `Vendor.{VendorName}.{Interface Name}`
version	String	`필수`	해당 인터페이스 버전 - 현재 Agent Interface는 대부분 1.0 버전을 사용 중

코드예제Capability Syntax

JSON

{
        "service": {
                "capabilities": [
                        {
                                "interface": "Recognizer",
                                "version": "1.0"
                        },
                        {
                                "interface": "Synthesizer",
                                "version": "1.0"
                        },
                        {
                                "interface": "AudioPlayer",
                                "version": "1.0"
                        },
                        {
                                "interface": "Template",
                                "version": "1.0"
                        },
                        {
                                "interface": "Vendor.{Vendor Name}.{Interface Name}",
                                "version": "1.0"
                        }
                ]
        }
}

kakaoIdocumentation

Kakao i Agent::AI Service Agent

페이지 이동경로