DroidRun: 자연어 명령으로 모바일 기기를 제어하는 AI 에이전트 프레임워크

9bow · 1월 23, 2026, 6:30오전

DroidRun 소개

DroidRun은 대규모 언어 모델(LLM, Large Language Model) 및 시각-언어 모델(VLM, Vision-Language Model)을 활용하여 Android 및 iOS 모바일 기기를 제어하고 자동화할 수 있는 강력한 프레임워크입니다. "Open Settings and turn on WiFi(설정 앱을 열고 와이파이를 켜줘)"와 같은 자연어 명령만으로 실제 스마트폰의 앱을 실행하고, 버튼을 클릭하며, 복잡한 워크플로우를 수행할 수 있게 해줍니다.

기존의 모바일 자동화 도구(Appium 등)는 사전에 정의된 좌표나 ID 기반의 스크립트가 필요하여 유지보수가 어렵고 유연성이 떨어졌습니다. 반면, DroidRun은 시각적 정보(Vision)와 접근성 트리(Accessibility Tree)를 이해하는 AI 에이전트를 통해, 마치 사람이 화면을 보고 조작하는 것처럼 유연하게 기기를 제어합니다.

DroidRun 프로젝트는 단순히 터치 명령을 보내는 것을 넘어, 화면의 상태를 분석(Vision capabilities)하고, 작업을 수행하기 위한 계획(Planning)을 수립하며, OpenAI, Gemini, Anthropic, Ollama 등 다양한 LLM 프로바이더를 입맛에 맞게 교체하여 사용할 수 있는 LLM Agnostic(특정 모델에 종속되지 않는) 구조를 갖추고 있습니다.

DroidRun vs. 기존 모바일 자동화 도구 비교

모바일 앱 테스트 및 자동화 분야에서 널리 쓰이는 Appium 및 UiAutomator 등과 같은 기존의 모바일 자동화 도구와 비교해보겠습니다. 기존의 도구들은 엄격한 선택자(Selector)와 코드 기반의 스크립트 작성이 필수적이며, 이에 따라 App UI가 조금만 바뀌어도 스크립트가 깨지는 문제(Brittle tests)가 발생합니다. 또한, "이 앱에서 가장 싼 호텔을 예약해줘"와 같은 추상적인 명령 수행이 불가능한 한계가 있었습니다.

이에 비해, AI 에이전트 방식으로 동작하는 DroidRun은 별도의 코드 기반 스크립트를 작성하지 않고, 자연어로 명령을 내릴 수 있습니다. DroidRun은 텍스트 정보뿐만 아니라 화면 이미지를 인식하는 VLM(Vision-Language Model)을 적극적으로 활용합니다. 따라서, AI 에이전트가 화면(Screenshot)이나 텍스트 요소를 분석하고 동작하기 때문에, UI 요소의 위치가 바뀌더라도 맥락에 맞는 버튼을 찾아 클릭합니다.

DroidRun의 주요 기능

DroidRun은 호스트 PC(Python 환경)와 모바일 기기(Android/iOS) 간의 통신을 중개하며, AI 모델의 추론 결과를 실제 디바이스 액션으로 변환합니다.

접근성 서비스를 위한 DroidRun Portal

DroidRun의 핵심 컴포넌트 중 하나는 모바일 기기에 설치되는 DroidRun Portal App입니다. DroidRun Portal App은 Android의 '접근성 서비스(Accessibility Service)' 권한을 사용하여 현재 화면에 있는 모든 UI 요소(버튼, 텍스트 입력창, 스크롤 영역 등)의 구조적 정보(Accessibility Tree)를 추출합니다.

또한, 단순한 좌표 클릭뿐만 아니라 특정 UI 요소에 ID를 할당하여 에이전트가 정확하게 대상을 식별하고 조작할 수 있도록 돕습니다.

특정 사업자에 종속되지 않는 멀티 모델 지원 (Model Agnostic)

특정 AI 모델에 락인(Lock-in)되지 않고, 사용자의 환경이나 비용, 성능 요구사항에 따라 모델을 선택할 수 있습니다. Google을 비롯하여 OpenAI, Anthropic, DeepSeek 등의 모델들을 지원하며, 로컬 모델을 위한 Ollama 또한 지원하고 있습니다.

모델 설정을 위해서는 config.yaml 파일을 변경하거나 CLI 인자를 통해 손쉽게 프로바이더를 변경할 수 있습니다. (예: --provider gemini --model gemini-2.0-flash) 상세한 내용은 DroidRun 공식 문서에서 확인하실 수 있습니다.

시각적 이해 기능 (Vision Capabilities)

DroidRun은 단순히 텍스트 트리 구조만 의존하는 것이 아니라, 화면 스크린샷을 캡처하여 AI에게 시각적 컨텍스트를 제공합니다. 이를 통해 에이전트는 현재 화면을 보고 "지금 로그인 화면이구나"라거나 "오류 팝업이 떴구나"와 같은 상황 판단을 할 수 있습니다.

이를 통해 접근성 정보가 누락된 커스텀 UI(게임 화면 등)에서도 시각 정보를 바탕으로 상호작용할 위치를 추정하고, 사용자의 요청에 맞춰 동작할 수 있습니다.

강력한 디버깅 및 추적 (Tracing)

에이전트가 어떤 생각 과정을 거쳐 행동했는지 파악하는 것은 매우 중요합니다. DroidRun은 에이전트의 동작 확인 및 추적을 위해 Arize Phoenix와 연동을 지원합니다. 사용자는 실행 추적(Trace) 기능을 통해 에이전트가 받은 프롬프트, LLM의 응답, 도구 실행 결과, 발생한 에러 등을 시각적으로 확인할 수 있습니다.

CLI 및 Python SDK 지원

개발자는 터미널에서 바로 명령을 내리거나, Python 코드로 복잡한 자동화 파이프라인을 구축할 수 있습니다. 다음은 CLI 사용 예시입니다:

# 기본 사용 (OpenAI)
droidrun "Open Settings and change display brightness to 50%"

# Gemini 모델 사용 및 Vision 기능 활성화
droidrun "Open Gallery and find photos of cats" --provider gemini --model gemini-2.0-flash --vision

다음은 Python SDK 사용 예시입니다:

from droidrun import DroidRun

# 에이전트 초기화
agent = DroidRun(provider="anthropic", model="claude-3-5-sonnet-20240620")

# 복잡한 작업 지시
result = agent.run("Find the CEO of Microsoft on LinkedIn and save the profile summary")
print(result)

더 상세한 사용 관련해서는 DroidRun 튜토리얼을 참고해주세요:

DroidRun 동작 예시 영상

다음은 DroidRun GitHub 저장소에 공개된 몇 가지 DroidRun 동작 예시 영상들입니다:

숙박시설 예약 (Accommodation Booking)

트렌드 분석(Trend Hunter)

연속 학습 지키기 (Streak Saver)

DroidRun 설치

DroidRun을 사용하기 위해서는 Python 3.10 이상 환경과 ADB(Android Debug Bridge)가 필요합니다. 먼저, 필수 요구사항은 다음과 같습니다:

Python 3.10+
ADB (Android SDK Platform-Tools)
Android 기기 (개발자 옵션 및 USB 디버깅 활성화 필요)

DroidRun 설치는 pip 명령어를 사용하여 쉽게 설치할 수 있습니다:

pip install droidrun

이후, 접근성 서비스를 통한 기기 사용을 위해 DroidRun Portal App 설치가 필요합니다.

기기와 연결된 상태에서 DroidRun을 처음 실행(droidrun setup)하면 자동으로 필요한 보조 앱(Portal APK) 설치를 시도하거나, 문서를 통해 APK를 다운로드하여 설치할 수 있습니다. 설치 후 '접근성 권한'을 반드시 허용해야 합니다.

설치가 완료된 후에는 사용하려는 LLM 사업자의 API 키를 환경 변수로 설정하거나, config.yml에서 설정합니다:

# For Google Gemini (default)
export GOOGLE_API_KEY=your-api-key-here

# For OpenAI
export OPENAI_API_KEY=your-api-key-here

# For Anthropic Claude
export ANTHROPIC_API_KEY=your-api-key-here

# For DeepSeek
export DEEPSEEK_API_KEY=your-api-key-here

상세한 설치 및 사용 관련해서는 DroidRun 공식 문서 중 빠른 시작(Quick Start) 문서를 참고해주세요:

라이선스

DroidRun 프로젝트는 MIT 라이선스로 공개 및 배포되고 있습니다.

DroidRun 공식 홈페이지

DroidRun 공식 문서

DroidRun 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~