LLM Wiki

← Docs hub

DeviceAgent TaskManager API Contract

이 페이지는 SoC/DeviceAgent 업체가 맞춰야 하는 TaskManager API와 event payload 계약을 현재 소스 기준으로 정리한다.

DeviceAgent TaskManager API Architecture

기준 소스:

~/work/1.A1_SoC_new/SoC/a1-packages/apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskManager.java
~/work/1.A1_SoC_new/SoC/a1-packages/apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskEventListener.java
~/work/1.A1_SoC_new/SoC/a1-packages/apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskReasonContract.java
~/work/1.A1_SoC_new/SoC/a1-packages/apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/DevicePlanningContextProvider.java
~/work/1.A1_SoC_new/SoC/a1-packages/apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskIngressClassifier.java

1. Control Method 목록

TaskManager.handleControlMethod(...)가 처리하는 method다.

Method 목적 주요 입력 주요 출력
submitTask 단일 task 등록 taskMethod, task params, source, cloud trace fields accepted, taskId, taskState, summary
submitWorkflow 여러 subtask workflow 등록 workflowName, subTasks, source accepted, workflow taskId, subtask states
getTaskStatus task 상세 조회 taskId task summary/detail
listTasks task 목록 조회 filter fields task list
getQueueStatus queue 상태 조회 optional filter queue summary
updateTaskProgress progress/status 갱신 taskId, progress/status/stage/message updated summary
cancelTask task 취소 taskId, reason cancelled summary
getTaskManagerStatus manager 상태 조회 none enabled/queue/metric 상태
getDevicePlanningContext Cloud plan 전 기기 context 조회 none device_context.v1 snapshot
classifyTaskIngress method가 task/control/event인지 분류 method, optional signalType signal type, action, reason

2. submitTask 처리 순서

현재 submitTask(...)는 아래 순서로 처리된다.

enabled check
-> taskMethod 필수 확인
-> TaskBundleValidator.validateSubmitTask
-> TaskPolicyRegistry.resolve
-> caller policy check
-> state condition check
-> resource policy check
-> TaskCommandFactory로 command 생성
-> executionMode에 따라 DIRECT / QUEUED_WAIT / ASYNC 처리

중요한 reject code:

Code 의미
taskmanager_disabled TaskManager 비활성
missing_task_method taskMethod 누락
validator error submit task schema/parameter 불일치
missing_task_command 실행 가능한 command 생성 실패

3. submitWorkflow 처리 순서

submitWorkflow(...)는 subTasks를 순차 실행하고, parallelGroup도 처리할 수 있다.

입력 구조:

workflowName
subTasks: ArrayList<Bundle>
source
cloud_workflow_id / cloudWorkflowId
cloud_plan_id / cloudPlanId

subtask 실행 흐름:

for each subTask:
  validateWorkflowSubTask
  currentStepIndex/currentStepMethod 갱신
  WORKFLOW_STEP_STARTED event
  command.run()
  WORKFLOW_STEP_COMPLETED event

parallelGroup 흐름:

type = parallelGroup
groupId
joinPolicy = all_success
failurePolicy = fail_parent | partial_success | continue_on_failure
tasks = child task list

4. Execution Mode 의미

Mode 의미
DIRECT TaskManager queue를 거치지 않고 즉시 실행한다.
QUEUED_WAIT queue에 넣고 완료까지 기다린 뒤 결과를 반환한다.
ASYNC queue에 넣고 즉시 accepted/task summary를 반환한다.

Cloud/온디바이스 관점에서는 복합 device workflow가 길어질 수 있으므로 ASYNC 또는 workflow queue 기반 event callback이 중요하다.

5. Task Event Payload

notifyTaskEvent(...)는 record.writeSummaryTo(eventData) 후 아래 필드를 추가한다.

method = onTaskEvent
eventName = event name

writeSummaryTo(...)가 넣는 핵심 필드:

Field 의미
taskId, task_id task id snake/camel 호환
taskMethod, task_method 실제 task method
taskQueue queue key
taskState, status 현재 상태
executionMode DIRECT/QUEUED_WAIT/ASYNC
priority task priority
source task source
cancellable 취소 가능 여부
retryCount retry 횟수
progress 진행률
stage 현재 stage
message 상태 메시지
currentStepIndex workflow 현재 step index
currentStepMethod workflow 현재 step method
workflowName workflow 이름
taskErrorCode 실패 error code
taskReason 실패 reason
reason_code, reasonCode 구조화된 reason code
reason_params, reasonParams 구조화된 reason params
recoverability 복구 가능성
suggested_action, suggestedAction 권장 후속 행동
requires_cloud_decision, requiresCloudDecision Cloud 재판단 필요 여부

Cloud trace alias:

snake_case camelCase
cloud_workflow_id cloudWorkflowId
workflow_id workflowId
cloud_step_id cloudStepId
step_id stepId
cloud_plan_id cloudPlanId
plan_id planId
cloud_output_key cloudOutputKey
output_key outputKey

6. Reason Code Contract

TaskReasonContract는 error code를 Cloud가 이해할 수 있는 reason code로 정규화한다.

입력 error 계열 reason_code
TIMEOUT, TASK_TIMEOUT TIMEOUT
INTERRUPTED INTERRUPTED
CANCELLED, USER_CANCELLED USER_CANCELLED
QUEUE_FULL, RESOURCE_BUSY, BUSY, DEVICE_BUSY DEVICE_BUSY
CPU_LIMIT, RAM_LIMIT, THERMAL_LIMIT RESOURCE_LIMIT
STATE_CONDITION_FAILED, BLOCKED_BY_STATE, CONDITION_FAILED STATE_CONDITION_FAILED
VALIDATION_FAILED, MISSING_TASK_METHOD, MISSING_TASK_COMMAND CAPABILITY_UNAVAILABLE
PATH_BLOCKED, PATH_BLOCKED_BY_OBSTACLE, NAVIGATION_PATH_BLOCKED PATH_BLOCKED
ROOM_NOT_FOUND, POSITION_NOT_FOUND, LOCATION_NOT_FOUND, TARGET_NOT_FOUND ROOM_NOT_FOUND
LOW_BATTERY, BATTERY_LOW LOW_BATTERY
SENSOR_ERROR, SENSOR_FAILURE SENSOR_ERROR

requires_cloud_decision은 LOW_BATTERY, DEVICE_BUSY, RESOURCE_LIMIT을 제외한 구조화 reason에서 대체로 true가 된다.

7. Device Planning Context

getDevicePlanningContext는 DevicePlanningContextProvider.snapshot(...)을 통해 Cloud plan 전 context를 제공한다.

최상위 필드:

schema_version = device_context.v1
snapshot_ts
updated_at_ms
main_state
battery
map
location
cleaning
movement
task_manager
capabilities

하위 구조:

필드 포함 정보
battery available, percent, is_low, is_charging, raw_capacity
map available, editable, rooms
location current_room_id, current_room_name, is_on_station
cleaning is_running, is_paused, last_action, area_info
movement moving_status, is_moving, is_paused, blocked
task_manager queue_status, busy, running_tasks, queue_summary
capabilities movement, room_cleaning, return_to_station, tts, schedule

8. Ingress Classification

classifyTaskIngress는 method가 TaskManager control인지, 일반 command task인지, event/status 성격인지 분류한다.

Signal type creates task action
COMMAND_TASK true submit_task
TASK_CONTROL false task_manager_api
PROGRESS_UPDATE false update_task_progress
RESULT_UPDATE false update_task_result
SENSOR_DATA false state_or_resource_update
TRIGGER false policy_trigger
EVENT_CALLBACK false event_callback
UNKNOWN false reject

9. 업체 구현 체크포인트

체크포인트 확인 방법
submitTask가 accepted/task summary를 반환하는가 단일 task unit test
submitWorkflow가 subtask state를 남기는가 workflow unit/instrumented test
WORKFLOW_STEP_STARTED/COMPLETED event가 올라오는가 event listener test
실패 시 reason_code, reason_params가 채워지는가 failure injection test
Cloud trace alias가 event에 남는가 logcat/artifact validator
getDevicePlanningContext가 stale/empty 없이 반환되는가 context snapshot test
cancelTask가 running/pending task를 정리하는가 cancellation test

10. Cloud 연동 관점에서 중요한 결론

관련 페이지