← Docs hub

A2A Scenario Walkthroughs

이 페이지는 실제 사용자 발화가 Cloud A2A, Runtime, 온디바이스 Bridge, DeviceAgent TaskManager를 거쳐 어떻게 처리되는지 시나리오별로 보여준다.

목표는 “어떤 모듈이 무엇을 판단하고, 어떤 데이터가 다음 계층으로 넘어가는지”를 한눈에 확인하는 것이다.

공통 흐름

사용자 발화
-> Cloud Planner
-> Cloud Runtime / Orchestrator
-> Cloud-only agent 실행 또는 device_task_requests 생성
-> 온디바이스 Bridge
-> DeviceAgent TaskManager
-> task_event
-> Cloud 기록 또는 replan

모든 시나리오에서 중요한 원칙:

• Planner는 selector가 아니라 step plan을 만든다.
• Runtime은 plan을 실행 가능한 Cloud step 또는 device request로 바꾼다.
• 정상 device event는 Cloud LLM 재판단 없이 기록과 local unlock에 사용한다.
• 실패/차단/사용자 결정 필요 event만 replan 후보가 된다.

Scenario 1. Cloud-only multi-step

발화:

보통 교통상황이 안 좋은 곳을 알아보고 오늘 그곳 정보를 알려줘

Planner 판단:

turn_mode = multi_turn 또는 singleton with multi-step plan
step_1 route=FRG purpose=상습 정체 지역 후보 검색
step_2 route=FRG purpose=step_1 결과 지역의 오늘 정보 검색 input_from=step_1
step_3 route=DEF purpose=사용자에게 자연어 요약 input_from=step_2

Runtime 처리:

step_1 -> FRG agent
step_2 -> FRG agent, step_1 output 사용
step_3 -> DEF response synthesis

Device 처리:

device_task_requests = []

Cloud 재판단:

정상 흐름에서는 없음.
FRG 실패, 외부 API 오류, 결과 불충분 시 Cloud 내부 fallback 또는 사용자 확인으로 전환.

핵심:

• 이 시나리오는 온디바이스 TaskManager를 쓰지 않는다.
• input_from이 중요하고, depends_on은 실행 순서 보조로만 쓰인다.

Scenario 2. Device-only sequential workflow

발화:

거실로 가서 공기청정하고 안방으로 이동해줘

Planner 판단:

step_1 route=ODL purpose=거실 이동 execution_target=device
step_2 route=ODL purpose=거실 청정 시작 execution_target=device depends_on=step_1 wait_policy=completed
step_3 route=ODL purpose=안방 이동 execution_target=device depends_on=step_2 wait_policy=completed

Runtime 변환:

device_task_requests = [
  {
    task_type: "device_intent_step",
    cloud_step_id: "step_1",
    token_text: "<sk_100>(position=거실)<sk_end>",
    depends_on: [],
    wait_policy: "completed"
  },
  {
    task_type: "device_intent_step",
    cloud_step_id: "step_2",
    token_text: "<sk_4>(position=거실)<sk_end>",
    depends_on: ["step_1"],
    wait_policy: "completed"
  },
  {
    task_type: "device_intent_step",
    cloud_step_id: "step_3",
    token_text: "<sk_100>(position=안방)<sk_end>",
    depends_on: ["step_2"],
    wait_policy: "completed"
  }
]

On-device 처리:

ForegroundService
-> CloudIntentWorkflowRunner
-> step_1 RUNNING
-> step_1 COMPLETED
-> step_2 unlock
-> step_2 COMPLETED
-> step_3 unlock
-> step_3 COMPLETED
-> WORKFLOW_COMPLETED

DeviceAgent 처리:

submitTask(step_1)
onTaskEvent(COMPLETED, step_1)
submitTask(step_2)
onTaskEvent(COMPLETED, step_2)
submitTask(step_3)
onTaskEvent(COMPLETED, step_3)

Cloud 재판단:

COMPLETED / WORKFLOW_COMPLETED는 재판단하지 않는다.
Cloud는 상태 기록과 user-visible progress에만 사용한다.

핵심:

• 물리적 순서가 중요하므로 depends_on과 wait_policy=completed가 필수다.
• Cloud LLM은 각 task 완료마다 다시 돌지 않는다.
• ComeToMe처럼 내부 lifecycle이 긴 device 기능을 A2A/TaskManager workflow로 보는 상세 예시는 19.comToMe A2A Workflow Example을 본다.

Scenario 3. Mixed Cloud + Device workflow

발화:

오늘 미세먼지 상태를 확인하고 나쁘면 거실 청정 시작해줘

Planner 판단:

step_1 route=FRG 또는 ODL purpose=현재 미세먼지/공기질 확인
step_2 route=ODL purpose=조건이 나쁘면 거실 청정 시작 input_from=step_1 execution_target=device

Runtime 처리:

step_1 -> Cloud/public lookup 또는 device state query
step_2 -> 조건 충족 시 device_task_requests 생성

조건 판단 위치:

Cloud가 public/weather/air-quality 정보를 해석해야 하면 Cloud step.
기기 내부 센서 상태를 봐야 하면 device_context 또는 ODL state query.
실제 청정 시작은 DeviceAgent TaskManager task.

On-device 처리:

조건 충족 후 내려온 device_task_requests만 실행.
조건 불충족이면 task 등록 없이 사용자에게 결과 안내.

Cloud 재판단:

조건 판단은 plan 실행 중 한 번 필요하다.
하지만 device task가 시작된 뒤 정상 진행 event마다 재판단하지 않는다.

핵심:

• mixed workflow는 input_from과 execution_target이 둘 다 중요하다.
• Cloud-only 판단과 device execution의 경계를 흐리면 token 비용과 오동작 위험이 커진다.

Scenario 4. Failure and replan

발화:

거실로 갔다가 안방으로 가서 청정해줘

정상 plan:

step_1 ODL move 거실
step_2 ODL move 안방 depends_on=step_1
step_3 ODL clean 안방 depends_on=step_2

실패 event:

{
  "eventName": "BLOCKED",
  "cloud_workflow_id": "wf_123",
  "cloud_step_id": "step_2",
  "task_id": "task_456",
  "taskMethod": "move",
  "requires_cloud_decision": true,
  "reason_code": "PATH_BLOCKED",
  "reason_params": {
    "target_room": "안방",
    "blocked_area": "복도"
  }
}

Cloud 처리:

workflow_state.py가 event를 기록한다.
requires_cloud_decision=true이므로 replan 후보로 표시한다.
Planner/replan은 reason_code와 현재 workflow state를 보고 다음 행동을 결정한다.

가능한 replan:

1. 사용자에게 "안방으로 가는 길이 막혀 있어요. 거실에서 청정을 시작할까요?" 확인
2. 대체 경로가 가능하면 DeviceAgent에 alternative move task 생성
3. 전체 workflow cancel 후 안전 정지

핵심:

• 자연어 reason만 보내면 안정적인 replan이 어렵다.
• reason_code, reason_params, requires_cloud_decision이 있어야 Cloud가 정책적으로 판단할 수 있다.

Scenario 5. User interruption

진행 중 workflow:

step_1 거실 이동 RUNNING
step_2 거실 청정 WAITING_DEPENDENCY
step_3 안방 이동 WAITING_DEPENDENCY

새 발화:

아니 그거 취소하고 지금 날씨 알려줘

Planner 판단:

current utterance is primary
cancel active workflow
new route=FRG purpose=현재 날씨 lookup

On-device 처리:

active workflow cancel request
pending device steps cleanup
running task cancel 또는 safe stop

Cloud 처리:

session_state에서 기존 workflow 종료/취소 기록
새 FRG step 실행

핵심:

• active workflow가 있더라도 현재 발화가 topic shift/cancel이면 기존 workflow를 계속 밀면 안 된다.
• 취소는 Cloud plan과 온디바이스 task queue 양쪽에서 정리되어야 한다.

시나리오별 핵심 필드

다음에 볼 페이지

• Planner and Routing
• Contract Matrix
• Device Task Flow
• Validation Guide