← Docs hub

Adaptive Home Guardian Supervisor

Adaptive Home Guardian은 사용자 부재 중 기기가 지정 공간을 순찰하고, 로컬 Vision과 보안 상태를 관찰하며, 배터리·네트워크·음성 개입에 맞춰 안전하게 계속·중단·복귀·질문을 선택하는 대표 Agentic 시나리오다.

1. 쉽게 설명하면

이 기능은 “거실로 이동하고, 안방으로 이동하고, 스테이션으로 복귀”처럼 고정된 명령 목록을 재생하는 기능이 아니다.

목표를 기억한다
  -> 기기 상태를 관찰한다
  -> 정상 진행은 로컬에서 계속한다
  -> 의미 있는 변화만 판단한다
  -> 필요한 경우 계획을 바꾼다
  -> 물리 완료 증거로 종료한다

상위 목표는 집을 안전하게 확인하고 스테이션으로 복귀한다다. 순찰 도중 사람 감지, 저조도, 저전력, AWS 연결 단절, 사용자 음성 개입이 발생해도 이 목표는 유지된다. 다만 DeviceAgent 정책을 우회하거나 raw Vision frame을 일반 LLM prompt로 보내지는 않는다.

2. 구현 상태 범례

현재 Adaptive Home Guardian 전체는 부분 연결 상태다. 이동·복귀, Managed Security lifecycle, WSS/Vision 의미 관찰과 durable relay는 코드로 연결돼 있고 Security·Streaming·VitalSign의 확정 충돌 admission도 1차 반영됐다. Supervisor decision-to-plan bridge와 On-device 공통 OrchestrationResponse dispatch도 코드로 연결됐다. 다만 공통 owner/lease registry와 platform-signed 실기기 재계획 E2E가 남아 전체 Experience 완료 상태는 아니다.

검증 단계를 쉽게 읽는 법

3. 기능별 현재 위치

한 시나리오에서 기능군이 협업하는 방식

이 때문에 Adaptive Home Guardian은 기능을 순서대로 한 번 호출하는 매크로가 아니다. 목표가 유지되고, 상태 변화가 observation으로 축약되며, DeviceAgent의 로컬 안전 판단과 Cloud의 제한된 재계획으로 폐루프를 만드는 것이 목표다. Cloud decision-to-plan 결과는 이제 semantic observation과 task-event에 공통인 On-device 실행 관문을 통해 TaskManager bridge로 전달된다. 다만 실기기에서 전체 관찰·재계획·물리 완료를 검증하지 않았으므로 아직 완성된 폐루프는 아니다.

중요한 현재 공백

1. Cloud registry의 security_patrol은 lifecycle task로 연결됐고, 실제 보드의 WSS 가용성 조회도 수행했다. 현재 결과는 available=false, reasonCodes=5다. 이는 WSS 미구독과 PIN 미등록의 합이며 privacy, home lock, network, tilting, camera 오류는 아니다. 선행 설정이 없어 실제 WSS 물리 상태 전이는 아직 E2E 검증하지 않았다.
2. On-device는 Security 전용 문장 adapter 대신 범용 TaskManager bridge를 사용한다. 이 경계는 단위 테스트로 고정됐지만 실기기 전달 증거는 남아 있다.
3. MR6 TaskManager의 WSS start/pause/resume/stop과 terminal evidence는 코드 연결됐다. Security·Streaming·VitalSign의 확정 충돌은 typed task와 현재 상태로 조기 거절하지만 camera·Vision·movement의 공통 owner/lease는 아직 통합되지 않았다.
4. device_context.v1에는 LLM pipeline, AWS 연결, Security snapshot이 추가됐지만 Streaming과 policy blocker는 아직 없고, LLM native model readiness와 death signal도 없다.
5. Vision raw report는 WSS 내부에 유지된다. 현재 A2A로 승격되는 것은 debounced low-light, 1초 지속 person 감지, WSS session·condition과 신원정보 없는 verification outcome이다. TaskManager가 시작한 Security session의 workflow/step correlation은 코드 연결됐지만 asset lifecycle과 platform-signed 실기기 E2E 증거는 아직 없다.
6. task-event와 semantic observation의 durable outbox는 코드 연결됐지만 실기기 프로세스 kill/restart 검증과 운영 dead-letter 정책이 남아 있다.
7. Cloud decision-to-plan bridge가 생성한 catalog-grounded 요청은 deliverSemanticObservation()에서 공통 OrchestrationResponse handler로 전달된다. workflow, task, control request와 replan TTS가 task-event 응답과 같은 실행 관문을 사용하며 JVM unit, 전체 unit, assemble, lint를 통과했다. platform-signed 실기기에서 callback correlation과 physical terminal까지 확인하는 E2E는 남아 있다.

2026-07-30 Managed Security lifecycle 1차 반영

Planner typed action
  security_patrol + start|pause|resume|stop
    -> Cloud device task contract
    -> On-device generic ManagedDeviceTask
    -> MR6 security queue
    -> MainApi WSS request
    -> WSS actual state transition
    -> security.started|paused|resumed|stopped

• 사용자 문장 keyword 분기는 추가하지 않았다.
• 이미 요청 상태에 있으면 idempotent 성공 완료를 기록한다.
• 불가능한 상태 전이는 abort event로 기록해 timeout으로 숨기지 않는다.
• 구독·PIN·privacy 등 시작 admission 거절은 security_command_rejected로 즉시 실패한다.
• startSecurityMode의 취소·보상 method는 stopSecurityMode다.
• Cloud 126개, Managed Security 시점 MR6 DeviceAgent 214개와 후속 admission 포함 전체 220개, APK build, TaskManagerClient 및 On-device 관련 단위 검증은 통과했다.
• platform-signed 실기기 WSS E2E는 아직 수행하지 않았다.

현재 MR6 DeviceAgent 산출물은 A1 platform certificate로 서명해 실기기에 배포했고, local release와 system priv-app APK SHA-256 일치, 재부팅, TaskManager 초기화, Security dry-run terminal callback까지 확인했다. 실제 WSS 가용성이 false이므로 실제 Security session과 Vision-to-Cloud E2E는 수행하지 않았다.

2026-07-30 관찰 계약 1차 반영

현재 구현에는 아래 기반이 추가됐다.

1. MR6가 물리 완료·중단 evidence를 bounded semantic observation으로 저장한다.
2. DevicePlanningContextProvider가 최근 observation snapshot을 제공한다.
3. MR6가 신규 observation을 onSemanticObservation callback으로 방출한다.
4. On-device는 task event와 observation을 저장 후 순서대로 Cloud에 전달한다.
5. 프로세스가 재시작되면 app-private 큐를 읽어 미전송 event를 replay한다.
6. Cloud는 observation을 검증·중복 제거하고 workflow state에 반영한다.
7. 정상 observation은 일반 LLM 호출을 만들지 않는다.

Cloud는 requires_cloud_decision=true인 의미 경계에 한해 typed Experience Supervisor를 호출한다. decision enum, workflow당 budget, 동일 event dedup, state_etag 충돌 차단까지 코드 연결됐다. 단, decision을 실행 가능한 Planner plan으로 바꾸는 bridge, WSS event의 active workflow correlation, 실기기 restart replay 검증은 남아 있다.

AWS 연결 상태는 setAwsConnect의 최초 상태와 실제 전이만 network.aws_iot_session_changed로 기록한다. 이 observation은 telemetry이며 자동 재계획을 유발하지 않는다. Planner snapshot에는 network.aws_iot_connected가 포함되지만, 이 값은 MQTT topic 구독 완료나 publish ACK를 뜻하지 않는다.

WSS 중앙 fan-out은 WssSemanticObservationAdapter를 통해 아래 상태만 allowlist한다.

• security.session_state_changed
• vision.low_light_changed
• security.condition_changed
• security.person_detected
• security.verification_started
• security.verification_result
• security.verification_timed_out

Planner snapshot에는 Security session, stage, current area, low-light, low-battery pause가 포함된다. security.verification_result는 passed|failed|timed_out outcome과 pin|face|none method만 노출한다. 원본 Vision report, frame, bbox, 이름, member ID, 얼굴 유사도, PIN, RSSI, free-form message는 포함하지 않는다. WSS request_id는 domain 인증 세션의 상관관계일 뿐 Cloud workflow_id나 step_id가 아니다. TaskManager가 시작한 WSS session은 MainApi -> WssManager 경로에서 별도 experience_id/workflow_id/step_id allowlist를 결합하고 정지 callback 방출 뒤 제거한다. 이 correlation은 telemetry를 올바른 workflow에 붙이기 위한 것이며 event type만으로 실시간 재계획을 열지는 않는다.

LLM·음성 상태는 On-device Agent가 이미 호출하는 MainApi.setLlmStatus의 수락된 전이를 voice_llm.pipeline_state_changed로 정규화한다. observation과 Planner snapshot에는 아래 상태 축만 포함한다.

• pipeline_state
• pipeline_busy
• voice_session_active
• reasoning_backend
• output_state
• model_readiness

STT text, prompt, LLM response, TTS text는 포함하지 않는다. reported status는 실제 native model 준비 완료나 생존을 증명하지 않으므로 model_readiness=unknown을 유지한다. 정상 전이는 requires_cloud_decision=false인 telemetry이고, active workflow/step과의 correlation도 아직 없어 직접 재계획을 일으키지 않는다.

Cloud Planner는 DeviceAgent snapshot 전체를 그대로 prompt에 넣지 않는다. voice_llm, network, security에서 허용한 필드와 최근 non-stale 의미 이벤트 최대 6건의 type별 scalar allowlist만 compact context로 투영하며, 비어 있는 section은 생략한다. 이는 다음 turn의 조건·현재 상태 판단 근거이지 workflow 실행이나 Supervisor 호출 자체가 아니다.

이 연결은 발화 keyword 규칙이 아니다. DeviceAgent가 이미 정의한 숫자 상태 protocol을 typed 축으로 매핑하고 개인정보·원문을 제거하는 계약 경계다.

2026-07-30 Supervisor 1차 반영

정상 observation
  -> 상태만 갱신, LLM 무호출

explicit decision observation
  -> bounded semantic context
  -> Experience Supervisor LLM
  -> continue | ask_user | replan | abort | return_to_station | complete
  -> budget + dedup + state_etag 검증
  -> workflow decision 저장

모델이 직접 SK_xx, taskMethod, 임의 기기 명령을 만들지는 않는다. 현재 a2a-experience-plan-bridge-v1 계약은 return_to_station을 capability registry의 기본 operation과 기존 DeviceAgent task compiler로 변환한다. 일반 replan은 현재 plan에 저장된 allowed_action_contracts 안에서만 두 번째 bounded Planner를 호출한다. Planner 결과의 capability, operation, required argument, dependency를 다시 검증한 뒤에만 device_task_requests 또는 device_workflow_requests를 만든다. 모델이 taskMethod를 직접 만들지 않는다.

같은 semantic event의 decision ID는 동일한 dispatch ID를 만들며, catalog 밖 capability나 기존 plan에서 grounding되지 않은 argument는 실행하지 않는다. Gemini 일시 장애에는 Cloud가 5xx를 반환하므로 On-device outbox가 동일 event ID를 유지한 채 재시도한다. 현재 Cloud 전용 25 passed, Cloud 관련 회귀 206 passed까지 확인했다.

4. 목표 데이터 흐름

사용자 목표 또는 예약 trigger
  -> Cloud A2A Planner
     - 상위 목표, 성공 조건, 허용된 capability, replan budget 작성
  -> On-device Bridge
     - typed action과 DeviceAgent task 계약 변환
  -> DeviceAgent TaskManager
     - admission, queue, timeout, cancel, completion 관리
  -> WSS / AMR / Vision domain
     - 순찰, 사람 감지, 검증, 로컬 recovery
  -> semantic observation + task event
  -> On-device durable ordered outbox
  -> Experience Supervisor
     - continue | ask | replan | abort | return | complete

정상적인 PROGRESS와 Area 도착마다 Cloud LLM을 다시 호출하지 않는다. Domain이 처리할 수 없는 의미 경계에서만 Supervisor 판단을 요청한다.

5. 목표·관찰·판단·실행·증거

Goal

goal: 사용자 부재 중 지정 공간을 안전하게 확인한다
success:
  - admitted_area_patrol_completed
  - meaningful_security_events_handled
  - security_session_stopped
  - device_physically_docked
constraints:
  - device_policy_is_authoritative
  - raw_vision_frame_never_enters_general_llm_context
  - user_cancel_always_wins
  - bounded_replan_only

Observe

Supervisor가 받아야 하는 것은 raw sensor stream이 아니라 다음과 같은 semantic observation이다.

{
  "event_id": "obs_guardian_0007",
  "type": "security.person_detected",
  "source": "DeviceAgent.WssVisionObserver",
  "observed_at_ms": 1785400000000,
  "freshness_ms": 320,
  "confidence": 0.93,
  "privacy_class": "semantic_only",
  "correlation": {
    "experience_id": "exp_guardian_001",
    "workflow_id": "wf_guardian_001",
    "step_id": "patrol_areas"
  },
  "facts": {
    "area_id": "2",
    "presence": "detected",
    "light": "normal"
  }
}

bbox, 원본 frame, 얼굴 이미지, signed URL, credential은 이 envelope에 포함하지 않는다.

Decide

Act

초기 실행 계획은 아래 여섯 단계다.

1. Security, Map, battery, privacy, network 가용성을 확인한다.
2. WSS Security session을 시작한다.
3. WSS domain이 승인된 공간의 순찰과 Vision 관찰을 소유한다.
4. 의미 사건이 발생하면 로컬 검증 또는 제한된 Cloud 재계획을 수행한다.
5. 순찰을 종료하고 Security session 정지를 확인한다.
6. movement.stationCharging을 확인한 뒤 결과를 요약한다.

Evidence

명령 수락이나 MQTT response만으로 물리 완료를 선언하지 않는다.

6. 상태 모델

experience:
  contract_version: experience.state.v1
  experience_id: exp_guardian_001
  goal_id: adaptive_home_guardian
  status: active
  phase: patrolling
  current_area_id: "2"
  remaining_area_ids: ["3", "6"]
  active_workflow_id: wf_guardian_001
  observation_cursor: obs_guardian_0007
  domain_state:
    security: person_detecting
    movement: paused_for_verification
    network: connected_cached
    voice_llm: idle
  intervention_budget:
    local_retry_remaining: 1
    cloud_replan_remaining: 2
    user_question_remaining: 1
  terminal_evidence: []

Cloud에는 전체 raw 상태 대신 현재 판단에 필요한 allowlist만 제공한다. 정상 진행은 observation_cursor와 telemetry만 갱신한다.

7. 로컬 판단과 Cloud 재계획 경계

로컬에서 끝낼 것

• capability 존재 여부와 DeviceAgent safety/policy gate
• event debounce, duplicate suppression, freshness 판정
• 정상 Area 이동과 domain-owned 다음 순찰 단계
• 1회 이내의 안전한 local retry
• 네트워크 단절 중 로컬 관찰과 encrypted asset queue 유지
• 사용자 취소의 즉시 전달

Cloud가 판단할 것

• 상위 목표와 사용자 제약 해석
• 여러 대안 중 사용자 경험상 적절한 결과 선택
• 로컬 recovery 소진 후 다른 공간·복귀·중단 결정
• 음성 개입이 질문인지 계획 수정인지 취소인지 판정
• 불확실한 보안 사건의 사용자 알림 수준과 설명

문장 keyword로 시나리오를 분기하지 않는다. Planner는 Capability Card와 fresh semantic context를 보고 typed plan을 만들고, DeviceAgent는 실제 method grounding과 admission을 소유한다.

8. 현재와 목표의 연결표

9. 단계별 구현 순서

Phase 1. 관찰 계약

1. completion, voice_llm, network, security와 person/verification producer는 유지하고 policy producer를 단계적으로 연결한다.
2. 현재 연결한 person_detected, low_light_changed, verification_result의 workflow/step correlation을 platform-signed 실기기에서 검증한다.
3. 모든 observation에 source, timestamp, freshness, privacy class를 붙인다.
4. MR6 observation을 기존 Binder callback policy를 통해 On-device receiver로 전달한다.

Phase 2. Managed Security lifecycle

1. check/start/pause/resume/stop TaskManager capability 등록은 코드 완료.
2. WSS running state와 TaskManager terminal event 연결은 코드 완료.
3. Security·Streaming·VitalSign의 확정 충돌 admission은 1차 코드 완료.
4. camera, Vision, motion, mic, display의 공통 owner/lease 통합은 남아 있다.

Phase 3. A2A 연결

1. Cloud registry의 security_patrol lifecycle 등록은 코드 완료.
2. 온디바이스는 전용 mapping 대신 범용 typed task bridge를 재사용한다.
3. task event와 observation을 ordered durable outbox로 전송한다.
4. 정상 진행과 requires_cloud_decision을 분리한다.
5. semantic observation과 task-event의 Cloud 응답을 공통 OrchestrationResponse dispatch 관문으로 처리하는 코드는 완료했다.

Phase 4. Supervisor MVP

1. typed decision의 capability-grounded task/Planner plan 변환은 Cloud 코드와 전용 회귀까지 완료했다.
2. 사람 감지, 저조도, 배터리 부족, AWS 단절, 음성 개입을 검증한다.
3. Console에 Goal -> Observe -> Decide -> Act -> Evidence를 표시한다.
4. 실기기에서 Security 종료와 물리 도킹까지 E2E 증거를 수집한다.

10. 검증 시나리오

현재 통과를 주장할 수 있는 범위는 이동·복귀·generic TaskManager lifecycle의 부분 검증뿐이다. HG-01부터 HG-10까지의 전체 실기기 검증은 아직 남아 있다.

11. 소스 근거

MR6 DeviceAgent

• apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskExecutorBootstrap.java
• apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskManager.java
• apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskCompletionStateStore.java
• apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/DevicePlanningContextProvider.java
• apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/recognition/VisionAIManager.java
• apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/wss/vision/WssVisionObserver.java
• apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/wss/WssManager.java
• apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/llm/LlmManager.java
• apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/interaction/InterScheduleManager.java
• apps/IotAgent/app/src/main/java/com/sk/airbot/iotagent/mqtt/client/AWSIoTMQTTClient.java
• apps/IotAgent/app/src/main/java/com/sk/airbot/iotagent/mqtt/topic/IotTaskManagerBridge.java

On-device Agent

• app/src/main/java/com/skmagic/ondeviceai/agent/service/ForegroundService.kt
• app/src/main/java/com/skmagic/ondeviceai/agent/service/DeviceCommunicator.kt
• app/src/main/java/com/skmagic/ondeviceai/agent/service/CloudIntentWorkflowRunner.kt
• app/src/main/java/com/skmagic/ondeviceai/agent/service/DurableOrderedDeviceEventOutbox.kt

Cloud A2A

• gemini/a2a/registry/capability_registry.v2.json
• gemini/a2a/planner/main_router_api.py
• gemini/a2a/runtime/task_manager.py
• gemini/a2a/runtime/workflow_state.py

12. 관련 문서

• DeviceAgent 기능·데이터 카탈로그
• Capability 조합 가이드
• Device Context v2 계약
• Experience Supervisor
• Adaptive Home Guardian Plan JSON
• Agentic Capability 변경 이력