agent-desktop legge l'albero di accessibilità, non lo screenshot

Ogni agente di computer use che lavora a screenshot gira nello stesso ciclo costoso. Fare una foto dello schermo. Chiedere a un modello di visione dove sia il pulsante. Convertire la risposta in coordinate in pixel. Cliccare. Fare un'altra foto per scoprire se è successo qualcosa.
Funziona, nello stesso senso in cui funziona l'OCR: in modo impressionante, e mai abbastanza affidabile da poterlo lasciare andare da solo. I modi in cui fallisce sono variazioni di un unico tema: la foto di un'interfaccia è una rappresentazione con perdita di un'interfaccia.
agent-desktop, pubblicato da Vercel Labs e arrivato a circa 23.300 stelle, di cui circa 5.400 nell'ultima settimana, prende l'altra strada. Non guarda lo schermo. Legge l'albero di accessibilità dell'applicazione di destinazione e lo restituisce come JSON, con un riferimento per ogni elemento su cui l'agente può agire. L'agente clicca o digita su un riferimento, rilegge l'interfaccia per verificare il risultato, e ripete.

Il ciclo vive nel tuo agente. Il binario non contiene nessun modello.
Installazione e primo contatto
Il pacchetto si installa globalmente con npm:
npm install -g agent-desktop
agent-desktop status
`status` riporta piattaforma, permessi e superfici supportate. È il primo comando giusto, perché il computer use si blocca al passo dei permessi molto più spesso che a quello della logica. Su macOS il comando successivo è `agent-desktop permissions --guide`, che accompagna nella concessione dell'accessibilità. Anche Homebrew funziona su macOS e Linux. Bun, Yarn e pnpm installano lo stesso pacchetto; i binari nativi per x64 e ARM64 sono inclusi.
Il ciclo di tre comandi è questo:
agent-desktop snapshot --app Finder -i
agent-desktop click @s8f3k2p9:e8
agent-desktop snapshot --app Finder -i
L'opzione `-i` limita lo snapshot agli elementi interattivi. Il clic usa un riferimento preso da quello snapshot specifico. Il secondo snapshot non è manutenzione facoltativa: è il modo in cui scopri se il clic ha fatto quello che pensi.
Le decisioni di progetto che contano
Ci sono quattro scelte in questo strumento che vale la pena capire prima di costruirci qualcosa sopra.
I riferimenti appartengono al loro snapshot. Un `@e8` da solo viene rifiutato con `INVALID_ARGS`. Se l'interfaccia cambia tra osservazione e azione, l'azione restituisce `STALE_REF` o `AMBIGUOUS_TARGET`, e la risposta corretta è fare un nuovo snapshot e usare i suoi riferimenti. È più severo della maggior parte degli strumenti di automazione, ed elimina un'intera classe di clic sbagliati silenziosi.
Le applicazioni dense hanno un percorso di ispezione in due fasi. Per qualcosa come Slack, l'approccio documentato è `snapshot --skeleton --app Slack -i --compact` per mappare l'applicazione, poi `snapshot --root @s8f3k2p9:e3 -i --compact` per scendere in una regione. Senza questo, l'albero completo di un'app complessa è troppo JSON da tenere in mano per un agente.
Di default è headless. Le azioni per riferimento passano dall'API di accessibilità senza spostare il puntatore né rubare il focus, così la macchina resta utilizzabile mentre l'agente lavora. L'opzione globale `--headed` passa all'input fisico, che serve quando l'applicazione controlla eventi reali e non altrimenti.
I segreti possono restare fuori dagli argomenti del processo. `type`, `set-value` e `clipboard-set` accettano `--stdin` per testo inviato da una pipe. Dato che gli argomenti della riga di comando sono visibili nell'elenco dei processi, questa è la differenza tra una password che compare nell'output di `ps` e una che non compare. Il consiglio del README è eseguire i passaggi con segreti come comandi separati, perché il testo JSON inviato in blocco ricompare nell'elenco degli argomenti.
C'è una nota a piè di pagina su PowerShell che farà risparmiare un'ora a qualcuno: metti tra virgolette ogni riferimento, perché un `@token` nudo è l'operatore di splatting.
Che cosa è davvero il livello piattaforma
Sotto la CLI c'è una libreria C, e sotto entrambi c'è lo stesso nucleo. Ogni binario è compilato per un sistema operativo e parla con la sua API di accessibilità: AX API su macOS, UI Automation su Windows, AT-SPI su Linux. Il nucleo raggiunge il sistema solo attraverso un trait `PlatformAdapter`, ed è per questo che una sola base di codice può presentare la stessa busta JSON su tre modelli di accessibilità molto diversi.
Quell'architettura spiega anche il tetto dello strumento. Può agire solo su ciò che l'albero di accessibilità espone. Le applicazioni che disegnano la propria interfaccia su un canvas e non espongono nulla restano invisibili o quasi, per quanto bravo sia l'adattatore. Gli agenti a screenshot quei casi li coprono. Gli agenti a riferimenti no. Lo scambio è precisione sulle app fatte bene contro copertura di quelle fatte male.
Un confronto concreto
Pensa a un compito piccolo che gli agenti a screenshot gestiscono male: rinominare dodici file in un file manager del desktop.
Un agente a screenshot guarda la finestra, individua dodici etichette con i nomi dei file e produce dodici coppie di coordinate. Clicca la prima, seleziona il testo, digita un nome nuovo, preme invio e aspetta che la lista si riordini. Ogni coordinata successiva è ormai scaduta, perché l'ordine della lista è cambiato. L'agente deve riosservare dopo ogni rinomina, cioè dodici chiamate di visione e dodici occasioni di cliccare la riga sbagliata.
L'approccio per riferimenti osserva una volta. Lo snapshot restituisce l'albero della finestra con un riferimento per ogni riga, più un id di snapshot. Ogni rinomina è un'azione su un riferimento preciso, e dopo ogni azione l'agente rilegge l'albero per confermare che il nome nuovo sia comparso. Se la lista si riordina, i riferimenti dello snapshot originale scadono e lo strumento lo dice, che è esattamente il comportamento che vuoi: un fallimento rapido ed esplicito invece di un'azione silenziosa sul file sbagliato.
La differenza di affidabilità viene da dove viene calcolata la struttura. Nel primo caso un modello ricostruisce una lista di file dai pixel e qualche volta sbaglia. Nel secondo il sistema operativo riporta la lista di file che già mantiene, e non sbaglia praticamente mai.
L'avviso di sicurezza non è una formula
Il README contiene un avvertimento che merita di essere citato invece che parafrasato: snapshot, letture degli appunti, screenshot, output dei comandi e artefatti di debug possono contenere contenuti privati del desktop, e vanno tenuti fuori dai log pubblici e dagli upload.
È un pericolo reale e nuovo. Un agente a screenshot perde pixel. Un agente ad albero perde testo strutturato, molto più facile da indicizzare, da cercare e da commettere per sbaglio. Se registri le traiettorie dell'agente per fare debug, stai registrando quello che c'era sullo schermo in quel momento, in un formato che un grep trova.
La parte che invecchierà bene
Vercel Labs ne ha già rilasciati due: agent-browser per il web, agent-desktop per le applicazioni locali, entrambi in Rust, entrambi in tendenza nella stessa settimana. Il pattern che condividono è un rifiuto: non far fare al modello un lavoro che il sistema operativo ha già fatto.
L'idea utile è lì, più che in qualsiasi comando specifico. Un modello di visione che legge uno screenshot sta inferendo una struttura che esiste già in un albero di accessibilità, e paga quell'inferenza in latenza, token e tasso di errore. Leggere l'albero non costa quasi niente e restituisce qualcosa che l'agente può verificare.
Gli agenti che finiranno in produzione non saranno quelli che vedono meglio. Saranno quelli che hanno smesso di aver bisogno di guardare.
Articoli correlati
Un server, una streamer IA: dentro il codice che manda avanti una diretta notturna
open-yoki è il codice di produzione di una host IA che va in diretta ogni sera su Binance Square, con persona, voce e funzioni legate al denaro rimosse. headless Chrome disegna il frame, ffmpeg spinge RTMP, una cartella di Markdown decide umore e post.
Pinky lascia che un agent guidi il tuo telefono e tiene premuto Invia finché non tocchi Consenti
Pinky collega qualsiasi agent MCP a un iPhone o Android vero e impone l'approvazione nel proprio gateway invece che in un prompt. Le app bancarie sono invisibili, i campi password sono off limits e su Android 13 l'agent riceve un secondo schermo nascosto.
AnyModelBot mette un piccolo team di bot IA sulla tua macchina, chiavi comprese
AnyModelBot è un'app desktop che fa girare più bot insieme, ognuno con la sua persona, il suo modello, la sua cartella di lavoro e la sua memoria. Ci parli dentro l'app oppure da WeChat, Feishu, Telegram, Slack e Discord, e file, cronologia e chiavi API restano sul tuo disco.
SeedRealtime di ByteDance prende due frame al secondo e decide quando parlare
Doubao-Seed-Realtime-1.0 mette frame di camera, frame di schermo e voce in un'unica sessione full duplex, a non più di due frame al secondo. Le decisioni interessanti sono la frequenza dei frame, il parlato proattivo e la risposta di audit attiva di serie.