← Docs hub

19.comToMe A2A Workflow Example

이 문서는 /home/silogood/work/19.comToMe 폴더의 설계 자료를 A2A Wiki 관점으로 다시 정리한 것이다.

실제 폴더 내용은 command 하나가 아니라 ComeToMe 이동/추종 기능 설계다. 따라서 이 문서는 아래 기능을 A2A/TaskManager 구조에 어떻게 얹을지 설명한다.

• "나에게와" 사용자 방향 기반 ComeToMe
• "거실로와", "주방으로와" 같은 등록 장소 기반 이동
• 1단계 이상에서 등록 화자 확인 gate
• DoA, Vision, AMR, FollowMe를 연결하는 장기 task lifecycle
• 2단계 이상에서 화자/공간 기반 후속 연속동작
• 3단계에서 후속 기능 제안

원본 근거:

/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. 실제 19.comToMe 폴더 내용

현재 폴더는 코드 구현체보다 설계 문서와 다이어그램 중심이다.

핵심은 ComeToMe를 단발 ODL 명령으로 보면 안 된다는 점이다. 이 기능은 호출어, 의도 분류, stage gate, 화자인식, DoA, Vision, AMR, FollowMe, 후속 task가 이어지는 장기 device workflow다.

2. 단계별 기능 범위

원본 설계는 ComeToMe를 0-1, 0-2, 1, 2, 3 단계로 확장한다.

3. A2A에서의 해석

Cloud A2A Planner는 ComeToMe 내부의 DoA/Vision/AMR 세부 단계를 매번 LLM으로 재계획하면 안 된다. Cloud의 역할은 사용자의 발화를 다음처럼 큰 의도와 slot으로 정리하는 것이다.

예시 발화:

하이나무, 나에게와

Planner 관점:

{
  "turn_mode": "singleton",
  "selected_routes": ["ODL"],
  "steps": [
    {
      "id": "step_1",
      "route": "ODL",
      "purpose": "사용자 방향 기반 ComeToMe 실행",
      "execution_target": "device",
      "device_intent": {
        "method": "comeToMe",
        "params": {
          "commandType": "user_direction",
          "utterance": "나에게와"
        }
      }
    }
  ]
}

예시 발화:

하이나무, 거실로와

Planner 관점:

{
  "turn_mode": "singleton",
  "selected_routes": ["ODL"],
  "steps": [
    {
      "id": "step_1",
      "route": "ODL",
      "purpose": "등록 장소 기반 ComeToMe 실행",
      "execution_target": "device",
      "device_intent": {
        "method": "comeToMe",
        "params": {
          "commandType": "place_name",
          "roomName": "거실",
          "utterance": "거실로와"
        }
      }
    }
  ]
}

4. DeviceAgent TaskManager로 내려가는 구조

온디바이스 Bridge는 Cloud step을 DeviceAgent TaskManager.submitTask 또는 submitWorkflow로 넘긴다.

단일 ComeToMe task 예:

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

2단계 이상에서 후속 연속동작이 붙는 경우는 workflow가 된다.

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

중요한 점:

• Cloud는 DoA -> 회전 -> Vision -> target_pose -> AMR -> FollowMe를 세부 task로 쪼개서 매번 판단하지 않는다.
• DeviceAgent의 ComeToMeTaskManager 또는 TaskManager 내부 executor가 이 세부 lifecycle을 관리해야 한다.
• Cloud가 개입하는 시점은 실패/차단/사용자 확인 필요처럼 requires_cloud_decision=true인 경우다.

5. ComeToMe TaskManager 내부 lifecycle

원본 설계의 lifecycle은 다음 구조다.

A1 대기
-> 호출어 "하이나무" 감지
-> ComeToMe 의도 분류
-> rollout stage 확인
-> stage >= 1이면 등록 화자 확인
-> 명령 타입 분기
   - user_direction: DoA 각도 판별 -> 회전 -> Vision 사용자 감지 -> target_pose 생성
   - place_name: 장소명 해석 -> 등록 장소 좌표 조회 -> target_pose 생성
-> AMR에 target_pose 전달
-> AMR 목적지 도착
-> Vision / Speaker 사용자 확인
-> FollowMe 대상 확인
-> FollowMe 수행
-> stage >= 2이면 후속 연속동작
-> stage >= 3이면 후속 기능 제안

이 lifecycle은 DeviceAgent/SoC 쪽에서 task state machine으로 구현되어야 한다.

6. 화자인식 gate

원본 com-to-me-speaker-recognition-service-scenario.md 기준:

• Sherpa ONNX SpeakerEmbeddingExtractor를 사용한다.
• PoC 기준 engine 기본 threshold는 0.45f, 서비스 수락 기준은 0.50f 후보로 기록되어 있다.
• 등록은 3회 이상 발화를 기준으로 speaker profile을 만든다.
• 식별은 best speaker, score, 2위 후보와 margin, 다화자/겹침/잡음 stop 조건을 함께 본다.
• 1단계 이상에서만 ComeToMe/장소 이동 앞단에 등록 화자 확인 gate를 둔다.

판단 결과 예:

data class SpeakerVerificationResult(
    val speakerId: String?,
    val displayName: String?,
    val score: Float,
    val margin: Float?,
    val threshold: Float,
    val accepted: Boolean,
    val reason: String
)

TaskManager 판단:

7. 실패 reason contract

ComeToMe는 물리 이동과 사용자 인식이 결합된 기능이므로 실패 reason이 중요하다.

예시 event:

{
  "eventName": "FAILED",
  "taskMethod": "comeToMe",
  "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,
    "commandType": "user_direction"
  },
  "requires_cloud_decision": true,
  "suggested_action": "ASK_USER_RETRY_OR_ENROLL"
}

8. A2A 통합 설계 판단

권장 구조:

• Cloud Planner는 comeToMe를 ODL device intent로 판단한다.
• Cloud Runtime은 device_task_requests로 변환한다.
• On-device Bridge는 TaskManager.submitTask 또는 submitWorkflow로 전달한다.
• DeviceAgent는 ComeToMeTaskManager 또는 TaskManager executor에서 stage gate와 세부 lifecycle을 관리한다.
• DoA/Vision/AMR/FollowMe 정상 진행은 로컬에서 처리한다.
• Cloud replan은 structured reason과 requires_cloud_decision=true가 있는 경우만 연다.

피해야 할 구조:

• Cloud가 DoA/Vision/AMR 세부 이벤트마다 LLM을 호출한다.
• Cloud가 target_pose를 추측해서 직접 만든다.
• 화자인식 실패에도 이동을 시작한다.
• 장소명 기반 이동에서 등록 좌표와 현재 map frame 일치성을 확인하지 않는다.
• Vision 120도/3m 범위를 벗어난 사용자를 억지로 target으로 만든다.
• FollowMe 전환 시 사용자 후보 연속성 검증을 하지 않는다.

9. 원본 설계의 주요 제약

원본 설계에서 명시된 중요한 제약:

• Vision은 전방 120도, 3m 이내에서 안정적으로 좌표 특정이 가능한 것으로 가정한다.
• "일로와", "따라와"처럼 의미/음향 패턴이 가까운 발화 간 의도 분류 혼동 가능성이 있다.
• DoA 오차가 크면 회전 후 Vision 유효 범위에 사용자가 들어오지 않을 수 있다.
• 화자인식은 등록 음성 품질, 주변 소음, 발화 길이, 마이크 입력 품질에 따라 false accept/false reject가 발생할 수 있다.
• 음성 프로필은 생체 정보에 준해 동의/삭제/암호화 정책이 필요하다.
• 장소명 기반 이동은 방 이름과 좌표의 최신성, map frame 일치성, 중복/유사 장소명 처리에 영향을 받는다.

10. 검증 시나리오

11. 관련 문서

• 19.comToMe DeviceAgent Contract
• SoC TaskManager Execution Subsystem
• DeviceAgent / SoC Domain Map
• Device Task Flow
• Validation Guide
• Vendor API Acceptance Checklist