Agent Device를 사용하여 AI 에이전트가 iOS 앱을 조작하게 해보았다

서론

Callstack Incubator가 공개한 Agent Device는 AI 에이전트용 CLI (Command Line Interface) 도구입니다. iOS / Android / TV / 데스크톱 앱을 조작할 수 있습니다. 액세서빌리티 트리 (Accessibility Tree)를 바탕으로 UI 요소에 @e1과 같은 참조를 통해 접근할 수 있습니다.

이를 통해 Claude Code나 Codex와 같은 코딩 에이전트가 "실제 기기를 보고·만지는" 것이 가능해집니다.

실제 사용감 측면에서 흥미로운 점은, CLI 명령어를 직접 입력할 필요가 거의 없다는 점입니다. Skill 대응 클라이언트를 위한 Skill이나, MCP (Model Context Protocol) 대응 클라이언트를 위한 MCP 서버가 공식적으로 제공되므로, 등록만 마치면 자연어로 요청하는 것만으로 동작합니다. 에이전트가 내부적으로 open → snapshot → screenshot 시퀀스를 구성하여 실행해 줍니다.

본 기사에서는 macOS + iOS 시뮬레이터에서 Skill을 통한 워크플로우를 구동하고, 내부에서 어떤 조작을 하고 있는지 CLI의 기본 루프와 함께 정리합니다.

Agent Device란 무엇인가

공식 README는 "Mobile app verification for AI agents"라고 설명하고 있습니다. 요점을 정리하면 다음과 같습니다.

• 액세서빌리티 트리 (Accessibility Tree)로 UI를 표현한다. 스크린샷이 아니라 요소의 role / label / text를 구조화한 스냅샷을 반환하므로, LLM (Large Language Model)의 토큰을 절약할 수 있습니다.
• 스냅샷 내의 각 요소에 짧은 핸들이 할당되어, @e1과 같은 짧은 ref (reference)로 조작할 수 있다. press @e2와 같은 형태로 바로 조작할 수 있습니다. ref는 스냅샷마다 다시 할당되므로 화면이 바뀌면 다시 가져와야 합니다.
• 크로스 플랫폼 (Cross-platform)을 지원한다. iOS / Android / tvOS / Android TV / macOS / Linux를 동일한 명령어 체계로 다룰 수 있습니다.
• 세션 단위로 상태를 유지한다. open으로 연 앱은 close할 때까지 상태를 유지하며, 여러 명령어를 가로질러 조작할 수 있습니다.
• 기록 및 재생이 가능하다. 조작 스크립트로 저장하여 결정론적(Deterministic)으로 재실행할 수 있습니다.
• 에이전트 연동을 전제로 한다. Skill / Rules / MCP 서버 / 직접 CLI 등 다양한 연동 방법을 공식적으로 준비하고 있어, 클라이언트가 대응하는 형태를 선택할 수 있습니다.

Vercel Labs의 agent-browser에서 착안하였으며, 공식 README에도 "the same idea for mobile, TV, and desktop apps"라고 명시되어 있습니다. 컨셉은 "코딩 에이전트가 모바일 UI를 직접 만질 수 있게 하는 것"입니다.

Appium / Maestro와 어떻게 다른가

Agent Device는 모바일 앱을 조작하는 도구이므로, Appium이나 Maestro와 같은 E2E (End-to-End) 테스트 도구와 유사한 영역으로 보입니다. 다만, 주안점은 조금 다릅니다.

관점	Appium	Maestro	Agent Device
주요 용도	E2E 테스트 자동화	E2E 테스트 자동화	AI 에이전트에 의한 UI 조작 및 replay
...			.ad suite 실행은 가능. 템플릿 구상은 있으나 전용 기반은 아직 미약함

테스트 케이스를 사람이 명시적으로 작성하고 CI (Continuous Integration)에서 안정적으로 실행하고 싶다면 Appium이나 Maestro가 후보가 됩니다. 반면, Claude Code 등의 에이전트에게 "지금 앱을 보고, 이 설정을 바꾸고, 결과를 확인해줘"라고 요청하는 용도라면 Agent Device가 더 자연스럽습니다.

그렇다고 해도, .ad 파일이 있으므로 Agent Device로도 E2E와 같은 재실행은 가능합니다. 차이점은 "처음부터 사람이 DSL (Domain Specific Language)을 작성하는 것"보다, "에이전트에게 실제 기기 UI를 탐색하게 하고, 그 성과를 replay 가능한 E2E 시나리오로 떨어뜨리는" 흐름을 만들기 쉽다는 점입니다.

이는 애드혹(Ad-hoc)한 수동 확인을 회귀 테스트(Regression Test)로 승격시키기까지의 거리가 짧아진다는 의미에서 유용합니다. 버그 수정 후의 재현 확인, 사양 변경 중의 스모크 테스트(Smoke Test), 액세서빌리티 레이블이나 화면 전환 조사 등을 우선 자연어로 시도해 보고, 안정적인 조작 순서와 확인 포인트를 발견하면 .ad

남길 수 있습니다.

반면, CI (Continuous Integration)에 올리는 관점에서는 Maestro가 전용 기반이 더 잘 갖춰져 있습니다. Maestro Cloud에는 병렬 실행, 디바이스 분리, GitHub Actions / Bitrise / CircleCI 등의 CI 연동, PR 연동 기능이 준비되어 있습니다. Agent Device도 .ad suite 실행, retry (재시도), artifacts (결과물) 출력은 가능하며, GitHub Actions / EAS용 템플릿도 공개되어 있습니다. 다만 템플릿은 얼리 액세스 (Request Early Access) 단계이므로, Maestro Cloud와 같은 매니지드 실행 기반으로 즉시 사용할 수 있는 것과는 성격이 다릅니다. 어떤 runner에서 simulator / emulator를 실행할지, 결과물을 어디로 집약할지, PR의 필수 체크 항목으로 어떻게 포함할지는 현 시점에서는 프로젝트 측에서 설계해야 할 부분이 커 보입니다.

셋업: CLI와 Skill / MCP 설치하기

셋업은 크게 2단계로 나뉩니다.

1. CLI 설치

npm install -g agent-device@latest
agent-device --version

pnpm / yarn에서도 마찬가지로 글로벌 설치가 가능합니다. 글로벌 환경을 더럽히고 싶지 않다면 npx agent-device@latest --version과 같이 매번 실행하는 방식으로도 동작합니다.

2. Claude Code에 Skill 넣기

여기서는 Claude Code를 예로 듭니다. Skill을 지원하는 클라이언트라면 공식 Skill을 설치하는 것이 가장 간편합니다.

npx skills add callstackincubator/agent-device

이렇게 하면 Claude Code 세션 내에서 agent-device Skill을 사용할 수 있게 됩니다. Skill은 내부적으로 agent-device help workflow를 읽어 들여, 버전에 맞는 올바른 커맨드 체계를 에이전트에게 전달합니다.

MCP (Model Context Protocol)를 지원하는 클라이언트 (Cursor 등)에서는 MCP 서버로 등록합니다.

{
"mcpServers": {
"agent-device": {
...

글로벌 설치를 하지 않은 경우에는 command를 npx로, args를 ["-y", "agent-device@<version>", "mcp"]로 교체합니다.

Claude Code에서 자연어로 요청하기

Skill 설치가 끝났다면, Claude Code의 채팅창에 평소처럼 요청을 작성하기만 하면 됩니다. 실제로 자신의 Expo 템플릿을 사용하여 "설정 화면에서 언어를 English로 변경했을 때 UI가 예상대로 영어로 바뀌는지"를 확인하도록 시켰을 때, 던진 문장은 다음과 같습니다.

"agent-device를 사용해서, iOS 시뮬레이터에서 실행 중인 앱의 설정 언어를 English로 바꿨을 때의 동작을 확인하고 스크린샷을 찍어줘"

에이전트가 실행한 커맨드 열을 순서대로 나열하면 다음과 같은 흐름이 되었습니다.

• agent-device devices --platform ios로 구동 중인 시뮬레이터 열거
• agent-device apps --platform ios로 대상 앱 탐색 → 해당 앱이 설치되어 있지 않아 Expo Go를 통한 접근으로 판단
• lsof -nP -iTCP:8081 -sTCP:LISTEN으로 Metro가 실행 중임을 확인
• agent-device open "Expo Go" exp://127.0.0.1:8081 --platform ios로 앱 열기
• agent-device snapshot -i로 UI 트리(UI tree)를 가져오고, @e26 [button] "설정, tab, 2 of 2"와 같은 ref (참조)를 분석
• 설정 탭 → 언어 셀 → 피커(picker)에서 English를 차례로 탭
• 주요 화면마다 agent-device screenshot ./xxx.png로 증적 저장

사람은 커맨드 체계나 액세시빌리티 레이블 (accessibility label) 형식을 알 필요가 없습니다. Skill이 "snapshot -i

를 찍어서 ref를 ID로 지정한다", "액션이 일어날 때마다 다시 찍는다"라는 규칙을 에이전트가 준수하도록 만들어 줍니다.

(참고) CLI를 직접 다루며 동작 이해하기

평소에는 Skill을 통해 처리하는 경우가 많지만, 디버깅 시나 CI/CD에 통합할 때는 CLI를 직접 호출하게 됩니다. 기본 패턴을 익혀두면 에이전트가 무엇을 하고 있는지 이해하기 쉬워집니다.

# 1. 앱 목록
agent-device apps --platform ios
# 2. 앱 실행 (bundle id 지정)
...

snapshot -i의 출력 이미지는 다음과 같은 형태입니다 (정렬됨).

@e1 button "Tabs"
@e2 textfield "Address" placeholder="Search or enter website name"
@e3 button "Bookmarks"
...

여기서부터는 ref를 지정하여 조작합니다.

agent-device fill @e2 "https://zenn.dev"
agent-device screenshot ./artifacts/zenn-top.png
agent-device close

기본 루프는 open -> snapshot -i -> press/fill/scroll -> verify -> close입니다. 화면 전환이 일어날 때마다 snapshot을 다시 찍는 것이 철칙입니다.

.ad 파일로 E2E 시나리오 실행해 보기

자연어로 요청하는 방식은 탐색에는 편리하지만, 동일한 확인 작업을 반복해서 실행하고 싶을 때는 .ad 파일로 저장해 두면 다루기 쉽습니다. .ad는 Agent Device의 시나리오 파일로, open, press, wait, is, close와 같은 조작을 순서대로 작성할 수 있습니다.

이번 템플릿에서는 설정 화면에서 언어를 일본어로 변경하고, UI가 일본어로 바뀌었는지 확인하는 시나리오를 e2e/settings-language.ad로 배치했습니다.

# 설정 탭에서 언어를 일본어로 변경하고, UI가 일본어화되었는지 확인하는 재사용 시나리오.
# 실행: agent-device test ./e2e/settings-language.ad
# 전제 조건: Metro 실행 완료 (pnpm start) 및 iOS 시뮬레이터에서 Expo Go 사용 가능.
...

실행은 agent-device test입니다. 사전에 Metro를 실행하고, iOS 시뮬레이터에서 Expo Go를 사용할 수 있는 상태로 만들어 둡니다.

agent-device test ./e2e/settings-language.ad

실행 후에는 .agent-device/test-artifacts/ 하위에 결과가 남습니다. 이번 실행에서는 다음과 같은 result.txt가 생성되었습니다.

file: <workspace>/e2e/settings-language.ad
session: default:test:<run-id>:1-settings-language:attempt-1
attempt: 1/1
...

실제 파일은 다음과 같은 경로에 출력됩니다.

.agent-device/test-artifacts/<run-id>/e2e__settings-language.ad/attempt-1/result.txt

동일한 디렉토리에는 replay.ad도 저장되어 있어, 어떤 시나리오를 실행한 결과인지 나중에 확인할 수 있습니다.

.agent-device/test-artifacts/<run-id>/e2e__settings-language.ad/attempt-1/
├── replay.ad
└── result.txt

포인트는 화면의 문구나 액세시빌리티 레이블 (accessibility label)을 조건으로 작성할 수 있다는 점입니다. 위의 예시에서는 시작 언어가 영어든 일본어든 상관없이 동작하도록 ||를 사용하여 후보 레이블을 나열했습니다. is "visible"을 통해 言語, 日本語와 利用規約이 표시되어 있는 것까지 확인하고 있으므로, 단순한 조작 재생이 아니라 최소한의 기대치(expectation)를 포함한 E2E 시나리오가 됩니다.

이런 형태로 구성해 두면, 자연어(Natural Language)로 시도한 확인 과정을 '일회성 검증'으로 끝내지 않고, 나중에 재실행할 수 있는 스모크 테스트(Smoke Test)로 만들 수 있습니다. 처음부터 완성도 높은 E2E를 작성하기보다는, 에이전트가 탐색한 조작 순서, 접근성 레이블(Accessibility Label), 확인 포인트(Confirmation Point)를 인간이 확인하고 .ad 파일로 옮겨가며 키워 나가는 이미지입니다.

CI에서 실행할 경우에도, 명령어 자체는 agent-device test로 충분합니다.

agent-device test ./e2e --timeout 60000 --retries 1 --artifacts-dir ./tmp/agent-device-artifacts

다만, 모바일 CI 관점에서 보면, 이 이후의 환경 구축은 별도로 필요합니다. 예를 들어, iOS 시뮬레이터(Simulator)나 Android 에뮬레이터(Emulator)를 실행하는 러너(Runner), Expo / Metro의 실행, 테스트용 앱 바이너리(App Binary) 준비가 필요합니다. 스크린샷이나 리플레이 로그(Replay Log)의 저장, PR 코멘트나 필수 체크 항목으로의 반영 등도 GitHub Actions와 같은 CI 측에서 구성해야 합니다. Agent Device 측에도 GitHub Actions / EAS용 템플릿 구상이 있지만, 현시점에서는 얼리 액세스(Early Access) 단계입니다. 이 부분은 Maestro Cloud와 같은 매니지드(Managed) 기반을 가진 도구와의 차이점으로 이해해 두면 좋을 것 같습니다.

요약

• Agent Device는 모바일 UI를 'AI 에이전트가 이해하기 쉬운 형태'로 공개하는 CLI이며, 스크린샷에 의존하지 않는 설계가 신선했다.
• 셋업만 완료되면 CLI 명령어를 외우지 않아도 자연어로 요청하는 것만으로 동작한다. 스크린샷이 아닌 구조화된 스냅샷(Structured Snapshot)을 반환하고, 요소를 짧은 ref @eN으로 지정할 수 있어 LLM의 컨텍스트(Context) 소비도 억제할 수 있다.
• Skill / MCP가 공식적으로 제공되므로, 코딩 에이전트에게 자연어로 요청하는 워크플로우와 궁합이 좋다.
• .ad 파일로 남겨두면 E2E처럼 재실행할 수 있어, 애드혹(Ad-hoc)한 수동 확인을 스모크 테스트로 승격시키기 쉽다.
• CI에 올리는 것 자체는 가능하다. 다만 Maestro Cloud와 같이 일반 사용이 용이한 매니지드 실행 기반과는 아직 차이가 있으며, 러너(Runner)나 아티팩트(Artifacts) 관리는 프로젝트 측에서 설계해야 한다.

참고 링크

Discussion