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 프레임워크로 설계되지 않았습니다. 프론트엔드 팀은 코드 생성 다음 단계인 실제 앱 검증을 에이전트 루프 안에서 처리하는 데 이 도구를 씁니다.
왜 필요한가?
웹 자동화 쪽에서는 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 TD
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 closeagent-device는 접근성 snapshot을 중심 입력으로 씁니다. 그래서 앱의 접근성 품질이 곧 에이전트 자동화 품질이 됩니다. 버튼 이름, 역할, test id, form label이 잘 잡혀 있으면 에이전트가 더 안정적으로 화면을 이해합니다. 반대로 시각적으로는 멀쩡하지만 접근성 트리가 빈약한 앱은 에이전트에게도 흐릿하게 보입니다.
설치와 에이전트 연결
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 workflowAI Agent Setup 문서 ↗는 Cursor, Codex, Claude Code, Windsurf, Cline, Goose 같은 에이전트 클라이언트에서 CLI 또는 MCP로 연결하는 방법을 다룹니다. MCP 서버는 agent-device mcp로 실행합니다. 문서에 따르면 MCP는 임의 셸 명령을 실행하지 않고, 설치된 command contract를 구조화된 tool로 노출합니다.
agent-device mcpCodex에서는 프로젝트 지침이나 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를 등록할 수 있습니다.
npx -y agent-device@latest를 조용히 실행시키지 말라고 권합니다. 매번 mutable npm package를 가져와 실행하기 때문입니다. 일반적인 에이전트 워크플로라면 global install, project-local install, 또는 사용자가 검토한 정확한 버전을 씁니다.
무엇을 할 수 있나?
Commands 문서 ↗의 명령은 대상 준비, 관찰, 동작, 증거, 반복으로 나눌 수 있습니다.
| 범주 | 대표 명령 | 쓰임 |
|---|---|---|
| 대상 준비 | 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 headersReact 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 -iReplay로 일회성 검증을 테스트 자산으로 바꾸기
agent-device는 에이전트가 탐색한 흐름을 script로 저장합니다. Replay & E2E Testing 문서 ↗는 두 단계 모델을 제시합니다.
- Agent pass:
snapshot으로 현재 ref를 찾고click @e..,fill @e..처럼 탐색합니다. - Deterministic pass: 기록된
.adscript를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를 시작한 뒤 일부 흐름을
.adreplay나 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, 화면 내용, 앱 로그에 토큰이나 개인정보가 섞였는지 먼저 확인합니다.
마무리
웹에서는 브라우저 자동화와 DevTools 연동을 에이전트 개발에 이미 씁니다. React Native나 Expo처럼 코드 변경과 simulator 확인이 빠르게 이어지는 환경이라면 agent-device로 같은 검증 루프를 모바일 앱에 만들 수 있습니다.
관련 내부 포스트:
- Chrome DevTools MCP: AI 에이전트로 브라우저 세션 디버깅하기 — 웹 런타임을 에이전트에게 열어주는 흐름
- OpenAI Codex 모바일 앱 통합 — 모바일에서 에이전트 작업을 운영하는 관점
- OpenAI Codex Record & Replay — 반복 가능한 작업 흐름을 skill과 replay 관점으로 보는 글
참고 자료
- 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 ↗ —
.adscript, replay, Maestro export