A2A Vendor Handoff

이 페이지는 SoC/DeviceAgent 업체에 전달해야 하는 구현 요구사항을 정리한다.

A2A Vendor Handoff Diagram

업체가 구현해야 하는 핵심

영역	요구사항
DevicePlanningContextProvider	Cloud plan 전에 필요한 최소 기기 상태 snapshot 제공
TaskManager	`submitTask`, `submitWorkflow`, `getTaskStatus`, `cancelTask` 제공
Task Event	`QUEUED`, `RUNNING`, `PROGRESS`, `COMPLETED`, `WORKFLOW_COMPLETED`, `FAILED`, `BLOCKED`, `PAUSED` 전달
Reason Contract	실패/차단 사유를 `reason_code`, `reason_params`로 구조화
Trace Metadata	`cloud_workflow_id`, `cloud_step_id`, `cloud_plan_id`, `cloud_output_key` 보존
Queue Policy	순차 실행, 의존성, 취소, 중복 처리 정책 정의

Cloud가 필요로 하는 Device Context

battery
map/room availability
current room
movement availability
cleaning/running state
task queue state
capability availability

이 정보는 Cloud가 애초에 불가능한 plan을 만들지 않도록 돕는다.

Task Event 최소 스키마

eventName/status
task_id
taskMethod
cloud_workflow_id
cloud_step_id
cloud_plan_id
cloud_output_key
requires_cloud_decision
reason_code
reason_params
progress
timestamp

Reason Code 원칙

자연어 reason만 보내면 Cloud가 안정적으로 정책 판단하기 어렵다. DeviceAgent는 구조화된 code와 params를 보내고, 사용자에게 보여줄 문장은 Cloud 또는 온디바이스가 만들 수 있어야 한다.

예:

{
  "reason_code": "PATH_BLOCKED",
  "reason_params": {
    "target_room": "안방",
    "blocked_area": "복도"
  },
  "requires_cloud_decision": true
}

완료 기준

TaskManager API가 온디바이스에서 호출 가능하다.
복합 workflow가 순차 실행된다.
정상 완료는 Cloud LLM 재판단 없이 다음 task로 진행된다.
실패/차단은 구조화된 reason과 함께 Cloud에 올라간다.
ADB 실기기 logcat에서 trace field가 확인된다.