A2A Role-Based Reader Paths

이 문서는 A2A Wiki를 역할별로 읽기 위한 안내서다. 전체를 처음부터 끝까지 읽을 수도 있지만, 실제 업무에서는 담당자가 다르기 때문에 각자 필요한 장부터 들어가는 편이 빠르다.

A2A Role-Based Reader Paths

1. 언제 이 문서를 보는가

아래 상황이면 이 문서부터 본다.

Cloud A2A 담당자가 planner/runtime 수정 범위를 알고 싶다.
온디바이스 담당자가 Cloud 응답을 어떻게 DeviceAgent로 넘길지 알고 싶다.
DeviceAgent/SoC 업체가 TaskManager와 callback 계약을 구현해야 한다.
QA/SQA가 어떤 테스트 증거를 요구해야 하는지 정리해야 한다.
PM/아키텍트가 전체 흐름과 남은 리스크를 빠르게 파악해야 한다.

2. 역할별 빠른 경로

역할	먼저 볼 문서	그 다음 볼 문서	완료 전 확인
PM / 아키텍트	System Overview, Visual Map	Book Roadmap, Status and Gap Audit	Next Action Board, Documentation Quality Audit
Cloud Planner 담당	Planner and Routing	Contract Matrix, Device Task Flow, Scenario Walkthroughs	Benchmark and Router Evolution, Evidence Index
Cloud Runtime 담당	Device Task Flow	Source Map, Contract Matrix	Validation Guide, Requirements Traceability Matrix
On-device Bridge 담당	Contract Matrix, Device Task Flow	Source Map, Work Breakdown	Validation Guide, Vendor Test Evidence Template
DeviceAgent / SoC 업체	Vendor Handoff	DeviceAgent TaskManager API Contract, SoC TaskManager Execution Subsystem, DeviceAgent / SoC Domain Map	Vendor API Acceptance Checklist, Vendor Open Questions
19.comToMe 담당	19.comToMe A2A Workflow Example	19.comToMe DeviceAgent Contract, SoC TaskManager Execution Subsystem	Vendor Open Questions, Validation Guide
QA / SQA	Validation Guide	Requirements Traceability Matrix, Evidence Index	Vendor Test Evidence Template, Status and Gap Audit
Memory / Personalization 담당	Memory and Personalization	Memory DB and Sync Contract, System Overview	Evidence Index, Status and Gap Audit

3. Cloud Planner 담당 경로

목표:

발화를 route family와 step plan으로 바꾸는 판단 구조를 이해한다.
turn_mode, steps, depends_on, input_from, execution_target, wait_policy가 언제 필요한지 안다.
device 명령을 직접 실행하지 않고 runtime으로 넘기는 경계를 이해한다.

읽는 순서:

완료 기준:

Planner output이 schema에 맞는다.
복합명령에서 step 순서와 의존성이 명확하다.
token_text를 임의 생성하지 않는다.
정상 task 진행마다 Cloud LLM을 다시 호출하지 않는다는 원칙을 지킨다.

4. Cloud Runtime 담당 경로

목표:

Planner step을 agent 실행 또는 device_task_requests로 변환하는 경계를 이해한다.
Cloud-only step, device step, mixed workflow를 구분한다.
task event가 들어왔을 때 replan이 필요한지 판단한다.

읽는 순서:

완료 기준:

device_task_requests에 cloud_workflow_id, cloud_step_id, cloud_output_key가 보존된다.
COMPLETED는 다음 step unlock으로 처리한다.
FAILED, BLOCKED, PAUSED만 Cloud replan 후보가 된다.

5. On-device Bridge 담당 경로

목표:

Cloud 응답을 받아 device intent workflow로 실행하는 방법을 이해한다.
depends_on을 지키고, native task event를 Cloud trace metadata와 함께 report한다.
온디바이스가 임의로 Cloud plan을 재해석하지 않는 경계를 지킨다.

읽는 순서:

완료 기준:

task_type=device_intent_step을 순차 workflow로 등록한다.
이전 step 완료 전 다음 step을 실행하지 않는다.
정상 이벤트는 local 상태/UI/audit에 반영하고, 판단 필요 event만 Cloud로 올린다.

6. DeviceAgent / SoC 업체 경로

목표:

submitTask, submitWorkflow, getTaskStatus, cancelTask, getDevicePlanningContext의 역할을 이해한다.
실패 사유를 자연어가 아니라 reason_code, reason_params, requires_cloud_decision으로 올린다.
기존 native 조건 판단을 우회하지 않고 TaskManager 정책 아래에서 실행한다.

읽는 순서:

완료 기준:

TaskManager API가 온디바이스에서 호출 가능하다.
event callback이 trace field를 유지한다.
실패/차단 사유가 구조화되어 올라온다.
업체 테스트 증거가 Vendor Test Evidence Template에 맞게 제출된다.

7. QA / SQA 경로

목표:

어떤 수준의 테스트가 완료를 증명하는지 구분한다.
HTML 문서 생성, unit test, dry-run, 실기기 E2E를 혼동하지 않는다.
ADB/logcat artifact와 vendor evidence를 수집할 기준을 잡는다.

읽는 순서:

완료 기준:

검증 수준이 L0~L5 중 어디인지 명시된다.
device_task_requests -> TaskManager -> callback -> Cloud report trace가 끊기지 않는다.
실기기 미검증 항목을 완료로 판정하지 않는다.

8. PM / 아키텍트 경로

목표:

전체 구조와 책임 경계를 빠르게 이해한다.
업체/Cloud/온디바이스/QA 작업을 분리해 진행 상태를 판단한다.
다음 회의에서 닫아야 할 질문과 결정 사항을 파악한다.

읽는 순서:

완료 기준:

담당자별 next action이 분리되어 있다.
업체에 넘길 계약 문서와 테스트 증거 양식이 준비되어 있다.
실기기/benchmark/Memory 구현 공백이 별도로 추적된다.

9. 관련 문서