← Docs hub

SoC TaskManager Execution Subsystem

TaskManager는 A2A와 DeviceAgent/SoC를 연결하는 큰 기능 범주다. 단순히 “명령을 queue에 넣는 클래스”가 아니라, Cloud가 만든 plan을 실제 기기 실행으로 안전하게 소비하기 위한 DeviceAgent 실행 오케스트레이션 서브시스템으로 봐야 한다.

이 문서의 기준은 아래와 같다.

• Cloud A2A는 “무엇을 어떤 순서로 할지” 계획한다.
• 온디바이스 브릿지는 Cloud plan을 DeviceAgent task/workflow 호출로 변환한다.
• SoC/DeviceAgent TaskManager는 “실행 가능한 단위로 등록하고, 순서/상태/실패/취소/이벤트를 관리한다.”
• 실제 이동/청정/스케줄 조건 판단은 각 도메인 매니저가 유지한다.

1. 큰 기능 범주

SoC 관점에서 TaskManager는 아래 7개 기능을 하나의 실행 계층으로 묶는다.

즉 TaskManager는 Cloud가 이해하는 plan 언어와 DeviceAgent가 실행하는 legacy/device-domain 명령 사이의 중간 실행 계층이다.

2. A2A와 맞물리는 위치

전체 call chain은 다음처럼 정리된다.

사용자 발화
-> Cloud A2A Planner
-> Cloud Runtime device_task_requests
-> On-device Bridge
-> DeviceAgent TaskManager.submitWorkflow / submitTask
-> TaskPolicy / Validator / Resource check
-> TaskExecutorRegistry or legacy FunctionCallHandler
-> moving / cleaning / map / schedule / interaction domain manager
-> MCU / AMR / wrapper / sensor
-> TaskEventListener / AppCmd module callback
-> On-device Bridge event relay
-> Cloud replan only if requires_cloud_decision=true

여기서 중요한 정책은 다음이다.

• 정상 QUEUED, RUNNING, PROGRESS, COMPLETED, WORKFLOW_COMPLETED는 Cloud LLM을 매번 다시 돌리지 않는다.
• FAILED, BLOCKED, 의미 있는 PAUSED, 사용자 결정 필요 상황만 Cloud replan 후보가 된다.
• Cloud plan은 task 실행 전 전체 조건을 확정하지 않는다. 각 subtask 실행 직전에 DeviceAgent domain manager가 다시 판단한다.

3. 내부 구성요소

3.1 TaskManager.java

역할:

• 외부 control method dispatch.
• 단일 task와 workflow 등록.
• queue/executor lifecycle 관리.
• status/progress/cancel/context/query 제공.
• event listener와 module callback으로 event 전파.

주요 근거:

3.2 TaskPolicyRegistry.java

역할:

• method별 execution mode, queue, priority, timeout, cancel method를 정한다.
• exact policy가 없으면 method name 기준 fallback queue를 고른다.

예:

설계상 의미:

• get 계열은 대체로 DIRECT.
• set 계열이면서 시간이 걸리는 명령은 ASYNC 또는 QUEUED_WAIT.
• movement/cleaning/ai는 cancellable 성격을 가진다.

3.3 TaskBundleValidator.java

역할:

• strict validation이 켜졌을 때 method별 필수 slot을 확인한다.
• workflow subtask도 동일하게 검증할 수 있다.

예:

설계상 의미:

• Cloud plan이 “안방 청정”이라고 해도, DeviceAgent task payload에는 실제 실행 가능한 slot이 있어야 한다.
• 발화에서 가져온 room/area/action/mode slot은 이 계층에서 누락 여부를 검출할 수 있어야 한다.

3.4 TaskExecutorRegistry.java와 executor classes

역할:

• task method를 실행 가능한 TaskExecutor에 바인딩한다.
• TaskExecutorBootstrap.registerSkeletonExecutors(...)가 movement, cleaning, LLM/TTS, IoT, update executor를 등록한다.

현재 구조:

주의:

• skeleton executor가 곧 제품 실행 완성은 아니다.
• 실제 구현에서는 executor가 기존 FunctionCallHandler 또는 domain manager 경로를 타야 한다.
• 기존 음성 명령의 안전조건을 우회하는 direct wrapper 호출은 피해야 한다.

3.5 TaskResourceMonitor.java

역할:

• CPU, RAM pressure, thermal level 같은 resource snapshot을 보관한다.
• TaskManager.writeManagerStatus(...)와 resource policy 판단에 연결된다.

설계상 의미:

• device가 과열/자원 부족이면 task admission에서 막거나 지연시킬 수 있어야 한다.
• Cloud는 resource detail을 모두 판단하지 않고, DeviceAgent reason contract를 통해 결과를 받는 쪽이 현실적이다.

3.6 TaskReasonContract.java

역할:

• legacy error/status를 Cloud가 이해 가능한 구조화 reason으로 변환한다.
• recoverability, suggested action, requires_cloud_decision을 결정한다.

대표 reason:

3.7 DevicePlanningContextProvider.java

역할:

• Cloud plan 전에 필요한 최소 device context를 snapshot으로 만든다.

현재 snapshot 축:

schema_version
snapshot_ts / updated_at_ms
main_state
battery
map
location
cleaning
movement
task_manager
capabilities

설계상 의미:

• Cloud는 이 context로 불가능한 plan을 줄인다.
• 하지만 최종 실행 가능 여부는 여전히 DeviceAgent 실행 시점의 domain manager 판단이 우선이다.

3.8 TaskIngressClassifier.java

역할:

• 들어온 method가 task control인지, command task인지, progress/result/sensor/event/trigger인지 분류한다.

설계상 의미:

• 모든 입력을 task로 등록하면 안 된다.
• sensor/status/progress/event는 queue 실행명령이 아니라 상태 갱신 또는 callback일 수 있다.

4. Workflow 실행 모델

submitWorkflow는 subTasks를 받아 순차 또는 일부 parallel group으로 실행한다.

순차 실행 원칙:

1. workflow task record를 만든다.
2. subtask를 하나씩 읽는다.
3. subtask validation을 수행한다.
4. WORKFLOW_STEP_STARTED event를 발생시킨다.
5. subtask command를 실행한다.
6. 성공하면 step state를 COMPLETED로 바꾸고 WORKFLOW_STEP_COMPLETED event를 발생시킨다.
7. 모든 subtask result를 parent workflow result에 모은다.

복합명령에서 이 구조가 중요한 이유:

• 1번 이동 task가 끝나기 전 2번 청정 task를 시작하면 실제 위치가 아직 바뀌지 않았을 수 있다.
• 2번 task 실행 직전에는 배터리, map, current movement, cleaning state가 달라졌을 수 있다.
• 따라서 task 등록 시점의 상태가 아니라 실행 시점 상태를 봐야 한다.

5. Event 모델

TaskManager event는 크게 두 그룹이다.

정상 진행 event:

QUEUED
STARTED
PROGRESS
WORKFLOW_STEP_STARTED
WORKFLOW_STEP_COMPLETED
COMPLETED
WORKFLOW_COMPLETED

Cloud는 이 event를 받아도 기본적으로 LLM replan을 하지 않는다. 온디바이스와 DeviceAgent가 다음 step을 이어간다.

판단 필요 event:

FAILED
BLOCKED
PAUSED
CANCELLED
NEEDS_USER_INPUT

이 event는 reason_code, reason_params, requires_cloud_decision 여부가 중요하다. Cloud는 이 값이 있어야 사용자에게 다시 물을지, 대체 경로를 만들지, 전체 workflow를 중단할지 판단할 수 있다.

6. SoC 업체 구현 기준

업체가 TaskManager를 구현할 때 최소한 아래 범위를 맞춰야 한다.

7. 금지해야 할 구현

아래 방식은 A2A 연계에는 맞지 않는다.

• Cloud가 setAirCleanerOperation 같은 내부 method만 직접 결정한다.
• 온디바이스가 token을 단순 문자열로만 전달하고 task lifecycle을 추적하지 않는다.
• TaskManager가 기존 FunctionCallHandler/domain manager 조건을 우회한다.
• COMPLETED event를 받을 때마다 Cloud LLM을 다시 호출한다.
• 실패 event에 자연어 message만 있고 reason_code가 없다.
• cloud_step_id가 callback에서 유실된다.
• getDevicePlanningContext가 실제 device state 없이 빈 skeleton만 반환한다.

8. 검증 시나리오

ADB 없이 가능한 검증:

• submitTask fixture로 accepted/task id/status event shape 확인.
• submitWorkflow 3-step fake executor로 step 순서 확인.
• TaskBundleValidator strict mode로 필수 slot 누락 실패 확인.
• TaskReasonContract reason normalization fixture 확인.
• TaskIngressClassifier가 command/progress/sensor/event를 올바르게 분류하는지 확인.

ADB/실기기 필요 검증:

• 실제 이동 task가 domain manager와 AMR 경로를 타는지 logcat 확인.
• 실제 청정 task가 기존 FunctionCallHandler/cleaning manager 조건을 우회하지 않는지 확인.
• path blocked, room not found, low battery 같은 실패 event가 구조화되어 올라오는지 확인.
• Cloud trace field가 온디바이스, DeviceAgent, callback, Cloud report까지 유지되는지 확인.

9. 관련 문서

• 19.comToMe A2A Workflow Example
• DeviceAgent / SoC Domain Map
• DeviceAgent TaskManager API Contract
• DeviceAgent Vendor Implementation Package
• Vendor API Acceptance Checklist
• Validation Guide
• Requirements Traceability Matrix