ThumbAgent

Local-first platform that gives AI agents a real thumb on mobile devices.

中文 | English

Plataforma local-first y multiplataforma de Skills para dispositivos móviles, orientada a agentes de IA.

Progreso actual

El proyecto ha completado ITER-0052 Desktop Device Screen & Live Observation: el workbench de escritorio muestra un panel de pantalla del dispositivo durante la ejecución de tareas de Agent, con capturas reales tras cada acción actualizadas en tiempo real por turnos; el informe de tarea permite expandir la evidencia de capturas por turno. Runtime añade un endpoint de contenido de solo lectura GET /v1/artifacts/{artifact_id}/content (autenticación con Bearer token, solo capturas PNG, límite de 8 MiB por archivo, no-store), y el evento task.step_completed incluye el screenshot_artifact_id de ese turno.

El workbench de escritorio (Tauri 2) inicia y autentica automáticamente el Runtime local. La página de inicio muestra el diagnóstico de preparación unificado y la lista de dispositivos detectados, y admite el envío de tareas en lenguaje natural, la línea de tiempo de ejecución y el informe completo. El desarrollo de escritorio se describe en apps/desktop/README.md. Usa Python 3.11+:

make check
make run

Runtime escucha por defecto en 127.0.0.1:8765 y ofrece /v1/health, /v1/devices y POST /v1/devices/{device_id}/observe.

Related MCP server: Android MCP Server

Vista previa para desarrolladores de MCP Skills

Al realizar la validación local con un dispositivo físico en macOS + Codex desktop, puedes usar un script de un clic:

./scripts/run-mcp-preview.zsh

En la primera ejecución, el script pide el model Key y guarda por separado el model Key y el token local estable de Runtime en el Keychain de inicio de sesión de macOS; en los inicios posteriores no vuelve a preguntar. El script detiene de forma segura el antiguo mobile_agent.api.server que ocupa el puerto de destino, reutiliza el registro MCP sin cambios e inicia un nuevo Runtime. Si Codex/ChatGPT ya está en ejecución, no es necesario cerrarlo ni volver a abrirlo. Solo cuando se produce el primer registro, se usa --refresh-mcp explícito, o cambian la configuración de MCP o el Tool Catalog, es necesario reiniciar Codex una vez y crear una nueva tarea para refrescar el entorno MCP en caché; un reinicio normal de Runtime no lo requiere.

El model Key solo entra en el Keychain y en el entorno del proceso de Runtime; no se escribe en el repositorio ni en la salida del script. El script se mantiene en primer plano; pulsa Ctrl+C para detener Runtime. Si solo quieres comprobar las rutas de Python, ADB, Codex y la configuración del modelo sin leer claves ni modificar la configuración de MCP, usa:

./scripts/run-mcp-preview.zsh --check

Cuando necesites forzar la actualización del registro MCP o eliminar el Secret de vista previa:

./scripts/run-mcp-preview.zsh --refresh-mcp
./scripts/run-mcp-preview.zsh --forget-secrets

Actualizar el registro no rota el token del Keychain. Si el puerto de destino está ocupado por otro programa, el script se negará a matarlo por error; solo detiene automáticamente los procesos cuya línea de comandos pertenezca explícitamente a mobile_agent.api.server.

Para que Web, CLI y MCP compartan el mismo Runtime, inicia el servicio con un token local explícito:

MOBILE_AGENT_API_TOKEN=<local-random-token> \
MOBILE_AGENT_ADB_PATH=/usr/local/platform-tools/adb \
make run

Luego configura el servidor stdio en el MCP Host con el mismo token. Ver ejemplo en mcp-server.example.json. El comando que realmente inicia el MCP Host es:

PYTHONPATH=runtime \
MOBILE_AGENT_API_TOKEN=<same-local-random-token> \
python3.11 -m mobile_agent.mcp

MCP ofrece Tools a nivel de objetivos, que cubren el diagnóstico de preparación, la inspección de dispositivos y aplicaciones instaladas, el ciclo de vida de la aplicación, las tareas asíncronas de Agent, la consulta/cancelación de tareas, los registros desensibilizados, las instantáneas agregadas de rendimiento, los paquetes de evidencia de diagnóstico, la comparación de rendimiento y la limpieza local de retención de Artifacts. No expone ADB, Shell arbitrarios, rutas de archivo arbitrarias ni Tools atómicos como input.tap. Las acciones que requieren confirmación solo pueden recibir confirmed=true cuando el MCP Host ya ha mostrado al usuario los parámetros y el impacto y ha obtenido su confirmación.

Una vez iniciado, puedes ver el diagnóstico unificado de preparación:

PYTHONPATH=runtime python3.11 -m mobile_agent.cli.runtime_diagnose

GET /v1/readiness y la Web UI muestran Android Gateway, la conexión/autorización del dispositivo, la Session, la ocupación del Lease y las sugerencias de reparación. Cuando ADB no está instalado o la ruta es incorrecta, Runtime sigue iniciando la interfaz de diagnóstico y ya no sale directamente por ADB_NOT_FOUND.

Para ver las capacidades actuales, riesgos, requisitos de confirmación y limitaciones de un único dispositivo:

PYTHONPATH=runtime python3.11 -m mobile_agent.cli.device_inspect <device_id>

MCP también ofrece mobile_list_apps y mobile_inspect_app de solo lectura, para listar de forma acotada los identificadores de aplicaciones y consultar la versión, el origen de instalación y el estado habilitado de una única aplicación. No devuelven la ruta del APK, la firma, los permisos ni el dumpsys original, ni inician o modifican aplicaciones.

La instalación local de APK solo acepta un único .apk dentro del directorio <data-dir>/apks. El Agent externo debe llamar primero a mobile_prepare_apk_install para obtener una Approval de corta duración que contenga el nombre del archivo, el tamaño, SHA-256, el package id del Manifest y el impacto del reemplazo; solo después de que el MCP Host muestre ese resumen al usuario y obtenga una confirmación explícita se puede llamar a mobile_install_apk. La Approval caduca a los diez minutos y por defecto solo puede usarse una vez. Runtime no descarga URLs, no acepta split APKs ni argumentos ADB arbitrarios.

La desinstalación de aplicaciones usa un proceso independiente en dos fases: mobile_prepare_app_uninstall → mobile_uninstall_app. Prepare devuelve de solo lectura la versión de la aplicación, la determinación de aplicación de sistema y el impacto del borrado de datos; las aplicaciones de sistema o las de atributos desconocidos se rechazan directamente. Solo después de que el usuario confirme explícitamente de nuevo ese resumen se puede enviar la tarea de desinstalación asíncrona. No se debe reintentar automáticamente en caso de fallo o de unknown outcome.

El ciclo de vida de la aplicación ofrece mobile_inspect_app_state, mobile_launch_app y mobile_stop_app. La comprobación de estado solo devuelve si el proceso existe, si está en primer plano y el flag stopped; lanzar o detener devuelve un task_id asíncrono, y antes de detener una aplicación que no es de sistema se requiere una confirmación explícita. Para borrar permanentemente los datos de una aplicación, primero hay que llamar a mobile_prepare_app_data_clear, mostrar el nombre del paquete, la versión y el impacto del borrado de datos y obtener una nueva confirmación explícita, y después llamar a mobile_clear_app_data. El borrado de datos de la aplicación no la desinstala; no se debe reintentar automáticamente en caso de fallo o de resultado desconocido.

Tras la confirmación explícita, se captura una instantánea de los registros recientes (hay que pasar el token local de API generado al iniciar Runtime):

PYTHONPATH=runtime python3.11 -m mobile_agent.cli.device_logs_collect \
  <device_id> --max-lines 500 --minimum-level info --confirm --token <runtime-token>

Los registros se desensibilizan primero y luego se guardan como un Artifact local de hasta 1 MiB; CLI y REST no devuelven el contenido del registro. Añadir --async-task permite obtener inmediatamente el task_id y usar el estado de ejecución unificado, los eventos, la cancelación y el informe de tarea:

PYTHONPATH=runtime python3.11 -m mobile_agent.cli.device_logs_collect \
  <device_id> --confirm --async-task --deadline-seconds 60 --token <runtime-token>

Captura una instantánea agregada de CPU, memoria, temperatura de la batería y carga del sistema:

PYTHONPATH=runtime python3.11 -m mobile_agent.cli.device_performance_snapshot \
  <device_id> --async-task --deadline-seconds 90 --token <runtime-token>

El Artifact de rendimiento solo contiene métricas JSON agregadas; no guarda el texto original de dumpsys, nombres de procesos ni detalles de la aplicación.

Captura de una sola vez capturas de pantalla, UI Tree, registros desensibilizados, rendimiento agregado y estado opcional de la aplicación, y genera un ZIP local con manifiesto SHA-256:

PYTHONPATH=runtime python3.11 -m mobile_agent.cli.diagnostic_bundle_collect \
  <device_id> --app-id <package-id> --max-log-lines 500 \
  --minimum-log-level info --confirm --token <runtime-token>

El paquete de diagnóstico es de riesgo Medium y debe confirmarse explícitamente. CLI, Web, REST y MCP solo devuelven los metadatos del Artifact y un resumen seguro; no incluyen en línea capturas de pantalla, UI Tree, registros ni el contenido del ZIP. Los nombres de archivo dentro del paquete son fijos, el tamaño total no supera los 24 MiB y no se sube ni se envía a ningún sitio.

Para ver el espacio ocupado por los Artifacts locales y precomprobar de solo lectura la evidencia que supera el período de retención por defecto de 7 días:

PYTHONPATH=runtime python3.11 -m mobile_agent.cli.local_storage
PYTHONPATH=runtime python3.11 -m mobile_agent.cli.local_data_cleanup_prepare \
  --retention-days 7 --max-artifacts 500 --token <runtime-token>

Prepare no elimina archivos; solo devuelve el número de candidatos, el tamaño, la fecha límite y una Approval de corta duración. Solo después de que el usuario revise el resumen de impacto y vuelva a confirmar explícitamente se puede enviar la tarea de limpieza asíncrona:

PYTHONPATH=runtime python3.11 -m mobile_agent.cli.local_data_cleanup \
  <approval-id> --confirm --token <runtime-token>

La limpieza solo acepta el ID de Artifact generado por el sistema, la ruta relativa, el tamaño y SHA-256 vinculados en la Approval; no acepta rutas arbitrarias, no elimina la base de datos de tareas, configuraciones, claves o APKs, y no se ejecuta automáticamente en segundo plano ni reintenta automáticamente los fallos.

Para comparar dos tareas de instantánea de rendimiento completadas en el mismo dispositivo:

PYTHONPATH=runtime python3.11 -m mobile_agent.cli.device_performance_compare \
  <baseline_task_id> <candidate_task_id> --token <runtime-token>

El informe de tarea de Web también puede establecer una instantánea correcta como línea base y luego seleccionar otra instantánea para comparar. El resultado de la comparación solo indica la dirección numérica y el umbral de estabilidad de las dos muestras; no determina automáticamente causalidad ni regresión de rendimiento.

Si adb no está en PATH, puedes configurarlo explícitamente:

MOBILE_AGENT_ADB_PATH=/usr/local/platform-tools/adb

ITER-0003 añade GET /v1/tools, POST /v1/tools/{tool_id}/invoke y POST /v1/skills/app.open/invoke. input.tap es de riesgo Medium y por defecto requiere confirmación explícita.

ITER-0004 añade análisis seguro de la jerarquía de UI, Selector semántico, input.tap_element y POST /v1/skills/settings.navigate/invoke. El clic semántico es de riesgo Medium y se rechaza cuando la coincidencia no es única.

ITER-0005 añade input.swipe y input.text restringidos por políticas, búsqueda de scroll semántico acotada y POST /v1/skills/settings.scroll_navigate/invoke. Tanto el scroll como la entrada son de riesgo Medium y requieren confirmación explícita por defecto; los escenarios de contraseñas, códigos de verificación, pagos, seguridad de cuentas y envío automático no están dentro del alcance de esta iteración.

ITER-0006 añade un Task Runner mínimo, el informe de evidencia TaskRun y el endpoint síncrono de tipo vista previa POST /v1/tasks/settings.scroll_navigate/run. Este endpoint solo envuelve la Skill existente settings.scroll_navigate y no sustituye al diseño posterior de cola de tareas asíncronas.

ITER-0007 añade un Task Store en proceso, TaskEvent y los endpoints de consulta GET /v1/tasks/{task_id} y GET /v1/tasks/{task_id}/events. Este Store solo es válido durante el ciclo de vida del proceso de Runtime actual y todavía no ofrece recuperación tras reinicio.

ITER-0008 añade la primera versión de la vista de informe de tarea de CLI, que puede renderizar TaskRun y TaskEvent como un informe legible para el usuario:

PYTHONPATH=runtime python3.11 -m mobile_agent.cli.task_report <task_id>

Este comando consulta tareas y eventos desde la API de Runtime local.

ITER-0009 añade un SQLite Task Store que, por defecto, guarda las tareas y eventos en <data-dir>/mobile-agent.db. Cuando se establece MOBILE_AGENT_DATA_DIR, la base de datos se encuentra en ese directorio; de lo contrario, usa el directorio de datos local por defecto de la plataforma.

ITER-0010 añade una lista de tareas históricas:

PYTHONPATH=runtime python3.11 -m mobile_agent.cli.task_list --limit 20

La lista muestra un resumen de las tareas recientes; puedes copiar task_id y usar task_report para ver los detalles.

ITER-0011 añade una Web UI local. Tras iniciar Runtime, abre:

http://127.0.0.1:8765/ui

para ver el historial de tareas y los detalles del informe de tarea.

ITER-0012 añade el botón «Ejecutar demo segura» en la Web UI. El botón selecciona un dispositivo Android en línea y ejecuta una tarea fija: abrir los ajustes del sistema y entrar en la página de pantalla/brillo. La solicitud POST sigue usando el token local de Runtime y solo puede activarse desde páginas loopback del mismo origen.

ITER-0013 añade una vista previa del bucle de Agent antes de la integración del modelo: POST /v1/tasks/agent.run. Este endpoint usa un Planner determinista para generar decisiones restringidas; por ahora solo admite el objetivo de demostración segura «entrar en la página de pantalla/brillo de los ajustes del sistema», y escribe el resumen de observación, la decisión del Planner, el resultado de ejecución de la Skill y la evidencia en el informe de tarea.

ITER-0014 añade en la Web UI un campo de entrada de tareas en lenguaje natural y el botón «Ejecutar vista previa de Agent». La página llama a POST /v1/tasks/agent.run y, cuando la tarea regresa, actualiza la lista de historial y abre el informe de tarea.

ITER-0015 añade el contrato de vista previa interna del LLM Planner y MockLLMPlanner. La salida de tipo modelo debe pasar primero por un análisis estructurado y la validación de campos, y después por una segunda validación con la allowlist de Skills del Agent Runner; esta iteración no llama a ningún servicio de modelo real ni lee claves de modelo.

ITER-0016 añade la vista previa del Planner Provider compatible con OpenAI, desactivada por defecto. El Provider puede construir solicitudes de estilo chat-completions, analizar respuestas estructuradas a través de un transport inyectable y reutilizar la validación de salida del Planner de ITER-0015; el Runtime por defecto no habilita un Provider real y las pruebas no dependen de la red ni de claves de modelo.

ITER-0017 añade una puerta de configuración del Provider de modelo: la configuración por defecto sigue devolviendo RuleBasedPlanner; solo cuando se habilita explícitamente openai_compatible, se proporcionan base_url, model y api_key_ref, y se resuelve la clave mediante el SecretResolver inyectado, se construye un Planner compatible con OpenAI. Esta iteración no se conecta al Runtime por defecto ni lee claves reales.

ITER-0018 añade una entrada de estado de solo lectura para el Provider de modelo: GET /v1/model-provider/status y el panel de estado «Provider de modelo» en la Web UI. El estado solo muestra si está habilitado, el provider, el modelo y si hay una referencia de clave configurada; no devuelve la clave real ni el texto original de api_key_ref; el Runtime por defecto sigue sin habilitar un modelo real.

ITER-0019 añade la lectura de la configuración local del modelo: al iniciarse, Runtime lee <data-dir>/model-provider.json o el archivo especificado por MOBILE_AGENT_MODEL_CONFIG, y permite que las variables de entorno MOBILE_AGENT_MODEL_* sobrescriban los campos de configuración. El archivo de configuración solo guarda api_key_ref; el SecretResolver de vista previa de desarrollo solo resuelve referencias env:MOBILE_AGENT_MODEL_SECRET_*; el Agent Runner por defecto sigue sin llamar a un modelo real.

ITER-0020 integra de forma controlada el Planner de modelo en el Runtime por defecto: cuando la configuración está desactivada, se sigue usando el Planner por reglas; cuando está activada y la referencia de clave es resoluble, se usa un Planner compatible con OpenAI; cuando está activada pero no disponible, las tareas de Agent fallan explícitamente con MODEL_UNAVAILABLE, sin volver silenciosamente al Planner por reglas. La salida del modelo sigue debiendo pasar por el análisis estructurado, la allowlist de Skills, el Policy Engine y el Device Gateway.

ITER-0021 mejora la tarjeta de estado del Provider de modelo en la Web UI: distingue no habilitado, conectado, configuración no disponible y configuración leída, y cuando no está disponible sugiere revisar el archivo de configuración, MOBILE_AGENT_MODEL_CONFIG y MOBILE_AGENT_MODEL_SECRET_*. El repositorio incluye un ejemplo de configuración: model-provider.example.json.

ITER-0022 actualiza la vista previa de Agent de «una ronda de decisión del modelo que llama a una Skill grande» a «múltiples rondas de decisión del modelo + ejecución de Tools atómicos + nueva observación en cada ronda». El Planner puede emitir run_tool y finish; Runtime solo permite Tools de la lista blanca y, en finish, realiza una verificación determinista mediante el UI Selector; la ruta antigua run_skill sigue siendo compatible.

ITER-0023 promueve AgentObservationSummary, AgentDecision y AgentStepResult de los informes por ronda de Agent a JSON Schema públicos, y actualiza el Schema de TaskRun para admitir oficialmente agent.run. El escritorio, CLI y futuros Agent externos pueden consumir de forma estable los informes de múltiples rondas Observe–Plan–Act.

ITER-0024 añade retroalimentación de progreso de las acciones de Agent: Runtime compara la aplicación en primer plano y el árbol de UI antes y después del Tool, devuelve changed / unchanged al modelo en la siguiente ronda y evita volver a despachar la misma acción sin progreso. El informe de Web muestra a la vez el Tool real, los parámetros y el progreso de la página.

ITER-0025 optimiza la Observation en el lado del modelo: filtra los nodos de diseño sin semántica, da prioridad a los textos visibles y a los nodos accionables, añade metadatos de truncamiento del resumen y desensibiliza números de teléfono, correos electrónicos e identificadores numéricos largos comunes antes de que el texto de la UI entre en el Prompt del modelo y en el resumen de la tarea.

ITER-0026 añade un contrato estricto de ToolCall para el Agent, una reparación acotada de una sola vez para los parámetros inválidos del modelo y la conservación de la evidencia de las rondas fallidas. En un dispositivo real se ha completado el bucle de modelo de múltiples rondas de «entrar en pantalla y brillo».

ITER-0027 establece la base de evaluación en línea del Agent impulsada por objetivos: el modelo real replanifica cada vez frente a la interfaz actual del dispositivo; la evaluación solo restringe el objetivo, el estado final, las Tools prohibidas y el presupuesto de rondas, sin comparar rutas de acción fijas. Un agent.run completado puede evaluarse mediante POST /v1/tasks/{task_id}/evaluate; el ejemplo de escenario está en agent-evaluation-scenario.example.json.

ITER-0042 organiza varios escenarios independientes de ruta en una Suite versionada. Primero ejecuta los objetivos de la Suite mediante Web o MCP, y luego pasa los task_id completados a la CLI de agregación de solo lectura; este comando solo llama a la API de evaluación existente y no envía ni reproduce acciones del dispositivo:

./scripts/report-mcp-evaluation.zsh \
  --suite evaluations/android-settings-smoke-v1.json \
  --task settings.bluetooth.v1=task_<id> \
  --task settings.display-brightness.v1=task_<id> \
  --task settings.battery.v1=task_<id>

El informe muestra la tasa de éxito total, la tasa por escenario, p50/p95 de duración, el número medio de rondas y de Tools, y las estadísticas de reintentos del Provider, NO_PROGRESS, MODEL_UNAVAILABLE y violaciones de políticas. La Suite define objetivos y condiciones de éxito independientes; no contiene rutas de acción fijas. El script solo lee la información de conexión local de mobile-agent registrada en Codex; no imprime el token ni envía tareas del dispositivo.

ITER-0028 refuerza la fiabilidad: la localización de objetivos sin efectos secundarios y el fallo de verificación de finish pueden retroalimentar al modelo como una ronda fallida para que continúe planificando; finish puede combinar la app/activity en primer plano y el UI Selector; los clics en el área del sistema superior y en el área de gestos inferior se bloquean antes de su despacho. Los tiempos de espera del Provider, los errores HTTP, de conexión y de formato de respuesta se registran de forma clasificada, y las solicitudes de modelo reintentables se reintentan como máximo una vez; un Selector inválido solo muestra un diagnóstico desensibilizado a nivel de campo. Cuando el modelo omite reason no crítico para la seguridad, Runtime genera una nota de auditoría fija y no inicia solicitudes adicionales de reparación del modelo por ello; las Tools, los Selectors, las políticas y las condiciones de finalización siguen siendo estrictamente validados.

ITER-0029 añade condiciones de éxito opcionales propiedad de Runtime para el llamador. POST /v1/tasks/agent.run puede recibir acceptance, que valida el finish emitido por el modelo usando la semántica all-of de app id en primer plano, Activity y UI Selector único; la ruta sigue siendo planificada dinámicamente por el modelo a partir de la Observation en tiempo real. El informe de tarea persiste y muestra goal_acceptance y completion_source. El ejemplo de solicitud está en agent-run-runtime-acceptance.example.json.

ITER-0030 añade la compilación de objetivos en dos fases: POST /v1/goals/compile convierte un objetivo corto en lenguaje natural en un borrador de AgentGoalSpec revisable, que incluye el objetivo de ejecución mejorado, supuestos, confianza y condiciones de éxito opcionales. El borrador del modelo debe ser confirmado explícitamente por el usuario antes de pasarlo a agent.run; la tarea sigue siendo planificada dinámicamente por el modelo a partir de la Observation en tiempo real y no genera rutas de acción fijas. Ver ejemplo en agent-goal-spec.example.json.

ITER-0031 añade la ejecución asíncrona de Agent: POST /v1/tasks/agent.run/async devuelve inmediatamente 202 Accepted y el task_id; GET /v1/task-executions/{task_id} y /events ofrecen estado persistido y eventos por ronda; POST /v1/task-executions/{task_id}/cancel solicita la cancelación en un límite seguro. La creación asíncrona admite Idempotency-Key; el endpoint síncrono original `

• Entrada de desarrollo de Agent

• Guía de contribución

• Documentación y normas de iteración

• Normas de desarrollo de ingeniería

• Normas de evolución de Contract y API

• Modelo de Capability

• Normas de desarrollo de Skill

• Fiabilidad y semántica de ejecución

• Normas de datos y migración

• Normas de errores y diagnóstico

• Límites de arquitectura

• Normas de pruebas

• Normas de seguridad

• Normas de colaboración multi-Agent

• Registro de decisiones de arquitectura

• Índice de iteraciones

Licencia

Apache-2.0