⏱️ Lectura: 12 min
Durante los últimos dos años, los agentes de IA aprendieron a navegar la web con una madurez sorprendente: abren pestañas, rellenan formularios, leen el DOM y toman decisiones. Proyectos como agent-browser de Vercel hicieron ese patrón trivial. Pero el mundo móvil quedó atrás: controlar un iPhone o un Android desde un modelo de lenguaje seguía siendo territorio de adb shell, xcuitest y pegamento frágil. Ahí es donde aparece agent-device, una CLI publicada por el equipo de Callstack que busca darle a los agentes el mismo lenguaje universal para mover dedos, leer pantallas y escribir texto en dispositivos físicos y virtuales.
📑 En este artículo
El proyecto, disponible en callstackincubator/agent-device, ya acumula 1.788 estrellas en GitHub, está escrito en TypeScript, se distribuye como paquete npm bajo licencia MIT y se autodescribe como un unified control plane for physical and virtual devices via an agent-driven CLI. En este tutorial vamos a ver qué problema resuelve exactamente, cómo instalarlo en los tres sistemas operativos principales, y cómo integrarlo en flujos reales de QA automatizado o de agentes autónomos. La idea no es traducir el README: es construir una guía práctica para desarrolladores LATAM que están explorando cómo darle manos a sus modelos.
Introducción: el problema que resuelve
Cualquiera que haya intentado automatizar pruebas end-to-end en móvil conoce el dolor. Appium funciona, pero exige configurar un servidor, drivers específicos por plataforma y mucho XPath. Maestro simplificó parte de la historia con YAML declarativo, pero sigue pensado para humanos que escriben flujos, no para modelos que exploran pantallas de forma iterativa. Y cuando lo que querés es que un agente LLM descubra por sí mismo dónde tocar, qué texto leer y cómo reaccionar ante un diálogo inesperado, todas esas herramientas se sienten rígidas: asumen que el flujo es conocido de antemano.
La tendencia de 2026 va en la dirección opuesta. Los agentes necesitan bucles: inspeccionar el estado, razonar, actuar, reinspeccionar y repetir. Para eso, cada paso debe ser barato en tokens (nada de volcar el árbol de accesibilidad completo cada vez), determinista (la misma acción produce el mismo resultado) y replayable (poder guardar lo que funcionó y reproducirlo después como test). agent-device nace exactamente en ese cruce: tomar el modelo mental de agent-browser y portarlo al ecosistema móvil, donde iOS, tvOS, macOS, Android y AndroidTV se controlan con herramientas nativas muy distintas.
Qué es agent-device
En palabras simples, agent-device es una CLI que se instala globalmente vía npm y expone una serie de comandos verbosos pero memorables: apps, open, snapshot, press, fill, scroll, wait, close. Cada comando actúa sobre una sesión abierta contra un dispositivo real o un simulador, y devuelve información estructurada pensada para que un agente la procese sin ahogarse en tokens.
Los pilares conceptuales que vale la pena entender antes de escribir código son los siguientes:
- Sesiones — se abre un target una vez, se interactúa dentro de esa sesión y se cierra limpiamente. Esto elimina el costo de arranque de cada comando y mantiene el contexto de navegación.
- Snapshots — una representación compacta del árbol de accesibilidad visible. No es un dump XML gigante: es la pantalla actual en formato resumido, con referencias a los elementos accionables.
- Refs vs selectores — las refs (como
@e3o@e5) son identificadores efímeros útiles para exploración. Los selectores son duraderos, ideales para reproducir un flujo semanas después sin que se rompa. - Scripts .ad — flujos guardados con
--save-script. Se reproducen conreplay, o se ejecutan como suite serial contest, con reintentos automáticos de hasta 3 veces adicionales, timeouts por test y reportes de tests flaky. - Skills para agentes — el repo incluye
skills/agent-device/SKILL.md, una guía operativa compacta pensada para que modelos como Claude la carguen en contexto y usen la CLI correctamente.
Esa última pieza es clave: agent-device no solo expone comandos, sino que viene con su propia documentación para agentes. Es un patrón que está empezando a verse en varios proyectos del ecosistema, y probablemente se convierta en estándar.
Instalación
agent-device se distribuye como paquete npm global. Requiere Node.js (recomendado 20 o superior) y, según la plataforma que quieras automatizar, las herramientas nativas correspondientes: Xcode y sus Command Line Tools para iOS/tvOS/macOS, y Android SDK Platform-Tools para Android/AndroidTV.
macOS
Esta es la plataforma más completa, ya que es la única donde podés automatizar iOS, tvOS y macOS además de Android. Instalá primero Node y las herramientas de Xcode, luego el paquete:
# Node vía Homebrew
brew install node
# Xcode Command Line Tools
xcode-select --install
# Android platform-tools (opcional, solo si automatizas Android)
brew install --cask android-platform-tools
# agent-device
npm install -g agent-device
# Verificar instalación
agent-device --versionEn macOS, agent-device incluye un helper local llamado agent-device-macos-helper que se compila bajo demanda para manejar permisos de escritorio, diálogos del sistema y snapshots de superficies de desktop. Si trabajás desde una instalación source, se compila localmente con Swift; en releases oficiales se usa una build firmada y notarizada. Si querés apuntar a un binario propio, definí la variable AGENT_DEVICE_MACOS_HELPER_BIN con una ruta absoluta al ejecutable.
Linux
En Linux podés automatizar Android y AndroidTV (iOS/tvOS/macOS no aplican porque requieren herramientas propietarias de Apple). La instalación es directa:
# Node vía nvm (recomendado)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20
# Android platform-tools (Ubuntu/Debian)
sudo apt update
sudo apt install android-tools-adb android-tools-fastboot
# agent-device
npm install -g agent-device
# Verificar que adb detecta el dispositivo
adb devicesSi usás Arch Linux o Fedora, reemplazá el paso de apt por pacman -S android-tools o dnf install android-tools respectivamente. Para conectar un dispositivo físico Android, activá las opciones de desarrollador y el USB debugging desde ajustes del teléfono.
Windows
En Windows también podés controlar Android (iOS requiere macOS). La forma más limpia es usar winget o choco:
:: Instalar Node LTS con winget
winget install OpenJS.NodeJS.LTS
:: Instalar platform-tools
winget install Google.PlatformTools
:: Instalar agent-device
npm install -g agent-device
:: Verificar
agent-device --version
adb devicesUna vez instalado, podés deshabilitar el aviso de actualización en cualquier sistema con AGENT_DEVICE_NO_UPDATE_NOTIFIER=1. Por defecto, la CLI hace un chequeo liviano en background durante sesiones interactivas y sugiere un reinstall cuando hay versión nueva, lo cual refresca también los skills/ que viajan con la herramienta.
Uso básico: tu primer flujo
Antes de abrir nada, conviene listar las apps disponibles en el target para confirmar el bundle id exacto. En iOS los identificadores suelen parecerse a com.apple.mobilesafari, y en Android a com.google.android.youtube. El comando es el mismo:
agent-device apps --platform ios
agent-device apps --platform androidCon el id correcto, el ciclo canónico que propone el README es el siguiente. Imaginemos que queremos abrir una app de ejemplo llamada SampleApp, inspeccionar la pantalla, presionar un botón, escribir en un campo y cerrar:
agent-device open SampleApp --platform ios
agent-device snapshot -i
agent-device press @e3
agent-device diff snapshot -i
agent-device fill @e5 "test"
agent-device press @e5
agent-device type " more" --delay-ms 80
agent-device closeLos puntos interesantes: snapshot -i devuelve el estado interactivo con refs frescos. diff snapshot te muestra qué cambió desde el último snapshot, lo cual es enorme para el consumo de tokens de un agente, porque evita re-enviar toda la pantalla si solo se abrió un modal. type acepta --delay-ms para simular escritura humana cuando la app hace debouncing de texto. Y si el elemento que buscás está fuera de la pantalla visible, el snapshot por defecto no te lo devolverá como ref accionable: te dará una pista de scroll, y vos decidís si ejecutar scroll down y re-snapshotear.
Integración en proyectos reales
El valor real de agent-device aparece cuando dejás de escribir comandos a mano y lo integrás en dos tipos de flujos: suites de test determinísticas y bucles de agente autónomo. Veamos ambos.
Suites de tests replayables
Cualquier sesión interactiva puede guardarse como script .ad agregando la flag --save-script. El resultado es un archivo de texto plano, legible, con la secuencia exacta de acciones y selectores durables. Después, podés reproducirlo o ejecutarlo como parte de una suite:
# Guardar la sesión como script mientras se ejecuta
agent-device open SampleApp --platform ios --save-script ./tests/login-happy-path.ad
# Reproducir un script puntual
agent-device replay ./tests/login-happy-path.ad
# Ejecutar todos los scripts de una carpeta como suite
agent-device test ./tests/El runner soporta metadatos en el propio script para configurar reintentos (hasta 3 adicionales), timeouts por test, y generación de artefactos. Todo queda por defecto bajo .agent-device/test-artifacts: cada intento escribe su propio replay.ad y result.txt, y los intentos fallidos conservan logs y capturas copiadas cuando aplican. Esto te da algo que Appium históricamente ha sido malo en entregar: evidencia reproducible de por qué falló un test, sin pegamento adicional.
Agente autónomo con LLM
El segundo patrón es el que motiva el proyecto. Un agente (por ejemplo, con Claude o GPT) recibe una tarea en lenguaje natural como “abrí la app de contactos y creá un contacto llamado Rubén con número +503 7555 0000”. El agente invoca agent-device como tool, observa snapshots, razona y actúa. Un pseudo-loop en Node se vería así:
import { execSync } from 'node:child_process';
function ad(cmd) {
return execSync(`agent-device ${cmd} --json`, { encoding: 'utf8' });
}
const maxSteps = 15;
let step = 0;
ad('open com.apple.MobileAddressBook --platform ios');
while (step < maxSteps) {
const snapshot = JSON.parse(ad('snapshot -i'));
const action = await llm.decideNextAction({
goal: 'crear contacto Rubén +503 7555 0000',
screen: snapshot,
});
if (action.type === 'done') break;
ad(`${action.verb} ${action.target} ${action.value ?? ''}`.trim());
step += 1;
}
ad('close');El patrón es limpio porque la CLI imprime JSON cuando se le pide, y los comandos mutantes en modo no-JSON imprimen una confirmación corta de éxito, lo cual le permite al agente distinguir acciones exitosas de no-ops silenciosos. Para flujos que requieran una orientación específica, rotate portrait o rotate landscape dejan el dispositivo en un estado determinista antes de continuar.
Cuándo usarlo y cuándo no
Ninguna herramienta sirve para todo, y agent-device es honesta al respecto. Úsala cuando tu objetivo sea exploración iterativa por parte de un agente, cuando necesités snapshots token-efficient para alimentar un LLM, cuando tu suite de tests tenga que convivir con ingeniería asistida por IA, o cuando quieras una CLI unificada entre iOS, tvOS, macOS, Android y AndroidTV sin montar un servidor Appium.
Evítalo cuando lo que necesitás es un framework de pruebas maduro con años de documentación y una comunidad masiva: para eso Appium sigue siendo el rey. Tampoco es la mejor opción si tu equipo ya tiene una inversión fuerte en Maestro o Detox y lo que buscás es un reemplazo drop-in: son herramientas con filosofía diferente. Y si tu flujo depende críticamente de validación visual pixel-perfect con comparación de screenshots, probablemente necesités combinar agent-device con una herramienta de visual testing dedicada.
Otro trade-off importante: agent-device se apoya en las APIs de accesibilidad del sistema. Si tu app tiene accesibilidad pobre (labels vacíos, jerarquías rotas, botones que no anuncian su rol), los snapshots van a ser difíciles de interpretar. La buena noticia es que arreglar esto hace tu app mejor para usuarios con discapacidades al mismo tiempo.
Alternativas
Vale la pena comparar agent-device con tres opciones que cubren espacios cercanos, sin caer en rankings subjetivos:
- Appium — el estándar histórico. Arquitectura cliente-servidor con drivers por plataforma, enorme ecosistema de bindings (Python, Java, Ruby, JS), documentación madura. A cambio, configuración pesada y snapshots verbose que no están pensados para consumo por LLMs.
- Maestro — DSL YAML declarativo centrado en legibilidad humana. Excelente para pipelines CI donde los flujos son conocidos. Menos adecuado para exploración dinámica donde el agente decide el próximo paso en runtime.
- agent-browser — el primo web de agent-device, de Vercel. Misma filosofía (sesiones, snapshots, refs) aplicada a navegadores. Si tu agente ya lo usa para la web, agent-device se integra con el mismo modelo mental, lo cual reduce la carga cognitiva enormemente.
Conclusión
agent-device es de esos proyectos que no inventan una categoría nueva pero llegan en el momento exacto: los agentes de IA están aprendiendo a operar computadoras completas, y el móvil era el eslabón que faltaba en la cadena. Callstack, que ya tiene mucho recorrido en el mundo React Native, puso una CLI pragmática, con soporte multiplataforma real, scripts replayables, runner con reintentos y skills diseñadas para que los modelos la usen bien sin pelear con la documentación.
Si estás armando automatización móvil en 2026 y querés que tu stack hable el mismo idioma que tus agentes, vale la pena probarlo. El proyecto es MIT, vive en callstackincubator/agent-device y tiene homepage propia con documentación extendida. Para empezar basta con npm install -g agent-device y un dispositivo a mano.
📱 ¿Te gusta este contenido? Únete a nuestro canal de Telegram @programacion donde publicamos a diario lo más relevante de tecnología, IA y desarrollo. Resúmenes rápidos, contenido fresco todos los días.
0 Comentarios