← Docs hub

TaskManager Device Context Planning Spec

이 문서는 A2A planner가 DevicePlanningContext와 DeviceAgent TaskManager를 함께 사용할 때 제품/사양적으로 무엇을 만들 수 있는지 정리한다. 핵심은 기기가 단순 명령 수신기가 아니라, 현재 상태를 제공하고 장기 task를 관리하며 callback을 통해 planner가 다시 판단할 수 있는 실행 파트너가 된다는 점이다.

1. 한 줄 결론

TaskManager와 device context가 안정적으로 연결되면 A2A는 “발화를 token으로 변환하는 라우터”가 아니라 현재 상태를 보고, 작업을 등록하고, 진행 중 이벤트를 관찰하고, 필요한 순간에만 재계획하는 기기 작업 planner가 된다.

2. 현재 구현 경계

현재 스케줄링은 세 층으로 존재한다. 제품 사양에서는 이 층들을 구분해야 한다.

SCH는 자연어 소유 family이고 특정 저장소의 이름이 아니다. Cloud SCH는 발화의 의미를 해석한 뒤 native_product, deferred_task, event_continuation 중 하나를 선택한다. 기기 고유 schedule과 TaskManager schedule은 같은 “예약” 표현을 쓰지만 수명주기와 사용자 기대가 다르므로 하나의 저장소로 합치지 않는다.

2.1 2026-07-26 구현 정합 상태

schedule_kind가 전달된다는 사실과 해당 owner의 저장소에 실제 등록됐다는 사실은 구분한다. 단일 고정 청정 지연 예약은 Cloud 의미값에서 MR6 scheduleTask까지 연결됐지만, 복합 workflow와 제품 반복 예약의 owner adapter는 아직 남아 있다. 이 구간을 문자열별 분기표로 만들지 않고 capability catalog와 planner metadata로 변환해야 한다.

3. Planner가 사용할 수 있는 context

DeviceAgent DevicePlanningContextProvider 기준으로 planner가 활용할 수 있는 대표 정보는 아래다.

중요한 금지사항은 raw context를 TTS로 그대로 노출하지 않는 것이다. air_quality.co2, current_room_id, context 기준, capabilities.room_cleaning=true 같은 표현은 디버그 UI에는 표시할 수 있지만 사용자 음성 응답에는 쓰지 않는다.

4. 제품적으로 가능한 기능

4.1 현재 상태 Q&A

기기가 자신의 상태를 설명한다.

이 영역은 대부분 ODL -> DEF 성격이다. device context를 조회하지만 side effect는 없다.

4.2 즉시 복합명령

여러 기기 동작을 하나의 workflow로 묶는다.

이 영역은 ODL -> ODL이다. planner는 목표 순서를 만들고, TaskManager는 각 step의 실제 완료와 실패 reason을 관리한다.

4.3 조건부 실행

context를 먼저 읽고 조건이 맞으면 실행한다.

이 영역은 DEF/ODL -> ODL 혼합이다. 조건이 device context에 의해 결정되므로 TaskManager admission 전 context refresh가 중요하다.

4.4 작업 스케줄링

즉시 실행하지 않고 task/workflow를 예약한다.

이 영역은 SCH -> ODL/TaskManager handoff다. Cloud SCH가 schedule slot과 종류를 결정하고, 실행 owner가 등록/조회/취소를 담당한다. 실행 시점에는 deferred_task가 원래 ODL task/workflow로 TaskManager queue에 admission된다.

4.4.1 시간 표현을 구분하는 기준

단기와 장기를 분 단위 threshold 하나로 나누지는 않는다. 반복성, 사용자 관리 기대, 제품 고유 capability, 임의 workflow 여부를 함께 본다. 다만 deferred_task는 일회성만 허용하고, 반복·수정 가능한 예약은 product scheduler가 소유한다.

4.4.2 상대시간과 멱등성 계약

상대시간 발화는 각 계층이 현재 시각을 다시 추론하지 않도록 의미값을 보존한다.

Cloud SCH relative_delay_seconds
-> case-2 trigger.relative_delay_ms
-> on-device triggerAtMs = now + relativeDelayMs
-> MR6 SCHEDULED record

중복 방지는 발화 문자열이 아니라 request_id를 기준으로 한다. local shim은 짧은 전송 중복을 막고, on-device는 같은 request/session을 전달하며, MR6는 같은 request_id의 예약 record가 있으면 deduplicated=true와 기존 scheduleId를 반환한다. 네트워크 retry나 Cloud 재추론이 있어도 actuator 예약은 한 건이어야 한다.

조회 명령의 source는 두 의미를 분리한다. command envelope의 source는 호출 주체이고, payload의 source는 사용자가 명시한 record filter다. envelope source를 암묵적 filter로 사용하면 API/monitor에서 생성 주체가 다른 예약이 사라져 보이므로 금지한다.

4.5 작업 중 개입

진행 중인 task에 사용자가 개입한다.

이 영역은 callback과 active workflow state가 있어야 안정된다. 정상 진행 event는 로컬에서 처리하고, FAILED, BLOCKED, PAUSED, NEEDS_USER_INPUT처럼 판단이 필요한 event만 Cloud replan 후보가 된다.

4.5.1 실행 중 동일 작업의 NOOP 계약

Planner가 새 단일 device task를 만들었더라도, device_context.task_manager.active_tasks의 현재 step이 같은 taskMethod로 이미 RUNNING이면 Cloud dispatch preflight에서 새 task를 보내지 않는다. 이때 기존 workflow owner와 active_workflow_id를 유지하고 device_task_noop.code=ACTIVE_TASK_ALREADY_RUNNING을 반환한다. 사용자에게는 같은 작업이 이미 진행 중이라고 알린다.

이 판정은 발화 문자열이 아니라 구조화된 실행 의미를 비교한다. 현재 구현은 파라미터가 없는 단일 task에만 적용해 서로 다른 목적지나 설정값을 가진 작업을 잘못 합치지 않는다. 예를 들어 복합 workflow의 현재 step이 returnToStation인 동안 다시 복귀 명령이 들어오면 중복 task를 만들지 않는다. 2026-07-30 실기기 검증에서는 중복 제출 시 RETURN_TO_STATION_POLICY_NOT_ALLOWED와 원 workflow 중단이 발생했던 반면, 이 preflight 적용 후 단일 복귀 task는 STARTED -> COMPLETED와 물리 완료 callback까지 정상 수신됐다.

4.6 선제 대응

사용자가 묻기 전에 기기가 제안하거나 경고한다.

이 영역은 proactive agent 후보지만, side effect는 confirmation policy와 연결해야 한다.

5. Route/step 사양 기준

Planner는 이 흐름을 token 문자열이 아니라 capability, context, side-effect, schedule slot 기준으로 판단해야 한다.

6. TaskManager 지연 실행 API 목표

TaskManager schedule은 제품 예약 엔진이 아니라 일회성 task/workflow admission 예약 계약이다.

추가 정책 field도 필요하다.

현재 MR6 TaskManager 구현은 triggerAtMs/scheduledAtMs, 파일 영속화, exact alarm 재등록, missed-run grace를 갖춘 일회성 scheduler다. 반복 rule 생성은 구현돼 있지 않으므로 매일, 평일, 주말 발화를 TaskManager 반복 예약으로 표시하면 안 된다.

6.1 조건부 실행 계약

조건부 실행은 특정 발화 문자열을 코드에 나열해서 처리하지 않는다. Planner가 현재 device_context에 근거할 수 있는 조건을 step metadata로 구조화하고, runtime은 그 조건을 평가한 뒤 같은 ODL bridge/task mapper를 계속 태운다.

예시 계약:

{
  "id": "step_if_station_clean",
  "route": "ODL",
  "skill": "fixed_purify",
  "purpose": "스테이션 조건 확인 후 고정 청정 시작",
  "depends_on": [],
  "condition": {
    "type": "device_context",
    "path": "location.is_on_station",
    "operator": "is_true",
    "on_false_tts": "현재 조건이 맞지 않아 작업을 실행하지 않았습니다."
  }
}

지원하는 operator는 의미 단위로 제한한다. 발화 문자열을 코드에 직접 나열하지 않고, LLM이 선택한 path와 operator를 runtime이 평가한다.

원칙:

이 구조의 목적은 “스테이션에 있으면 청정 켜봐”, “작업 중 아니면 이동해”, “배터리 괜찮으면 복합 청정해” 같은 문장을 모두 같은 구조로 다루는 것이다. 발화별 분기를 늘리는 대신, condition path와 operator를 planner output contract로 일반화한다.

Planner에는 device_context 원본 전체를 그대로 넣지 않고 device_context_summary만 전달한다. 이 summary는 available_condition_paths, 현재 위치/도킹 여부, room name, TaskManager busy, 공기질 availability/grade 정도만 담는다. 따라서 LLM은 조건을 추론할 수 있지만, 사용자 TTS에 context, current_room_id, raw sensor key 같은 디버그 값을 노출하지 않아야 한다.

현재 runtime에서 열어둔 대표 condition path:

2026-07-24 Cloud runtime 기준 focused 검증:

python3 -m pytest test/test_e2e_orchestrator_smoke.py test/test_orchestrator_task_plan.py -q
30 passed

python3 -m pytest \
  test/test_frg_presenter_api.py \
  test/test_e2e_orchestrator_smoke.py \
  test/test_orchestrator_task_plan.py -q
35 passed

python3 -m pytest \
  test/test_task_manager.py \
  test/test_task_orchestration_roundtrip.py \
  test/test_task_event_ingest.py \
  test/test_task_event_contract_verifier.py \
  test/test_device_task_mapper.py \
  test/test_voice_task_scenario.py \
  test/test_local_lambda_shim_tool.py -q
67 passed

python3 -m py_compile \
  gemini/a2a/runtime/task_manager.py \
  gemini/a2a/runtime/orchestrator.py \
  gemini/a2a/agents/frg/presenter_api.py \
  gemini/a2a/planner/main_router_api.py \
  gemini/a2a/planner/preclassifier.py \
  gemini/a2a/planner/flow_selection_core.py

python3 -m pytest test --ignore=test/A2A_TEST \
  --ignore=test/gemini_rag_api_test.py \
  --ignore=test/rag_judge_test.py \
  --ignore=test/test_chat.py \
  --ignore=test/test_flow_shadow_selector_schedule_priority.py -q
418 passed

검증한 케이스:

라이브 orchestrator probe 결과:

Text console/local shim 설정 주의:

GEMINI_API_KEY는 shim 프로세스 시작 시점에 환경변수로 들어가야 한다. 이미 떠 있는 shim에는 나중에 export한 값이 전파되지 않으므로, 키가 없던 shim은 종료 후 재시작해야 한다. 키 값은 command line이나 wiki에 남기지 않는다.

단, 2026-07-24 현재 route_turn은 ODL bridge shortcut을 먼저 타는 케이스가 있어 planner가 항상 직접 condition step을 생성하지는 않는다. runtime compiler의 조건부 bridge는 과도기 안전장치로 유지하되, 신규 기능은 planner가 condition metadata를 직접 내리는 방향으로 확장한다.

7. 현재 확인된 gap

8. 우선순위

9. 테스트 문장

10. 제품 효과

11. 사양상 주의점

• schedule 단어만으로 SCH가 아니다. 시간/반복/등록/조회/수정/삭제/취소 의도가 있어야 한다.
• 알람/모드/청정 “켜줘/꺼줘”는 즉시 제어면 ODL이고, 시간 조건이 붙으면 SCH다.
• SCH는 저장소가 아니다. 반복 제품 예약은 native_product, 일회성 지연 실행은 deferred_task, 완료 조건은 event_continuation으로 나눈다.
• context summary는 기기 상태 조회지만 side effect가 없으므로 실행 task를 만들지 않는다.
• TaskManager는 자연어를 해석하지 않는다. Cloud가 method/subTask를 만들고 TaskManager는 lifecycle, queue, policy, event, reason을 관리한다.
• 정상 event마다 Cloud LLM을 호출하지 않는다. replan은 실패, 차단, 사용자 입력 필요, schedule admission conflict 같은 경계로 제한한다.

12. 검증 근거

• TaskManager Live Monitor: 이동 하드웨어를 제외한 복합 action, 조건, 예약, TaskManager 제어 60건의 단계별 개선 및 최종 shadow 검증 결과
• 2026-07-26 실기기 상대시간 예약: relative_delay_seconds=3600에서 relative_delay_ms=3600000, scheduleId=scheduled-4까지 전달
• 동일 request_id 재전송: deduplicated=true, 기존 scheduled-4 반환, 활성 예약 수 증가 없음
• DeviceAgent 재부팅 후 조회: scheduled-4 복원, API envelope source와 record filter 분리 확인
• 검증 종료 후 scheduled-3, scheduled-4 취소 및 활성 예약 0건 확인