agent-device

Enrutador de descubrimiento para la CLI de agent-device con estado, instalación, ayuda, indicaciones y recursos

Documentación

agent-device

Automatización y verificación de aplicaciones móviles para agentes de codificación de IA. Proporciona a los agentes de codificación un bucle de retroalimentación en vivo de la aplicación a través de una CLI, un servidor MCP integrado o una API de Node.js tipada.

Permite que tu agente de codificación verifique sus cambios en la aplicación en ejecución. agent-device permite a los agentes inspeccionar, controlar, depurar y verificar aplicaciones en iOS, Android y HarmonyOS (simuladores, emuladores y dispositivos físicos), además de tvOS, Android TV, Amazon Vega OS TV (Vega Virtual Device), web, macOS y Linux. Los agentes leen instantáneas de accesibilidad eficientes en tokens en lugar de razonar solo sobre capturas de pantalla, actúan a través de referencias y selectores, y guardan evidencia para su revisión. También coordina el acceso a dispositivos entre árboles de trabajo de agentes paralelos y se conecta a nubes de dispositivos remotos.

Funciona con Claude Code, Codex, Cursor, Windsurf, Cline, Goose y cualquier agente que pueda ejecutar una CLI o conectarse a través de MCP, o como el tiempo de ejecución bajo agentes que construyas con el AI SDK o Eve. Desarrolladores en Expensify, Shopify y otros lo usan para verificar sus aplicaciones.

Inicio rápido

Instala la CLI y verifica la configuración. Requiere Node.js 22.12 o más reciente; la automatización web requiere Node.js 24 o más reciente. Consulta Instalación para conocer los requisitos de destino.

npm install -g agent-device@latest
agent-device doctor
agent-device help workflow

Ejecuta doctor tú mismo antes de entregar la CLI a un agente; help workflow enlaza a las guías de depuración, reproducción y perfilado, y la ayuda instalada siempre coincide con la versión instalada.

Conduce una aplicación desde la CLI

Agrega un contacto en la aplicación integrada de Contactos de 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

Las referencias solo son válidas desde la salida más reciente: después de un comando --settle, usa las referencias en su diff y toma una nueva instantánea solo si el diff omite lo que necesitas. Las instantáneas provienen del árbol de accesibilidad de la aplicación, por lo que etiquetas claras, roles e ID de prueba hacen que las ejecuciones del agente sean más confiables; usa capturas de pantalla y video como evidencia o cuando los datos de accesibilidad sean deficientes.

agent-device demo showing Codex using agent-device to create a new contact in the iOS Contacts app from a simple prompt

Agrega herramientas MCP a tu agente

agent-device mcp inicia el servidor MCP oficial de stdio, exponiendo los comandos instalados como herramientas estructuradas a través de la misma ruta de ejecución que la CLI:

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

Consulta Configuración de Agentes de IA para la configuración por cliente y cuándo preferir la CLI simple sobre MCP.

Escríbelo desde Node.js

createAgentDeviceClient() brinda al código de Node.js acceso tipado a los mismos comandos, como herramientas de modelo en tu propio agente o desde código de orquestación:

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();
}

Consulta la API de Node.js, los ejemplos ejecutables y las guías de integración de AI SDK y Eve.

Qué pueden hacer los agentes

Inspeccionar el estado de la aplicación a través de instantáneas de accesibilidad, referencias, selectores y árboles de componentes de React Native.
Actuar sobre la interfaz visible tocando o presionando elementos, completando campos, desplazándose, haciendo gestos, esperando, verificando el estado y manejando alertas.
Diagnosticar fallos con capturas de pantalla, video, registros, trazas, datos de red, muestras de rendimiento, detalles de fallos y perfiles de React.
Repetir flujos de trabajo guardando pasos de trabajo como scripts de .ad para uso local o CI. Exporta YAML estricto de Maestro cuando sea necesario.

Consulta Comandos para conocer los comandos y la evidencia que admite cada destino.

Diagram of the agentic development loop: humans assign tasks, agents write and review code, agent-device verifies mobile apps, pull requests receive evidence, and bugs or performance issues lead to fixes

Qué pedirle a tu agente

Con la CLI instalada, indicaciones como estas funcionan de principio a fin:

"Implementa la pantalla de incorporación, ejecútala en el simulador de iOS y el emulador de Android, y adjunta capturas de pantalla."
"Reproduce este fallo y captura los registros que conducen a él."
"Comprueba si este cambio causa re-renderizaciones innecesarias de React Native."
"Explora el flujo de pago una vez, guárdalo como un script de reproducción y ejecútalo en CI."
"Verifica esta solicitud de extracción en un dispositivo físico y adjunta evidencia revisable."

Próximos pasos

Configuración de Agentes de IA: habilidades, reglas de proyecto y configuración por cliente para Cursor, Codex, Claude Code, Windsurf y otros.
Inicio Rápido: una ejecución guiada en la aplicación de prueba Expo incluida con capturas de pantalla, reproducción y datos de rendimiento.
Reproducción y E2E y Depuración y Perfilado: pruebas repetibles y caza de errores.

Dónde ejecutar agent-device

El mismo modelo de sesión y evidencia funciona en cada paso: el agente explora la aplicación, captura evidencia, guarda una reproducción, la ejecuta en CI y avanza a dispositivos remotos.

Ruta	Mejor para	Comienza 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 solicitudes de extracción y fusiones con scripts de reproducción y artefactos capturados.	Prueba la plantilla de flujo de trabajo EAS.
Nube / remoto	Ejecutores de Linux, dispositivos administrados y trabajos remotos.	Configura un proxy remoto, conecta una nube de dispositivos (BrowserStack, AWS Device Farm, Limrun) o contacta a Callstack para QA de equipo.

Cómo funciona

agent-device mantiene el estado del dispositivo en sesiones. Utiliza un puente de accesibilidad local para instantáneas del simulador de iOS y XCTest para interacciones de iOS, iOS físico y tvOS; ADB y el asistente de instantáneas en Android; HDC y ArkUI uitest en HarmonyOS; Vega CLI/VDA en Vega Virtual Device; un asistente local en macOS; y AT-SPI en Linux.

La profundidad del soporte varía según el destino. Los backends más nuevos como HarmonyOS y Vega OS cubren un subconjunto de comandos; ejecuta agent-device capabilities --platform <platform> para ver qué admite un destino.

Las sesiones están limitadas al árbol de trabajo de git del llamador, y las reclamaciones de dispositivos locales del host evitan que los agentes paralelos se apoderen de los simuladores y emuladores de los demás. Inspecciona la propiedad sin un daemon a través de agent-device device status y resuelve propietarios definitivamente muertos con agent-device device release --stale. Los mismos comandos conducen dispositivos alojados en BrowserStack, AWS Device Farm y Limrun.

agent-device utiliza el proceso de inspeccionar-actuar-verificar de agent-browser de Vercel para aplicaciones móviles, TV y de escritorio. El soporte básico de --platform web ejecuta agent-browser en el mismo sistema de sesión y reproducción.

Preguntas frecuentes

¿Qué es agent-device?

agent-device es una herramienta de línea de comandos y un servidor MCP que permite a los agentes de codificación de IA inspeccionar, controlar y verificar aplicaciones móviles y guardar evidencia para su revisión. Admite iOS, Android, HarmonyOS, TV, web, macOS y Linux.

¿Hay un servidor MCP para la automatización de aplicaciones móviles?

Sí. agent-device mcp inicia el servidor MCP oficial de stdio. El Inicio Rápido anterior tiene la configuración del cliente, y Configuración de Agentes de IA cubre los detalles por cliente.

¿Funciona con React Native, Expo, Flutter y aplicaciones nativas?

Sí. agent-device admite aplicaciones nativas de iOS y Android, además de aplicaciones de React Native, Expo y Flutter en destinos compatibles. Los comandos y la evidencia varían según el destino.

¿En qué se diferencia de los servidores MCP móviles?

El servidor MCP es un punto de entrada al mismo tiempo de ejecución utilizado por la CLI y la API de Node.js tipada. Las sesiones, la propiedad del dispositivo, los selectores, la evidencia, la reproducción, los flujos de trabajo de CI y el enrutamiento en la nube se mantienen consistentes en los tres.

¿Puedo construir mi propio agente o producto de QA sobre agent-device?

Sí. El cliente de Node.js tipado es una superficie pública sobre ese mismo tiempo de ejecución, por lo que un agente que construyas hereda todo lo anterior. Comienza con las guías de API de Node.js, AI SDK o Eve.

¿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 YAML estricto de Maestro.

¿Puede agent-device ejecutarse en CI?

Sí. Graba una ejecución como un script de .ad, reprodúcela en CI y conserva las capturas de pantalla y los registros como artefactos; la plantilla de flujo de trabajo EAS es un ejemplo funcional.

Artículos y videos

Artículos

Videos

¿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 de código abierto bajo la licencia MIT. Visita agent-device.dev o contacta a Callstack.