← Docs hub

AI-Agent ↔ DeviceAgent 인터페이스

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

연동 보강: 등록·서버 저장 완료 판정, 실패·늦은 응답·복구, 프로필 삭제·동의 철회, 시험별 기대 결과. 표의 제품 제안은 구현 전 규칙이며 기존 Bundle에 미구현 필드를 추가하라는 의미가 아니다.

서버 관심사 조회 (09-17 추가)

필수 타입·유효기간·실패·JSON·구조도 전체 명세. 원본은 서버, 기기 결과 보관은 5초 요청 기한까지다. 아래 이전 set/getVoiceProfileInterests는 더 이상 DB를 처리하지 않고 SERVER_OWNED_PERSONALIZATION을 반환한다.

DeviceAgent가 AI-Agent로 보내는 실행 요청, AI-Agent가 돌려주는 상태·관리 결과, 프로필 전달과 그 ACK를 구분한다. 등록 App용 화면 실행 Intent와는 다른 경계다.

DeviceAgent 중심 구조

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

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

getVoicePersonalization

방향: AI-Agent → DeviceAgent → IoTAgent → Backend. AI-Agent가 sendModuleCommand로 요청하고 DeviceAgent는 CALLER_IOT=2 callback에 전달한다. 등록 App은 이 요청을 보내지 않는다.

DeviceAgent는 AI-Agent 호출자와 버전·타입·기한을 검사한다. 유효 요청은 0, 거절은 -1이다. 0은 콜백 중계 수락이며 서버 조회 완료가 아니다. MQTT 연결이 없으면 별도 실패 콜백 없이 기한이 끝날 수 있다.

호출 조건·처리: 등록 화자 확정과 관심사 기능 활성 후 새 요청 한 건을 추적한다. 새 요청은 이전 pending과 임시 결과를 비운다.

오류·중복·검증: 잘못된 caller·타입·만료는 거절하며 별도 callback이 없을 수 있다. 다른 requestId/voiceId, 취소 후 응답, 중복 응답을 사용하지 않는지 확인한다.

{
  "method": "getVoicePersonalization",
  "contractVersion": "voice-personalization-v1",
  "requestId": "query-001",
  "voiceId": "voice-001",
  "issuedAtMs": 1789689600000,
  "expiresAtMs": 1789689605000
}

시각은 형식 예시다. 실행 시 현재 시각과 5초 후 시각으로 대체한다.

voicePersonalizationResult

방향: Backend → IoTAgent → DeviceAgent → AI-Agent. IoTAgent가 sendModuleCommand로 보내고 DeviceAgent는 CALLER_LLM=1 callback으로 전달한다. 등록 App에는 전달하지 않는다.

허용 코드는 WEATHER, AIR_QUALITY, HEALTH, SCHEDULE, TRAVEL, FOOD, CULTURE, SPORTS, FINANCE, TECHNOLOGY다. 최대 10개, 중복 금지이며 빈 목록은 관심사 미설정이다. putStringArrayList를 사용한다.

서버 실패는 PROFILE_NOT_FOUND 또는 BACKEND_UNAVAILABLE이며 interestCodes를 포함하지 않는다. DeviceAgent는 IoTAgent 호출자·타입·기한을 검사하고, AI-Agent는 현재 requestId·voiceId·기한을 대조한다. 종료된 요청·다른 화자·중복 응답을 사용하지 않는다. 조회 결과는 원 요청의 5초 기한까지만 임시 보관하고 로컬 DB에 저장하지 않는다.

현재 서버 통신은 VoiceProfileMqttTestBridge와 샘플 Backend 경로다. 제품 AWS 인증·권한·통신 검증과 LLM 프롬프트 자동 주입은 완료 범위가 아니다.

호출 조건·처리: 서버가 원 요청에 대응해 반환한다. AI-Agent는 유효 성공만 snapshot에 보관한다.

오류·중복·검증: 실패에는 interestCodes를 넣지 않는다. 동일 결과 재수신·기한 연장·다른 화자 응답이 무시되는지 확인한다.

{
  "method": "voicePersonalizationResult",
  "contractVersion": "voice-personalization-v1",
  "requestId": "query-001",
  "voiceId": "voice-001",
  "success": true,
  "reasonCode": "",
  "expiresAtMs": 1789689605000,
  "personalizationEnabled": true,
  "interestCodes": [
    "WEATHER",
    "HEALTH"
  ],
  "revision": 2
}

1. 방향과 함수

AI-Agent 내부 등록·인식·저장 구조와 알고리즘은 별도 설계 페이지에서 확인한다.

DeviceAgent는 등록 상태·관리 결과를 만들어내지 않는다. commitVoiceProfile 수신 후 대기 저장 결과만 DeviceAgent가 직접 생성한다. sendModuleCommand의 Int 반환값과 callback의 업무 결과를 구분한다.

2. DeviceAgent → AI-Agent 실행 요청

공통: method:String, contractVersion:String, requestId:String. issuedAtMs/expiresAtMs가 있으면 Long 타입을 보존한다. 기존 등록·관리 경로의 Service 만료 검사는 보장되지 않는다. 신규 서버 관심사 조회는 별도 버전과 기한 검사를 적용한다.

등록 제어 9종은 등록 App 송신 표에 정의한 Bundle을 그대로 중계한다. AI-Agent는 녹음·재녹음·취소·개인화 처리를 수행한다. IoTAgent의 원격 start는 먼저 등록 Activity를 열므로 바로 이 실행 요청과 같지 않다.

limit은 기본 20, 1~50이며 beforeTurnId는 기본 0, 0 이상이다. voiceId는 1~128자 영문·숫자·하이픈·밑줄이다. 관심사 변경은 모바일 → Backend HTTPS 경로이며 이 관리 요청 표에 포함하지 않는다. 구형 setVoiceProfileInterests/getVoiceProfileInterests가 AI-Agent까지 도달하면 voiceProfileInterestsResult(success=false, reasonCode=SERVER_OWNED_PERSONALIZATION)를 반환한다. 이 실패에는 voiceId와 interestCodes가 없다.

3. AI-Agent → DeviceAgent 상태 이벤트

method=voiceProfileStateChanged, contractVersion=voice-profile-v2.

DeviceAgent는 등록 App(8)과 IoTAgent(2)로 동일 상태를 복사 전달한다. success 필드를 만들어 성공/실패로 바꾸지 않는다. 상태 enum·화면 대응은 등록 App 수신 규칙을 함께 본다.

4. AI-Agent → DeviceAgent 프로필 전달

이 단계에서 AI-Agent는 이미 로컬 프로필을 생성했다. DeviceAgent는 전달 대기 저장을 수행한다. 등록 App은 임베딩을 받지 않는다.

DeviceAgent 검증 상한: voiceId 1~128자, 임베딩 1~4096개, 각 값은 유한한 수. 4096은 실제 모델 차원이 아니라 방어 상한이다. 모델별 벡터 차원은 생성 모델을 따른다. 원본 audio/pcm/wav는 금지다.

송신 코드 예제

val input = Bundle().apply {
    putString("method", "commitVoiceProfile")
    putString("contractVersion", "voice-profile-v2")
    putString("requestId", requestId)
    putString("voiceId", voiceId)
    putString("nickname", nickname)
    putString("locale", locale)
    putBoolean("personalizationEnabled", personalizationEnabled)
    putFloatArray("referenceEmbedding", referenceEmbedding)
}
DeviceControlProxy.getService()?.sendModuleCommand(input, Bundle())

변수는 실제 등록 결과다. 임베딩을 JSON 문자열·ByteArray·임의 숫자 배열로 바꾸지 않는다. 코드에서는 각 모듈의 Contract 상수를 사용한다.

5. DeviceAgent → AI-Agent 저장 결과

DeviceAgent가 검증·암호화 대기 저장 후 다음 Bundle을 CALLER_LLM=1 callback으로 반환한다.

현재 ACK에는 voiceId가 없다. AI-Agent는 동일 requestId의 pending 프로필과 연결한다. 상대 구현에서 임의로 voiceId를 필수 수신값으로 추가하지 않는다.

{
  "method": "voiceProfileCommitResult",
  "contractVersion": "voice-profile-v2",
  "requestId": "vp-example-001",
  "accepted": true,
  "cloudSynced": false,
  "reasonCode": "WAITING_CLOUD_SYNC"
}

JSON은 Bundle 값 설명용이다. 현재 제품 Cloud ACK 경로·늦은 ACK 처리 정책은 미구현이며 성공값을 강제로 돌려주면 안 된다. commit의 Int 반환은 accepted이면 0, 저장/검증 실패이면 -1이며 별도 callback도 발생할 수 있다. 호출자 거절은 callback 전에 반환될 수 있다.

6. AI-Agent → DeviceAgent 관리 결과

공통 키: method:String, contractVersion:String, requestId:String, success:Boolean, reasonCode:String. 요청 ID/버전은 대응하는 요청과 맞춘다. DeviceAgent는 결과 검증 후 IoTAgent(2)로 전달하며 등록 App으로 전달하지 않는다.

객체 목록은 putParcelableArrayList, 관심사 문자열 목록은 putStringArrayList로 전송한다. JSON 문자열을 대신 넣지 않는다. 프로필 목록 검증 상한은 profiles 64개다. 실패 시 성공 필드 일부가 없을 수 있다.

삭제 성공 후 DeviceAgent는 같은 voiceId의 대기 사본 제거를 시도한다. 제거 실패가 원래 성공 응답에 반영되지 않을 수 있으며 전체 삭제 트랜잭션을 보장하지 않는다.

8. 구현 시 반드시 구분할 것

1. 등록 제어는 DeviceAgent가 중계하지만 녹음은 AI-Agent가 소유한다.
2. 상태 이벤트, commit ACK, 관리 결과는 서로 다른 method와 성공 판정 기준을 사용한다.
3. DeviceAgent의 UID 패키지 검사는 공유 system UID 내부 앱을 완전히 분리하지 못한다.
4. 중복 start, 생성 중 취소, 지연 작업, 상태 순번, 재시도·재부팅 복구는 현재 코드의 보완 대상이다.
5. Bundle 상수와 ModuleCmdCallbackPolicy 허용 목록을 함께 적용해야 callback이 도착한다.

9. 요청별 수명과 완료 판정

이 절은 2026-09-18 작업본의 함수 흐름을 확인한 결과다. Binder 호출 반환, DeviceAgent 보관, 서버 저장 완료는 서로 다른 결과다.

프로필 전달 결과에 따른 처리

예를 들어 requestId=registration-demo-01의 저장 결과가 accepted=true, cloudSynced=false이면 모바일 App에 “서버 등록 완료”를 보여주면 안 된다. persist.sys.vp.local_ack=true는 로컬 시험을 위해 완료를 흉내 내는 설정이지 실제 AWS 저장 증거가 아니다.

책임과 재시도 범위

• AI-Agent는 상태와 프로필을 생성한다. DeviceAgent는 호출자·입력 검증 후 Bundle 복사본을 대상 callback으로 전달한다. 상태를 자체적으로 다음 단계로 바꾸지 않는다.
• retryVoiceProfileDelivery는 기존 pending 프로필을 다시 보낸다. 전체 startVoiceProfileEnrollment 재호출은 새 녹음 흐름을 시작할 수 있으므로 전달 재시도 대용으로 쓰지 않는다.
• 현재 AI-Agent의 전송 runCatching(...).isSuccess는 호출 중 예외가 없었다는 뜻이다. 업무 완료 ACK를 받은 뜻이 아니다.
• 생성 중 취소와 늦은 생성 완료의 충돌은 내부 구조의 비동기 수명에 별도로 기재했다. ACK의 요청 ID 검사만으로 이 경합까지 해결되지는 않는다.

인터페이스 시험표

아래는 구현 검토에서 도출한 시험 조건이며 실기기 통과 결과가 아니다.

구현 근거·연결 문서

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

• 등록 App ↔ DeviceAgent
• 전체 Binder 메서드별 규격
• 현재 구현 한계
• IoTAgent ↔ IoT Core