agent-desktop computer use: manejar un escritorio con un agente de IA

agent-desktop computer use: un agente de IA maneja macOS, Windows y Linux con el árbol de accesibilidad. Instalación, seguridad, trazas y límites.
agent-desktop computer use : piloter un bureau par agent IA

agent-desktop computer use: el repositorio vercel-labs/agent-desktop ofrece una línea de comandos que permite a un agente de IA ver y manejar las aplicaciones de escritorio en macOS, Windows y Linux. No usa capturas de pantalla: lee el árbol de accesibilidad del sistema y lo devuelve en JSON, con una referencia («ref») para cada elemento sobre el que el agente puede actuar. Vercel Labs publica el repositorio con licencia Apache 2.0.

Para un SRE, este tipo de herramienta cambia el perímetro de riesgo. Un agente que hace clic y escribe texto actúa sobre un equipo real, con los permisos del usuario. ¿Qué dice el repositorio, cómo se instala y qué se puede trazar y controlar cuando un agente maneja un escritorio?

Aclaración de honestidad: span.observer no ha instalado ni ejecutado agent-desktop. Los comandos proceden del README, de los archivos docs/, de CONCEPTS.md y de la documentación del proyecto, leídos el 5 de noviembre de 2026. Las capturas siguientes reproducen esos textos. No pudimos releer el número de estrellas en la fuente ese día, así que no lo citamos.

agent-desktop computer use: qué dice el repositorio

  • Principio: la herramienta lee el árbol de accesibilidad de una aplicación y lo imprime en JSON. El agente actúa sobre una ref, vuelve a leer la interfaz para comprobar el resultado y repite. Según el README, el bucle vive en tu agente: agent-desktop no incluye ningún modelo.
  • Forma: una CLI y una biblioteca en C. El registro de cambios del repositorio fecha la versión 1.2.0 el 5 de noviembre de 2026.
  • Licencia: Apache 2.0, según el README y el archivo LICENSE.
  • Comandos: el README cuenta 60 nombres de comandos, 56 de ellos operativos. Cuatro (key-down, key-up, mouse-down, mouse-up) se niegan a ejecutarse mientras no haya un demonio capaz de soltar una tecla o un botón mantenido.
  • MCP: la versión 1.2.0 añade agent-desktop mcp, un servidor MCP sobre stdio que expone cada comando como una herramienta.

Una precaución sobre el respaldo: el proyecto procede de un laboratorio de un proveedor conocido, pero sigue siendo joven y evoluciona rápido (cambios incompatibles en la 1.1.0 según el registro de cambios). Lee el registro antes de cada actualización.

Recorrido por los comandos y las salidas

La primera captura recoge el inicio rápido del README y el extracto de snapshot que muestra. Se ve el sobre JSON: un snapshot_id, un contador de refs, el indicador complete y, para cada elemento accionable, un ref_id que incluye el identificador del snapshot.

Extracto del README de vercel-labs/agent-desktop: tres comandos snapshot, click y de nuevo snapshot sobre Finder, y el sobre JSON de un snapshot con snapshot_id, ref_count, complete y un elemento treeitem con un ref_id
Source : github.com

Este diseño tiene una consecuencia útil para la seguridad. Según el README, una ref pertenece a su snapshot: una ref suelta como @e8 se rechaza con INVALID_ARGS. Cuando la interfaz cambia, la acción devuelve STALE_REF o AMBIGUOUS_TARGET. Así, el agente no hace clic «a ciegas» en una posición obsoleta: tiene que volver a leer la pantalla.

La segunda captura muestra el contrato de errores descrito en docs/json-output.md. Cada error lleva un campo disposition: delivery indica si la acción llegó a enviarse y retry indica si se puede repetir. La documentación precisa que solo se repita automáticamente cuando retry vale safe y que se trate unknown como no seguro.

Extracto de docs/json-output.md: sobre JSON de un error STALE_REF en el comando click, con recovery (refresh_snapshot_then_retry_original) y disposition not_delivered, retry safe
Source : github.com

Instalación paso a paso

Los comandos siguientes proceden del README. Requisitos según la tabla de plataformas: macOS 13 o superior, Windows 10 1809 o superior, o Ubuntu 24.04 o superior (X11 o Wayland).

  1. Instala el paquete npm, que incluye los binarios nativos x64 y ARM64:
    npm install -g agent-desktop
  2. En macOS y Linux, Homebrew también funciona: brew install agent-desktop. El README aclara que no existe un paquete oficial de Scoop.
  3. Comprueba la plataforma, los permisos y las superficies compatibles:
    agent-desktop status
    agent-desktop permissions --guide   # macOS : guide pour l'autorisation Accessibilité
  4. Lanza el bucle observar, actuar, comprobar:
    agent-desktop snapshot --app Finder -i
    agent-desktop click @s8f3k2p9:e8
    agent-desktop snapshot --app Finder -i
  5. Para un cliente MCP, declara el servidor (extracto del README):
    { "mcpServers": { "agent-desktop": { "command": "agent-desktop", "args": ["mcp"] } } }

En PowerShell, el README pide poner cada ref entre comillas simples, porque un @token suelto es el operador de splatting.

Seguridad: lo que está documentado y lo que queda de tu cuenta

  • Datos privados: el README advierte de que los snapshots, las lecturas del portapapeles, las capturas de pantalla y las salidas de comandos pueden contener contenido privado del escritorio. Pide mantenerlos fuera de los registros públicos.
  • Modo sin cabeza por defecto: las acciones sobre una ref pasan por la API de accesibilidad, sin mover el puntero ni tomar el foco. La opción global --headed autoriza la entrada física.
  • Secretos: type, set-value y clipboard-set aceptan --stdin para mantener el texto fuera de los argumentos de proceso. El README aconseja ejecutar los pasos secretos como comandos separados, porque el texto de un lote JSON aparece en los argumentos.
  • Permisos: en macOS, el programa que lanza agent-desktop necesita el permiso de Accesibilidad. Conceder este derecho a un agente equivale a confiarle el equipo.
  • Límite funcional: la herramienta solo ve lo que la aplicación publica en su árbol de accesibilidad. La FAQ del repositorio lo dice: una aplicación sin árbol no es visible.

Estas salvaguardas de la herramienta no sustituyen a las del agente. Consulta las salvaguardas de los agentes de IA en producción para los límites de acciones que conviene fijar en producción, y la detección del envenenamiento de herramientas MCP si conectas el servidor agent-desktop mcp a un cliente que carga otras herramientas.

Observar a un agente que maneja un escritorio

El repositorio documenta un mecanismo de sesiones y trazas, no telemetría OpenTelemetry: nuestras búsquedas en los archivos Markdown del repositorio no encuentran ni OpenTelemetry, ni OTLP, ni Prometheus. Por tanto, no hay que suponerla.

La tercera captura recoge la sección «Sessions and traces» de la referencia de comandos. Una sesión es una carpeta bajo ~/.agent-desktop/sessions/<id>/ con un manifiesto y, por defecto, un directorio trace/. Los segmentos de traza son archivos JSONL, uno por proceso.

Extracto de commands-system.md del repositorio: comando session start con un nombre, session end, y cuatro líneas sobre trace show, trace export, la redacción de campos sensibles y la opción screenshots no redactada
Source : github.com
  • Cronología: trace show devuelve la cronología fusionada de los eventos; trace export escribe un visor HTML autónomo. Ambos prescinden de los permisos del sistema.
  • Redacción: las líneas de traza sustituyen los campos sensibles (text, value, name, title, url…) por { "redacted": true }. Con --screenshots, los PNG de antes y después de la acción no se redactan: trátalos como capturas de pantalla sensibles.
  • Aislamiento: una sesión tiene su propio espacio de snapshots. Varios agentes pueden compartir un identificador de sesión, siempre que cada uno use las refs cualificadas de su propio snapshot.
  • Seguimiento: status indica session_id, tracing y artifacts.

Para enlazar estas trazas con tu supervisión, queda trabajo por hacer: enviar tú mismo un span por acción desde el orquestador del agente, con el comando, el código de error y la duración, y nunca el contenido de los campos. El principio coincide con el de un agente que maneja Chrome mediante DevTools o el de un navegador headless para agentes: la herramienta actúa y la instrumentación se coloca alrededor. El proyecto no documenta ninguna integración con Dynatrace; una exportación OTLP desde tu orquestador hacia Dynatrace SaaS sigue siendo posible, y su configuración depende de la documentación de Dynatrace.

Buenas prácticas

  • Ejecuta el agente en una cuenta o una máquina dedicadas, sin sesión abierta sobre datos sensibles.
  • Repite un comando solo si error.disposition.retry vale safe.
  • Mantén el modo sin cabeza por defecto; activa --headed solo para un paso concreto.
  • Pasa los secretos por --stdin, en comandos separados.
  • Activa las sesiones con nombre, elimina las antiguas con session gc y mantén privadas las carpetas de trazas.
  • Registra en tu propia telemetría el nombre del comando, el código de error y la duración, sin el contenido leído.

Preguntas frecuentes

¿Necesita agent-desktop capturas de pantalla?

No. Según la FAQ del repositorio, los comandos que reciben una ref encuentran el elemento en el árbol de accesibilidad, no por comparación de píxeles. El comando screenshot existe por separado.

¿Maneja agent-desktop también páginas web?

No. La documentación indica que no automatiza páginas web y remite a agent-browser para ello.

¿Recibe un modelo remoto mis datos?

La FAQ precisa que la CLI nativa no exige ningún servicio de modelo remoto. Tu agente, en cambio, envía lo que lee a su propio modelo: te corresponde controlar ese flujo. Un asistente opcional del repositorio, JEV, envía el objetivo y descripciones de pantalla al proveedor que configures.

Conclusión

agent-desktop aporta un computer use basado en el árbol de accesibilidad, con salidas JSON estrictas y un contrato de errores claro. Su punto fuerte para la operación es la trazabilidad: sesiones, trazas y redacción por defecto. Sus límites son los del género: un agente que actúa sobre un equipo real, datos privados por todas partes y ninguna telemetría estándar que conectar. Relee la documentación antes de cada despliegue.

span.observer es un blog independiente de la comunidad, no afiliado a Vercel ni a agent-desktop, ni a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Las marcas citadas pertenecen a sus propietarios. Las herramientas evolucionan rápido: comprueba siempre los comandos y las opciones en su documentación oficial.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Worktrunk git worktree : CLI pour agents de code en parallèle

Worktrunk git worktree: CLI para agentes de código en paralelo

Next Post
kagent agents IA Kubernetes : le framework en détail

kagent agentes de IA Kubernetes: el framework en detalle

Related Posts