Skip to content
푸땡로그
Go back

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, 공식 문서 확인 내용 기준입니다.

왜 필요한가?

웹 자동화 쪽에서는 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을 찍으라고 안내합니다.

Bash
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

agent-device는 접근성 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 이상을 요구합니다.

Bash
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는 임의 셸 명령을 실행하지 않고, 설치된 command contract를 구조화된 tool로 노출합니다.

Bash
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 문서 ↗의 명령은 대상 준비, 관찰, 동작, 증거, 반복으로 나눌 수 있습니다.

범주대표 명령쓰임
대상 준비boot, open, close, devices, capabilitiessimulator, 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 일부를 포함해 반환할 수 있습니다.

Bash
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으로 결과를 확인합니다.

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

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

agent-device는 에이전트가 탐색한 흐름을 script로 저장합니다. Replay & E2E Testing 문서 ↗는 두 단계 모델을 제시합니다.

  1. Agent pass: snapshot으로 현재 ref를 찾고 click @e.., fill @e..처럼 탐색합니다.
  2. Deterministic pass: 기록된 .ad script를 replay로 다시 실행합니다.
Bash
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처럼 넘길 수 있습니다.

Bash
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는 기능 구현 후 실제 앱에서 짧은 검증을 반복해야 하는 구간에 맞습니다.

이미 안정적인 대규모 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는 하지 않는다고 설명합니다. replay가 실패하면 제안된 selector를 사람이 검토하고, script를 직접 고친 뒤 새로 replay합니다.

마무리

웹에서는 브라우저 자동화와 DevTools 연동을 에이전트 개발에 이미 씁니다. React Native나 Expo처럼 코드 변경과 simulator 확인이 빠르게 이어지는 환경이라면 agent-device로 같은 검증 루프를 모바일 앱에 만들 수 있습니다.

관련 내부 포스트:


참고 자료


Share this post on:

Previous Post
디지털 접근성 소송 연간 약 6,000건 추세, AI 생성 콘텐츠의 접근성 검증 격차 — A11Y 주간 다이제스트 2026.07.27 ~ 08.02
Next Post
Grues in Comic: AI 에이전트가 클래식 게임을 다시 엮는 법