android-agent: ADB를 통한 실제 Android 기기 제어용 오픈소스 Python 프레임워크

당신의 Android에 유령을 소환하세요.

유령은 화면을 보고, 버튼을 탭하며, 결코 잠들지 않습니다.

ADB를 통해 실제 Android 폰을 제어하기 위한 오픈소스 Python 프레임워크입니다. 앱 설치가 필요 없으며, 흔적을 남기지 않습니다. 순수한 자동화(Automation)를 지향합니다.

모든 앱에 대한 기술 (skills) 을 정의하고, 대시보드나 API를 통해 실행하며, 폰 팜 (phone farm) 전체로 확장할 수 있습니다.

유령은 당신이 탭하는 것을 그대로 탭합니다

• 50개 이상의 ADB 메서드 — 탭 (tap), 스와이프 (swipe), 타이핑 (type), 클립보드 (clipboard), 스텔스 변형 (stealth variants)
• 실시간 휴대폰 화면 스트리밍 (MJPEG 및 WebRTC)
• 스트리밍되는 화면에서의 대화형 터치-투-탭 (touch-to-tap)
• 기기별 작업 큐 (job queues)를 갖춘 멀티 디바이스 폰 팜 (phone farm)

모든 앱을 위한 재사용 가능한 기술(skills)을 구축하세요

• 앱별 YAML 기반 UI 요소 정의
• 전제 조건 확인 기능이 포함된 Python 액션 클래스 (action classes)
• 액션들을 체인처럼 연결하는 다단계 워크플로 (workflows)
• TikTok 및 Play Store용 내장 기술 (skills)
  기술 허브 (Skill Hub) — 커뮤니티 레지스트리에서 기술을 찾아보고 검색하고 설치하세요
• CLI에서 설치: android-agent skill install tiktok

유령에게 새로운 기술을 가르치세요

• BFS 기반 자동 앱 탐색기 (auto app explorer) — 모든 화면과 전환을 발견합니다
• LLM 지원 기술 생성기 (Skill Creator) — 실시간 기기 스트림을 보면서 AI와 채팅하세요
• AI가 UI 요소를 식별하고 액션/워크플로 코드를 생성합니다

유령의 활동을 확장하세요

• 기기별 작업 큐를 갖춘 멀티 디바이스 폰 팜 (phone farm)
• 봇 러너 (Bot runner): 자동화 작업을 큐에 추가, 예약 및 모니터링
• ADB 화면 녹화 기능을 포함한 기기별 통합 테스트

Python 3.10+
Android 폰 (USB 디버깅 활성화 필요: 설정 > 개발자 옵션 > USB 디버깅)
ADB 설치 및 PATH 설정 (adb devices 실행 시 휴대폰이 목록에 나타나야 함)
Node.js 18+ (프론트엔드 개발 서버용)

# 1. 저장소 클론 (Clone the repo)
git clone https://github.com/ghost-in-the-droid/android-agent.git
cd ghost-in-the-droid
...

.env.example을 .env로 복사하거나 (제공되는 경우), 프로젝트 루트에 .env 파일을 생성하세요. 서버는 Pydantic Settings를 통해 설정을 읽습니다. 선택적 변수에는 다음이 포함됩니다:

변수 (Variable)	용도 (Purpose)
OPENAI_API_KEY	LLM 기능 (Skill Creator, Agent Chat)
ANTHROPIC_API_KEY	대체 LLM 제공업체
OPENROUTER_API_KEY	OpenRouter LLM 제공업체
DEFAULT_DEVICE	ADB 시리얼 번호 (비어 있을 경우 자동 감지)

로컬 모델에는 API 키가 필요하지 않습니다: Phone Agent 탭에서 Ollama를 선택하세요 — Ollama를 통해 완전히 로컬 머신에서 실행됩니다. 설치하고, 모델을 pull한 뒤 시작하세요:

brew install ollama # 또는 curl -fsSL https://ollama.com/install.sh | sh
ollama serve &
ollama pull llama3.2:3b # 2GB, 빠름, 우수한 도구 사용 (tool-use) 능력

android-agent/
run.py # 엔트리 포인트 (Entry point): :5055 포트에서 Uvicorn 실행
gitd/
...

백엔드 (Backend) (run.py)는 기기 제어, 스킬 (skills), 봇 (bots), 스케줄링 (scheduling), 스트리밍 (streaming)을 담당하는 라우터(routers)와 함께 5055 포트에서 FastAPI 서버를 시작합니다. 프론트엔드 (Frontend) (frontend/)는 /api/*를 통해 백엔드와 통신하는 Vue 3 SPA입니다. 개발 중에는 Vite가 API 호출을 백엔드로 프록시 (proxy) 합니다. **스킬 (Skills)**은 특정 앱과 상호작용하는 방법을 정의합니다. 각 스킬은 elements.yaml (UI 요소), Python 액션 (원자적 작업, atomic operations), 그리고 워크플로 (workflows, 다단계 시퀀스)를 가집니다. **봇 (Bots)**은 bots/common/adb.py의 Device 클래스를 사용하여 휴대폰을 제어하는 장시간 실행되는 서브프로세스 (subprocess) 스크립트입니다. 백엔드가 이들을 생성하고 관리합니다. **데이터베이스 (Database)**는 SQLAlchemy 2.0 ORM 및 Alembic 마이그레이션 (migrations)을 사용하는 SQLite입니다.

백엔드는 FastAPI를 통해 대화형 API 문서를 자동으로 생성합니다:

Swagger UI: http://localhost:5055/docs
ReDoc: http://localhost:5055/redoc

API 도메인: phone, streaming, skills, creator, explorer, agent-chat, bot, scheduler, tests, tools, misc.

탭 (Tab)	기능 (What It Does)
Phone Agent	실시간 기기 스트림 (MJPEG/WebRTC), 화면 탭/스와이프, 다중 기기 보기
...

이 프로젝트는 Android 제어를 위한 35개의 도구(tools)를 포함한 MCP 서버를 제공합니다. MCP 호환 AI 클라이언트 (Claude Code, Claude Desktop, Cursor, VS Code Copilot, Windsurf)라면 무엇이든 이를 사용할 수 있습니다.

단 하나의 명령어로 — Claude Code, Codex, Cursor, VS Code Copilot, Windsurf와 함께 작동합니다:

claude mcp add android-agent -- uvx --from ghost-in-the-droid android-agent-mcp

그게 전부입니다. uvx는

패키지를 설치하고, 격리된 환경 (isolated env)을 생성하며, MCP 서버를 실행합니다. 클론 (clone), 가상 환경 (venv), 수동 설정이 필요 없습니다.

다른 클라이언트 (Other clients) — 명령어는 동일하며, 등록 방식만 다릅니다:

# Codex (OpenAI)
codex mcp add android-agent -- uvx --from ghost-in-the-droid android-agent-mcp

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
"mcpServers": {
"android-agent": {
...

VS Code Copilot (.vscode/mcp.json):

{
"servers": {
"android-agent": {
...

Cursor (.cursor/mcp.json) / Windsurf (~/.codeium/windsurf/mcp_config.json):

{
"mcpServers": {
"android-agent": {
...

리포지토리를 클론하는 **기여자 (contributors)**를 위해: .mcp.json이 이미 준비되어 있습니다 — 첫 claude 실행 시 35개의 도구 (tools)를 바로 사용할 수 있습니다.

카테고리	도구 (Tools)
화면 (Screen)	screenshot , get_elements , get_screen_tree , get_screen_xml , screenshot_annotated , screenshot_cropped
...

# 퍼블릭 레지스트리 (public registry) 검색
android-agent skill search tiktok
# 스킬 (skill) 설치
...

스킬 레지스트리 (skill registry)는 이 리포지토리의 registry/에 위치합니다. 커뮤니티 스킬은 android-agent-skill 태그가 붙은 리포지토리로부터 매일 밤 자동으로 발견됩니다.

스킬을 만드는 두 가지 방법:

커뮤니티 스킬 (Community skill) (본인의 리포지토리):

• skill.yaml, elements.yaml, 액션 (actions), 워크플로 (workflows)를 포함한 새 리포지토리 생성
• 리포지토리에 android-agent-skill 토픽 태그 지정 - 허브에 자동으로 나타납니다 (매일 밤 스크래퍼 작동)

공식 스킬 (Official skill) (이 리포지토리에 PR 제출):

• 먼저 커뮤니티 스킬로서 빌드 및 테스트 수행
• registry/에 스킬을 추가하는 PR (Pull Request) 오픈
• CI 검증, 메인테이너 리뷰를 거쳐 "Official" 배지 획득

각 스킬에는 다음이 필요합니다:

skill.yaml — 메타데이터 (이름, 버전, 앱 패키지, 액션, 워크플로)
elements.yaml — UI 요소 리소스 ID 및 설명
actions/ — precondition() 및 execute()를 포함하여 Action을 확장하는 Python 클래스
workflows/

— Workflow를 확장하는 Python 클래스

steps() 포함

전체 가이드는 CONTRIBUTING.md를 참조하세요.

계층 (Layer)	기술 (Technology)
백엔드 (Backend)	FastAPI, Uvicorn, Python 3.10+
...

테스트는 연결된 Android 휴대전화가 필요한 통합 테스트 (integration tests) 입니다:

# 특정 기기에서 모든 테스트 실행
DEVICE=<serial> python3 -m pytest tests/ -v --tb=short
# 단일 테스트 파일 실행
...

adb devices를 통해 기기 시리얼 (serial) 번호를 확인하세요.

이 프로젝트는 스키마 마이그레이션 (schema migrations)을 위해 Alembic을 사용합니다:

# 모델 편집 후 마이그레이션 생성
alembic revision --autogenerate -m "add new_field to my_table"
# 대기 중인 마이그레이션 적용
...

유령은 기술을 익힐수록 더 강력해집니다. 다음 사항은 CONTRIBUTING.md를 참조하세요:

• 새로운 앱을 위한 기술 (skills) 추가 (가장 영향력이 큼)
• 액션 (actions) 및 워크플로우 (workflows) 작성
• 백엔드 아키텍처 (backend architecture) 및 코드 스타일 (code style)
• PR 프로세스

MIT — 유령은 자유롭습니다. 유령은 오픈 소스 (open source) 입니다. 유령은 당신의 것입니다.