A2A Source Map
이 페이지는 설명과 실제 소스 파일을 연결하는 지도다.
Cloud A2A
Repo:
~/work/8.cloudLLM/backend-cloud-llm-lambda
Planner / Prompt:
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
핵심 함수:
| 파일 | 라인/영역 | 함수/영역 | 역할 |
|---|---|---|---|
main_router_api.py |
2643+ |
route_turn(...) |
Cloud request를 받아 planner routing 결과를 만든다. |
main_router.system_prompt.txt |
전체 | Planner policy | route family, turn_mode, multi-step, STT_NULL, device context 판단 기준을 정의한다. |
main_router.response_schema.json |
전체 | Response schema | Planner가 반환해야 하는 JSON shape를 제한한다. |
Runtime / Orchestrator:
gemini/a2a/runtime/orchestrator.py
gemini/a2a/runtime/task_manager.py
gemini/a2a/runtime/workflow_state.py
gemini/a2a/runtime/session_state.py
핵심 함수:
| 파일 | 라인/영역 | 함수/영역 | 역할 |
|---|---|---|---|
orchestrator.py |
1391+ |
orchestrate_turn(...) |
한 턴의 A2A runtime 진입점이다. |
orchestrator.py |
92+ |
_respond(...) |
route 결과와 session state를 최종 응답 구조로 묶는다. |
orchestrator.py |
1181+ |
_respond_from_route_execution(...) |
route 실행 결과를 response로 변환한다. |
task_manager.py |
192+ |
build_device_task_requests(...) |
Planner/route 결과에서 온디바이스로 보낼 device_task_requests를 만든다. |
task_manager.py |
173+ |
_device_intent_requests_from_plan(...) |
multi-step plan 안의 device intent step을 request 목록으로 추출한다. |
task_manager.py |
146+ |
_step_device_intent_request(...) |
단일 step을 task_type=device_intent_step payload로 변환한다. |
task_manager.py |
134+ |
_step_token_text(...) |
step에서 안전하게 제공된 token_text를 읽는다. |
workflow_state.py |
616+ |
_task_event_requires_cloud_replan(...) |
task event가 Cloud replan 후보인지 판단한다. |
Cloud에서 특히 중요한 연결:
route_turn(...)
-> orchestrate_turn(...)
-> build_device_task_requests(...)
-> _step_device_intent_request(...)
-> response.orchestration.device_task_requests
검증 도구:
gemini/a2a/tools/task_event_contract_verifier.py
gemini/a2a/tools/device_task_dry_run.py
gemini/a2a/tools/device_e2e_runner.py
gemini/a2a/tools/device_e2e_audit.py
gemini/a2a/tools/device_logcat_evidence.py
gemini/a2a/tools/device_e2e_artifact_validator.py
On-device Bridge
Repo:
~/work/2.A1_LLM_Aent/skmagic_ondeviceai_agent
Cloud request 수신:
app/src/main/java/com/skmagic/ondeviceai/agent/service/ForegroundService.kt
핵심 함수:
| 파일 | 라인/영역 | 함수 | 역할 |
|---|---|---|---|
ForegroundService.kt |
2220-2265 |
executeCloudDeviceTaskRequests(...) |
Cloud 응답의 deviceTaskRequests를 읽고 legacy/native task와 device_intent_step을 분기한다. |
ForegroundService.kt |
2291-2341 |
executeNextCloudIntentStep() |
CloudIntentWorkflowRunner에서 다음 실행 가능한 step을 꺼내 실행한다. |
ForegroundService.kt |
2344-2390 |
handleCloudIntentNativeTaskEvent(...) |
DeviceAgent native task event를 active cloud intent workflow에 반영한다. |
ForegroundService.kt |
2428+ |
executeCloudDeviceControlRequests(...) |
기존 device control request 계열 처리 경로다. |
Workflow Runner:
app/src/main/java/com/skmagic/ondeviceai/agent/service/CloudIntentWorkflowRunner.kt
핵심 클래스/함수:
| 파일 | 라인/영역 | 클래스/함수 | 역할 |
|---|---|---|---|
CloudIntentWorkflowRunner.kt |
38+ |
CloudIntentWorkflowRunner |
Cloud가 내려준 device intent step workflow의 상태와 dependency unlock을 관리한다. |
CloudIntentWorkflowRunner.kt |
42-55 |
submitWorkflow(...) |
step을 workflow에 등록하고 dependency 초기 상태를 정한다. |
CloudIntentWorkflowRunner.kt |
57-69 |
submitWorkflowFromCloudRequests(...) |
Cloud device_task_requests에서 intent step만 추출한다. |
CloudIntentWorkflowRunner.kt |
71-82 |
nextRunnableStep(...), markNativeTaskSubmitted(...) |
다음 실행 가능한 step 선택과 native task id 기록. |
CloudIntentWorkflowRunner.kt |
98-140 |
handleNativeTaskEventAndBuildCloudReport(...) |
native task event를 workflow 상태와 Cloud report로 변환한다. |
CloudIntentWorkflowRunner.kt |
149-162 |
unlockReadySteps(...) |
dependency가 완료된 step을 PENDING으로 연다. |
CloudIntentWorkflowRunner.kt |
164-205 |
buildCloudReport(...) |
step-level event report를 만든다. |
CloudIntentWorkflowRunner.kt |
208-234 |
buildWorkflowCompletedReportIfDone(...) |
모든 step 완료 시 workflow-level WORKFLOW_COMPLETED report를 만든다. |
상태 모델:
PENDING
WAITING_DEPENDENCY
RUNNING
COMPLETED
FAILED
Device Intent 실행:
app/src/main/java/com/skmagic/ondeviceai/agent/service/DeviceIntentExecutor.kt
app/src/main/java/com/skmagic/ondeviceai/agent/service/DeviceCommandSink.kt
app/src/main/java/com/skmagic/ondeviceai/agent/service/CloudDeviceTaskRequests.kt
app/src/main/java/com/skmagic/ondeviceai/agent/data/ManagedDeviceTask.kt
핵심 클래스/함수:
| 파일 | 클래스/함수 | 역할 |
|---|---|---|
DeviceIntentExecutor.kt |
DeviceIntentExecutor.execute(...) (86+) |
token intent를 기존 FunctionCallHandler/managed task 경로로 실행한다. |
DeviceCommandSink.kt |
sink 구현체 | direct command와 managed task submission 경계를 분리한다. |
DeviceCommunicator.kt |
submitManagedTask(...) (380+) |
온디바이스에서 DeviceAgent TaskManager로 managed task를 제출한다. |
CloudDeviceTaskRequests.kt |
device intent 판별 유틸 (6-31) |
task_type=device_intent_step request를 식별한다. |
ManagedDeviceTask.kt |
data model | Cloud trace metadata를 task params에 보존한다. |
온디바이스 실행 연결:
ForegroundService.executeCloudDeviceTaskRequests(...)
-> CloudIntentWorkflowRunner
-> executeNextCloudIntentStep()
-> DeviceIntentExecutor.execute(...)
-> DeviceCommunicator.submitManagedTask(...)
-> DeviceAgent TaskManager
DeviceAgent / SoC
Repo:
~/work/1.A1_SoC_new/SoC/a1-packages
TaskManager:
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskManager.java
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskEventListener.java
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskReasonContract.java
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskIngressClassifier.java
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/DevicePlanningContextProvider.java
TaskManager API 상수:
| Method | 역할 |
|---|---|
submitTask |
단일 task를 queue에 등록한다. |
submitWorkflow |
복수 task workflow를 등록한다. |
getTaskStatus |
task 상태를 조회한다. |
listTasks |
등록된 task 목록을 조회한다. |
getQueueStatus |
queue 상태를 조회한다. |
updateTaskProgress |
task progress를 갱신한다. |
cancelTask |
task를 취소한다. |
getTaskManagerStatus |
TaskManager 자체 상태를 조회한다. |
getDevicePlanningContext |
Cloud plan 전에 필요한 기기 상태 snapshot을 만든다. |
classifyTaskIngress |
입력이 task/event/status/query 성격인지 분류한다. |
핵심 구현 위치:
| 파일 | 라인/영역 | 함수/영역 | 역할 |
|---|---|---|---|
TaskManager.java |
31-41 |
API method constants | TaskManager가 처리하는 control method 목록. |
TaskManager.java |
102-143 |
handleControlMethod(...) |
TaskManager API dispatch 관문. |
TaskManager.java |
169-226 |
submitTask(...) |
validator/policy/resource check 후 task를 등록한다. |
TaskManager.java |
228-313 |
submitWorkflow(...) |
subtask workflow를 구성하고 step event를 만든다. |
TaskManager.java |
845-884 |
cancelTask(...) |
취소 요청과 CANCELLED event를 처리한다. |
TaskManager.java |
1449-1466 |
summary reason/trace fields | reason_code, reason_params, requires_cloud_decision, cloud trace alias를 기록한다. |
TaskManager.java |
1515-1528 |
notifyTaskEvent(...) |
onTaskEvent payload를 listener와 module callback으로 전달한다. |
TaskEventListener.java |
onTaskEvent(...) |
callback contract | DeviceAgent에서 온디바이스로 event를 전달하는 callback contract다. |
TaskReasonContract.java |
12-120 |
reason code contract | 실패/차단 사유, 복구 가능성, Cloud decision 필요 여부를 구조화한다. |
TaskIngressClassifier.java |
76+ |
ingress classifier | task manager API와 일반 명령을 분류한다. |
DevicePlanningContextProvider.java |
29-164 |
context provider | battery/map/room/queue/capability snapshot을 만든다. |
API 진입:
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/main/api/MainApi.java
역할:
- 외부 API 진입점에서 TaskManager method를 먼저 처리한다.
submitTask,submitWorkflow,getDevicePlanningContext같은 task manager API를 legacy command와 구분한다.
도메인별 실행 권한:
자세한 연결 구조는 DeviceAgent / SoC Domain Map에 정리되어 있다.
| 도메인 | 대표 파일 | 역할 |
|---|---|---|
task/ |
TaskManager.java, TaskReasonContract.java, DevicePlanningContextProvider.java |
Cloud/Bridge task/workflow 입구, queue/event/reason/context 관리 |
moving/ |
MovingLocationManager.java, MovingController.java, RobotMovementController.java |
방/좌표 이동, 스테이션 복귀, 이동 pause/resume/callback |
cleaning/ |
AirCleaningManager.java, CleaningTransaction.java, MovingCleaningManager.java, BaseCleaningManager.java |
청정 시작/정지/상태, 이동 청정, 청정 transaction |
map/ |
MapManager.java |
room id/name, station area, split space, map edit state, position to room |
schedule/ |
ScheduleAlarmReceiver.java, ScheduleManager.java, ScheduleDao.java, Schedule.java |
등록 스케줄, 실행 가능 조건, 스케줄 DB |
interaction/ |
InterScheduleManager.java, ActionBase.java |
인터렉션 스케줄 pause/resume/stop, sub-action callback |
중요한 설계 판단:
get성격의 상태조회는DevicePlanningContextProvider나 각 domain manager snapshot을 통해 읽는다.set성격의 장기 실행 명령은TaskManager.submitTask또는submitWorkflow를 통해 관리한다.- 기존 domain manager의 조건 판단을 우회해서 wrapper 함수만 직접 호출하면 안 된다.
- Cloud/온디바이스에서 내려온 managed task가 기존 직접 실행 경로를 우회하지 않고 TaskManager 정책을 통과하도록 하는 관문이다.
4-module call chain
Cloud Planner
route_turn(...)
Cloud Runtime
orchestrate_turn(...)
build_device_task_requests(...)
On-device Bridge
executeCloudDeviceTaskRequests(...)
CloudIntentWorkflowRunner
DeviceIntentExecutor.execute(...)
DeviceAgent / SoC
TaskManager.submitTask(...)
TaskEventListener.onTaskEvent(...)
Cloud Runtime
workflow_state._task_event_requires_cloud_replan(...)
이 call chain을 기준으로 디버깅하면 “Planner가 잘못 냈는지”, “Runtime 변환이 빠졌는지”, “온디바이스가 request를 못 받았는지”, “DeviceAgent callback이 안 올라왔는지”를 단계별로 분리할 수 있다.
테스트
Cloud:
test/test_task_manager.py
test/test_workflow_state.py
test/test_task_event_contract_verifier.py
test/test_task_orchestration_roundtrip.py
test/test_device_task_dry_run_tool.py
test/test_device_e2e_runner_tool.py
test/test_device_e2e_audit_tool.py
test/test_device_logcat_evidence_tool.py
test/test_device_e2e_artifact_validator_tool.py
On-device:
CloudIntentWorkflowRunnerTest.kt
DeviceIntentExecutorTest.kt
CloudDeviceTaskRequestsTest.kt
ManagedTaskDeviceCommandSinkTest.kt
CloudIntentTaskEventLogTest.kt
DeviceAgent:
TaskManagerTest.java
TaskManagerInstrumentedTest.java
테스트 연결 기준:
| 검증 질문 | 봐야 할 테스트 |
|---|---|
| Cloud가 device request를 만드는가 | test_task_manager.py, test_task_orchestration_roundtrip.py, test_device_task_dry_run_tool.py |
| task event가 replan 정책을 타는가 | test_workflow_state.py, test_task_event_contract_verifier.py |
| 온디바이스 workflow가 dependency를 지키는가 | CloudIntentWorkflowRunnerTest.kt |
| token intent가 managed task로 내려가는가 | DeviceIntentExecutorTest.kt, ManagedTaskDeviceCommandSinkTest.kt |
| DeviceAgent TaskManager API가 동작하는가 | TaskManagerTest.java, TaskManagerIntegrationTest.java, TaskManagerInstrumentedTest.java |