<a href="https://www.callstack.com/open-source?utm_campaign=generic&utm_source=github&utm_medium=referral&utm_content=agent-device" align="center">
<picture>
<img alt="agent-device: open source device layer for agents" src="https://raw.githubusercontent.com/callstack/agent-device/HEAD/website/docs/public/agent-device-banner.jpg">
</picture>
</a>
agent-device
npm version
CI
License: MIT
Glama MCP server
AI 코딩 에이전트를 위한 오픈 소스 디바이스 계층입니다. 코딩 에이전트가 로컬 또는 클라우드 환경에서 디바이스 및 시뮬레이터의 모바일, 웹, TV, 데스크톱 앱을 CLI(Command Line Interface), 내장 MCP 서버 또는 타입 지정된 Node.js API를 통해 제어할 수 있도록 합니다.
<!-- Intro rule: category line, job pitch with the platform list, works-with/proof lines, nothing else. Per-platform transports, tool names, vendor lists, and support caveats belong in "How it works" and website/docs, never here. Every name in the proof lines must link to public evidence. -->
코딩 에이전트가 실행 중인 앱에서 변경 사항을 검증하도록 하세요. agent-device는 iOS, Android 및 HarmonyOS(시뮬레이터, 에뮬레이터, 실제 디바이스), 그리고 tvOS, Android TV, Fire TV (Fire OS), Amazon Vega OS TV (Vega Virtual Device), 웹, macOS, Linux에서 앱을 검사하고, 제어하며, 디버깅하고, 검증할 수 있도록 합니다. 에이전트는 단순히 스크린샷에 대한 추론 대신 토큰 효율적인 접근성 스냅샷을 읽고, 참조(refs)와 선택자(selectors)를 통해 동작하며, 검토를 위한 증거를 저장합니다. 또한 병렬 에이전트 작업 트리 전반에 걸쳐 디바이스 액세스를 조정하고 원격 디바이스 클라우드에 연결할 수 있습니다.
Claude Code, Codex, Cursor, Windsurf, Cline, Goose 및 CLI를 실행하거나 MCP(Message Control Protocol)를 통해 연결할 수 있는 모든 에이전트와 함께 작동하며, AI SDK 또는 Eve로 구축하는 에이전트의 런타임으로도 사용될 수 있습니다. Expensify, Shopify 및 기타 사용자들은 이를 사용하여 앱을 검증합니다.<p>
agent-device는 다음에서 모바일 자동화 기능을 제공합니다.
<a href="https://e2e.tester.army/?utm_source=github&utm_medium=organic&utm_campaign=agent-device-readme-202610&utm_content=readme-powered-by">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/e2e-logo-dark.png">
<img src="https://raw.githubusercontent.com/callstack/agent-device/HEAD/docs/assets/e2e-logo-light.png" width="24" height="24" align="middle" alt="">
</picture>
e2e</a>
그리고
<a href="https://github.com/pingdotgg/t3code">
<img src="https://raw.githubusercontent.com/callstack/agent-device/HEAD/docs/assets/t3-code-logo.svg" width="24" height="24" align="middle" alt="">
T3 Code</a>.</p>
빠른 시작 (Quick start)
CLI를 설치하고 설정을 확인합니다. Node.js 22.12 이상이 필요하며, 웹 자동화에는 Node.js 24 이상이 필요합니다. 대상 요구 사항은 설치(Installation)를 참조하십시오.
npm install -g agent-device@latest
agent-device doctor
agent-device help workflow
CLI를 에이전트에게 전달하기 전에 직접 doctor를 실행하십시오. help workflow는 디버깅, 리플레이 및 프로파일링에 대한 가이드로 연결됩니다.
CLI에서 앱 구동하기 (Drive an app from the CLI)
내장된 iOS 연락처 앱에 연락처를 추가합니다:
agent-device open Contacts --platform ios
...
참조(Refs)는 최신 출력에서만 유효합니다: --settle 명령 실행 후, 해당 diff에 있는 참조를 사용하고 필요한 내용이 diff에 누락된 경우에만 새 스냅샷을 찍으세요. 스냅샷은 앱의 접근성 트리(accessibility tree)에서 가져오므로, 명확한 레이블(labels), 역할(roles), 테스트 ID는 에이전트 실행을 더 안정적으로 만듭니다. 접근성 데이터가 부족할 때는 스크린샷과 비디오를 증거로 사용하세요.
agent-device demo showing Codex using agent-device to create a new contact in the iOS Contacts app from a simple prompt
에이전트에 MCP 도구 추가하기
agent-device mcp는 공식 stdio MCP 서버를 시작하며, 설치된 명령을 CLI와 동일한 실행 경로에서 구조화된 도구(structured tools)로 노출합니다:
{
"mcpServers": {
"agent-device": {
...
개별 클라이언트 설정 및 MCP 대신 일반 CLI를 선호해야 하는 경우에 대한 내용은 AI agent setup을 참조하세요.
Node.js에서 스크립팅하기
createAgentDeviceClient()는 사용자의 에이전트 내 또는 오케스트레이션 코드에서 모델 도구(model tools)처럼 동일한 명령에 대한 타입 접근을 Node.js 코드에 제공합니다:
import { createAgentDeviceClient } from 'agent-device';
const client = createAgentDeviceClient({ session: 'qa-run' });
...
Node.js API, 실행 가능한 예제, 그리고 AI SDK 및 Eve 통합 가이드를 참조하세요.
에이전트가 할 수 있는 일
- 접근성 스냅샷(accessibility snapshots), 참조(refs), 선택자(selectors)를 통해 앱 상태를 검사하고, React Native 렌더링을 프로파일링하여 상호 작용 속도를 저하시키는 요소를 찾을 수 있습니다.
- 요소 탭 또는 누르기, 필드 채우기, 스크롤, 제스처 수행, 대기(waiting), 상태 단언(asserting state), 알림 처리 등을 통해 보이는 UI에 조치를 취할 수 있습니다.
- 스크린샷, 비디오, 로그, 트레이스, 네트워크 데이터, 성능 샘플, 충돌 상세 정보 및 React 프로파일을 사용하여 실패를 진단할 수 있습니다.
- 로컬 사용 또는 CI(지속적 통합)용으로 작동 단계를
.ad 스크립트로 저장하여 워크플로우를 반복할 수 있습니다. 필요에 따라 엄격한 Maestro YAML로 내보낼 수 있습니다.
각 타겟이 지원하는 명령어와 증거(evidence)는 [Commands]를 참조하세요.
Diagram of the agentic development loop: humans assign tasks, agents write and review code, agent-device verifies mobile apps, pull requests receive evidence, and bugs or performance issues lead to fixes
에이전트에게 무엇을 요청해야 할까요 (What to ask your agent)
CLI가 설치되면 다음과 같은 프롬프트들이 엔드투엔드로 작동합니다:
- "온보딩 화면을 구현하고, 이를 iOS 시뮬레이터와 Android 에뮬레이터에서 실행한 후 스크린샷을 첨부해 주세요."
- "이 충돌(crash)을 재현하고 그로 이어지는 로그를 캡처해 주세요."
- "이 변경 사항이 불필요한 React Native 리렌더링을 유발하는지 확인해 주세요."
- "결제 흐름(checkout flow)을 한 번 탐색하고, 이를 재생 스크립트(replay script)로 저장하여 CI에서 실행해 주세요."
- "이 풀 리퀘스트(pull request)를 실제 장치(physical device)에서 검증하고 검토 가능한 증거를 첨부해 주세요."
다음 단계 (Next steps)
agent-device를 실행할 위치 (Where to run agent-device)
동일한 세션 및 증거 모델이 모든 단계에서 작동합니다. 에이전트는 앱을 탐색하고, 증거를 캡처하며, 재생(replay)을 저장하고, CI에서 실행한 다음, 원격 장치로 이동합니다.
| 경로 (Path) | 최적의 용도 (Best for) | 시작 방법 (Start with) |
|---|
| Local | 시뮬레이터, 에뮬레이터, 실제 장치(physical devices), macOS 및 Linux에서 명령어를 테스트하고 앱을 디버깅하는 경우. | Quick Start를 따르세요. |
| ... | | |
작동 방식 (How it works)
agent-device는 세션에 장치 상태(device state)를 유지합니다. iOS 시뮬레이터 스냅샷을 위해 로컬 접근성 브릿지(local accessibility bridge)와 XCTest를, 물리적 iOS 및 tvOS 상호 작용을 위해 사용하며; Android, Android TV, Fire OS에는 ADB와 스냅샷 헬퍼를, HarmonyOS에는 HDC 및 ArkUI uitest를, Vega Virtual Device에는 Vega CLI/VDA를, macOS에는 접근성 트리(accessibility tree)를 통해 Electron 및 기타 Chromium 기반 앱을 포함하는 로컬 헬퍼를, Linux에는 AT-SPI를 사용합니다.
지원 깊이는 대상(target)마다 다릅니다. HarmonyOS나 Vega OS와 같은 일부 백엔드는 명령어의 부분 집합을 지원합니다. 어떤 대상이 무엇을 지원하는지 확인하려면 agent-device capabilities --platform <platform>을 실행하세요. capabilities matrix에는 각 대상, 데스크톱, 웹 및 클라우드 제공업체가 어떤 명령어를 지원하는지 보여줍니다.
세션은 호출자의 git worktree 범위로 제한되며, 호스트 로컬 장치 클레임(host-local device claims)은 병렬 에이전트가 서로의 시뮬레이터와 에뮬레이터를 가로채는 것을 방지합니다. 데몬 없이 소유권을 검사하려면 agent-device device status를 실행하고, 소유자가 확실히 더 이상 실행되고 있지 않은 클레임을 해제하려면 agent-device device release --stale을 실행하세요. 동일한 명령어들은 BrowserStack, AWS Device Farm, TestMu AI, Limrun에서 호스팅되는 장치들을 구동합니다.
agent-device는 모바일, TV 및 데스크톱 앱의 경우 Vercel의 agent-browser에서 가져온 inspect-act-verify 프로세스를 사용합니다. 기본적인 --platform web 지원은 동일한 세션과 리플레이 시스템 내에서 agent-browser를 실행합니다.
FAQ
agent-device란 무엇인가요?
agent-device는 AI 코딩 에이전트가 모바일 앱을 검사(inspect), 제어(control), 검증(verify)하고 검토를 위해 증거를 저장할 수 있게 해주는 명령줄 도구이자 MCP 서버입니다. iOS, Android, HarmonyOS, TV, 웹, macOS 및 Linux를 지원합니다.
모바일 앱 자동화를 위한 MCP 서버가 있나요?
네. agent-device mcp는 공식 stdio MCP 서버를 시작합니다. 위의 퀵 스타트에는 클라이언트 설정이 포함되어 있으며, AI agent setup에서 클라이언트별 세부 정보를 다룹니다.
React Native, Expo, Flutter 및 네이티브 앱과 작동하나요?
네. agent-device는 지원되는 대상에서 네이티브 iOS 및 Android 앱뿐만 아니라 React Native, Expo, Flutter 앱도 지원합니다. 명령어와 증거는 대상마다 다릅니다.
모바일 MCP 서버와 어떻게 다른가요?
MCP 서버는 CLI와 타입이 지정된 Node.js API가 사용하는 동일한 런타임에 대한 진입점 중 하나입니다. 세션(Sessions), 디바이스 소유권(device ownership), 셀렉터(selectors), 증거(evidence), 리플레이(replay), CI 워크플로우(CI workflows), 클라우드 라우팅(cloud routing)은 이 세 가지 모두에서 일관되게 유지됩니다.
agent-device를 사용하여 자체 에이전트 또는 QA 제품을 구축할 수 있나요?
네. 타입이 지정된 Node.js 클라이언트는 동일한 런타임 위에 구축된 공개 인터페이스(public surface)이므로, 사용자가 구축하는 에이전트는 위의 모든 기능을 상속받습니다. Node.js API, AI SDK, 또는 Eve 가이드를 참고하여 시작하세요.
Appium, Detox 또는 Maestro와 어떻게 다른가요?
agent-device를 사용하면 에이전트가 앱 상태를 읽고 실행 시간(run time)에 각 명령을 선택합니다. 안정적이고 반복 가능한 테스트 스위트(test suites)의 경우, 웹 및 모바일 앱용 TypeScript 테스트 프레임워크인 e2e를 사용하세요. agent-device는 실행 기록을 .ad 스크립트로 저장하거나 엄격한 Maestro YAML 형식으로 내보낼 수도 있습니다.
agent-device는 CI에서 실행될 수 있나요?
네. 실행 기록을 .ad 스크립트로 녹화하고 CI에서 리플레이하며, 스크린샷과 로그를 아티팩트(artifacts)로 보관할 수 있습니다. EAS 워크플로우 템플릿이 작동하는 예시입니다.
아티클 및 비디오
아티클
비디오
누가 agent-device를 사용하나요?
