rdp-cli
Automação de tela virtual do Android para agentes de IA
A automação de tela virtual do Android permite que um agente de IA controle e teste um aplicativo em uma superfície de exibição separada.
Em vez de controlar apenas a tela física principal, o agente pode criar uma tela virtual própria da sessão, definir tamanho e DPI, iniciar um aplicativo e verificar cada ação com uma nova captura de tela.
Com o rdp-cli, o agente se conecta a dispositivos Android por ADB via USB ou Wi-Fi, seleciona uma tela virtual e executa um fluxo de automação baseado em capturas.
Resumo: a automação de tela virtual do Android oferece ao agente uma tela separada para tarefas de GUI. O fluxo confiável é criar a tela, capturar, executar uma ação, capturar novamente e verificar o resultado.
Tela virtual do Android ou tela principal
O rdp-cli oferece dois destinos de tela Android:
main: controla a tela física principal do telefone.virtual: cria uma tela virtual própria para a sessão de automação.
A tela virtual é útil quando o agente precisa de tamanho e DPI controlados. O Agent, o GUI Viewer e o Web Viewer usam o destino escolhido na sessão. O comportamento do aplicativo e as permissões do sistema podem variar conforme o dispositivo e o app.
Uma tela virtual não é um emulador Android na nuvem. O aplicativo continua sendo executado em um dispositivo Android físico autorizado, e a compatibilidade depende da versão do Android, do fabricante e do aplicativo.
Quando usar uma tela virtual?
Esse método é útil para:
- Repetir testes de GUI no Android
- Testar aplicativos sem uma API disponível
- Executar formulários, logins e aprovações
- Usar um tamanho fixo em testes visuais
- Salvar capturas como evidência
- Executar um app em um destino de tela separado
Se o telefone ainda não estiver conectado, consulte primeiro Controlar um Android com um agente de IA por USB ou Wi-Fi.
Requisitos
Prepare:
- Um dispositivo com Android 12 ou posterior
- Depuração USB ou sem fio ativada
- Autorização ADB confirmada no telefone
- O aplicativo instalado
- Uma versão do rdp-cli compatível com Android
- Um tamanho de tela virtual e DPI adequados
Android 12+ é a base de suporte atual do rdp-cli. O Google Pixel 3 com Android 12 é um dispositivo de referência verificado, mas a compatibilidade pode variar.
Criar uma tela virtual do Android
Depois de detectar e autorizar o dispositivo, crie uma sessão com tela virtual:
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
Substitua DEVICE_ID, o tamanho da tela, o DPI e o nome do pacote pelos valores reais.
O comando retorna um ID de sessão. Salve-o para as próximas operações. Consulte a referência de comandos do rdp-cli.
Observe, aja e verifique
Não envie ações usando uma captura antiga.
Capture primeiro a tela virtual atual:
rdp-cli screenshot \
--session SESSION \
--out before.png
Inspecione a imagem, localize o controle e envie uma ação usando a observação mais recente:
rdp-cli android touch \
--session SESSION \
--kind tap \
--x X \
--y Y \
--observation OBSERVATION
Capture a tela novamente:
rdp-cli screenshot \
--session SESSION \
--out after.png
A segunda captura é a verificação real. Uma resposta de entrada bem-sucedida apenas confirma que o comando foi enviado; ela não prova que o aplicativo alcançou o estado esperado.
Transferir arquivos e adicionar revisão humana
Para texto Unicode ou com várias linhas, use o método da área de transferência do Android:
rdp-cli android text \
--session SESSION \
--method clipboard \
--text "Test order completed." \
--observation OBSERVATION
Você também pode enviar arquivos de teste para a pasta da sessão:
rdp-cli files upload \
--session SESSION \
--local ./test-data.json \
--path test-data.json
Baixe o resultado, aguarde a conclusão da transferência e verifique o arquivo.
Quando for necessária uma revisão humana, abra a mesma sessão no navegador:
rdp-cli watch --session SESSION --viewer web
Uma pessoa pode pausar o agente, tratar uma solicitação de permissão ou corrigir uma tela inesperada e devolver o controle. Depois de uma mudança de controle, o agente deve capturar uma nova tela.
Limitações
- A autorização ADB é obrigatória.
- A compatibilidade depende do dispositivo e da versão do Android.
- Alguns aplicativos podem se comportar de forma diferente em uma tela virtual.
- As permissões do sistema e o comportamento de áudio continuam valendo.
- Janelas seguras podem limitar as capturas.
- O rdp-cli fornece controle do dispositivo, mas não inclui um modelo de IA.
- O planejamento fica a cargo do agente de IA externo.
Perguntas frequentes
A automação de tela virtual do Android exige root?
O fluxo documentado do rdp-cli não exige root. É necessária uma conexão ADB autorizada por USB ou Wi-Fi.
Posso automatizar qualquer aplicativo Android em uma tela virtual?
Não há garantia. Alguns aplicativos dependem da tela física, de serviços do dispositivo ou de permissões específicas. Teste o aplicativo no hardware desejado.
Como verificar se uma ação foi concluída?
Capture a tela antes da ação, envie uma entrada, capture novamente e verifique o resultado visível. O envio correto do comando não significa que a tarefa terminou.
O rdp-cli inclui um agente de IA?
Não. O rdp-cli fornece conexão, capturas, entradas, controle da sessão e resultados estruturados. Um agente externo decide as ações.
Conclusão
A automação de tela virtual do Android é útil quando um agente precisa de um destino de exibição controlado para testes GUI ou fluxos repetitivos.
O padrão confiável é:
Criar a tela virtual → capturar a tela → executar uma ação → capturar novamente → verificar o resultado
Com o rdp-cli, o agente pode iniciar um app na tela virtual, interagir com controles visíveis, transferir arquivos de teste e pedir revisão humana quando necessário.