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.

Leia o Guia de início rápido do rdp-cli.