← Docs hub

DeviceAgent Agentic Capability Composition Guide

이 문서는 DeviceAgent 기능을 새로운 Agentic 시나리오로 조합하기 위한 실무 규격이다. 자연어 키워드와 개별 method를 직접 연결하는 룰 모음이 아니라, 의미 capability와 실제 실행·관찰 계약 사이의 경계를 정의한다.

1. Capability Card를 두는 이유

Planner가 DeviceAgent의 모든 AIDL·Bundle method를 직접 보게 하면 다음 문제가 생긴다.

• 같은 기능의 legacy·TaskManager·domain method 중 잘못된 경로를 선택한다.
• 명령 수락을 물리 완료로 오인한다.
• Vision, WSS, Streaming, VitalSign의 자원 충돌을 알기 어렵다.
• 새 method가 추가될 때 prompt와 후처리 코드를 동시에 수정해야 한다.
• 자연어 표현별 예외가 늘어 룰 기반 라우팅으로 퇴행한다.

Capability Card는 이 문제를 아래 두 단계로 분리한다.

LLM Planner
  사용자 목표 -> semantic capability와 의존관계

Deterministic Runtime
  capability -> 검증된 method, queue, timeout, resource, terminal evidence

LLM은 무엇을 왜 어떤 순서로 할지를 결정한다. DeviceAgent는 지금 실행해도 안전한지, 어떤 실제 method를 쓸지, 정말 끝났는지를 판정한다.

2. Capability Card 필드

기계 판독 자산:

• Capability Card JSON Schema
• 현재 Capability Card Catalog
• Adaptive Home Guardian Plan

2.1 성숙도와 Planner 사용 범위

현재 move_to_room, return_to_station, start_room_cleaning, schedule_workflow, after_step_delay, product_interaction은 M3 후보다. security_patrol, voice_content, vital_sign_session은 관찰 계약이 불완전한 M2이고, live_view는 현재 No-Go다.

2.2 Cloud runtime binding manifest

Capability Card ID는 시나리오 의미 ID이고 Cloud catalog ID와 이름이 항상 같지는 않다. deviceagent-agentic-capability-cards.json의 deviceagent-cloud-runtime-binding.v1 manifest가 아래 세 연결을 명시한다.

• cloud_capability_ids: 현재 capability_registry.v2.json에 존재하는 실행·상태 capability
• route_families: DEF·FRG·STM·ETR·SCH처럼 전문 Agent가 소유하는 결과
• workflow_primitives: after_step, scheduleWorkflow, experience_supervisor처럼 단일 기기 capability가 아닌 orchestration 기능

현재 18개 Card는 14개 connected, 3개 partial, 1개 blocked다. start_room_cleaning -> stationary_purify, vital_sign_session -> vital_signs, air_quality_assessment -> check_air_quality처럼 이름이 다른 연결도 자동 감사한다. voice_content, product_interaction, perception_presence_assessment는 일부 경계만 연결돼 partial이고, live_view는 Binder 보안과 terminal 계약이 닫힐 때까지 blocked다.

이 manifest는 문장 keyword를 method로 치환하는 규칙이 아니다. Planner가 선택한 의미 Card가 실제 catalog·전문 Agent·workflow primitive 중 어느 실행 평면으로 내려가는지 검증하는 구조 계약이다.

3. 기능 간 Resource Compatibility

표의 의미:

• A: 독립 lifecycle로 병행 가능
• C: 조건부. DeviceAgent admission 또는 domain pause/resume 필요
• X: exclusive resource 충돌
• D: 해당 domain이 내부적으로 소유해야 하며 외부 workflow가 분해 금지
• ?: 현재 코드 evidence만으로 안전한 병행을 보장할 수 없음

이 표는 Cloud가 안전을 우회하기 위한 허용표가 아니다. Cloud는 충돌 가능성을 조기에 발견해 계획을 조정하고, 최종 판정은 DeviceAgent가 현재 main state와 domain state를 읽고 수행한다.

3.1 현재 코드에서 확인된 강한 충돌

• Streaming 시작은 VitalSign 실행 중 거절된다.
• Streaming은 Vision pipeline을 비활성화하고 AMR manual mode를 소유한다.
• WSS는 privacy, home lock, PIN, subscription, network, battery, Map, camera, tilting, drive 상태를 검사한다.
• WSS와 VitalSign은 main-state 정책상 동시 실행할 수 없다.
• WSS 순찰 이동은 WSS domain이 소유하므로 외부에서 독립 setMoveTo 단계를 섞어서는 안 된다.

3.2 아직 공통 lease가 아닌 것

현재 TaskResourcePolicy는 opt-in CPU·RAM·thermal threshold만 판정한다. camera, microphone, display, AMR manual mode, security session 같은 기능 자원은 domain 내부 조건문에 분산돼 있다. 목표 구조는 이를 CapabilityResourceRegistry 같은 device-side registry로 모으는 것이다.

4. 시나리오 조립 절차

4.1 Goal 정규화

사용자 발화를 method 목록으로 바꾸지 않고 다음을 먼저 만든다.

goal:
  outcome: "사용자 부재 중 집을 안전하게 확인"
  success:
    - "지정 공간 관찰 완료"
    - "중요 이벤트 처리"
    - "스테이션 복귀"
  constraints:
    - "privacy 우회 금지"
    - "사용자 취소 우선"

4.2 Capability 후보 선택

Planner는 catalog 설명과 현재 context를 사용해 capability를 선택한다. 실제 method는 catalog/runtime adapter가 결정한다.

goal 보호
  -> security_patrol
  -> return_to_station
  -> voice_content

4.3 Slot grounding

• 공간은 map.rooms의 ID·이름으로 resolve한다.
• 좌표를 LLM이 생성하지 않는다.
• 공기질·배터리·네트워크는 freshness가 있는 context만 사용한다.
• 누락된 slot이 안전과 무관하면 device default를 사용한다.
• 안전·대상 slot이 모호하면 사용자가 확인하기 전 실행하지 않는다.

4.4 Resource graph 생성

각 capability의 exclusive/shared resource를 합쳐 충돌을 찾는다.

security_patrol:
  exclusive = camera + vision_pipeline + security_session

live_view:
  exclusive = camera + vision_pipeline + streaming_session

result:
  같은 phase에서 병행 불가

4.5 실행 graph 생성

availability
  -> start security
  -> domain-owned patrol
  -> stop security
  -> return station
  -> summarize

depends_on, wait_for, timeout, cancel, compensation을 명시한다. 사용자 문장을 다시 파싱해 다음 단계를 생성하지 않는다.

4.6 완료 evidence 확인

일반 task의 주요 event는 STARTED, PROGRESS, COMPLETED, FAILED, CANCELLED와 workflow-step event다. 예약 admission은 별도로 BLOCKED를 내보낼 수 있다.

4.7 Bounded replan

모든 progress에 LLM을 호출하지 않는다.

5. 조합 가능한 대표 시나리오

6. Adaptive Home Guardian 실행 계약

전용 Supervisor 문서는 실제 source 근거, 현재 연결 상태, semantic observation, 로컬/Cloud 판단 경계와 검증 시나리오를 한 흐름으로 설명한다.

실행 계약 JSON은 다음을 구조화한다.

• 목표와 성공 조건
• admission context
• exclusive·shared resource lease
• 단계별 capability와 의존관계
• 단계별 completion target
• event별 local action과 Cloud decision
• local retry·Cloud replan·사용자 질문 budget
• 현재 구현 차단 항목

현재 계약 중 Security lifecycle, ordered relay, a2a-experience-plan-bridge-v1은 runtime code에 연결됐다. Supervisor decision-to-plan bridge는 Cloud 코드로 연결됐다. 모델은 raw taskMethod를 만들지 않고 현재 plan의 allowed_action_contracts와 capability catalog 안에서만 task/workflow를 생성한다. semantic observation과 task-event 응답은 On-device의 공통 OrchestrationResponse handler에서 workflow, task, control request를 같은 TaskManager bridge로 전달한다. Cloud plan 생성과 DeviceAgent 실행 dispatch는 계속 별도 성숙도로 관리하며, 코드 연결과 실기기 물리 완료 검증을 구분한다. 다만 아래 항목이 남아 있으므로 전체 시나리오를 실기기 완료로 간주하지 않는다.

1. semantic observation에서 생성된 요청의 platform-signed 실기기 dispatch, callback correlation, physical terminal E2E.
2. 범용 On-device Security task 전달과 WSS terminal event의 실기기 E2E.
3. 프로세스 재시작을 견디는 ordered relay의 kill/restart 증거와 dead-letter 정책.
4. device_context.v2의 policy blocker와 native model readiness/death 상태.
5. Vision, WSS, Streaming, VitalSign, LLM의 device-side resource lease registry.
6. Supervisor가 만든 재계획의 plan history·step result를 console과 workflow persistence에서 end-to-end로 관찰하는 계약.

7. 새로운 시나리오 검토 체크리스트

새 아이디어는 아래 질문을 모두 통과해야 한다.

1. 사용자 결과가 한 문장으로 명확한가?
2. 필요한 capability가 Card에 존재하는가?
3. 중간 단계는 M3이거나 제한 조건이 명시된 M2인가?
4. 필수 slot을 runtime context에서 grounding할 수 있는가?
5. exclusive resource 충돌이 없는가?
6. 각 단계의 물리 완료 evidence가 있는가?
7. 취소와 실패 시 compensation이 있는가?
8. 정상 progress와 재계획 경계를 구분했는가?
9. raw Vision·로그·내부 필드를 LLM이나 TTS에 노출하지 않는가?
10. 기기 로컬 safety gate가 Cloud 판단보다 우선하는가?

이 체크리스트를 통과하지 못하면 기능이 있어도 Agentic workflow에는 편입하지 않는다.

8. 관련 문서

• DeviceAgent 기능·데이터 카탈로그
• Adaptive Home Guardian Supervisor
• Adaptive Welcome & Care Supervisor
• Agentic Capability 변경 이력
• Device Context v2 계약
• Experience Supervisor
• Cloud-On-device-DeviceAgent 데이터 흐름
• TaskManager API Contract