LLM Wiki

← Docs hub

DeviceAgent Vendor Implementation Package

이 문서는 SoC/DeviceAgent 업체에 전달할 구현 패키지의 진입점이다.

목표는 “복합명령을 Cloud가 계획하고, 온디바이스가 DeviceAgent TaskManager에 task/workflow를 등록하며, DeviceAgent가 실행 상태와 실패 사유를 구조화해서 돌려주는 구조”를 업체가 그대로 구현하고 증명하게 하는 것이다.

DeviceAgent Vendor Implementation Package

전달 범위

영역 업체가 제공해야 하는 것 완료 증거
TaskManager API submitTask, submitWorkflow, getTaskStatus, cancelTask, getDevicePlanningContext API별 unit/instrumented test
Event Callback onTaskEvent payload와 lifecycle event event listener test, logcat
Reason Contract reason_code, reason_params, requires_cloud_decision failure injection test
Trace Metadata cloud_workflow_id, cloud_step_id, cloud_plan_id, cloud_output_key 보존 artifact validator
Planning Context battery, map, location, cleaning, movement, queue, capability snapshot context snapshot sample
Queue Policy sequential workflow, cancel, duplicate, busy policy workflow test

업체가 구현해야 하는 핵심 시나리오

1. 단일 task 등록

온디바이스가 submitTask를 호출하면 DeviceAgent는 task를 등록하고, accepted 결과와 task id를 반환해야 한다.

On-device
-> DeviceAgent TaskManager.submitTask
-> accepted=true, taskId
-> onTaskEvent(QUEUED/RUNNING/COMPLETED or FAILED)

2. 복합 workflow 등록

여러 subtask가 있는 경우 submitWorkflow는 순차 실행을 보장해야 한다.

subtask_1: move to living room
subtask_2: move to bedroom
subtask_3: start cleaning

완료 기준:

3. 실패/차단 처리

실패/차단 시 자연어 reason만 보내면 안 된다.

{
  "eventName": "FAILED",
  "task_id": "task-123",
  "cloud_workflow_id": "wf-001",
  "cloud_step_id": "step_2",
  "reason_code": "PATH_BLOCKED",
  "reason_params": {
    "target_room": "안방",
    "blocked_area": "복도"
  },
  "requires_cloud_decision": true
}

Cloud는 이 구조화 필드가 있어야 사용자에게 다시 물을지, 대체 plan을 만들지, 중단할지 판단할 수 있다.

패키지 문서 구성

문서 용도
Vendor Handoff 업체 전달 요약
DeviceAgent TaskManager API Contract 현재 소스 기준 API 계약
SoC TaskManager Execution Subsystem TaskManager를 SoC 실행 오케스트레이션 기능 범주로 구현하기 위한 구조
DeviceAgent / SoC Domain Map TaskManager 뒤의 moving/cleaning/map/schedule 도메인 연결 구조
Vendor API Acceptance Checklist API별 수용 기준과 제출 증거
Vendor Test Evidence Template 업체가 제출할 테스트 결과 양식
Vendor Open Questions 구현 전 닫아야 할 미확정 질문
Requirements Traceability Matrix 요구사항 ID와 설계/구현/검증 연결

소스 기준점

DeviceAgent:

파일 라인/영역 업체 대조 포인트
TaskManager.java 31-41 TaskManager control method 상수 목록.
TaskManager.java 102-143 handleControlMethod(...)가 submitTask, submitWorkflow, getTaskStatus, cancelTask, getDevicePlanningContext 등을 dispatch.
TaskManager.java 169-226 submitTask(...) validation, policy, execution mode, accepted/result 반환.
TaskManager.java 228-313 submitWorkflow(...) subtask 순차 실행, workflow step event 발생.
TaskManager.java 845-884 cancelTask(...) 취소 처리와 CANCELLED event.
TaskManager.java 1449-1466 reason_code, reason_params, requires_cloud_decision, trace field summary 기록.
TaskManager.java 1515-1528 notifyTaskEvent(...)와 onTaskEvent callback 전송.
TaskReasonContract.java 12-56 error code를 Cloud용 reason_code로 정규화.
TaskReasonContract.java 58-69 room/position 관련 reason_params 구성.
TaskReasonContract.java 71-120 recoverability, suggested action, cloud decision 필요 여부.
DevicePlanningContextProvider.java 29-43 device_context.v1 snapshot 최상위 schema.
DevicePlanningContextProvider.java 54-164 battery, map, location, cleaning, movement, task_manager, capabilities 구성.

On-device Bridge:

파일 라인/영역 업체 대조 포인트
ForegroundService.kt 2220-2265 Cloud device_task_requests 수신 후 intent workflow 또는 legacy task 등록.
ForegroundService.kt 2291-2341 다음 runnable step 실행, native task submit, completed/failed report.
ForegroundService.kt 2344-2375 DeviceAgent callback event에서 step id, status, reason code/params 파싱.
CloudIntentWorkflowRunner.kt 42-69 Cloud request를 local workflow step으로 등록.
CloudIntentWorkflowRunner.kt 71-82 runnable step 선택과 native task 제출 상태 반영.
CloudIntentWorkflowRunner.kt 98-140 native task event를 Cloud report로 변환.
CloudIntentWorkflowRunner.kt 149-162 dependency 완료 후 다음 step unlock.
CloudIntentWorkflowRunner.kt 164-205 task_event report payload 구성.
CloudIntentWorkflowRunner.kt 208-234 모든 step 완료 시 WORKFLOW_COMPLETED report 생성.

Cloud:

gemini/a2a/runtime/task_manager.py
gemini/a2a/runtime/workflow_state.py
gemini/a2a/runtime/orchestrator.py

인수 기준

제품 통합 완료로 보려면 아래가 모두 필요하다.

업체 제출물 검토 순서

  1. submitTask 단일 성공 fixture를 본다.
  2. submitWorkflow 3-step 순차 성공 fixture를 본다.
  3. WORKFLOW_STEP_STARTED, WORKFLOW_STEP_COMPLETED, WORKFLOW_COMPLETED event 순서를 본다.
  4. 실패 주입 fixture에서 reason_code, reason_params, requires_cloud_decision을 본다.
  5. getDevicePlanningContext snapshot에서 schema와 freshness를 본다.
  6. logcat에서 cloud_workflow_id, cloud_step_id, cloud_plan_id, cloud_output_key가 끝까지 유지되는지 본다.

수용 불가 조건

아래 중 하나라도 있으면 업체 구현 완료로 보지 않는다.

관련 요구사항