droidrun/mobile-harness

Mobile Harness – Android 및 iOS에서 AI 에이전트를 위한 휴대용 제어 지침

정의 – 언어 모델 기반 AI 에이전트가 실제 Android 또는 iOS 기기와 통신할 수 있게 하는 경량의 Markdown 중심 하네스입니다. 에이전트 런타임이 아닙니다. 에이전트가 UI 작업, 스크린샷, 앱 실행 등을 수행하기 위해 호출하는 Python API(mobilerun_core)를 제공합니다. 이 하네스는 로컬 기기(ADB 또는 Portal HTTP 서버를 통해) 및 Mobilerun 클라우드 서비스를 통한 클라우드 호스팅 기기에서 작동합니다.

주요 기능

• 한 번의 호출로 기기에 연결:

  from mobilerun_core import Mobilerun
  m = Mobilerun()
  dev = m.connect("<id>", backend="cloud")
  

• Android 및 iOS용 통합 API: ui(), screenshot(), start_app(), tap_node(), type(), scroll() 등.
• 접근성 트리에서 작동하는 헬퍼 메서드(find_nodes, tap_text, scroll_until).
• 자동 기능 감지(device.capabilities, device.supports(...)).
• 선택적 클라우드 백엔드(MOBILERUN_CLOUD_API_KEY 필요).
• 로컬 백엔드:
  • ADB를 통한 Android(더 풍부한 기능을 위한 선택적 Portal HTTP 포함).
  • Android Portal HTTP 전용.
  • 오픈 소스 ios-portal HTTP 서버를 통한 iOS.
• 에이전트가 생성한 모든 상태(메모리, 자격 증명, 사용자 지정 앱 카드)는 git 무시 local/ 폴더에 저장되어 사용자 데이터를 저장소와 분리합니다.

벤치마크 – 표준 코딩 에이전트와 GPT-6 스타일 모델을 사용하여 공개 AndroidWorld(116개 작업) 및 iOSWorld(133개 작업) 스위트에서 평가되었습니다. 결과: Android 평균 점수 100%, iOS 평균 점수 98.24%, 바이너리 통과율은 각각 100% 및 93.23%입니다. 자세한 작업 재생 및 방법론은 README에 링크되어 있습니다.

설치

1. 저장소를 클론합니다.
2. Python 가상 환경(Python 3.11-3.13)을 만들고 핵심 라이브러리를 설치합니다:

   python -m venv .venv
   .venv/bin/pip install "mobilerun-core[local]"
   .venv/bin/python -c "from mobilerun_core import Mobilerun"
   

3. 플랫폼별 설정(ADB, Portal 서버, 클라우드 API 키 등)은 install.md를 따르세요.

AI 에이전트 사용 방법 – README에는 에이전트에게 저장소를 클론하고 설치 단계를 실행하도록 지시하는 붙여넣기 가능한 Agent Setup Prompt가 제공됩니다. 환경이 준비되면 에이전트는 생성된 코드에서 직접 Mobilerun을 가져오고, 기기에 연결하고, 기능을 쿼리하고, UI 작업을 호출할 수 있습니다.

배포 – 이 하네스는 skills.sh CLI(npx skills add droidrun/mobile-harness)를 통해 스킬로 에이전트에 추가하거나 Claude Code 플러그인(/plugin marketplace add droidrun/mobile-harness)으로 추가할 수 있습니다. 두 방법 모두 동일한 Python 패키지를 설치하고 local/ 데이터 디렉토리를 적절한 런타임 위치에 유지합니다.

대상 사용자 – LLM 기반 모바일 자동화 에이전트를 구축하는 연구원 및 개발자, 특히 Android와 iOS 모두에서 일관되고 언어 모델에 친화적인 API가 필요한 사람들(기기가 로컬 또는 클라우드에서 실행되는지 여부에 관계없이).