← Docs hub
이 문서는 업체에게 전체 위키를 전달하기 전, 구현 범위와 제출 evidence를 한 장으로 설명하기 위한 문서다.
1. 한 줄 요약
Cloud는 “무엇을 어떤 순서로 할지” 계획하고, DeviceAgent/SoC는 “그 계획을 안전하게 실행하고 상태와 실패 사유를 구조화해서 돌려주는 것”을 구현한다.
2. 업체가 꼭 이해해야 하는 경계
| 영역 |
Cloud A2A |
On-device Bridge |
DeviceAgent/SoC |
| 발화 해석 |
route family, step plan, missing slot, replan 판단 |
Cloud 응답 수신/전달 |
직접 판단하지 않음 |
| 실행 계획 |
steps, depends_on, input_from 생성 |
local workflow로 변환 |
task/workflow queue 실행 |
| 기기 상태 |
필요한 context 요청 |
context 전달 |
현재 상태 snapshot 제공 |
| 정상 진행 |
LLM 재판단하지 않음 |
event relay |
local lifecycle 처리 |
| 실패/차단 |
replan 또는 사용자 질문 |
Cloud로 escalate |
reason_code, requires_cloud_decision 제공 |
3. 업체 구현 Must
| 구현 항목 |
요구 |
| TaskManager API |
submitTask, submitWorkflow, getTaskStatus, cancelTask |
| Task 상태 |
QUEUED, RUNNING, PROGRESS, COMPLETED, FAILED, CANCELLED |
| Workflow 상태 |
step 순서, dependency, terminal state 관리 |
| Reason contract |
실패/차단을 code와 params로 구조화 |
| Trace metadata |
cloud_plan_id, cloud_workflow_id, cloud_step_id, cloud_output_key 유지 |
| Context provider |
배터리, 위치, map, task queue, capability 상태 제공 |
| AAR/API boundary |
외부 모듈이 같은 TaskManager contract를 호출할 수 있는 표면 제공 |
4. 업체가 제출해야 하는 Evidence
| Evidence |
내용 |
| API fixture |
submit/status/cancel/workflow request/response 샘플 |
| Event trace |
정상 workflow와 실패 workflow log |
| Reason matrix |
실패 케이스별 reason_code, recoverability, suggested_action |
| ADB logcat |
실기기에서 trace metadata가 유지되는 증거 |
| Regression result |
기존 command가 TaskManager wrapper 후에도 동작하는 증거 |
| Build artifact |
테스트한 APK/AAR/image 식별자 |
5. 업체에게 요구하지 않는 것
- Cloud Planner prompt 구현
- route family benchmark 튜닝
- LLM model 선택
- 모든 proactive 정책 구현
- 정상 progress마다 Cloud 판단 호출
6. 우선 구현 순서
- TaskManager 단일 task API
- Workflow queue와 dependency
- Event/reason contract
- 기존 MainApi command wrapper
- AAR/API boundary
- Schedule fixed cleaning adapter
- 실기기 evidence 제출
7. 회의 때 닫아야 할 질문
| 질문 |
왜 필요한가 |
| Task ID와 workflow ID는 누가 생성하는가 |
Cloud/DeviceAgent trace 충돌 방지 |
| 실패 reason code enum은 어디서 관리하는가 |
replan 정책 안정화 |
| AAR 외부 API는 어떤 package/class로 배포하는가 |
framework로 사용 가능해야 함 |
| 기존 MQTT/App/PUI command도 TaskManager로 들어오는가 |
중앙 실행 계층으로 정리 |
| schedule API는 DeviceAgent 내부인지 별도 서버 relay인지 |
1차 마일스톤 구현 범위 확정 |
관련 문서