A2A Contract Matrix
이 페이지는 Cloud A2A, 온디바이스 Bridge, DeviceAgent TaskManager 사이에 오가는 주요 계약을 한 표로 정리한다.
Contract Overview
| 계약 | From | To | 목적 |
|---|---|---|---|
voice_context |
On-device | Cloud | 현재 발화, 세션, workflow, memory, device context 전달 |
router_result |
Cloud Planner | Cloud Runtime | route family, owner, step plan 전달 |
session_state |
Cloud Runtime | On-device | 다음 turn에 필요한 compact state 전달 |
device_task_requests |
Cloud Runtime | On-device | device 실행 요청 전달 |
device_intent_step |
Cloud Runtime | On-device Workflow Runner | tokenized device workflow step 전달 |
submitTask |
On-device | DeviceAgent TaskManager | 단일 실행 task 등록 |
submitWorkflow |
On-device | DeviceAgent TaskManager | 복수 task workflow 등록 |
onTaskEvent |
DeviceAgent | On-device | task 상태/완료/실패 callback |
task_event |
On-device | Cloud | task event를 Cloud workflow state로 전달 |
memory_snapshot |
On-device | Cloud | memory context 전달 |
memory_update |
Cloud | On-device | memory/session/workflow 갱신안 전달 |
Planner Output Contract
turn_mode
selected_routes
selected_flow_id
owner_selection
steps
missing_slots
stt_null_*
Multi-step step의 필수 축:
id
route
purpose
execution_target
depends_on
input_from
wait_policy
token_text
원칙:
- semantic dependency는
input_from으로 표현한다. - physical device ordering은
depends_on과wait_policy=completed|event로 표현한다. token_text는 추측 금지다.
Device Task Request Contract
| 형태 | 조건 | 주요 필드 |
|---|---|---|
device_intent_step |
token_text 기반 workflow | task_type, token_text, cloud_*, depends_on, wait_policy |
| legacy task request | ODL bridge taskMethod 기반 | taskMethod, params, cloud_*, executionMode |
Trace 필드:
cloud_workflow_id
cloud_step_id
cloud_plan_id
cloud_output_key
이 네 필드는 Cloud, 온디바이스, DeviceAgent, logcat, artifact validator를 연결하는 핵심이다.
Task Event Contract
정상 event:
QUEUED
RUNNING
PROGRESS
COMPLETED
WORKFLOW_COMPLETED
재판단 후보 event:
FAILED
BLOCKED
TIMEOUT
PAUSED
NEEDS_USER_INPUT
필수 event 필드:
eventName/status
cloud_workflow_id
cloud_step_id
task_id
taskMethod
requires_cloud_decision
reason_code
reason_params
Failure Smells
| 증상 | 의심 영역 |
|---|---|
| final response는 있는데 기기 실행 없음 | device_task_requests 누락 |
| task는 실행됐지만 다음 step이 안 열림 | cloud_step_id 또는 COMPLETED callback 누락 |
| workflow가 끝났는데 계속 active | WORKFLOW_COMPLETED 누락 |
| 실패했는데 Cloud가 아무 반응 없음 | requires_cloud_decision 또는 reason_code 누락 |
| logcat validator 실패 | trace field 또는 log format 누락 |
| planner가 device step을 Cloud step처럼 처리 | execution_target/wait_policy 누락 |