← Docs hub

DeviceAgent ↔ 등록 App 구현 요청서

2026-09-29 구현 범위: 화자 등록·상태 전달·목록·삭제·서버 관심사 조회가 대상이다. 대화내역 저장·조회·삭제·용량 조회·실시간 저장 알림은 다음 차수로 제외했으며 현재 공개 인터페이스에 없다. 발음 보조 값도 외부에서 받거나 보내지 않고 AI-Agent 내부에서만 처리한다.

대상: SoC DeviceAgent 담당과 기기 등록 App 담당. 여기서 등록 App은 핸드폰 APP이나 Launcher가 아니라 기기의 화자인식 등록 화면이다. 외부에서 요청이 기기로 오는 방법은 SoC·APP·Backend 담당 간 설계 범위다.

담당별 범위 · AI-Agent 경계

상세 연동 보강: 8~13절에 Intent·제어 필드의 필수 여부, 메서드별 실행 가능 상태, 전체 callback 예시, 오류 코드와 인수 시험을 추가했다. 현재 코드가 자동 처리하지 않는 경우도 구분한다.

1. 구현할 연결

DeviceAgent는 UI 요청을 AI-Agent에 중계한다. 등록 App은 직접 녹음하거나 임베딩 파일을 AI-Agent에 보내지 않는다. 마이크·음질 검사·등록 상태의 주체는 AI-Agent다.

2. DeviceAgent가 열 화면

NEW_TASK는 서비스에서 Activity를 열 때 적합한 Task를 찾거나 새로 만든다. CLEAR_TOP은 대상 Activity 위의 화면을 정리한다. 이 Flag가 녹음이나 등록을 취소하는 것은 아니다. 기존 Activity 재사용 시에는 onNewIntent로 요청을 받으며, 실제 재사용 여부는 launchMode 등에도 영향을 받는다.

locale은 등록 메타데이터이며 기기의 언어/STT/TTS 설정 변경 명령이 아니다. 송신 규약은 ko-KR/en-US이지만 현재 수신 검증은 비어 있지 않은 길이 32자 이하 문자열 검사이며 두 값만 강제하는 구현은 아니다.

원격 시작 경로는 화면을 여는 단계다. 사용자가 시작을 누르면 아래 start Bundle을 보낸다. 화면이 열렸다고 녹음 시작·등록 완료로 보고하지 않는다. 현재 원격 취소는 Activity에 전달되므로 화면 실행 실패나 다른 활성 요청 충돌의 외부 결과 처리는 SoC 담당이 보완할 항목이다.

3. Proxy와 callback 등록

SoC는 등록 App의 callback 이름·대상 번호와 허용 호출자 패키지를 연결한다. 등록 App 담당은 Proxy 연결·해제와 화면 생명주기를 관리한다. 기기 설치 시 플랫폼 서명과 권한을 맞춰야 하며 임의 debug 서명으로 시스템 앱을 교체하지 않는다.

4. 공통 Bundle과 버튼 요청

모든 제어 요청은 아래 필드를 포함한다. output Bundle에서 최종 결과를 읽지 않는다.

현재 등록 App 클라이언트는 expiresAtMs를 보내지 않는다. 외부 통신의 만료 필드를 이 UI 요청에 임의로 필수화하지 않는다.

nickname은 trim 후 1~40자이며 경로 구분자·제어문자를 허용하지 않는다. userId는 계정 관리 신규 요구가 아니라 현재 클라이언트 호환 필드다. DeviceAgent에서 nickname을 임의 사용자 계정 ID로 변환하지 않는다.

개인화 버튼은 enabled를 보내며 초기 Intent의 personalizationEnabled와 키가 다르다. 관심사 항목 등록·변경은 핸드폰 APP/Backend 기능이며 이 화면의 구현 범위가 아니다.

요청 예시

val input = Bundle().apply {
    putString("method", "retryVoiceProfileSet")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", requestId)
    putLong("issuedAtMs", System.currentTimeMillis())
    putInt("setIndex", currentSetIndex)
}
val result = DeviceControlProxy.getService()?.sendModuleCommand(input, Bundle())
// result가 0이어도 재녹음 화면을 확정하지 않고 상태 callback을 확인한다.

이 코드는 필드 형식 예시다. 실제 구현에서는 Contract 상수와 연결 오류 처리를 사용한다.

5. 즉시 반환과 실제 상태

등록 클라이언트의 send는 현재 0 이상이면 true다. 이는 전송 수락 Boolean이며 업무 결과가 아니다. DeviceAgent의 화면 실행 실패 -3은 원격 UI 시작 경로의 반환으로, 위 UI 제어 결과와 구분한다.

상태 callback 필드

등록 클라이언트는 현재 nickname/voiceId를 화면 상태 객체에 옮기지 않는다. DeviceAgent는 원본 Bundle의 필드를 임의로 제거하지 않는다. 화면 담당은 현재 requestId, 버전과 상태값을 확인하고 이전/중복 순번이 화면을 되돌리지 않도록 처리한다.

VALIDATING_SET은 현재 전달 enum이 아니다. 화면 문구와 실제 state를 혼동하여 새 enum을 추가하지 않는다. 오류 상태라고 모두 terminal=true인 것은 아니다.

6. 취소·재연결·완료 규칙

상태 순번은 현재 세션 기준이며 재부팅 복구까지 보장하지 않는다. 재시작 후 진행 중 등록의 복원·정리 정책은 별도 통합 확인 대상이다.

7. 양쪽 구현 요청과 인수 시험

필수 시나리오: 시작 전 닫기, 녹음 중 나가기 취소/확정, 녹음 실패 후 다시 녹음, 생성 실패, 전달 실패, 종료 callback 유실, 완료 후 닫기. 외부 MQTT 없이 시험 호출자로 화면 실행과 callback 왕복을 먼저 확인할 수 있다.

8. 필수 필드와 누락값 처리

송신 규칙은 연동 구현에서 지켜야 할 입력이고, 현재 처리는 코드가 실제 검사하거나 사용하는 방식이다. 기본값이 있다고 잘못된 요청이 항상 정상 처리되는 것은 아니다.

화면 Intent

등록 App 자체의 직접 실행 경로에는 일부 기본값이 있지만 정상 연동에서 누락 입력을 대신 채우는 규약으로 사용하지 않는다. 이 Intent에는 PCM/WAV/임베딩을 넣지 않는다.

제어 Bundle 추가 필드

공통 method/contractVersion/requestId/issuedAtMs는 4절을 따른다.

reason의 현재 UI 송신값은 USER_EXIT_CONFIRMED, MOBILE_CANCELLED, UI_STATE_TIMEOUT이다. 요청 사유와 반환 reasonCode는 같은 필드도 같은 값도 아니다.

DeviceAgent의 등록 App 제어 검사는 공통 envelope와 호출자 중심이다. 모든 UI payload 필드를 DeviceAgent에서 검사해 오류 callback으로 돌려주는 구조가 아니다. 잘못된 입력은 전달 반환 0 이후에도 AI-Agent에서 무시될 수 있다.

9. 메서드별 실행 조건과 상태 결과

나가기 확인창에서 계속하기를 누르면 현재 RECORDING_SET에 retryVoiceProfileSet을 보낸다. 이는 중단 지점의 PCM 이어붙이기가 아니라 현재 세트를 다시 녹음하는 동작이다.

세트 녹음 성공 뒤에는 700ms 표시 지연 후 다음 세트 또는 PERSONALIZATION_SETTINGS로 이동한다. 이 지연 중 취소하면 다음 단계로 넘어가지 않도록 AI-Agent가 작업을 무효화한다.

10. 상태 callback과 UI 수신 순서

완전한 녹음 상태 예시

// AI-Agent가 생성한 Bundle을 DeviceAgent가 등록 App callback(8)에 복사 전달한다.
val recording = Bundle().apply {
    putString("method", "voiceProfileStateChanged")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", "enrollment-example-001")
    putLong("stateSequence", 1L)
    putString("state", "RECORDING_SET")
    putInt("setIndex", 1)
    putInt("setCount", 5)
    putInt("progress", 0)
    putString("reasonCode", "")
    putBoolean("terminal", false)
    putString("nickname", "사용자A")
    // voiceId는 생성 전이므로 생략한다.
}

DeviceAgent는 이 상태를 새로 만들어 보내는 것이 아니라 AI-Agent로부터 받은 값을 보존한다. 예시는 필드 타입 확인용이다.

실제 수신 필터

1. Client에서 method=voiceProfileStateChanged, 버전=voice-profile-v2 확인.
2. requestId 존재와 알려진 enum 확인. 모르는 enum이면 무시.
3. UI Reducer에서 현재 화면의 requestId와 일치하는지 확인.
4. stateSequence가 마지막 수신보다 클 때만 적용. 같거나 작으면 무시.
5. 현재 화면이 이미 terminal이면 이후 상태 무시.
6. 메인 스레드에서 진행률·버튼·오류를 갱신하고 취소 대기 중 terminal이면 화면 종료.

callback의 nickname/voiceId는 현재 Client의 UI 상태 객체로 옮기지 않는다. 현재 화면의 이름은 실행 Intent를 사용한다. 따라서 완료 callback을 임의로 닉네임 변경 통로로 사용하지 않는다.

시작→녹음 상태 왕복

DeviceAgent: requestId를 포함한 Intent로 화면 실행
등록 App: Proxy 연결 → getVoiceProfileEnrollmentState
DeviceAgent: 같은 Bundle을 AI-Agent callback(1)에 전달
AI-Agent: WAITING_START 상태 송신
DeviceAgent: 상태를 등록 App callback(8)에 전달
사용자: 시작 버튼
등록 App: startVoiceProfileEnrollment
AI-Agent: RECORDING_SET → SET_ACCEPTED 또는 SET_REJECTED
DeviceAgent: 순번과 타입을 보존하여 등록 App에 전달

나가기 확정→종료 왕복

등록 App: 녹음 중이면 pause 요청 → 나가기 확인창
사용자: 나가기 확정
등록 App: 취소 대기 표식을 먼저 설정 → cancel 요청 전송
AI-Agent: 현재 녹음/지연 작업 정리 → CANCELLED, terminal=true
DeviceAgent: 동일 requestId의 상태 callback 전달
등록 App: 상태 필터 통과 → finishAndRemoveTask()

전송 후 대기 표식을 만들면 빠른 callback을 놓칠 수 있으므로 순서가 중요하다. 취소 대기 10초는 elapsedRealtime() 기준이며 issuedAtMs의 벽시계와 혼용하지 않는다.

11. 오류 코드와 UI 처리

현재 UI는 일부 코드만 전용 문구로 매핑하고 나머지는 공통 오류 안내를 쓴다. 코드마다 별도 화면이 구현되어 있다는 뜻이 아니다. MULTI_SPEAKER는 UI 문구 매핑에 있으나 현재 검사기의 실제 다중 화자 검출을 보장하는 코드로 해석하지 않는다.

PROFILE_FAILED라도 terminal=true인 시작 거절과 terminal=false인 생성 실패를 구분한다. 현재 UI는 stage 중심으로 재시도 버튼을 선택하는 부분이 있어, 모든 실패에서 버튼이 실제 실행으로 이어지는지 인수 시험이 필요하다.

12. 시간·중복·재연결 제한

새 요청 ID는 별도 등록이다. 같은 requestId의 start는 세션이 보존되는 동안만 중복 시작을 막는다. close로 세션이 제거된 후까지 영구 중복 방지를 보장하지 않는다.

UI는 마지막 stateSequence를 기억한다. AI-Agent가 재시작되어 순번 0으로 돌아오면 이전 UI가 새 상태를 무시할 수 있다. 세션 복구·순번 재설정 정책은 현재 완성된 기능으로 간주하지 않는다. 단순 재연결에서 상태 조회를 한다는 사실과 재부팅 복구 보장은 다르다.

13. 인터페이스 인수 시험표

위 표는 합격 판정 기준과 확인할 제한 사항이다. 문서 검토·샘플 실행만으로 실기기 시험 통과를 뜻하지 않는다.

14. REQUEST / RESPONSE 값 예시

예시는 실제 Binder로 주고받는 Android Bundle을 Kotlin으로 구성한 코드다. 각 코드 블록은 독립된 예시이며 import android.os.Bundle을 사용한다. request는 요청 Bundle, callback은 상대편에서 구성해 돌려주는 Bundle이다. JSON 직렬화나 request/callback이라는 포장 필드는 전송하지 않는다. 필드명을 확인하기 쉽게 문자열로 표시했으며 구현에서는 기존 Contract 상수를 사용한다. 식별자·닉네임·시각은 설명용 값이다.

sendModuleCommand()의 동기 반환 0은 해당 호출의 수락/중계를 뜻한다. 아래 callback과 별개이며 최종 성공을 뜻하지 않는다. callback이 동기 반환보다 먼저 도착할 수도 있다. 허용되지 않은 caller나 잘못된 필드는 중계 단계에서 거절될 수 있으므로, 모든 요청에 반드시 callback이 온다고 가정하지 않는다.

이 절의 요청은 등록 App → DeviceAgent → AI-Agent, callback은 AI-Agent → DeviceAgent → 등록 App 순서다. 모든 등록 제어 결과의 method는 voiceProfileStateChanged이며, 버튼별 startResponse 같은 method를 새로 만들지 않는다. 아래 상태 순번은 예시이고 녹음 진행 callback 수에 따라 실제 값은 달라진다.

14.1 화면 연결 직후 상태 조회

// REQUEST: 요청 송신 측에서 구성
val request = Bundle().apply {
    putString("method", "getVoiceProfileEnrollmentState")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", "enroll-001")
    putLong("issuedAtMs", 1790000000000L)
}

// RESPONSE: 상대편에서 구성하여 별도 callback으로 전달
val callback = Bundle().apply {
    putString("method", "voiceProfileStateChanged")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", "enroll-001")
    putLong("stateSequence", 0L)
    putString("state", "WAITING_START")
    putInt("setIndex", 1)
    putInt("setCount", 5)
    putInt("progress", 0)
    putString("reasonCode", "")
    putBoolean("terminal", false)
    putString("nickname", "")
}

해당 ID의 세션이 아직 없을 때의 응답이다. 이미 진행 중이면 현재 상태를 반환하며 녹음을 새로 시작하지 않는다.

14.2 등록 시작

// REQUEST: 요청 송신 측에서 구성
val request = Bundle().apply {
    putString("method", "startVoiceProfileEnrollment")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", "enroll-001")
    putLong("issuedAtMs", 1790000001000L)
    putString("nickname", "Niky")
    putString("locale", "ko-KR")
    putString("userId", "sample-user-001")
}

// RESPONSE: 상대편에서 구성하여 별도 callback으로 전달
val callback = Bundle().apply {
    putString("method", "voiceProfileStateChanged")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", "enroll-001")
    putLong("stateSequence", 1L)
    putString("state", "RECORDING_SET")
    putInt("setIndex", 1)
    putInt("setCount", 5)
    putInt("progress", 0)
    putString("reasonCode", "")
    putBoolean("terminal", false)
    putString("nickname", "Niky")
}

RECORDING_SET 수신이 녹음 상태 진입 신호다. 요청 전송만으로 등록 성공 화면을 띄우지 않는다. 같은 requestId의 중복 시작은 현재 상태를 반환한다. userId는 현재 등록 App이 함께 보내는 기존 필드이므로 예시에 포함했지만, AI-Agent가 프로필 식별 키로 사용하지 않는다. 화자 식별 키는 생성된 voiceId다.

14.3 녹음 자원 사용 중 오류와 다시 녹음

다음은 시작 시 다른 작업이 녹음 자원을 사용 중인 경우다. 앞의 정상 시작과는 별도 실패 사례다.

// REQUEST: 요청 송신 측에서 구성
val request = Bundle().apply {
    putString("method", "startVoiceProfileEnrollment")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", "enroll-busy-001")
    putLong("issuedAtMs", 1790000001000L)
    putString("nickname", "Niky")
    putString("locale", "ko-KR")
    putString("userId", "sample-user-001")
}

// RESPONSE: 상대편에서 구성하여 별도 callback으로 전달
val callback = Bundle().apply {
    putString("method", "voiceProfileStateChanged")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", "enroll-busy-001")
    putLong("stateSequence", 1L)
    putString("state", "SET_REJECTED")
    putInt("setIndex", 1)
    putInt("setCount", 5)
    putInt("progress", 0)
    putString("reasonCode", "AUDIO_BUSY")
    putBoolean("terminal", false)
    putString("nickname", "Niky")
}

// REQUEST: 요청 송신 측에서 구성
val request = Bundle().apply {
    putString("method", "retryVoiceProfileSet")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", "enroll-busy-001")
    putLong("issuedAtMs", 1790000008000L)
    putInt("setIndex", 1)
}

// RESPONSE: 상대편에서 구성하여 별도 callback으로 전달
val callback = Bundle().apply {
    putString("method", "voiceProfileStateChanged")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", "enroll-busy-001")
    putLong("stateSequence", 2L)
    putString("state", "RECORDING_SET")
    putInt("setIndex", 1)
    putInt("setCount", 5)
    putInt("progress", 0)
    putString("reasonCode", "")
    putBoolean("terminal", false)
    putString("nickname", "Niky")
}

재시도 응답은 녹음 자원을 확보한 경우다. 계속 사용 중이면 다시 거절될 수 있다. Service는 전달된 setIndex로 임의 세트를 선택하지 않고 현재 세트를 다시 녹음한다.

14.4 나가기 확정: 취소 결과를 받은 뒤 종료

// REQUEST: 요청 송신 측에서 구성
val request = Bundle().apply {
    putString("method", "cancelVoiceProfileEnrollment")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", "enroll-001")
    putLong("issuedAtMs", 1790000010000L)
    putString("reason", "USER_EXIT_CONFIRMED")
}

// RESPONSE: 상대편에서 구성하여 별도 callback으로 전달
val callback = Bundle().apply {
    putString("method", "voiceProfileStateChanged")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", "enroll-001")
    putLong("stateSequence", 8L)
    putString("state", "CANCELLED")
    putInt("setIndex", 1)
    putInt("setCount", 5)
    putInt("progress", 0)
    putString("reasonCode", "USER_CANCELLED")
    putBoolean("terminal", true)
    putString("nickname", "Niky")
}

진행 중인 동일 세션 취소 사례다. UI는 현재 requestId 및 증가한 stateSequence를 확인하고 종료한다. 이미 종료된 세션은 기존 종료 상태를 반환할 수 있다. reason은 요청 사유이고 callback의 reasonCode와 값이 같을 필요는 없다.

14.5 개인화 선택과 프로필 생성

5개 세트가 통과하여 PERSONALIZATION_SETTINGS일 때 보내는 요청이다. 관심사 코드 저장 요청이 아니라 개인화 사용 여부 선택이다.

// REQUEST: 요청 송신 측에서 구성
val request = Bundle().apply {
    putString("method", "setVoiceProfilePersonalization")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", "enroll-001")
    putLong("issuedAtMs", 1790000040000L)
    putBoolean("enabled", true)
}

// RESPONSE: 상대편에서 구성하여 별도 callback으로 전달
val callback = Bundle().apply {
    putString("method", "voiceProfileStateChanged")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", "enroll-001")
    putLong("stateSequence", 30L)
    putString("state", "CREATING_LOCAL_PROFILE")
    putInt("setIndex", 5)
    putInt("setCount", 5)
    putInt("progress", 100)
    putString("reasonCode", "")
    putBoolean("terminal", false)
    putString("nickname", "Niky")
}

요청을 처리하면 프로필 생성을 시작한다. 이후 PENDING_DEVICE_DELIVERY를 거치며, 전달 완료 조건을 충족했을 때 수신하는 최종 상태의 예시는 다음과 같다. 생성·전달 실패는 각각 PROFILE_FAILED·DELIVERY_FAILED이며 완료로 취급하지 않는다.

// 비동기 상태 callback: AI-Agent에서 구성
val callback = Bundle().apply {
    putString("method", "voiceProfileStateChanged")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", "enroll-001")
    putLong("stateSequence", 32L)
    putString("state", "COMPLETED")
    putInt("setIndex", 5)
    putInt("setCount", 5)
    putInt("progress", 100)
    putString("reasonCode", "")
    putBoolean("terminal", true)
    putString("nickname", "Niky")
    putString("voiceId", "vp_demo_01")
}

COMPLETED는 전달 완료 조건을 충족한 뒤에만 보낸다. 로컬 시험 ACK로 완료된 경우에는 실제 서버 저장 증거가 아니다.

14.6 일시 정지와 닫기는 별도 성공 응답이 없음

두 요청에도 contractVersion=voice-profile-v2를 넣는다. 일시 정지 뒤 계속하기는 retryVoiceProfileSet으로 현재 세트를 처음부터 녹음한다. 진행 중 세션에 close하면 취소가 먼저 수행될 수 있으므로, 정상 완료 뒤 닫기와 중간 취소를 구분한다.

Binder에서 주고받는 위치

DeviceAgent는 요청/결과 method에 맞는 수신자에게 전달한다. 등록 상태는 등록 App과 IoTAgent로 전달하지만, 개인화 조회 결과를 등록 App에 전달하지 않는다. 표의 onModuleCallbackLoop는 DeviceAgent 내부 함수이며 등록 App에서 호출하는 API가 아니다.

등록 App의 실제 전송 형태는 다음과 같다. request에는 아래 각 사례의 요청 Bundle을 넣는다.

// 등록 App: DeviceControlProxy가 연결된 상태에서 실행
val service = DeviceControlProxy.getService()
if (service != null) {
    val output = Bundle()
    val returnCode = service.sendModuleCommand(request, output)
    val acceptedForRouting = returnCode >= 0
    // acceptedForRouting은 최종 등록 성공이 아니다.
    // 최종 상태는 아래의 별도 onModuleCallback으로 받는다.
}

다음은 등록 App callback에서 실제 타입으로 필드를 읽는 부분이다. 기존 callback 구현 안에서 사용하며, 상태 화면 적용 시 현재 requestId와 stateSequence를 대조한다.

override fun onModuleCallback(outdata: Bundle?) {
    val state = outdata ?: return
    if (state.getString("method") != "voiceProfileStateChanged") return
    if (state.getString("contractVersion") != "voice-profile-v2") return
    val requestId = state.getString("requestId") ?: return
    val stage = state.getString("state") ?: return
    val sequence = state.getLong("stateSequence", -1L)
    val setIndex = state.getInt("setIndex", 1)
    val progress = state.getInt("progress", 0)
    val terminal = state.getBoolean("terminal", false)
    val reasonCode = state.getString("reasonCode").orEmpty()
    // 추출 이후 기존 상태 reducer에 전달한다.
}

위 수신 코드는 등록 상태용이다. 개인화 결과는 AI-Agent에서 getStringArrayList("interestCodes"), getLong("revision"), getBoolean("success") 등 해당 결과 계약의 필드로 읽는다. 생성 예시의 callback을 요청자가 자기 자신에게 보내는 구조가 아니다.

Connections

• 소스 위치: SoC DeviceAgent.java, ModuleCmdCallbackPolicy.java; 등록 App DeviceAgentVoiceProfileClient.kt, VoiceProfileRegistrationActivity.kt, VoiceProfileExitWait.kt.
• 기존 등록 화면 상세 자료: Sample 설명과 과거 보완 항목 포함. 겹치는 현재 구현 기준은 본 페이지를 먼저 본다.
• 전체 시나리오 참고: APP/서버 흐름은 참고이며 이 구현 요청서의 책임 범위를 넓히지 않는다.