← Docs hub

DeviceAgent / SoC Domain Map

이 문서는 Cloud A2A와 온디바이스 브릿지가 실제 기기 실행으로 내려갈 때, DeviceAgent 내부의 어떤 도메인이 실행 권한을 가져야 하는지 정리한다.

핵심 결론은 단순하다.

• Cloud는 사용자 발화를 보고 계획과 순서를 만든다.
• 온디바이스 브릿지는 Cloud plan을 DeviceAgent가 소비할 수 있는 task/workflow 요청으로 바꾼다.
• DeviceAgent TaskManager는 task queue, workflow, 상태 이벤트, reason code를 관리한다.
• 실제 실행 가능 여부와 세부 조건은 cleaning, moving, map, schedule, interaction 도메인 매니저가 최종 판단해야 한다.
• Cloud나 브릿지가 기존 도메인 매니저의 조건 판단을 우회해서 set 함수만 직접 호출하면 안전하지 않다.

TaskManager 자체를 SoC 실행 오케스트레이션 기능 범주로 자세히 보려면 SoC TaskManager Execution Subsystem을 먼저 본다.

1. 왜 이 지도가 필요한가

복합명령 예시는 아래처럼 보인다.

거실로 가서 청정하고 안방으로 이동해줘

Cloud A2A 관점에서는 2~3개의 ODL step으로 계획할 수 있다.

{
  "steps": [
    {"route": "ODL", "purpose": "거실 이동"},
    {"route": "ODL", "purpose": "거실 청정"},
    {"route": "ODL", "purpose": "안방 이동"}
  ]
}

하지만 실제 실행 시점에는 아래 조건들이 계속 바뀐다.

• 현재 충전대 위인지
• 맵이 편집 중인지
• 대상 방이 실제 맵에 있는지
• 이동 중인지, 청정 중인지, 인터렉션 스케줄 중인지
• 배터리 부족, 경로 막힘, 센서 오류가 있는지
• 1번 task가 끝난 뒤 2번 task를 시작해도 되는지

따라서 Cloud가 처음에 모든 실행 조건을 확정하는 구조가 아니라, DeviceAgent가 각 task 실행 직전에 도메인 매니저를 통해 다시 확인해야 한다.

2. 계층별 책임

3. DeviceAgent 핵심 도메인

3.1 task/

역할:

• Cloud/Bridge에서 들어온 task/workflow 요청의 공식 입구다.
• task queue, workflow step, parallel group, cancel/compensation, event listener를 관리한다.
• 실패 reason을 reason_code, reason_params, recoverability, suggested_action, requires_cloud_decision 형태로 정규화한다.

주요 근거:

설계상 의미:

• COMPLETED는 “task 1개가 정상 완료됨”이라는 로컬 진행 이벤트다.
• WORKFLOW_COMPLETED는 workflow 전체가 정상 완료됨이라는 로컬 완료 이벤트다.
• Cloud는 정상 이벤트에 매번 LLM 판단을 하지 않는다.
• Cloud replan은 FAILED, BLOCKED, 의미 있는 PAUSED, 사용자 개입, 취소, 목표 변경처럼 판단이 필요한 event에서만 열린다.

3.2 cleaning/

역할:

• 팬 시작/정지, 고정 청정, 이동 청정, 선택/AI/스캐닝 청정, 청정 transaction 상태를 담당한다.
• CleaningTransaction은 현재 청정 중인지, 일시정지인지, 마지막 action과 area 정보를 제공한다.

주요 근거:

설계상 의미:

• Cloud가 “안방 청정”이라고 계획해도, 실제 청정 시작 가능 여부는 cleaning/ 도메인과 현재 상태가 판단해야 한다.
• sk_4 같은 token이 있다면 token 자체가 최종 하드웨어 명령이 아니라, DeviceAgent 내부에서 기존 청정 조건 판단을 타는 task entry로 연결되어야 한다.

3.3 moving/

역할:

• 방/좌표 이동, 스테이션 복귀, 일시정지/재개, 이동 callback을 담당한다.
• 이동 완료 callback은 청정, 인터렉션 스케줄, 매핑, 일반 이동 중 어느 flow가 이동을 요청했는지에 따라 다른 callback으로 전달된다.

주요 근거:

설계상 의미:

• 복합명령에서 “1. 거실 이동 -> 2. 안방 이동 후 청정”은 1번 이동 완료 callback 이후 2번 task를 시작해야 한다.
• 2번 task 등록 시점에 조건을 고정하면 안 된다. 실행 직전에 현재 위치/맵/이동 상태를 다시 봐야 한다.

3.4 map/

역할:

• 공간 id/name, split space, station area, map edit state, room polygon, 현재 위치 판단을 담당한다.
• map 삭제 시 관련 스케줄과 공기질 연동 설정까지 영향을 받는다.

주요 근거:

설계상 의미:

• Cloud plan의 roomName="안방"은 DeviceAgent에서 실제 roomId 또는 area id로 resolve되어야 한다.
• map editing 중이거나 room id가 없으면 DeviceAgent는 STATE_CONDITION_FAILED 또는 ROOM_NOT_FOUND 류 reason으로 막아야 한다.

3.5 schedule/와 interaction/

역할:

• 등록된 스케줄의 실행 조건, 인터렉션 스케줄, action prepare/start/stop/pause/resume을 담당한다.
• 스케줄은 단순 시간 트리거가 아니라 privacy mode, mapping, night mode, lock mode, off-station, current movement priority를 모두 확인한다.

주요 근거:

설계상 의미:

• Cloud가 SCH plan을 만들더라도 실행 가능성은 DeviceAgent의 schedule 정책이 최종 판단한다.
• 기존 스케줄 정책을 우회해 Cloud가 직접 이동/청정 task만 내려버리면 privacy/night/lock/mapping 조건을 빠뜨릴 수 있다.

4. get과 set의 분리

복합명령 설계에서 중요한 분리는 get과 set이다.

따라서 “현재 공기질 알려줘” 같은 조회는 task로 만들 필요가 약하다. 반대로 “거실로 가서 청정해줘”는 이동/청정의 실행 lifecycle이 있으므로 task/workflow로 관리해야 한다.

5. 안전한 실행 모델

권장 구조:

1. Cloud가 recognized_text + voice_context + device_context를 보고 plan을 만든다.
2. ODL step은 Cloud runtime에서 device_task_requests로 변환된다.
3. 온디바이스 브릿지는 요청을 DeviceAgent의 submitWorkflow 또는 submitTask로 전달한다.
4. DeviceAgent TaskManager는 queue에 등록하되, 각 subtask 실행 시점에 기존 domain manager 조건을 탄다.
5. 정상 이벤트는 DeviceAgent/온디바이스가 이어서 처리한다.
6. 판단이 필요한 실패 이벤트만 Cloud에 올려 replan한다.

피해야 할 구조:

1. Cloud가 setAirCleanerOperation 같은 내부 함수를 직접 고른다.
2. 온디바이스가 기존 token/조건 판단을 거치지 않고 wrapper만 호출한다.
3. TaskManager가 도메인별 조건을 모른 채 함수 호출만 순서대로 실행한다.
4. 모든 PROGRESS/COMPLETED event마다 Cloud LLM을 다시 돌린다.

6. 예시: 이동 후 청정 workflow

발화:

거실로 가서 청정하고 안방으로 이동해줘

Cloud plan:

{
  "turn_mode": "multi_turn",
  "steps": [
    {
      "id": "step_1",
      "route": "ODL",
      "purpose": "거실로 이동",
      "output": "arrival_state"
    },
    {
      "id": "step_2",
      "route": "ODL",
      "purpose": "거실 청정 시작",
      "input_from": ["step_1"]
    },
    {
      "id": "step_3",
      "route": "ODL",
      "purpose": "안방으로 이동",
      "input_from": ["step_2"]
    }
  ]
}

On-device request:

{
  "method": "submitWorkflow",
  "workflowName": "device_intent_workflow",
  "source": "cloud_a2a",
  "subTasks": [
    {
      "taskMethod": "moveToRoom",
      "roomName": "거실"
    },
    {
      "taskMethod": "startAirCleaning",
      "roomName": "거실",
      "dependsOnPrevious": true
    },
    {
      "taskMethod": "moveToRoom",
      "roomName": "안방",
      "dependsOnPrevious": true
    }
  ]
}

DeviceAgent 내부 실행:

1. TaskManager.submitWorkflow(...)가 workflow를 등록한다.
2. 첫 subtask 실행 직전에 moveToRoom adapter가 MapManager로 room id/position을 resolve한다.
3. MovingLocationManager.move(...)가 이동을 시작한다.
4. 도착 callback이 오면 subtask 1을 COMPLETED로 표시한다.
5. subtask 2 실행 직전에 CleaningTransaction, MapManager, device policy를 다시 확인한다.
6. 청정 시작이 가능하면 기존 cleaning manager를 통해 실행한다.
7. 실패하면 TaskReasonContract에 맞춘 reason event를 발생시킨다.

7. 업체 전달 포인트

DeviceAgent/SoC 담당 업체에는 아래를 명확히 요청해야 한다.

8. 남은 공백

현재 문서화된 구조는 DeviceAgent 앱 내부 도메인 중심이다. 아직 full AOSP 관점의 init.rc, Binder service 등록, HAL/AIDL, SELinux, partition 배치까지는 검증하지 않았다.

따라서 다음 단계는 둘로 나뉜다.

1. 단기: DeviceAgent task/domain adapter를 완성하고 fake/instrumented test로 workflow event를 검증한다.
2. 중기: SoC/AOSP 빌드 산출물 관점에서 DeviceAgent가 어떤 partition, permission, service boundary로 배치되는지 별도 분석한다.