LLM Wiki

← Docs hub

DeviceAgent TaskManager Framework Wiki

DeviceAgent TaskManager Framework 구조

1. 목적

이 문서는 DeviceAgent를 LLM/MCP/SDK에서 호출 가능한 내부 Framework 계층으로 재구성할 때, 현재 구현된 TaskManager를 어떤 위치에 두고 어떻게 연결해야 하는지 정의한다.

구현자는 이 문서를 기준으로 다음을 판단해야 한다.

2. 현재 코드 기준 사실

항목 현재 상태 코드 근거
Binder 진입 외부 모듈은 DeviceAgent.ServiceBinder.sendModuleCommand(...)로 진입 apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/DeviceAgent.java
MainApi 중앙 라우팅 모든 method는 MainApi.executeMethod(...)로 들어온다 apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/main/api/MainApi.java
TaskManager 제어 API submitTask, submitWorkflow, getTaskStatus, cancelTask 등은 TaskManager.handleControlMethod(...)가 선점 처리 apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskManager.java
Legacy command queue TaskManager가 비-Task 명령도 policy에 따라 legacy queue로 감쌀 수 있다 TaskManager.executeLegacy(...)
Executor skeleton Movement, CleaningAmp, LlmTts, Iot, Update executor skeleton은 있으나 실제 제어 연결은 미완 apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/*TaskExecutor.java
Framework command 패키지 framework/command에 CommandRegistry, FrameworkCommandBridge, MovementCommandHandler 등이 존재 apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/framework/command/

3. 목표 레이어

LLM utterance / SDK API / Client App
  -> LLM Command Policy / SDK Manager API
  -> DeviceAgent Binder API
  -> MainApi.executeMethod(...)
  -> TaskManager control API
  -> TaskExecutorRegistry
  -> Domain Executor
  -> Domain Adapter or FrameworkCommandBridge
  -> Existing Manager / Policy / HAL wrapper
  -> AMRAgent / LLMAgent / IotAgent / MCU / UpdateService

4. TaskManager가 담당해야 하는 것

TaskManager는 단순 method dispatcher가 아니다. 다음 속성이 필요한 실행 단위를 관리한다.

담당 설명
상태 PENDING, RUNNING, COMPLETED, FAILED, CANCELLED 등 lifecycle 유지
큐 이동/청소/업데이트처럼 동시에 실행하면 안 되는 command를 serial화
우선순위 일반 명령보다 emergency/stop/cancel 명령을 우선 처리
취소 실행 중 task에 대응하는 cancel/stop/compensation method 연결
timeout callback이 오지 않는 장시간 동작을 실패로 종료
진행률 updateTaskProgress 또는 내부 callback으로 progress 반영
완료 상관관계 기존 callback에 없는 taskId를 runtime registry로 매칭

5. Task로 관리해야 하는 후보

도메인 Task 대상 이유
Movement returnToStation, setMoveTo, setMoving, stopMovement AMR 이동은 비동기 완료/실패/취소가 필요
Cleaning setAirCleanerOperation, setStatusClean, stopCleaning, ampStop 청정 동작은 이동/상태/정책과 충돌 가능
LLM/TTS setChangeLlmStatus, setLlmTts, stopLlm, stopTts 음성 상호작용 중복/중단 정책 필요
IoT/Config setDeviceStatus, setConfig, getConfig 외부 상태 제어/설정 명령에 caller policy 필요
Update setFirmwareUpdateStatus, OTAUpdateArmResult, OTAUpdateMcuResult OTA는 장시간/단계형/복구 상태 관리 필요

6. Task로 관리하지 않는 후보

유형 예시 이유
단순 조회 getMainState, getBatteryInfo, getFirmwareVersion 즉시 응답이며 lifecycle 불필요
단순 UI 알림 setPopup, 일부 callback relay 실행 완료 관리보다 event relay 성격
Agent 내부 callback AllMovingInfo, setTtsText, setLlmStt 명령이 아니라 상태/event 입력
ByPass 명령 setLlmTtsByPass, setChangeLlmStatusByPass 코드상 정책관리 제외 의도가 명시됨

7. LLM Wiki에서의 연결 의미

LLM Wiki의 llm_command.xlsx는 사용자 발화와 skill token을 정의한다. 그러나 token은 최종 DeviceAgent method가 아니다.

권장 연결은 다음과 같다.

사용자 발화
  -> llm_command.xlsx rule
  -> MCP decisionType EXECUTE / DENY / NOOP / MULTI_TURN
  -> commandType 또는 legacySkillToken
  -> DeviceAgent taskMethod 결정
  -> submitTask 또는 submitWorkflow

예시:

LLM 기능 LLM token DeviceAgent taskMethod 실행 방식
스테이션 복귀 sk_1 returnToStation submitTask
선택 공간 청정 sk_4 setAirCleanerOperation + optional setMoveTo submitWorkflow
청정 OFF/PAUSE/RESUME sk_38 setStatusClean 또는 stopCleaning submitTask
TTS 중지 LLM 상태 제어 setChangeLlmStatus or stopTts submitTask

8. 구현 순서

  1. DeviceAgent.onCreate()에서 TaskExecutorBootstrap.registerSkeletonExecutors(false)를 호출한다.
  2. TaskModuleExecutor를 dry-run 전용이 아니라 실제 executeWired(...) hook 구조로 바꾼다.
  3. MovementTaskExecutor부터 실제 CmdPolicyManager 또는 FrameworkCommandBridge에 연결한다.
  4. callback correlation registry를 추가해 taskId -> taskMethod -> expected callback을 저장한다.
  5. AppCmd.sendModuleCallback_main(...) 또는 AMR callback 진입점에서 task 완료/실패를 update한다.
  6. LLM/MCP router는 직접 legacy method 호출 대신 submitTask/submitWorkflow를 우선 사용한다.

9. 상세 구현 링크