rdp-cli
AI 에이전트를 위한 Android 가상 디스플레이 자동화
Android 가상 디스플레이 자동화를 사용하면 AI 에이전트가 Android 앱을 제어하고 테스트할 별도의 표시 대상을 만들 수 있습니다.
물리적인 휴대폰 기본 화면만 제어하는 대신, 세션 전용 가상 디스플레이를 만들고 크기와 DPI를 설정한 뒤 앱을 실행하고 새로운 스크린샷으로 각 동작을 확인할 수 있습니다.
rdp-cli를 사용하면 AI 에이전트가 ADB를 통해 USB 또는 Wi-Fi로 Android 기기에 연결하고 가상 디스플레이에서 화면 기반 자동화를 수행할 수 있습니다.
요약: Android 가상 디스플레이 자동화는 AI 에이전트가 별도의 화면에서 GUI 작업을 수행하도록 합니다. 안정적인 흐름은 디스플레이 생성, 화면 캡처, 한 번의 동작, 새 화면 캡처와 결과 확인입니다.
Android 가상 디스플레이와 기본 화면
rdp-cli에는 두 가지 Android 표시 대상이 있습니다.
main: 현재 휴대폰의 물리적 기본 화면을 제어합니다.virtual: 자동화 세션 전용 가상 디스플레이를 만듭니다.
가상 디스플레이는 고정된 화면 크기와 DPI로 테스트해야 할 때 유용합니다. Agent, GUI Viewer와 Web Viewer는 세션에서 선택한 표시 대상을 사용합니다. 앱 동작과 시스템 권한은 기기와 앱에 따라 달라질 수 있습니다.
가상 디스플레이는 클라우드 Android 에뮬레이터가 아닙니다. 앱은 인증된 실제 Android 기기에서 실행되며, 호환성은 Android 버전, 제조사와 대상 앱에 따라 달라집니다.
가상 디스플레이를 언제 사용해야 하나요?
다음 작업에 적합합니다.
- Android GUI 테스트 반복 실행
- 사용 가능한 API가 없는 앱 테스트
- 양식, 로그인과 승인 흐름 실행
- 고정 크기의 시각적 테스트
- 각 동작의 스크린샷 증거 저장
- 별도의 표시 대상에서 앱 실행
기기를 아직 연결하지 않았다면 USB 또는 Wi-Fi로 AI 에이전트가 Android를 제어하는 방법을 먼저 확인하세요.
준비 사항
다음을 준비합니다.
- Android 12 이상 기기
- USB 디버깅 또는 무선 디버깅 활성화
- 휴대폰에서 ADB 인증 완료
- 대상 앱 설치
- Android 지원 rdp-cli 빌드
- 테스트에 사용할 가상 화면 크기와 DPI
rdp-cli의 지원 기준은 Android 12 이상입니다. Google Pixel 3의 Android 12가 검증된 참고 기기이며 다른 기기의 호환성은 다를 수 있습니다.
Android 가상 디스플레이 만들기
기기를 검색하고 인증한 후 가상 디스플레이 세션을 만듭니다.
rdp-cli connect \
--protocol adb \
--device usb:DEVICE_ID \
--transport usb \
--android-display virtual \
--android-virtual-size 1080x1920 \
--android-virtual-dpi 420 \
--android-start-app com.example.app
DEVICE_ID, 화면 크기, DPI와 앱 패키지 이름을 실제 값으로 바꾸세요.
명령은 세션 ID를 반환합니다. 이후 작업을 위해 저장하세요. 자세한 옵션은 rdp-cli 명령어 문서에서 확인할 수 있습니다.
관찰, 동작, 검증 흐름 사용하기
오래된 스크린샷을 사용해 입력을 보내지 마세요.
먼저 현재 가상 디스플레이를 캡처합니다.
rdp-cli screenshot \
--session SESSION \
--out before.png
스크린샷에서 대상 컨트롤을 찾은 다음 최신 observation으로 한 번의 동작을 보냅니다.
rdp-cli android touch \
--session SESSION \
--kind tap \
--x X \
--y Y \
--observation OBSERVATION
다시 캡처합니다.
rdp-cli screenshot \
--session SESSION \
--out after.png
두 번째 스크린샷이 실제 검증 결과입니다. 입력 명령의 성공은 명령이 전송되었다는 뜻일 뿐 앱이 예상 상태에 도달했다는 뜻은 아닙니다.
테스트 파일 전송과 사람의 검토
Unicode 또는 여러 줄 텍스트는 Android 클립보드 방식을 사용합니다.
rdp-cli android text \
--session SESSION \
--method clipboard \
--text "Test order completed." \
--observation OBSERVATION
세션 파일 루트에 테스트 파일을 업로드할 수도 있습니다.
rdp-cli files upload \
--session SESSION \
--local ./test-data.json \
--path test-data.json
처리 결과를 다운로드한 뒤 전송 완료 여부와 파일을 확인하세요.
사람의 검토가 필요하면 같은 세션을 브라우저에서 엽니다.
rdp-cli watch --session SESSION --viewer web
사람은 Agent 입력을 일시 중지하고 권한 대화상자나 예상하지 못한 화면을 처리한 뒤 제어권을 돌려줄 수 있습니다. 제어권이 바뀐 뒤에는 Agent가 새 스크린샷을 캡처해야 합니다.
제한 사항
- ADB 인증이 필요합니다.
- 기기와 Android 버전에 따라 호환성이 다를 수 있습니다.
- 일부 앱은 가상 디스플레이에서 다르게 동작할 수 있습니다.
- 시스템 권한과 오디오 동작이 적용됩니다.
- 보안 화면은 스크린 캡처를 제한할 수 있습니다.
- rdp-cli는 기기 제어를 제공하지만 AI 모델은 포함하지 않습니다.
- 작업 계획과 판단은 외부 AI 에이전트가 담당합니다.
FAQ
Android 가상 디스플레이 자동화에 root가 필요한가요?
문서화된 rdp-cli 흐름에는 root가 필요하지 않습니다. USB 또는 Wi-Fi를 통한 ADB 인증이 필요합니다.
모든 Android 앱을 가상 디스플레이에서 자동화할 수 있나요?
보장할 수 없습니다. 일부 앱은 물리 화면, 기기 서비스 또는 특정 시스템 권한에 의존합니다. 운영 환경에 사용하기 전에 대상 기기에서 테스트하세요.
자동화 동작이 성공했는지 어떻게 확인하나요?
동작 전에 스크린샷을 캡처하고 한 번의 입력을 보낸 다음 새 스크린샷에서 화면 결과를 확인하세요. 명령 전송 성공만으로 작업 완료를 판단하지 마세요.
rdp-cli에 AI 에이전트가 포함되어 있나요?
아니요. rdp-cli는 연결, 스크린샷, 입력, 세션 제어와 구조화된 결과를 제공합니다. 구체적인 작업은 외부 AI 에이전트가 결정합니다.
마무리
Android 가상 디스플레이 자동화는 AI 에이전트가 고정된 표시 대상에서 Android GUI 테스트나 반복 작업을 수행해야 할 때 유용합니다.
신뢰할 수 있는 패턴은 다음과 같습니다.
가상 디스플레이 생성 → 화면 캡처 → 한 번의 동작 → 다시 캡처 → 결과 확인
rdp-cli를 사용하면 Agent가 가상 디스플레이에서 앱을 실행하고 보이는 컨트롤을 조작하며 테스트 파일을 전송하고 필요할 때 사람의 검토로 전환할 수 있습니다.
rdp-cli 빠른 시작 가이드를 확인하세요.