agent-device

---

agent-device

Automação e verificação de aplicativos móveis para agentes de codificação de IA. Dê aos agentes de codificação um ciclo de feedback ao vivo do aplicativo por meio de uma CLI, servidor MCP integrado ou API Node.js tipada.

Deixe seu agente de codificação verificar suas alterações no aplicativo em execução. agent-device permite que agentes inspecionem, controlem, depurem e verifiquem aplicativos em iOS, Android e HarmonyOS (simuladores, emuladores e dispositivos físicos), além de tvOS, Android TV, Amazon Vega OS TV (Vega Virtual Device), web, macOS e Linux. Os agentes leem snapshots de acessibilidade eficientes em tokens em vez de raciocinar apenas sobre capturas de tela, agem por meio de refs e seletores e salvam evidências para revisão. Também coordena o acesso a dispositivos em worktrees paralelos de agentes e se conecta a nuvens de dispositivos remotos.

Funciona com Claude Code, Codex, Cursor, Windsurf, Cline, Goose e qualquer agente que possa executar uma CLI ou conectar-se via MCP, ou como o runtime sob agentes que você cria com o AI SDK ou Eve. Desenvolvedores na Expensify, Shopify e outros o usam para verificar seus aplicativos.

Início rápido

Instale a CLI e verifique a configuração. Requer Node.js 22.12 ou mais recente; 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 doctor você mesmo antes de entregar a CLI a um agente; help workflow vincula aos guias de depuração, reprodução e criação de perfil, e a ajuda instalada sempre corresponde à versão instalada.

Dirija um aplicativo a partir da CLI

Adicione um contato no aplicativo iOS Contatos integrado:

# 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

Refs são válidos apenas a partir da saída mais recente: após um comando --settle, use os refs em seu diff e tire um novo snapshot somente se o diff omitir o que você precisa. Snapshots vêm da árvore de acessibilidade do aplicativo, então rótulos claros, papéis e IDs de teste tornam as execuções do agente mais confiáveis; use capturas de tela e vídeo como evidência ou quando os dados de acessibilidade forem ruins.

Adicione ferramentas MCP ao seu agente

agent-device mcp inicia o servidor MCP stdio oficial, expondo os comandos instalados como ferramentas estruturadas no mesmo caminho de execução da CLI:

{
  "mcpServers": {
    "agent-device": {
      "command": "agent-device",
      "args": ["mcp"]
    }
  }
}

Consulte Configuração do Agente de IA para configuração por cliente e quando preferir CLI simples em vez de MCP.

Script a partir do Node.js

createAgentDeviceClient() dá ao código Node.js acesso tipado aos mesmos comandos, como ferramentas de modelo em seu próprio agente ou a partir de código de orquestração:

import { createAgentDeviceClient } from 'agent-device';

const client = createAgentDeviceClient({ session: 'qa-run' });
try {
  await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' });
  const snapshot = await client.capture.snapshot({ interactiveOnly: true });
  const button = snapshot.nodes.find((node) => node.role === 'button');
  if (button) await client.interactions.press({ ref: button.ref });
} finally {
  await client.sessions.close();
}

Consulte a API Node.js, os exemplos executáveis e os guias de integração AI SDK e Eve.

O que os agentes podem fazer

• Inspecionar o estado do aplicativo por meio de snapshots de acessibilidade, refs, seletores e árvores de componentes React Native.
• Agir na interface visível tocando ou pressionando elementos, preenchendo campos, rolando, fazendo gestos, esperando, afirmando estado e lidando com alertas.
• Diagnosticar falhas com capturas de tela, vídeo, logs, rastreamentos, dados de rede, amostras de desempenho, detalhes de falhas e perfis React.
• Repetir fluxos de trabalho salvando etapas de trabalho como scripts .ad para uso local ou CI. Exporte YAML Maestro estrito quando necessário.

Consulte Comandos para os comandos e evidências que cada destino suporta.

O que perguntar ao seu agente

Com a CLI instalada, prompts como estes funcionam de ponta a ponta:

• "Implemente a tela de integração, execute-a no simulador iOS e no emulador Android e anexe capturas de tela."
• "Reproduza esta falha e capture os logs que levam a ela."
• "Verifique se esta alteração causa re-renderizações desnecessárias do React Native."
• "Explore o fluxo de checkout uma vez, salve-o como um script de reprodução e execute-o no CI."
• "Verifique este pull request em um dispositivo físico e anexe evidências revisáveis."

Próximos passos

• Configuração do Agente de IA: habilidades, regras de projeto e configuração por cliente para Cursor, Codex, Claude Code, Windsurf e outros.
• Início Rápido: uma execução guiada no aplicativo de teste Expo incluído com capturas de tela, reprodução e dados de desempenho.
• Reprodução e E2E e Depuração e Criação de Perfil: testes repetíveis e caça a bugs.

Onde executar agent-device

O mesmo modelo de sessão e evidência funciona em cada etapa: o agente explora o aplicativo, captura evidências, salva uma reprodução, executa-a no CI e avança para dispositivos remotos.

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 reprodução e artefatos capturados.	Experimente o modelo de fluxo de trabalho EAS.
Nuvem / remoto	Runners Linux, dispositivos gerenciados e trabalhos remotos.	Configure um proxy remoto, conecte uma nuvem de dispositivos (BrowserStack, AWS Device Farm, Limrun) ou entre em contato com a Callstack para QA de equipe.

Como funciona

agent-device mantém o estado do dispositivo em sessões. Usa uma ponte de acessibilidade local para snapshots do simulador iOS e XCTest para interações iOS, iOS físico e tvOS; ADB e o auxiliar de snapshot no Android; HDC e ArkUI uitest no HarmonyOS; Vega CLI/VDA no Vega Virtual Device; um auxiliar local no macOS; e AT-SPI no Linux.

A profundidade do suporte varia por destino. Backends mais novos, como HarmonyOS e Vega OS, cobrem um subconjunto de comandos; execute agent-device capabilities --platform <platform> para ver o que um destino suporta.

As sessões são limitadas ao worktree git do chamador, e reivindicações de dispositivos locais impedem que agentes paralelos assumam os simuladores e emuladores uns dos outros. Inspecione a propriedade sem um daemon via agent-device device status e resolva proprietários comprovadamente mortos com agent-device device release --stale. Os mesmos comandos dirigem dispositivos hospedados em BrowserStack, AWS Device Farm e Limrun.

agent-device usa o processo inspecionar-agir-verificar do agent-browser da Vercel para aplicativos móveis, TV e desktop. O suporte básico a --platform web executa agent-browser no mesmo sistema de sessão e reprodução.

FAQ

O que é agent-device?

agent-device é uma ferramenta de linha de comando e servidor MCP que permite que agentes de codificação de IA inspecionem, controlem e verifiquem aplicativos móveis e salvem evidências para revisão. Suporta iOS, Android, HarmonyOS, TV, web, macOS e Linux.

Existe um servidor MCP para automação de aplicativos móveis?

Sim. agent-device mcp inicia o servidor MCP stdio oficial. O Início Rápido acima tem a configuração do cliente, e Configuração do Agente de IA cobre detalhes por cliente.

Funciona com React Native, Expo, Flutter e aplicativos nativos?

Sim. agent-device suporta aplicativos nativos 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 dos servidores MCP móveis?

O servidor MCP é um ponto de entrada para o mesmo runtime usado pela CLI e pela API Node.js tipada. Sessões, propriedade de dispositivos, seletores, evidências, reprodução, fluxos de trabalho CI e roteamento em nuvem permanecem consistentes em todos os três.

Posso construir meu próprio agente ou produto de QA em agent-device?

Sim. O cliente Node.js tipado é uma superfície pública sobre esse mesmo runtime, então um agente que você construir herda tudo acima. Comece pelos guias API Node.js, AI SDK ou Eve.

Como é diferente do Appium, Detox ou Maestro?

Com agent-device, um agente lê o estado do aplicativo e escolhe cada comando em tempo de execução. As 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 Maestro estrito.

O agent-device pode rodar em CI?

Sim. Grave uma execução como um script .ad, reproduza-a no CI e mantenha as capturas de tela e logs como artefatos; o modelo de fluxo de trabalho EAS é um exemplo funcional.

Artigos e vídeos

Artigos

• Construa um agente de QA de IA para aplicativos Expo com EAS Workflows
• Agent Device: automação 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 de IA
• Agentes em nuvem que testam aplicativos móveis em dispositivos reais

Quem usa agent-device?

Equipes e desenvolvedores na Callstack, JPMorgan Chase, Expensify, Shopify, Kindred, Total Wine & More, LegendList, HerLyfe, App & Flow e outros usam agent-device.

Documentação

• Docs
• Docs legíveis por agentes

Contribuindo

Consulte 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.