A2A Requirements Traceability Matrix
이 문서는 A2A 관련 요구사항을 설계 문서, 구현 위치, 검증 증거, 남은 공백에 연결한다.
목적은 단순 문서 정리가 아니라, 업체 전달과 QA 검증에서 “무엇이 구현되어야 하고 무엇이 아직 증거가 없는지”를 한 표로 고정하는 것이다.
상태 코드
| 상태 | 의미 |
|---|---|
| 완료 | 설계, 구현 위치, 테스트 증거가 모두 연결되어 있고 추가 실기기 확인만 선택 사항인 상태 |
| 부분 완료 | 설계와 구현 방향은 있으나 실제 payload 호환, 단말 로그, 업체 구현물 대조가 남은 상태 |
| 미완료 | 설계 수준만 있거나 구현/테스트 증거가 아직 없는 상태 |
| 업체 확인 필요 | DeviceAgent/SoC 업체 구현물과 대조해야 완료 판정 가능한 상태 |
추적 매트릭스
| ID | 요구사항 | 설계 문서 | 구현 위치 | 검증 증거 | 상태 | 다음 액션 |
|---|---|---|---|---|---|---|
| A2A-REQ-01 | 사용자 발화를 route family와 step plan으로 분해해야 한다. | Planner and Routing, System Overview | gemini/a2a/planner/main_router_api.py, gemini/a2a/planner/assets/main_router.system_prompt.txt, gemini/a2a/planner/assets/main_router.response_schema.json |
planner sample test, benchmark run 필요 | 부분 완료 | 최신 prompt 기준 full-run artifact를 고정한다. |
| A2A-REQ-02 | Planner는 selector가 아니라 multi-step plan을 만들 수 있어야 한다. | Planner and Routing, Scenario Walkthroughs | main_router.system_prompt.txt, main_router.response_schema.json |
Cloud-only / mixed sample test | 부분 완료 | input_from, depends_on, execution_target 샘플을 regression fixture로 고정한다. |
| A2A-REQ-03 | Cloud Runtime은 ODL/device step을 device_task_requests로 변환해야 한다. |
Device Task Flow, Contract Matrix | gemini/a2a/runtime/task_manager.py, gemini/a2a/runtime/orchestrator.py |
device task dry-run | 부분 완료 | 실제 Cloud response JSON fixture를 보존한다. |
| A2A-REQ-04 | Cloud는 정상 task 진행 이벤트마다 LLM replan을 하지 않아야 한다. | Contract Matrix, Validation Guide | gemini/a2a/runtime/workflow_state.py |
task event contract tests | 부분 완료 | QUEUED/RUNNING/PROGRESS/COMPLETED/WORKFLOW_COMPLETED replay test를 명시한다. |
| A2A-REQ-05 | 실패/차단/일시중단/사용자 결정 필요 이벤트만 Cloud replan 후보가 되어야 한다. | Device Task Flow, Vendor Handoff | workflow_state.py, TaskReasonContract.java |
contract tests, fake event replay | 부분 완료 | FAILED/BLOCKED/PAUSED/NEEDS_USER_INPUT fixture를 추가한다. |
| A2A-REQ-06 | On-device Bridge는 Cloud의 device_intent_step을 순차 workflow로 실행해야 한다. |
Device Task Flow, Scenario Walkthroughs | ForegroundService.kt, CloudIntentWorkflowRunner.kt, CloudDeviceTaskRequests.kt |
runner unit tests 필요 | 부분 완료 | depends_on 완료 전 다음 step 미실행 테스트를 고정한다. |
| A2A-REQ-07 | On-device Bridge는 실제 token/device intent를 DeviceAgent로 전달해야 한다. | Device Task Flow, Source Map | DeviceIntentExecutor.kt, DeviceCommunicator.kt, ManagedDeviceTask.kt |
ADB 전 dry-run 가능, 실기기 미검증 | 부분 완료 | fake DeviceCommunicator 기반 계약 테스트를 추가한다. |
| A2A-REQ-08 | DeviceAgent TaskManager는 task/workflow queue와 상태 이벤트를 제공해야 한다. | DeviceAgent TaskManager 기준 사양서, DeviceAgent TaskManager API Contract, Vendor Handoff, TaskManager Live Monitor | TaskManager.java, TaskPolicyRegistry.java, TaskBundleValidator.java, TaskExecutorRegistry.java, TaskEventListener.java, MainApi.java, TaskMonitorReporter.java, TaskMonitorCommandPoller.java |
TaskManagerTest, TaskMonitorCommandBridgeTest, TaskMonitorReporterTest, DeviceAgent assembleDebug --rerun-tasks, 실기기 setEyeLedColor routine command dispatch/ack evidence |
부분 완료 | TaskManager framework와 monitor/ack 경로는 검증됨. 실제 movement/cleaning actuator executor 연결은 업체 후속으로 분리한다. |
| A2A-REQ-09 | DeviceAgent 실패/차단 이벤트는 reason_code, reason_params, requires_cloud_decision을 포함해야 한다. |
Vendor Handoff, Contract Matrix | TaskReasonContract.java, TaskManager.java |
reason contract test 필요 | 업체 확인 필요 | 자연어 reason만 올라오는 경로가 없는지 점검한다. |
| A2A-REQ-10 | Cloud plan 전 최소 기기 상태 snapshot을 제공해야 한다. | DeviceAgent TaskManager 기준 사양서, Vendor Handoff, DeviceAgent TaskManager API Contract | DevicePlanningContextProvider.java, TaskManager.java, MainApi.java |
snapshot schema test 필요 | 업체 확인 필요 | battery/map/location/queue/capability 누락값 정책을 확정한다. |
| A2A-REQ-11 | 실기기에서 복합명령 E2E를 증명해야 한다. | Validation Guide, Scenario Walkthroughs | Cloud + On-device + DeviceAgent 전체 | ADB/logcat/artifact validator 필요 | 미완료 | ADB 연결 후 APK 설치, 복합명령 실행, logcat evidence를 수집한다. |
| A2A-REQ-12 | 업체 전달 문서는 API, 이벤트, 필드, 완료 기준을 빠짐없이 제공해야 한다. | Vendor Handoff, DeviceAgent Vendor Implementation Package, Vendor API Acceptance Checklist, Vendor Test Evidence Template, Vendor Open Questions | docs only | 문서 리뷰 필요 | 부분 완료 | 업체 리뷰에서 미확정 질문을 닫고 제출 증거 양식을 확정한다. |
| A2A-REQ-13 | 메모리/개인화는 session/day/week/profile 계층으로 설계되어야 한다. | Memory and Personalization, Memory DB and Sync Contract | 구현 예정 | schema design 문서화됨, 구현 증거 없음 | 부분 완료 | DB migration, repository, sync worker 구현 후 테스트를 추가한다. |
| A2A-REQ-14 | Router 성능은 family별 성공률과 실패 비용을 함께 관리해야 한다. | Benchmark and Router Evolution | benchmark scripts, prompt snapshots | latest full-run artifact 필요 | 부분 완료 | 채택 prompt 기준 benchmark 결과와 실패 샘플을 versioned artifact로 보존한다. |
| A2A-REQ-15 | 19.comToMe 같은 장기 device lifecycle 기능을 A2A/TaskManager workflow로 안전하게 실행할 수 있어야 한다. | 19.comToMe A2A Workflow Example, 19.comToMe DeviceAgent Contract, DeviceAgent TaskManager 기준 사양서, Vendor API Acceptance Checklist | TaskManager.java, TaskExecutorRegistry.java, ComeToMe 전용 TaskManager/Executor 구현 예정, 온디바이스 DeviceIntentExecutor.kt/DeviceCommunicator.kt |
19.comToMe fixture와 실기기 DoA/Vision/AMR/FollowMe evidence 필요 |
업체 확인 필요 | comeToMe method, stage gate, speaker gate, room mapping, target_pose, FollowMe callback, reason mapping을 확정한다. |
| A2A-REQ-16 | Speech/STT 환경에서 STT_NULL, slot fragment, topic shift, interruption을 context-aware loop 안에서 처리해야 한다. |
Speech-LLM Context-Aware A2A Architecture, Planner and Routing | main_router.system_prompt.txt, main_router_api.py, voice context/session state 구현 |
noisy speech regression fixture 필요 | 부분 완료 | STT_NULL/DEF/FRG/ODL/SCH noisy fixture와 active workflow slot fragment test를 추가한다. |
| A2A-REQ-17 | Route family는 실제 Agent/Skill 책임과 연결되어야 하며, Cloud-only/device-only/mixed plan 모두 표현 가능해야 한다. | Speech-LLM Context-Aware A2A Architecture, Scenario Walkthroughs, Device Task Flow | main_router.response_schema.json, runtime/orchestrator.py, runtime/task_manager.py |
Cloud-only/mixed/device-only fixture 필요 | 부분 완료 | depends_on, input_from, execution_target, wait_policy가 보존되는 regression test를 추가한다. |
| A2A-REQ-18 | Reactive voice turn과 proactive signal turn은 같은 A2A/TaskManager 생태계에서 운영되되, trigger/gate/safety/feedback 책임이 분리되어야 한다. | SK-Intellix Reactive and Proactive Operation, Speech-LLM Context-Aware A2A Architecture, Architecture Rationale and Benefits | 현재 브랜치: lambda_function.py, src/objects.py, runtime/__init__.py; 관련 브랜치: proactive_planner의 gemini/a2a/proactive/*, agents/proactive/planner_api.py, runtime/proactive_*, proactive_capability_policy.json |
proactive source map 확인, branch integration evidence 필요 | 부분 완료 | proactive_planner source/schema/tests를 현재 작업 브랜치와 대조하고 Lambda request/feedback fixture를 고정한다. |
| A2A-REQ-19 | Cloudflare 기반 TaskManager live monitor는 Task 상태, queue, routine traffic, command request, scenario evidence를 실시간으로 볼 수 있어야 한다. | TaskManager Live Monitor, TaskManager Live Monitor | ops/task-monitor/src/worker.js, ops/task-monitor/src/monitor-core.js, apps/task-monitor-dashboard/index.html, apps/task-monitor-dashboard/app.js, apps/task-monitor-dashboard/styles.css |
Worker npm test 16/16, node --check, dashboard Korean regression test, public Worker snapshot smoke, Cloudflare Pages deployment evidence |
완료 | 장기 run report 저장은 별도 D1/R2/Analytics Engine 설계로 분리한다. |
| A2A-REQ-20 | IoT/MQTT와 PUI에서 내려오는 command method는 TaskManager 단일 task로 감싸져야 하며 query/상태 응답성 호출은 직접 호출로 유지되어야 한다. | SoC TaskManager Vendor Implementation Workbook, TaskManager Live Monitor | CmdTopic.java, IotTaskManagerBridge.java, TaskManagerCommandBridge.java, DeviceControlResolver.java, SimulatorActivator.java |
IotTaskManagerBridgeTest, CmdTopicTaskManagerRoutingTest, IoT 직접 호출 허용 method 고정, TaskManagerCommandBridgeTest PUI route decision table, IotAgent assembleDevDebug, SKMLauncher assembleDebug, 2026-07-10 --rerun-tasks JVM 재검증 |
완료 | 신규 IoT/PUI command 추가 시 direct-call guard와 bridge unit test를 함께 갱신한다. |
| A2A-REQ-21 | Cloud command gateway에서 내려온 command는 DeviceAgent polling으로 TaskManager까지 전달되고 HANDLED/FAILED ack로 관측 가능해야 한다. |
TaskManager Live Monitor, TaskManager Live Monitor | /api/commands, /api/device/commands, TaskMonitorCommandBridge.java, TaskMonitorCommandPoller.java, TaskMonitorReporter.java |
Worker command gateway smoke, dry-run 미전달 unit test, pending command drain smoke, TaskMonitorCommandBridgeTest, malformed command FAILED ack/continue unit test, 실기기 device-poll-ack-final-1783685609 snapshot status=HANDLED |
완료 | 실제 actuator command open 전 method별 allowlist/safety gate와 dispatch:true gate를 유지한다. |
담당자별 액션
| 담당 | 우선 액션 |
|---|---|
| Cloud A2A | device_task_requests fixture와 event replay test를 보존한다. |
| On-device Bridge | CloudIntentWorkflowRunner dependency unlock과 native event report를 테스트한다. |
| DeviceAgent / SoC 업체 | 실제 movement/cleaning actuator executor, reason contract, planning context provider를 구현하고 필드 호환 증거를 제공한다. |
| QA/SQA | ADB 전 dry-run, fake event replay, ADB 후 logcat artifact validator를 분리해 실행한다. |
| PM/기술 리드 | 업체 전달 문서와 실제 구현물 대조 회의를 잡고 미확정 필드를 닫는다. |
릴리스 블로커
아래 항목은 제품 통합 완료 판정 전 반드시 닫아야 한다.
- A2A-REQ-08: 실제 movement/cleaning actuator executor 연결과 dry-run 해제 safety gate.
- A2A-REQ-09: 실패/차단 reason contract의 구조화 필드 확인.
- A2A-REQ-10: plan 전 device planning context freshness와 누락값 정책 확인.
- A2A-REQ-11: ADB 실기기 복합명령 E2E evidence 수집.
- A2A-REQ-12: 업체 구현 패키지 리뷰와 open question closure.
- A2A-REQ-15: 19.comToMe의 method/stage/speaker/location/DoA/Vision/AMR/FollowMe callback 계약 확정.
- A2A-REQ-16: Speech-noisy 발화와 active workflow fragment 회귀 테스트 고정.
- A2A-REQ-17: Agent/Skill plan과 mixed composite control fixture 고정.
- A2A-REQ-18: Reactive/proactive branch source 통합 여부와 proactive false-positive/feedback evidence 고정.
- A2A-REQ-19: 장기 run report 저장 요구가 제품 범위에 포함되는 경우 D1/R2/Analytics Engine 저장소 설계 확정.