코딩 에이전트가 모바일 앱을 직접 확인하는 CLI, agent-device

코딩 에이전트가 모바일 앱을 직접 확인하는 CLI, agent-device

AI 뉴스 썸네일

728x90

코딩 에이전트가 앱 코드를 고친 뒤 실제 화면까지 확인하려면 별도의 연결 도구가 필요해요. Callstack이 공개한 `agent-device`는 iOS와 Android 앱을 열고, 화면 상태를 읽고, 버튼을 누르고, 결과 증거까지 남기는 과정을 하나의 CLI로 묶었어요. 2

핵심 요약

구분	핵심	왜 볼 만한가요
작동 방식	접근성 트리에서 화면 요소를 읽고 명령 결과에 따라 다음 동작을 고를 수 있어요	코드를 수정한 에이전트가 실행 중인 앱에서 결과를 바로 확인할 수 있어요
지원 범위	iOS, Android, tvOS, Android TV, web, macOS, Linux 등을 다뤄요	모바일뿐 아니라 TV와 데스크톱 앱까지 같은 흐름으로 점검할 수 있어요
검증 자료	스크린샷, 영상, 로그, 네트워크 기록, 성능 자료를 저장해요	성공 여부를 문장으로만 보고하지 않고 화면과 로그를 함께 남길 수 있어요
반복 실행	정상 동작을 `.ad` 스크립트로 저장하고 Maestro YAML로 내보낼 수 있어요	탐색 과정에서 찾은 절차를 로컬이나 CI에서 다시 실행할 수 있어요

1. 코딩 에이전트가 앱 화면을 읽고 다음 동작을 골라요

`agent-device`는 실행 중인 앱의 접근성 스냅샷을 읽고 각 요소에 ref나 selector를 붙여요. 에이전트는 최신 스냅샷에서 필요한 요소를 찾은 뒤 탭, 입력, 스크롤, 제스처, 대기, 상태 확인 같은 명령을 실행해요. 명령 뒤에 바뀐 화면 정보가 돌아오면 그 결과를 읽고 다음 동작을 정할 수 있어요. Vercel `agent-browser`의 inspect-act-verify 방식을 모바일과 TV, 데스크톱 앱으로 넓힌 구조예요. 1

공식 예시는 iOS 연락처 앱을 열고 새 연락처를 만드는 과정을 보여줘요. 먼저 화면을 읽어 추가 버튼의 ref를 찾고, 버튼을 누른 뒤 새로 나타난 입력 필드에 값을 넣어요. 화면이 바뀌면 ref도 달라질 수 있어서 이전 식별자를 계속 쓰지 않고 가장 최근 결과를 기준으로 움직여야 해요. 이 제약은 접근성 정보가 정확할수록 실행도 안정적이라는 뜻이에요. 2

화면 조작보다 결과 확인 범위가 더 넓어요

버튼을 누르는 기능만 제공하는 도구는 아니에요. 스크린샷과 영상, 앱 로그, trace, 네트워크 데이터, 성능 샘플, 충돌 상세 정보, React 프로파일을 모을 수 있어요. 앱이 원하는 화면에 도착했는지 확인하고, 실패했다면 화면과 로그를 함께 살펴보는 흐름을 만들 수 있어요. 공식 문서는 지원하는 명령과 증거 종류가 대상 플랫폼마다 다르다고 밝혀요. 3

iOS와 Android 밖에서도 같은 CLI를 써요

지원 대상에는 iOS, Android, tvOS, Android TV, Amazon Vega OS TV, web, macOS, Linux가 들어가요. 내부 연결 방식은 플랫폼별로 달라요. iOS와 tvOS는 XCTest, Android는 ADB와 스냅샷 헬퍼, macOS는 로컬 헬퍼, Linux는 AT-SPI를 써요. 네이티브 앱뿐 아니라 React Native, Expo, Flutter로 만든 앱도 대상에 포함돼요. 다만 Vega OS는 현재 가상 기기 중심이고, 실제 Fire TV나 일부 캡처·selector 기능은 아직 지원하지 않아요. 2

기존 E2E 도구를 없애기보다 탐색 단계를 보완해요

Appium, Detox, Maestro는 사람이 테스트 절차를 미리 작성하고 유지하는 방식에 가까워요. `agent-device`는 에이전트가 실행 시점의 화면 상태를 읽고 명령을 고르는 데 초점을 맞춰요. 정상 동작을 찾으면 `.ad` 스크립트로 저장해 다시 실행할 수 있고, 엄격한 Maestro YAML로 내보낼 수도 있어요. 탐색과 디버깅은 에이전트가 맡고, 확인된 절차는 반복 가능한 테스트로 남기는 구성이 가능해요. 2

설치에는 Node.js 22.12 이상이 필요해요. 웹 자동화는 Node.js 24 이상을 요구해요. CLI를 설치한 뒤 `agent-device doctor`로 기기와 개발 환경 연결 상태를 먼저 확인하도록 안내해요. 플랫폼별 준비물이 달라서 실제 도입 전에는 팀이 사용하는 시뮬레이터, 에뮬레이터, 물리 기기에서 지원 범위를 확인하는 편이 안전해요. 4

왜 중요한가요

코딩 에이전트는 코드를 작성하고 테스트 명령을 실행하는 데 익숙하지만, 모바일 앱의 실제 화면에서 수정 결과를 확인하는 과정은 별도 도구에 의존해 왔어요. `agent-device`는 코드 변경과 화면 검증 사이를 CLI로 연결해요. 개발자는 에이전트가 남긴 스크린샷, 로그, 재생 스크립트를 함께 보고 수정 결과를 검토할 수 있어요. 2

도입할 때는 접근성 라벨과 role, test ID 품질을 먼저 봐야 해요. 화면 요소가 명확하게 노출되지 않으면 스냅샷만으로 안정적인 대상을 찾기 어려워요. 플랫폼마다 수집 가능한 증거와 명령도 다르므로, 기존 E2E 테스트를 한 번에 대체하기보다 실패 재현이나 기능 점검처럼 범위가 분명한 작업부터 붙이는 방식이 현실적이에요. 3

참고 자료

1. agent-device - AI 에이전트가 iOS/Android 기기를 제어하도록 돕는 CLI — GeekNews
2. callstack/agent-device — GitHub
3. agent-device Commands — Callstack 공식 문서
4. agent-device Installation — Callstack 공식 문서