agent-device: 모바일 앱을 직접 검증하는 AI 코딩 에이전트

AI 코딩 에이전트가 웹앱을 고칠 때는 브라우저를 열고, 콘솔을 보고, 스크린샷을 찍는 흐름이 점점 자연스러워지고 있습니다. 그런데 모바일 앱에서는 여전히 간극이 큽니다. 에이전트가 코드를 고쳐도 실제 iOS Simulator나 Android Emulator에서 버튼이 눌리는지, 화면 읽기 구조가 제대로 잡혔는지, 로그와 스크린샷 증거가 남는지는 사람이 따로 확인해야 하는 경우가 많습니다.

Callstack의 agent-device ↗는 이 틈을 겨냥한 오픈소스 CLI입니다. README는 이 도구를 “coding agent가 실행 중인 앱에서 변경사항을 검증하게 해주는” 장치 자동화 CLI로 소개하며, iOS, Android, tvOS, Android TV, Vega OS TV, web, macOS, Linux까지 지원 대상으로 둡니다.

먼저 결론부터 말하면, agent-device는 Appium이나 Detox를 대체하는 새 E2E 프레임워크라기보다, 에이전트가 앱 상태를 관찰하고 다음 행동을 고르고 증거를 남기게 하는 실행 레이어에 가깝습니다. 프론트엔드 팀 입장에서는 “코드 생성” 이후의 병목인 실제 앱 검증을 에이전트 루프 안으로 끌어오는 도구로 보는 편이 정확합니다.

기준 작성 시점 2026-08-04 · GitHub README, package.json의 0.20.5, 공식 문서 스냅숏 기준입니다.

이 글에서 다루는 내용:

agent-device가 기존 모바일 테스트 도구와 다른 지점
에이전트가 앱을 inspect-act-verify 루프로 다루는 방식
설치, MCP, replay, CI 적용 시 주의할 점

왜 필요한가?

웹 자동화 쪽에서는 Chrome DevTools MCP처럼 브라우저 런타임을 AI 에이전트에게 열어주는 흐름이 이미 보입니다. OpenAI 쪽에서도 Codex 모바일 앱 통합처럼 “폰에서 코딩한다”보다 “이동 중에 에이전트 작업을 운영한다”는 관점이 중요해지고 있습니다.

agent-device는 이 흐름을 모바일 앱 런타임으로 확장합니다. 공식 README ↗는 에이전트가 접근성 snapshot, ref, selector를 읽고, 탭과 입력 같은 기기 동작을 실행하고, 스크린샷과 로그 같은 evidence를 저장할 수 있다고 설명합니다.

기존 테스트 자동화와의 차이는 주체입니다. Appium, Detox, Maestro는 사람이 미리 테스트 스크립트를 작성하고 유지합니다. 반면 agent-device는 에이전트가 현재 화면을 읽고, 다음 행동을 정하고, 그 과정을 나중에 재실행 가능한 .ad script나 Maestro YAML로 넘길 수 있게 합니다.

핵심 개념

agent-device의 기본 루프는 단순합니다. 에이전트가 먼저 화면을 관찰하고, 현재 출력에서 받은 ref나 selector로 행동한 뒤, 다시 관찰해서 결과를 검증합니다.

flowchart LR
    A[Agent가 코드 수정] --> B[agent-device open]
    B --> C[snapshot -i로 앱 상태 관찰]
    C --> D[press / fill / scroll 등 실행]
    D --> E[재 snapshot으로 결과 검증]
    E --> F[screenshot / logs / replay script 증거 저장]
    F --> G[수정 또는 PR 리뷰]

README의 Quick start ↗는 Contacts 앱을 열고, snapshot -i로 @e2 같은 ref를 확인한 뒤, press @e2 --settle, fill @e7 "Ada" --settle, screenshot ./contact-form.png, close로 마무리하는 흐름을 보여줍니다. 중요한 점은 ref를 오래 믿지 말라는 규칙입니다. README는 --settle 이후 diff에 나온 최신 ref를 쓰고, 필요한 정보가 diff에 없으면 새 snapshot을 찍으라고 안내합니다.

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

접근성 snapshot을 중심 입력으로 쓰기 때문에, 앱의 접근성 품질이 곧 에이전트 자동화 품질이 됩니다. 버튼 이름, 역할, test id, form label이 잘 잡혀 있으면 에이전트가 더 안정적으로 화면을 이해합니다. 반대로 시각적으로는 멀쩡하지만 접근성 트리가 빈약한 앱은 에이전트에게도 흐릿하게 보입니다.

Tip 모바일 앱을 에이전트에게 맡기려면 먼저 접근성 label과 test id를 QA 인프라로 봐야 합니다. 화면 읽기 사용자에게 좋은 구조가 에이전트 자동화에도 그대로 이득이 됩니다.

설치와 에이전트 연결

Installation 문서 ↗는 agent-device를 에이전트가 터미널 명령을 실행할 머신에 설치하라고 안내합니다. 현재 package.json 기준으로 npm package 이름은 agent-device, CLI binary도 agent-device이며, Node.js 요구사항은 >=22.12입니다. 문서상 web automation은 Node.js 24 이상을 요구합니다.

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

AI Agent Setup 문서 ↗는 Cursor, Codex, Claude Code, Windsurf, Cline, Goose 같은 에이전트 클라이언트에서 CLI 또는 MCP로 연결하는 방법을 다룹니다. MCP 서버는 agent-device mcp로 실행하며, 문서는 MCP가 generic shell runner가 아니라 설치된 command contract를 구조화된 tool로 노출한다고 설명합니다.

agent-device mcp

Codex에서는 프로젝트 지침이나 AGENTS.md에 agent-device --version과 agent-device help workflow를 먼저 읽게 하는 규칙을 넣고, 터미널에서 CLI를 쓰게 하는 방식이 기본입니다. Claude Code는 CLI만 쓰거나 claude mcp add --transport stdio --scope user agent-device -- agent-device mcp로 MCP server를 등록할 수 있습니다.

주의 공식 setup 문서는 unattended agent에게 npx -y agent-device@latest를 조용히 실행시키지 말라고 권합니다. 매번 mutable npm package를 가져와 실행하기 때문입니다. 일반적인 에이전트 워크플로에서는 global install, project-local install, 또는 사용자가 검토한 정확한 버전을 쓰는 편이 낫습니다.

무엇을 할 수 있나?

Commands 문서 ↗는 명령 그룹을 꽤 넓게 잡습니다. 핵심은 open, snapshot, act, verify, evidence로 나눠 보면 쉽습니다.

범주	대표 명령	쓰임
대상 준비	`boot`, `open`, `close`, `devices`, `capabilities`	simulator, emulator, app session 준비
관찰	`snapshot -i`, `get`, `find`, `is visible`, `wait`	접근성 트리와 selector 기반 상태 확인
동작	`press`, `fill`, `scroll`, `gesture`, `back`, `home`	보이는 UI에 입력과 제스처 실행
증거	`screenshot`, `record`, `logs`, `network dump`, `trace`	리뷰와 디버깅에 필요한 artifact 저장
반복	`replay`, `test`, `replay export`	`.ad` script 재실행과 Maestro YAML export

모바일 앱에서 특히 유용한 부분은 로그와 네트워크입니다. Commands 문서는 logs clear --restart로 깨끗한 재현 창을 만들고, logs path로 경로를 얻은 뒤 grep으로 필요한 줄만 읽는 방식을 권합니다. network dump는 최근 HTTP 항목을 요약하거나 header/body 일부를 포함해 반환할 수 있습니다.

agent-device logs clear --restart
agent-device logs path
agent-device network dump 25 --include headers

React Native 팀이라면 Metro와도 연결됩니다. Commands 문서는 JavaScript 변경 후 agent-device metro reload를 사용해 Metro terminal에서 r을 누르는 것과 비슷한 reload를 실행하고, 이후 앱을 다시 열거나 snapshot으로 확인하는 흐름을 설명합니다.

agent-device metro reload
agent-device open com.example.myapp --platform android --serial emulator-5554 --relaunch
agent-device snapshot -i

Replay로 일회성 검증을 테스트 자산으로 바꾸기

agent-device의 흥미로운 지점은 에이전트가 탐색한 흐름을 그대로 버리지 않는다는 점입니다. Replay & E2E Testing 문서 ↗는 두 단계 모델을 제시합니다.

Agent pass: snapshot으로 현재 ref를 찾고 click @e.., fill @e..처럼 탐색합니다.
Deterministic pass: 기록된 .ad script를 replay로 다시 실행합니다.

agent-device open Settings --platform ios --session e2e --save-script
agent-device snapshot -i --session e2e
agent-device click @e13 --session e2e
agent-device close --session e2e

기본적으로 close 시점에 ~/.agent-device/sessions/<session>-<timestamp>.ad 경로로 replay script가 저장됩니다. 파일 경로를 직접 지정하려면 --save-script ./workflows/e2e-settings.ad처럼 넘길 수 있습니다.

agent-device replay ./workflows/e2e-settings.ad --session e2e-run

이 구조는 “에이전트가 한 번 잘 눌러본 흐름”을 CI 후보로 승격시키는 다리 역할을 합니다. 문서는 .ad script를 Maestro YAML로 export하는 agent-device replay export ./workflows/checkout.ad --out ./maestro/checkout.yaml도 제공합니다. 다만 exporter는 의도적으로 strict해서, agent-only inspection이나 지원하지 않는 selector shape를 조용히 버리지 않고 실패시킵니다.

어디에 잘 맞나?

agent-device가 가장 잘 맞는 곳은 “기능 구현 후 실제 앱에서 짧은 검증을 반복해야 하는” 구간입니다.

React Native 또는 Expo 앱에서 버튼, 폼, 라우팅, 접근성 label을 검증할 때
PR 리뷰에 screenshot, log, recording 같은 증거를 붙이고 싶을 때
에이전트가 고친 화면을 simulator/emulator에서 직접 확인하게 하고 싶을 때
탐색형 QA를 시작한 뒤 일부 흐름을 .ad replay나 Maestro YAML로 넘기고 싶을 때
Android TV, tvOS, Vega OS 같은 리모컨 중심 UI까지 같은 사고방식으로 다루고 싶을 때

반대로, 이미 안정적인 대규모 E2E suite가 있고 사람이 관리하는 테스트 코드가 충분하다면 agent-device를 전면 교체 도구로 볼 필요는 없습니다. README도 Appium, Detox, Maestro와 비교하면서 agent-device는 에이전트가 runtime에서 앱 상태를 읽고 명령을 선택하는 방식이며, 저장한 run을 .ad script나 strict Maestro YAML로 넘겨 기존 도구를 보완할 수 있다고 설명합니다.

운영할 때 조심할 점

첫째, 설치와 버전을 고정해야 합니다. Installation 문서는 global install 또는 project-local install을 일반 에이전트 워크플로에 권하고, CLI help가 현재 설치 버전의 operating contract라고 설명합니다. 블로그 글이나 예전 기억보다 agent-device help workflow가 우선입니다.

둘째, ref의 수명을 짧게 봐야 합니다. README는 최신 output에서 받은 ref만 쓰라고 강조합니다. 화면이 바뀐 뒤 오래된 @eN을 다시 쓰면 다른 요소를 누르거나 실패할 수 있습니다.

셋째, 접근성 트리를 QA 표면으로 관리해야 합니다. 접근성 snapshot이 흐릿하면 에이전트도 흐릿하게 판단합니다. 이건 도구 문제가 아니라 앱 구조 문제에 가깝습니다.

넷째, 민감한 데이터와 artifact 경로를 조심해야 합니다. Commands 문서는 logs, network dump, screenshot, record, trace가 증거를 남기는 기능이라고 설명합니다. PR이나 CI artifact에 올릴 때는 payload, header, 화면 내용, 앱 로그에 토큰이나 개인정보가 섞이지 않는지 확인해야 합니다.

주의 Replay 문서는 실패한 replay가 selector suggestion과 resume 정보를 줄 수 있지만, 자동 rewrite는 하지 않는다고 설명합니다. 제안된 selector를 사람이 검토하고 script를 직접 고친 뒤 새로 replay하는 쪽이 안전합니다.

마무리

agent-device의 방향은 분명합니다. AI 코딩 에이전트가 코드를 쓰는 데서 멈추지 않고, 실제 앱을 열고, 접근성 snapshot으로 상태를 읽고, 입력하고, 다시 확인하고, 증거를 남기게 하려는 도구입니다.

웹에서는 브라우저 자동화와 DevTools 연동이 에이전트 개발의 기본기가 되고 있습니다. 모바일 앱에서도 비슷한 일이 벌어질 가능성이 큽니다. 특히 React Native나 Expo처럼 코드 변경과 simulator 확인이 빠르게 이어지는 환경에서는 agent-device 같은 실행 레이어가 에이전트 워크플로의 빠진 조각이 될 수 있습니다.

참고 자료

callstack/agent-device GitHub README ↗ — 프로젝트 소개, quick start, 지원 대상
agent-device package.json ↗ — 현재 버전, Node.js engines, npm binary
Installation ↗ — 설치, 요구사항, MCP 실행
AI Agent Setup ↗ — Codex, Claude Code, Cursor, MCP 연결 방식
Replay & E2E Testing ↗ — .ad script, replay, Maestro export