agent-device
Roteador de descoberta para a CLI agent-device com status, instalação, ajuda, prompts e recursos
Documentação
agent-device
Deixe seu agente de codificação verificar suas alterações no aplicativo em execução.
agent-device permite que agentes de codificação inspecionem, controlem e verifiquem aplicativos em iOS, Android, HarmonyOS, tvOS, Android TV, Amazon Vega OS TV por meio do Vega Virtual Device (VVD), web, macOS e Linux. Os agentes podem ler snapshots de acessibilidade eficientes em termos de token quando suportados, encontrar elementos por ref ou seletor, executar ações no dispositivo e salvar evidências para revisão. O suporte ao HarmonyOS usa HDC e ArkUI uitest em dispositivos conectados e emuladores DevEco; use capabilities --platform harmonyos para inspecionar seu subconjunto de comandos baseado em evidências. O suporte inicial para Vega OS é exclusivo para VVD e cobre descoberta, ciclo de vida de aplicativos e controle completo do controle remoto de TV; Fire TV físico, captura e backends de seletor permanecem sem suporte.
Seu agente de codificação ou ferramenta de QA lê cada resultado e escolhe o próximo comando. agent-device executa o comando e salva evidências quando solicitado.
agent-device usa o processo inspect-act-verify do agent-browser da Vercel para aplicativos móveis, TV e desktop. O suporte básico de --platform web executa agent-browser na mesma sessão e sistema de replay.
Início rápido
Instale a CLI e verifique a configuração. Ela requer Node.js 22.12 ou mais recente; a automação web requer Node.js 24 ou mais recente. Consulte Instalação para requisitos de destino.
npm install -g agent-device@latest
agent-device doctor
agent-device help workflow
Execute agent-device doctor você mesmo antes de entregar a CLI a um agente. A ajuda da CLI instalada define o comportamento atual. agent-device help workflow fornece links para guias de depuração, replay, criação de perfil do React Native e outras tarefas.
Adicione um contato no aplicativo Contatos integrado do iOS:
# Start a session.
agent-device open Contacts --platform ios
# Inspect the screen. The example below shows the output; refs vary.
agent-device snapshot -i
# @e2 [button] "Add"
# Use the ref and wait for the UI to settle.
agent-device press @e2 --settle
# The diff includes:
# + @e7 [text-field] "First name"
agent-device fill @e7 "Ada" --settle
# The next diff shows changed values and current refs:
# - @e7 [text-field] "First name"
# + @e14 [text-field] "Ada"
# = @e15 [text-field] "Last name"
# Capture evidence and close the session.
agent-device screenshot ./contact-form.png
agent-device close
Use apenas refs da saída mais recente. Não assuma que um @eN anterior ainda identifica o mesmo elemento. Após um comando com --settle, use os refs no diff. Faça outro snapshot somente se o diff omitir o que você precisa.
--settle funciona da mesma forma em scroll e back, então scroll-then-observe e back-then-observe são uma única chamada também.
Snapshots usam a árvore de acessibilidade do aplicativo. Rótulos claros, papéis e IDs de teste tornam as execuções do agente mais confiáveis. Use capturas de tela e vídeos como evidência ou quando os dados de acessibilidade forem ruins. Use refs e seletores para ações e asserções quando puder.
O que os agentes podem fazer
- Inspecionar o estado do aplicativo por meio de snapshots de acessibilidade, refs, seletores e árvores de componentes do React Native.
- Agir na interface visível tocando ou pressionando elementos, preenchendo campos, rolando, fazendo gestos, esperando, verificando estado e lidando com alertas.
- Diagnosticar falhas com capturas de tela, vídeo, logs, rastros, dados de rede, amostras de desempenho, detalhes de falhas e perfis do React.
- Repetir workflows salvando passos funcionais como scripts
.adpara uso local ou CI. Exporte YAML do Maestro estrito quando necessário.
Consulte Comandos para os comandos e evidências que cada destino suporta.
Próximos passos
- Configure seu agente: execute a CLI a partir do Cursor, Codex, Claude Code, Windsurf ou outro terminal de agente. Consulte Configuração do Agente de IA para habilidades, regras, ferramentas MCP e configuração para cada cliente.
- Experimente o aplicativo de exemplo: clone o repositório e execute o aplicativo de teste Expo incluído. O Início Rápido cobre uma execução guiada com capturas de tela, replay e dados de desempenho.
- Crie testes repetíveis: use Replay & E2E para repetir testes. Use Depuração & Criação de Perfil para encontrar bugs.
Artigos e vídeos
Artigos
- Construa um agente de QA de IA para aplicativos Expo com EAS Workflows
- Agent Device: automação de iOS e Android para agentes de IA
- Construindo agentes de QA móveis com Vercel Eve
- Como otimizamos o Agent Device para automação de aplicativos móveis
Vídeos
- Verificando aplicativos móveis com agent-device
- Usando agent-device em um fluxo de trabalho de codificação com IA
- Agentes em nuvem que testam aplicativos móveis em dispositivos reais
Onde executar agent-device
| Caminho | Melhor para | Comece com |
|---|---|---|
| Local | Experimentar comandos e depurar aplicativos em simuladores, emuladores, dispositivos físicos, macOS e Linux. | Siga o Início Rápido. |
| CI/CD | Validação automatizada de pull requests e merges com scripts de replay e artefatos capturados. | Experimente o modelo de workflow EAS. O modelo de ações do GitHub em breve. |
| Nuvem / remoto | Executores Linux, dispositivos gerenciados e jobs remotos. | Use Agent Device Cloud, defina um perfil remoto com Comandos ou entre em contato com a Callstack para QA em equipe. |
Como funciona
agent-device mantém o estado do dispositivo em sessões. Ele envia comandos para XCTest no iOS e tvOS, ADB e o helper de snapshot no Android, HDC e ArkUI uitest no HarmonyOS, Vega CLI/VDA no Vega Virtual Device, um helper local no macOS e AT-SPI no Linux.
Aplicativos Node.js podem usar o cliente tipado ou subcaminhos públicos. agent-device/android-adb fornece a interface do provedor ADB do Android, ajudantes para logcat, área de transferência, teclado e aplicativos, e gerenciamento reverso de portas.
FAQ
O que é agent-device?
agent-device é uma ferramenta de linha de comando que permite que agentes de codificação inspecionem, controlem e verifiquem aplicativos e salvem evidências para revisão. Ela suporta iOS, Android, HarmonyOS, TV, web, macOS e Linux.
Funciona com React Native, Expo, Flutter e aplicativos nativos?
Sim. agent-device suporta aplicativos nativos de iOS e Android, além de aplicativos React Native, Expo e Flutter em destinos suportados. Os comandos e evidências variam por destino.
Como é diferente de Appium, Detox ou Maestro?
Com o agent-device, um agente lê o estado do aplicativo e escolhe cada comando em tempo de execução. Equipes usam Appium, Detox e Maestro para escrever e manter suítes de teste. agent-device pode complementá-los salvando suas execuções como scripts .ad ou exportando-os como YAML do Maestro estrito.
O agent-device pode ser executado em CI?
Sim. Grave uma execução como um script .ad, reproduza-a localmente ou em CI e salve capturas de tela, logs e outros artefatos para revisão. Consulte Replay & E2E ou comece com o modelo de workflow EAS.
Quem usa agent-device?
Equipes e desenvolvedores na Callstack, JPMorgan Chase, Expensify, Shopify, Kindred, Total Wine & More, LegendList, HerLyfe, App & Flow e outros usam o agent-device.
Documentação
Contribuindo
Veja CONTRIBUTING.md.
Feito na Callstack
agent-device é open source sob a licença MIT. Visite agent-device.dev ou entre em contato com a Callstack.