← Docs hub

19.comToMe DeviceAgent Contract

이 문서는 /home/silogood/work/19.comToMe 폴더의 ComeToMe 설계를 DeviceAgent/SoC 업체가 실제 구현 계약으로 옮길 때 필요한 항목을 정리한다.

기준 원본:

/home/silogood/work/19.comToMe/docs/strategy/short-term/com-to-me-system-design.md
/home/silogood/work/19.comToMe/docs/strategy/short-term/com-to-me-speaker-recognition-service-scenario.md
/home/silogood/work/19.comToMe/docs/diagrams/com-to-me-flow.mmd
/home/silogood/work/19.comToMe/docs/diagrams/com-to-me-speaker-recognition-service.svg

1. 핵심 결론

ComeToMe는 단순히 set 함수 하나로 끝나는 ODL 명령이 아니다. 호출어, 의도 분류, stage gate, 화자인식, DoA, 회전, Vision, AMR, FollowMe, 후속 task가 이어지는 장기 device workflow다.

따라서 구현 책임은 아래처럼 나누는 것이 맞다.

Cloud가 DoA/Vision/AMR 단계마다 LLM으로 판단하면 안 된다. 정상 진행은 DeviceAgent 내부 상태 머신이 처리하고, Cloud는 실패/차단/사용자 결정 필요 이벤트에서만 개입한다.

2. Cloud에서 내려가는 최소 intent

Cloud는 아래 수준까지 내려주면 충분하다.

2.1 사용자 방향 기반

{
  "method": "submitTask",
  "taskMethod": "comeToMe",
  "source": "cloud_a2a",
  "cloud_workflow_id": "wf_cometome_001",
  "cloud_step_id": "step_1",
  "cloud_output_key": "cometome_result",
  "commandType": "user_direction",
  "utterance": "나에게와",
  "rolloutStage": "0-1"
}

2.2 등록 장소 기반

{
  "method": "submitTask",
  "taskMethod": "comeToMe",
  "source": "cloud_a2a",
  "cloud_workflow_id": "wf_cometome_002",
  "cloud_step_id": "step_1",
  "cloud_output_key": "cometome_result",
  "commandType": "place_name",
  "roomName": "거실",
  "rawTarget": "거실로와",
  "rolloutStage": "0-2"
}

2.3 후속 연속동작 포함

{
  "method": "submitWorkflow",
  "workflowName": "come_to_me_followup_workflow",
  "source": "cloud_a2a",
  "cloud_workflow_id": "wf_cometome_003",
  "subTasks": [
    {
      "taskMethod": "comeToMe",
      "commandType": "place_name",
      "roomName": "거실",
      "rolloutStage": "2",
      "cloud_step_id": "step_1",
      "cloud_output_key": "cometome_arrival_context"
    },
    {
      "taskMethod": "deviceFollowupAction",
      "inputFrom": "cometome_arrival_context",
      "cloud_step_id": "step_2",
      "cloud_output_key": "followup_result"
    }
  ]
}

3. DeviceAgent 내부 task lifecycle

DeviceAgent는 comeToMe를 받으면 아래 순서의 상태 머신으로 처리해야 한다.

submitTask(comeToMe)
-> task_id 생성
-> stage gate 확인
-> commandType 분기
   - user_direction: DoA -> Rotation -> Vision -> target_pose
   - place_name: LocationResolver -> registered pose -> target_pose
-> AMR 이동
-> 도착 후 사용자 확인
-> FollowMe 시작
-> stage >= 2이면 후속 task context 생성
-> 완료 또는 실패 event 발행

각 내부 단계는 독립 모듈이지만, 순서 제어와 실패 정책은 TaskManager가 가진다.

4. Stage gate 계약

원본 설계의 rollout stage를 그대로 계약화하면 아래와 같다.

DeviceAgent는 stage 밖 기능을 실행하면 안 된다. 예를 들어 stage 0-1에서 "거실로와"가 들어오면 AMR 이동을 시작하지 않고 FEATURE_STAGE_UNAVAILABLE 또는 ROOM_NAVIGATION_STAGE_DISABLED 계열 reason을 올려야 한다.

5. 필수 데이터 모델

5.1 ComeToMe task context

{
  "task_id": "tm_task_001",
  "taskMethod": "comeToMe",
  "rolloutStage": "1",
  "commandType": "user_direction",
  "roomName": "",
  "speaker_id": "spk_001",
  "map_id": "home_map_001",
  "target_pose": {
    "x": 1.25,
    "y": 2.4,
    "theta": 0.0
  },
  "state": "MOVING_TO_TARGET",
  "retry_count": 0,
  "cloud_workflow_id": "wf_cometome_001",
  "cloud_step_id": "step_1",
  "cloud_output_key": "cometome_result"
}

5.2 Registered location

{
  "locationId": "loc_living_room_001",
  "ownerSpeakerId": "spk_001",
  "roomName": "거실",
  "aliases": ["거실", "큰방"],
  "pose": {
    "x": 3.2,
    "y": 1.8,
    "theta": 1.57
  },
  "mapId": "home_map_001",
  "updatedAtMs": 1760000000000
}

5.3 Speaker verification result

{
  "speakerId": "spk_001",
  "displayName": "사용자1",
  "score": 0.62,
  "margin": 0.14,
  "threshold": 0.5,
  "accepted": true,
  "reason": "ACCEPTED"
}

6. Callback / event 계약

정상 진행 event는 Cloud로 올라가도 되지만 Cloud LLM을 다시 돌리면 안 된다. Cloud 판단이 필요한 event만 requires_cloud_decision=true로 올린다.

6.1 정상 event

{
  "eventName": "PROGRESS",
  "task_id": "tm_task_001",
  "taskMethod": "comeToMe",
  "state": "VISION_TARGET_FOUND",
  "cloud_workflow_id": "wf_cometome_001",
  "cloud_step_id": "step_1",
  "progress": 55,
  "requires_cloud_decision": false,
  "eventPayload": {
    "doaAngleDeg": 42.0,
    "visionConfidence": 0.82,
    "distanceM": 2.1
  }
}

6.2 실패 event

{
  "eventName": "FAILED",
  "task_id": "tm_task_001",
  "taskMethod": "comeToMe",
  "state": "SPEAKER_GATE",
  "cloud_workflow_id": "wf_cometome_001",
  "cloud_step_id": "step_1",
  "reason_code": "SPEAKER_VERIFICATION_FAILED",
  "reason_params": {
    "rolloutStage": "1",
    "score": 0.42,
    "threshold": 0.5,
    "margin": 0.03,
    "commandType": "user_direction"
  },
  "requires_cloud_decision": true,
  "suggested_action": "ASK_USER_RETRY_OR_ENROLL"
}

7. Reason code 표준 후보

8. 업체 구현 범위

업체가 최소로 구현해야 하는 항목은 아래다.

9. 검증 fixture

ADB가 없을 때도 우선 JSON fixture로 아래를 검증해야 한다.

10. 업체에 반드시 확인할 질문

11. 관련 문서

• 19.comToMe A2A Workflow Example
• SoC TaskManager Execution Subsystem
• DeviceAgent / SoC Domain Map
• DeviceAgent TaskManager API Contract
• Vendor API Acceptance Checklist
• Vendor Open Questions