agent-device – AI 에이전트가 모바일·데스크톱 앱을 검증하게 하는 디바이스 자동화 CLI

왜 필요한가
기본 사용법
지원 기능
어디에 쓰면 좋은가
라이선스
관련 문서
참고 자료

agent-device는 코딩 에이전트가 실제 실행 중인 앱을 관찰하고 조작하며 변경사항을 검증하게 하는 디바이스 자동화 CLI다. iOS, Android, tvOS, Android TV, Vega OS TV, web, macOS, Linux를 대상으로 하며, 접근성 snapshot, selector, ref, screenshot, video, log 같은 증거를 에이전트 루프에 제공한다.

왜 필요한가

코딩 에이전트는 코드를 고친 뒤 “앱이 실제 화면에서 제대로 동작하는지” 확인해야 한다. 웹은 Playwright나 브라우저 하네스로 어느 정도 해결되지만, 모바일 앱·TV 앱·데스크톱 앱은 별도 실행 환경과 접근성 계층이 필요하다.

agent-device는 이 부분을 inspect-act-verify 루프로 만든다. 에이전트가 현재 화면을 읽고, ref나 selector로 동작을 수행하고, diff와 증거를 확인한 뒤 다음 명령을 고른다.

기본 사용법

Node.js 22.12 이상이 필요하다. web automation은 Node.js 24 이상이 필요하다.

npm install -g agent-device@latest
agent-device doctor
agent-device help workflow

iOS Contacts 앱에 연락처를 추가하는 흐름은 다음처럼 진행된다.

agent-device open Contacts --platform ios
agent-device snapshot -i
agent-device press @e2 --settle
agent-device fill @e7 "Ada" --settle
agent-device screenshot ./contact-form.png
agent-device close

중요한 규칙은 최신 출력의 ref만 사용하는 것이다. @e7 같은 ref는 화면 상태가 바뀌면 다른 요소를 가리킬 수 있다. --settle 후 diff에 나온 최신 ref를 기준으로 다음 동작을 선택해야 한다.

지원 기능

기능	설명
화면 관찰	접근성 tree, selector, React Native component tree, screenshot
UI 조작	tap, press, fill, scroll, gesture, wait, alert handling
실패 진단	screenshot, video, log, trace, network data, crash detail, React profile
반복 실행	`.ad` script 저장·재생, Maestro YAML export
증거 저장	PR 리뷰나 QA 확인용 screenshot·log·profile artifact 보관

지원 target마다 가능한 명령과 증거 종류는 다르다. 접근성 label, role, test ID가 잘 정의된 앱일수록 에이전트가 안정적으로 동작한다.

어디에 쓰면 좋은가

React Native, Expo, Flutter, native mobile 앱의 변경사항을 에이전트가 직접 검증하게 할 때
PR마다 사람이 스크린샷을 찍어 확인하던 흐름을 자동 evidence로 바꾸고 싶을 때
모바일 QA agent를 CI에서 돌리고, 실패 시 replay script와 artifact를 남기고 싶을 때
browser-use로는 다룰 수 없는 네이티브 앱·TV 앱·데스크톱 앱 검증이 필요할 때

Appium, Detox, Maestro가 사람이 작성한 테스트 suite 중심이라면, agent-device는 에이전트가 런타임에 상태를 읽고 다음 명령을 선택하는 작업에 맞춰져 있다. 다만 안정적인 회귀 테스트가 필요하면 agent-device run을 .ad script나 Maestro YAML로 저장해 결정론적 테스트와 함께 쓰는 편이 좋다.

라이선스

MIT

참고 자료

callstack/agent-device — GitHub 공식 저장소

Like?

AI Sparkup