← Docs hub

등록 App ↔ DeviceAgent 인터페이스

구현 협의용 최신 문서: DeviceAgent ↔ 등록 App 구현 요청서. 아래는 이전 상세·Sample 자료다. 직접 구현 책임과 현재 취소·재시도 기준은 신규 요청서를 먼저 확인한다.

화면·복구 보강: 등록 단계별 완료 화면, Binder 단절·start 응답 유실·앱 재시작, 관련 연동 시험. 제품 제안에서는 전송 성공으로 완료 화면을 표시하지 않고, 상태 조회로 복구하며 녹음 start를 자동 반복하지 않는다.

등록 화면을 만드는 쪽과 DeviceAgent를 구현하는 쪽이 맞출 값이다. 등록 App은 제어 Bundle을 보내고 상태 Bundle을 받는다. 녹음·임베딩은 AI-Agent가 처리하며 원본 음성을 등록 App에서 보내지 않는다.

개인화 선택과 서버 관심사

등록 App의 setVoiceProfilePersonalization(enabled:Boolean)은 개인화 사용 동의 후 프로필 생성을 시작하는 명령이다. 관심사 목록을 저장하는 명령이 아니다.

샘플 Backend는 기기 목록의 personalizationEnabled로 프로필을 확인한다. 동의하지 않은 프로필에 대한 관심사 저장은 거절하며, 과거 필드가 없는 프로필을 동의한 것으로 취급하지 않는다. 제품 계정 동의 연계는 별도다. COMPLETED가 LOCAL_TEST_ACK에서 나올 수 있으므로 실제 Cloud 저장 완료와 혼동하지 않는다.

서버 관심사 필드·실패·MQTT 명세

DeviceAgent 중심 구조

SVG 구조 그림 크게 보기 · 등록 App·AI-Agent ↔ DeviceAgent 전체 인터페이스 정의

등록 App은 화면과 사용자 입력을 담당하고, 등록·인식을 수행하는 서비스는 AI-Agent다. 아래 그림은 그중 등록 과정의 중계 순서다. DeviceAgent가 직접 녹음하거나 화자를 식별하는 구조는 아니다.

1. 주고받는 것

요청의 반환값은 전달 수락 여부이고 최종 결과가 아니다. 등록 App은 output Bundle이 아니라 callback으로 화면을 갱신한다.

2. 화면 실행: DeviceAgent → 등록 App

<a id="activity-flags"></a>

화면 실행 옵션(Flag)

Flag는 Android에 화면을 어떻게 열지 지정하는 옵션이다. 등록 데이터나 녹음 제어 명령이 아니다. Task는 뒤로가기로 이동하는 화면들의 묶음이다.

두 옵션은 비트 OR로 함께 지정한다. 표의 가운데 점은 두 옵션을 나열한 표기다.

intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)

예를 들어 화면 순서가 등록 화면 → 다른 화면이면 등록 화면 위의 다른 화면을 정리한다. 등록 화면 자체의 재사용 여부는 Manifest의 launchMode와 다른 Flag에도 영향을 받는다. 기본 standard에서는 CLEAR_TOP으로 등록 Activity까지 종료하고 다시 만들 수 있으며, 재사용되는 경우 새 요청은 onNewIntent()로 전달된다.

이 옵션만으로 녹음 취소, 등록 상태 초기화, 중복 요청 방지가 처리되지는 않는다. 이 처리는 별도의 등록·취소 메서드와 requestId 확인으로 관리해야 한다. Activity 내부 화면 전환까지 자동으로 초기화하는 옵션도 아니다.

참고: Android 공식 문서: Task와 화면 스택.

원격 시작은 화면만 연다. 사용자가 시작 버튼을 눌러야 등록 App이 start Bundle을 보낸다. 원격 취소도 현재 Activity를 거친다. 다른 활성 요청이 있거나 Activity 실행에 실패한 경우의 원격 실패 응답은 보완 대상이다.

<a id="locale-contract"></a>

locale 언어값 규약

다음은 한·영 연동에서 송신 측이 사용할 값이다. 현재 코드의 허용 검사와는 구분한다.

현재 구현의 기본값·검증 차이

따라서 송신 측은 위의 정확한 한·영 값을 보내야 한다. 수신 측에서도 이 두 값만 허용하도록 강제하려면 별도 코드 변경이 필요하다. 이번 문서 수정으로 검증 동작이 바뀌지는 않는다.

3. Proxy 연결과 공통 Bundle

연결: DeviceControlProxy.connect(context, callback, true, callbackClassName). 현재 callbackClassName은 등록 Activity의 전체 클래스명이다. 연결되면 getVoiceProfileEnrollmentState를 요청한다. 수신은 IDeviceControlProxyCallback.onModuleCallback(outdata)다.

등록 App의 모든 제어 요청은 다음 네 필드를 포함한다.

등록 App 클라이언트는 현재 expiresAtMs를 넣지 않는다. 원격 MQTT의 만료 검사와 UI 내부 등록 제어의 공통 필드를 혼동하지 않는다.

예시: 연결 후 현재 상태 조회

아래는 실제 클라이언트의 연결·송신 흐름을 간추린 예시다. context는 앱 Context, requestId는 실행 Intent에서 받은 값이다. 문자열 키는 읽기 쉽게 표시했으며 실제 구현에서는 VoiceProfileContract 상수를 사용한다.

val callback = object : DeviceControlProxy.IDeviceControlProxyCallback {
    override fun onServiceConnected() {
        val input = Bundle().apply {
            putString("method", "getVoiceProfileEnrollmentState")
            putString("contractVersion", "voice-profile-v2")
            putString("requestId", requestId)
            putLong("issuedAtMs", System.currentTimeMillis())
        }
        val service = DeviceControlProxy.getService() ?: return
        try {
            val result = service.sendModuleCommand(input, Bundle())
            if (result < 0) return // 전송 거절. 상태 수신으로 처리하지 않는다.
        } catch (error: android.os.RemoteException) {
            return // 연결 오류. 화면에서 재연결 안내가 필요하다.
        }
    }

    override fun onServiceDisconnected() {
        // 연결 해제 상태를 UI에 전달한다.
    }

    override fun onModuleCallback(outdata: Bundle?) {
        if (outdata?.getString("method") != "voiceProfileStateChanged") return
        if (outdata.getString("requestId") != requestId) return
        val state = outdata.getString("state") ?: return
        // state를 UI에 전달한다. 화면 갱신은 메인 스레드에서 처리한다.
    }
}
if (DeviceControlProxy.connected()) {
    DeviceControlProxy.setDeviceControlProxyCallback(callback)
    callback.onServiceConnected()
} else {
    DeviceControlProxy.connect(
        context.applicationContext, callback, true,
        "com.sk.airbot.voiceprofileregistration.VoiceProfileRegistrationActivity"
    )
}

흐름은 Proxy 연결 → 조회 Bundle 송신 → DeviceAgent가 AI-Agent로 중계 → 상태 콜백 수신 → UI 반영이다. sendModuleCommand()의 0 이상 반환값은 전송 수락이지 등록 완료가 아니다. 실제 상태는 콜백의 state로 확인한다. 예시는 흐름 설명용이며 화면의 오류 표시와 연결 수명 관리는 생략했다. 기존 클라이언트는 수신 값을 Listener로 전달하며, 위 예시는 현재 작업의 requestId를 확인할 위치도 함께 보여준다.

<a id="ui-commands"></a>

4. 버튼별 요청과 기대 결과

추가 입력은 3절 공통 Bundle에 붙인다. 모든 키는 실제 문자열이며 구현에서는 각 모듈의 Contract 상수를 사용한다.

nickname은 trim 후 1~40자이며 경로 구분자·제어 문자 금지다. 발음 보조 필드를 입력받거나 전달하지 않는다.

4.1 즉시 반환값: 전송 단계

호출 형식은 sendModuleCommand(input: Bundle, output: Bundle): Int다. 등록 제어는 두 번째 Bundle에서 결과를 읽는 방식이 아니라 별도 상태 콜백을 받는다.

현재 DeviceAgentVoiceProfileClient.send()는 Int를 그대로 노출하지 않고 0 이상이면 true, 음수·연결 실패·통신 예외이면 false로 변환한다. 따라서 UI에서 -1/-2를 구별하려면 클라이언트 반환형도 확장해야 한다. 문서에 적힌 오류 코드만으로 현재 UI가 세부 오류를 구분하는 것은 아니다.

4.2 비동기 결과: 버튼별 상태와 파라미터

모든 상태 결과는 onModuleCallback(Bundle)의 method="voiceProfileStateChanged"로 받는다. 요청 메서드마다 별도의 ...Response가 오는 구조가 아니다. 공통 필드의 타입·의미는 상태 콜백 필드를 따른다.

COMPLETED에 필요한 voiceId는 Bundle에는 있지만 현재 등록 App의 상태 모델에는 복사되지 않는다. DELIVERY_FAILED는 저장·동기화 실패 경로이며 단순히 음성 녹음 실패를 뜻하지 않는다. 무응답 경로에는 현재 공통 타임아웃 응답 규약이 없으므로, 전송 true만으로 화면을 완료 처리해서는 안 된다.

실제 송신 예제

val input = Bundle().apply {
    putString("method", "startVoiceProfileEnrollment")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", requestId) // Intent에서 받은 값
    putLong("issuedAtMs", System.currentTimeMillis())
    putString("nickname", "Niky")
    putString("locale", "ko-KR")
    putString("userId", "") // 기존 클라이언트 호환 필드
}
val transportResult = DeviceControlProxy.getService()
    ?.sendModuleCommand(input, Bundle())
// 수락 여부만 확인. 녹음/완료 화면은 상태 callback으로 전환한다.

<a id="state-fields"></a>

5. 상태 수신: DeviceAgent → 등록 App

AI-Agent가 만든 상태를 DeviceAgent가 복사해 등록 App(CALLER_VOICE_PROFILE_REGISTRATION=8)과 IoTAgent(CALLER_IOT=2)에 전달한다.

예시: 1번째 녹음 시작을 두 앱에 알림

AI-Agent가 requestId="vp-example-001" 작업의 녹음을 시작했다고 가정한다. 아래 값은 설명용 예시이며 실행 로그가 아니다.

AI-Agent: 상태 Bundle 생성
  method = "voiceProfileStateChanged"
  contractVersion = "voice-profile-v2"
  requestId = "vp-example-001"
  stateSequence = 2L
  state = "RECORDING_SET"
  setIndex = 1, setCount = 5, progress = 0
  reasonCode = "", terminal = false, nickname = "Niky"
          |
          v
DeviceAgent: 값은 바꾸지 않고 대상별 Bundle로 복사하여 콜백 전달
          |
          +--> 등록 App [대상 번호 8]
          |      onModuleCallback(Bundle)
          |      같은 requestId 확인 → 1/5 녹음 중 화면 표시
          |
          +--> IoTAgent [대상 번호 2]
                 onModuleCallback(Bundle)
                 원격 요청 측에 전달할 상태 이벤트로 처리

CALLER_VOICE_PROFILE_REGISTRATION=8과 CALLER_IOT=2는 DeviceAgent 내부의 콜백 수신 대상 번호다. 녹음 상태 enum이나 requestId가 아니며 위 상태 Bundle에 추가로 넣는 필드도 아니다. 두 앱은 같은 requestId·stateSequence·state를 받지만 사용하는 목적이 다르다. 등록 App은 기기 화면을 갱신하고, IoTAgent는 원격 상태 전달을 담당한다.

두 수신처의 처리 완료나 동시 수신까지 보장하는 ACK는 아니다. 현재 IoTAgent의 외부 결과 전달은 로컬 시험 Bridge 경로이며, 이 콜백 수신만으로 제품 AWS IoT Core 발행이나 모바일 수신이 완료됐다고 판단하면 안 된다. 상태 Bundle에 원본 음성이나 임베딩은 포함하지 않는다.

{
  "method": "voiceProfileStateChanged",
  "contractVersion": "voice-profile-v2",
  "requestId": "vp-example-001",
  "stateSequence": 2,
  "state": "RECORDING_SET",
  "setIndex": 1,
  "setCount": 5,
  "progress": 20,
  "reasonCode": "",
  "terminal": false,
  "nickname": "Niky"
}

위 JSON은 Bundle 값 설명용이며 Binder에 JSON 문자열을 넣는 예제가 아니다. 상태 Bundle에는 success가 없다.

현재 등록 App의 VoiceProfileStateUpdate 변환은 상태·순번·세트·진행률·사유·terminal을 읽는다. nickname/voiceId는 Bundle에 있어도 이 UI 모델에는 옮기지 않는다. 등록 App에서 완료 ID를 직접 사용할 기능을 추가한다면 수신 모델도 확장해야 한다.

<a id="ui-state"></a>

6. 화면 판정과 예외

DeviceAgent는 등록 제어를 CALLER_LLM=1로 전달하고 ModuleCmdCallbackPolicy의 상수 허용 목록을 맞춰야 한다. 현재 클라이언트는 sendModuleCommand 반환값 >=0을 수락으로 취급한다. -1/-2/-3은 분기별 오류이며 최종 등록 결과 enum이 아니다.

7. 클라이언트가 실제로 수신·적용하는 순서

DeviceAgentVoiceProfileClient와 VoiceProfileUiState의 현재 처리다. 표의 기본값은 누락을 허용하자는 권장 사양이 아니라 수신 구현의 동작이다. 송신자는 앞의 필드 명세대로 값을 모두 전달해야 한다.

클라이언트 자체는 callback의 contractVersion을 별도로 검증하지 않는다. DeviceAgent 검증을 통과한 메시지를 받는 구조다. 또한 callback의 nickname·voiceId는 현재 UI 상태 객체로 복사하지 않는다. 화면에서 이 값의 변경까지 반영된다고 가정하면 안 된다.

예: 같은 요청에서 순번 12의 VALIDATING_SET을 먼저 적용한 뒤 순번 11의 RECORDING_SET이 도착해도 녹음 화면으로 돌아가지 않는다. 반대로 서비스 재시작으로 순번이 초기화되면 기존 UI가 새 이벤트를 거부할 수 있어, 재연결만으로 세션 복구가 완성되지는 않는다.

8. 연결·나가기·타임아웃

오류 표시와 확인할 화면

오류 문구는 reasonCode, 버튼 행동은 stage에 따라 결정된다. 동일 오류 문구가 나온다고 같은 재시도 method를 보내는 것은 아니다.

화면 연동 시험표

아래는 실기기에서 추가 확인할 조건이며 완료된 시험 결과는 아니다.

구현 근거·검증 범위

2026-09-18 SoC 작업본의 DeviceAgentVoiceProfileClient.kt, DeviceAgent.java, ModuleCmdCallbackPolicy, AI-Agent VoiceProfileIpcContract.kt를 대조했다. 문서·정적 검토이며 새 실기기 시험 결과는 아니다.

• AI-Agent ↔ DeviceAgent: 프로필·상태·관리 결과
• 전체 Binder 메서드 상세와 한계
• IoTAgent ↔ IoT Core 토픽