LLM Wiki

← Docs hub

Vendor API Acceptance Checklist

이 문서는 DeviceAgent/SoC 업체 구현물을 받을 때 API별로 무엇을 확인해야 하는지 정의한다.

공통 필수 조건

모든 TaskManager API는 아래 조건을 만족해야 한다.

항목 기준
호출 경로 온디바이스 Bridge에서 호출 가능해야 한다.
결과 위치 outdata 또는 callback payload에서 결과를 읽을 수 있어야 한다.
trace 보존 cloud_workflow_id, cloud_step_id, cloud_plan_id, cloud_output_key가 lifecycle 동안 보존되어야 한다.
오류 구조 실패 시 reason_code, reason_params, requires_cloud_decision을 제공해야 한다.
로그 ADB logcat에서 task id, method, status, trace field를 확인할 수 있어야 한다.

소스 대조 기준

업체 구현물은 아래 기준점과 동등한 동작을 제공해야 한다.

기능 기준 소스 위치 대조 기준
control method dispatch TaskManager.java:102-143 method별 handler가 존재하고 false-positive dispatch가 없어야 한다.
single task submit TaskManager.java:169-226 validation, policy, command 생성, execution mode 처리가 있어야 한다.
workflow submit TaskManager.java:228-313 subtask 순차 실행과 step event가 있어야 한다.
cancel TaskManager.java:845-884 running/pending task cancel과 CANCELLED event가 있어야 한다.
event callback TaskManager.java:1515-1528 listener와 module callback으로 event payload가 나가야 한다.
reason contract TaskReasonContract.java:12-120 reason code, params, recoverability, suggested action, cloud decision이 구조화되어야 한다.
planning context DevicePlanningContextProvider.java:29-164 schema와 각 상태 하위 bundle이 있어야 한다.

submitTask

구분 수용 기준
입력 taskMethod, task params, source, cloud trace fields를 받는다.
성공 출력 accepted=true, taskId, taskState/status, taskMethod를 반환한다.
이벤트 QUEUED 또는 STARTED/RUNNING, 이후 COMPLETED 또는 FAILED를 전달한다.
실패 task method 누락, validator 실패, capability unavailable을 구조화 reason으로 반환한다.
테스트 정상 task 1건, 누락 param 1건, unsupported method 1건.

submitWorkflow

구분 수용 기준
입력 workflowName, subTasks, source, cloud workflow/plan trace를 받는다.
성공 출력 parent workflow id와 subtask summary를 반환한다.
순차성 subtask N 완료 전 subtask N+1을 실행하지 않는다.
이벤트 WORKFLOW_STEP_STARTED, WORKFLOW_STEP_COMPLETED, 최종 WORKFLOW_COMPLETED 또는 실패 이벤트를 전달한다.
실패 특정 subtask 실패 시 parent workflow 상태와 실패 step id를 확인할 수 있어야 한다.
테스트 3-step 순차 workflow, 2번째 step 실패 workflow, cancel workflow.

19.comToMe workflow 예시

19.comToMe처럼 내부 lifecycle이 긴 device 기능은 19.comToMe A2A Workflow Example을 기준 예시로 본다.

수용 기준:

항목 기준
task method 승격 ComeToMe가 submitTask.taskMethod=comeToMe 또는 submitWorkflow.subTasks[].taskMethod=comeToMe로 표현 가능해야 한다.
내부 lifecycle DoA, Vision, AMR, FollowMe 세부 단계는 DeviceAgent TaskManager/ComeToMeTaskManager가 관리해야 한다.
stage gate 0-1, 0-2, 1, 2, 3 rollout stage에 따라 허용 기능이 달라져야 한다.
speaker gate 1단계 이상에서 등록 화자 확인 실패 시 DoA/AMR 이동을 시작하지 않아야 한다.
slot 전달 발화에서 추출한 commandType, roomName, rolloutStage, speakerId 등 필요한 slot이 Bundle에 보존되어야 한다.
trace 유지 cloud_step_id, cloud_output_key, cloud_workflow_id가 ComeToMe callback까지 유지되어야 한다.
실패 구조 speaker/location/DoA/Vision/AMR/FollowMe 실패가 reason_code, reason_params, requires_cloud_decision으로 구조화되어야 한다.

리뷰어는 실제 DeviceAgent 구현에서 comeToMe method 이름, rollout stage, speaker profile, room mapping, target pose, FollowMe 전환 callback 기준을 업체에 요구해야 한다.

getTaskStatus

구분 수용 기준
입력 taskId를 받는다.
성공 출력 현재 status, progress, stage, taskMethod, trace field를 반환한다.
실패 없는 task id는 명확한 not found 결과를 반환한다.
테스트 running task 조회, completed task 조회, unknown task 조회.

cancelTask

구분 수용 기준
입력 taskId, cancel reason을 받는다.
성공 출력 cancel accepted 여부와 최종 상태를 반환한다.
이벤트 CANCELLED 이벤트가 올라온다.
범위 pending/running task와 workflow parent/child 취소 정책을 명확히 한다.
테스트 pending cancel, running cancel, already completed cancel.

getDevicePlanningContext

구분 수용 기준
입력 별도 인자 없이 현재 snapshot을 반환할 수 있어야 한다.
schema schema_version=device_context.v1을 포함한다.
필수 축 battery, map, location, cleaning, movement, task_manager, capabilities를 포함한다.
freshness snapshot_ts와 updated_at_ms가 있어야 한다.
누락값 unavailable 값을 null로 숨기지 말고 available=false 또는 명시적 상태로 표현한다.
테스트 정상 snapshot, map unavailable, busy queue 상태.

onTaskEvent

구분 수용 기준
이벤트명 정상, 실패, 취소, workflow step 이벤트를 구분한다.
필수 필드 eventName/status, task_id, taskMethod, cloud trace fields, progress, timestamp.
실패 필드 reason_code, reason_params, requires_cloud_decision, recoverability, suggested_action.
alias snake_case와 camelCase 중 Cloud/온디바이스가 합의한 필드는 누락 없이 제공한다.
테스트 completed event, failed event, blocked event, cancelled event.

제출물 체크리스트

업체는 아래 산출물을 제출해야 한다.

리뷰어 확인표

확인 항목 PASS 기준 결과
trace alias snake/camel 중 합의된 key가 callback까지 유지됨
workflow ordering event timestamp 기준 순차 실행이 증명됨
failure structure 실패 이벤트에 reason code/params가 있음
replan gate requires_cloud_decision 정책이 reason code와 일치함
context freshness snapshot timestamp가 있고 stale 여부 정책이 있음
cancellation parent/child 취소 정책이 문서와 로그로 확인됨