agent-device
Enrutador de descubrimiento para la CLI de agent-device con estado, instalación, ayuda, indicaciones y recursos
Documentación
agent-device
Deja que tu agente de codificación verifique sus cambios en la aplicación en ejecución.
agent-device permite a los agentes de codificación inspeccionar, controlar y verificar aplicaciones en iOS, Android, HarmonyOS, tvOS, Android TV, Amazon Vega OS TV a través del Vega Virtual Device (VVD), web, macOS y Linux. Los agentes pueden leer instantáneas de accesibilidad eficientes en tokens cuando son compatibles, encontrar elementos por ref o selector, ejecutar acciones del dispositivo y guardar evidencia para revisión. El soporte de HarmonyOS usa HDC y ArkUI uitest en dispositivos conectados y emuladores DevEco; usa capabilities --platform harmonyos para inspeccionar su subconjunto de comandos respaldado por evidencia. El soporte inicial de Vega OS es solo VVD y cubre descubrimiento, ciclo de vida de aplicaciones y control completo del control remoto de TV; los Fire TV físicos, la captura y los backends de selectores siguen sin ser compatibles.
Tu agente de codificación o herramienta de QA lee cada resultado y elige el siguiente comando. agent-device ejecuta el comando y guarda evidencia cuando se le pide.
agent-device usa el proceso inspect-act-verify del agent-browser de Vercel para aplicaciones móviles, TV y de escritorio. El soporte básico de --platform web ejecuta agent-browser en la misma sesión y sistema de reproducción.
Inicio rápido
Instala la CLI y verifica la configuración. Requiere Node.js 22.12 o superior; la automatización web requiere Node.js 24 o superior. Consulta Instalación para los requisitos de destino.
npm install -g agent-device@latest
agent-device doctor
agent-device help workflow
Ejecuta agent-device doctor tú mismo antes de entregar la CLI a un agente. La ayuda de la CLI instalada define el comportamiento actual. agent-device help workflow enlaza a guías para depuración, reproducción, perfilado de React Native y otras tareas.
Añade un contacto en la aplicación de Contactos de iOS integrada:
# 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
Usa solo los refs de la salida más reciente. No asumas que un @eN anterior sigue identificando el mismo elemento. Después de un comando con --settle, usa los refs de su diff. Toma otra instantánea solo si el diff omite lo que necesitas.
--settle funciona igual en scroll y back, así que desplazar-y-observar y volver-y-observar son una sola llamada también.
Las instantáneas usan el árbol de accesibilidad de la aplicación. Etiquetas claras, roles e IDs de prueba hacen que las ejecuciones del agente sean más fiables. Usa capturas de pantalla y vídeos como evidencia o cuando los datos de accesibilidad sean deficientes. Usa refs y selectores para acciones y aserciones cuando puedas.
Qué pueden hacer los agentes
- Inspeccionar el estado de la aplicación mediante instantáneas de accesibilidad, refs, selectores y árboles de componentes de React Native.
- Actuar sobre la interfaz visible tocando o presionando elementos, rellenando campos, desplazándose, haciendo gestos, esperando, verificando estado y gestionando alertas.
- Diagnosticar fallos con capturas de pantalla, vídeo, registros, trazas, datos de red, muestras de rendimiento, detalles de fallos y perfiles de React.
- Repetir flujos de trabajo guardando los pasos que funcionan como scripts de
.adpara uso local o CI. Exporta Maestro YAML estricto cuando sea necesario.
Consulta Comandos para los comandos y la evidencia que admite cada destino.
Siguientes pasos
- Configura tu agente: ejecuta la CLI desde Cursor, Codex, Claude Code, Windsurf u otro terminal de agente. Consulta Configuración de Agente de IA para habilidades, reglas, herramientas MCP y configuración de cada cliente.
- Prueba la aplicación de ejemplo: clona el repositorio y ejecuta la aplicación de prueba Expo incluida. Inicio Rápido cubre una ejecución guiada con capturas de pantalla, reproducción y datos de rendimiento.
- Crea pruebas repetibles: usa Reproducción y E2E para repetir pruebas. Usa Depuración y Perfilado para encontrar errores.
Artículos y vídeos
Artículos
- Construye un agente de QA de IA para aplicaciones Expo con EAS Workflows
- Agent Device: automatización de iOS y Android para agentes de IA
- Construyendo agentes de QA móvil con Vercel Eve
- Cómo optimizamos Agent Device para la automatización de aplicaciones móviles
Vídeos
- Verificando aplicaciones móviles con agent-device
- Usando agent-device en un flujo de trabajo de codificación con IA
- Agentes en la nube que prueban aplicaciones móviles en dispositivos reales
Dónde ejecutar agent-device
| Ruta | Mejor para | Empieza con |
|---|---|---|
| Local | Probar comandos y depurar aplicaciones en simuladores, emuladores, dispositivos físicos, macOS y Linux. | Sigue el Inicio Rápido. |
| CI/CD | Validación automatizada de pull requests y merges con scripts de reproducción y artefactos capturados. | Prueba la plantilla de flujo de trabajo EAS. La plantilla de GitHub Actions llegará pronto. |
| Nube / remoto | Runners de Linux, dispositivos gestionados y trabajos remotos. | Usa Agent Device Cloud, configura un perfil remoto con Comandos, o contacta con Callstack para QA de equipo. |
Cómo funciona
agent-device mantiene el estado del dispositivo en sesiones. Envía comandos a XCTest en iOS y tvOS, ADB y el helper de instantáneas en Android, HDC y ArkUI uitest en HarmonyOS, Vega CLI/VDA en el Vega Virtual Device, un helper local en macOS y AT-SPI en Linux.
Las aplicaciones Node.js pueden usar el cliente tipado o las subrutas públicas. agent-device/android-adb proporciona la interfaz del proveedor ADB de Android, helpers para logcat, el portapapeles, el teclado y las aplicaciones, y gestión de reenvío de puertos.
FAQ
¿Qué es agent-device?
agent-device es una herramienta de línea de comandos que permite a los agentes de codificación inspeccionar, controlar y verificar aplicaciones y guardar evidencia para revisión. Es compatible con iOS, Android, HarmonyOS, TV, web, macOS y Linux.
¿Funciona con React Native, Expo, Flutter y aplicaciones nativas?
Sí. agent-device es compatible con aplicaciones nativas de iOS y Android, además de aplicaciones React Native, Expo y Flutter en los destinos compatibles. Los comandos y la evidencia varían según el destino.
¿En qué se diferencia de Appium, Detox o Maestro?
Con agent-device, un agente lee el estado de la aplicación y elige cada comando en tiempo de ejecución. Los equipos usan Appium, Detox y Maestro para escribir y mantener suites de pruebas. agent-device puede complementarlos guardando sus ejecuciones como scripts de .ad o exportándolos como Maestro YAML estricto.
¿Puede agent-device ejecutarse en CI?
Sí. Graba una ejecución como script de .ad, reprodúcela localmente o en CI, y guarda capturas de pantalla, registros y otros artefactos para revisión. Consulta Reproducción y E2E o empieza con la plantilla de flujo de trabajo EAS.
¿Quién usa agent-device?
Equipos y desarrolladores en Callstack, JPMorgan Chase, Expensify, Shopify, Kindred, Total Wine & More, LegendList, HerLyfe, App & Flow y otros usan agent-device.
Documentación
Contribuciones
Consulta CONTRIBUTING.md.
Hecho en Callstack
agent-device es código abierto bajo la licencia MIT. Visita agent-device.dev o contacta con Callstack.