← Voltar ao blog
Aicerca de 7 min de leitura

agent-desktop lê a árvore de acessibilidade, não o screenshot

Publicado 14 de nov. de 2026
agent-desktop lê a árvore de acessibilidade, não o screenshot

Todo agente de computer use que trabalha com screenshots roda o mesmo ciclo caro. Tirar uma foto da tela. Perguntar a um modelo de visão onde está o botão. Converter a resposta em coordenadas de pixel. Clicar. Tirar outra foto para descobrir se alguma coisa aconteceu.

Funciona, no mesmo sentido em que o OCR funciona: de forma impressionante, e nunca confiável o bastante para você deixar rodando sozinho. Os modos de falha são variações de um mesmo tema: a foto de uma interface é uma representação com perda de uma interface.

O agent-desktop, lançado pela Vercel Labs e com cerca de 23.300 estrelas, sendo umas 5.400 na última semana, segue o outro caminho. Ele não olha para a tela. Lê a árvore de acessibilidade do aplicativo alvo e devolve isso como JSON, com uma referência para cada elemento sobre o qual o agente pode agir. O agente clica ou digita em uma referência, lê a interface de novo para conferir o resultado, e repete.

Sobre um teclado mecânico escuro flutuam vários retângulos de vidro translúcido, empilhados em camadas levemente deslocadas.

O ciclo mora no seu agente. O binário não contém nenhum modelo.

Instalação e primeiro contato

O pacote é uma instalação global de npm:

npm install -g agent-desktop
agent-desktop status

O `status` informa plataforma, permissões e superfícies suportadas. É o primeiro comando certo, porque o computer use trava na etapa de permissão muito mais vezes do que na de lógica. No macOS o próximo comando é `agent-desktop permissions --guide`, que conduz pela concessão de acessibilidade. O Homebrew também funciona no macOS e no Linux. Bun, Yarn e pnpm instalam o mesmo pacote; os binários nativos para x64 e ARM64 vêm incluídos.

O ciclo de três comandos é assim:

agent-desktop snapshot --app Finder -i
agent-desktop click @s8f3k2p9:e8
agent-desktop snapshot --app Finder -i

A opção `-i` limita o snapshot aos elementos interativos. O clique usa uma referência daquele snapshot específico. O segundo snapshot não é manutenção opcional: é assim que você descobre se o clique fez o que você acha.

As decisões de projeto que importam

Quatro escolhas nesta ferramenta valem ser entendidas antes de você construir qualquer coisa em cima dela.

Referências pertencem ao seu snapshot. Um `@e8` sozinho é rejeitado com `INVALID_ARGS`. Se a interface mudar entre a observação e a ação, a ação devolve `STALE_REF` ou `AMBIGUOUS_TARGET`, e a resposta correta é tirar um novo snapshot e usar as referências dele. É mais rígido do que a maioria das ferramentas de automação, e elimina uma classe inteira de cliques errados silenciosos.

Aplicativos densos têm um caminho de inspeção em duas etapas. Para algo como o Slack, a abordagem documentada é `snapshot --skeleton --app Slack -i --compact` para mapear o aplicativo, e depois `snapshot --root @s8f3k2p9:e3 -i --compact` para descer em uma região. Sem isso, a árvore completa de um app complexo é JSON demais para um agente carregar.

Por padrão ele é headless. As ações por referência passam pela API de acessibilidade sem mover o ponteiro nem roubar o foco, então a máquina continua utilizável enquanto o agente trabalha. A opção global `--headed` troca para entrada física, que você quer quando o aplicativo verifica eventos reais, e não em outro caso.

Segredos podem ficar fora dos argumentos do processo. `type`, `set-value` e `clipboard-set` aceitam `--stdin` para texto vindo de um pipe. Como argumentos de linha de comando são visíveis na lista de processos, essa é a diferença entre uma senha que aparece na saída do `ps` e uma que não aparece. O conselho do README é rodar os passos com segredos como comandos separados, porque o texto JSON enviado em lote reaparece na lista de argumentos.

Há uma nota de rodapé sobre PowerShell que vai economizar uma hora de alguém: coloque aspas em toda referência, porque um `@token` solto é o operador de splatting.

O que a camada de plataforma realmente é

Abaixo do CLI existe uma biblioteca em C, e abaixo dos dois está o mesmo núcleo. Cada binário é compilado para um sistema operacional e conversa com a API de acessibilidade daquele sistema: AX API no macOS, UI Automation no Windows, AT-SPI no Linux. O núcleo chega ao sistema apenas por um trait `PlatformAdapter`, e é por isso que uma única base de código consegue apresentar o mesmo envelope JSON sobre três modelos de acessibilidade bem diferentes.

Essa arquitetura também explica o teto da ferramenta. Ela só pode agir sobre o que a árvore de acessibilidade expõe. Aplicativos que desenham a própria interface em um canvas e não expõem nada ficam invisíveis ou quase, por melhor que seja o adaptador. Agentes baseados em screenshot dão conta desses casos. Agentes baseados em referência não. A troca é precisão em apps bem feitos contra cobertura dos mal feitos.

Uma comparação concreta

Pense numa tarefa pequena que agentes de screenshot resolvem mal: renomear doze arquivos em um gerenciador de arquivos do desktop.

Um agente de screenshot olha a janela, identifica doze rótulos de nome de arquivo e produz doze pares de coordenadas. Clica no primeiro, seleciona o texto, digita um nome novo, aperta enter e espera a lista se reordenar. Toda coordenada seguinte agora está vencida, porque a ordem da lista mudou. O agente precisa observar de novo depois de cada renomeação, o que dá doze chamadas de visão e doze chances de clicar na linha errada.

A abordagem por referências observa uma vez. O snapshot devolve a árvore da janela com uma referência por linha, mais um id de snapshot. Cada renomeação é uma ação sobre uma referência específica, e depois de cada ação o agente relê a árvore para confirmar que o nome novo apareceu. Se a lista se reordenar, as referências do snapshot original vencem e a ferramenta avisa, que é exatamente o comportamento que você quer: uma falha rápida e explícita em vez de uma ação silenciosa no arquivo errado.

A diferença de confiabilidade vem de onde a estrutura é calculada. No primeiro caso, um modelo reconstrói uma lista de arquivos a partir de pixels e erra algumas vezes. No segundo, o sistema operacional informa a lista de arquivos que ele já mantém, e não erra praticamente nunca.

O aviso de segurança não é enchimento

O README traz um alerta que merece ser citado em vez de parafraseado: snapshots, leituras de área de transferência, screenshots, saída de comandos e artefatos de depuração podem conter conteúdo privado do desktop, e devem ficar fora de logs públicos e de uploads.

É um perigo real e novo. Um agente de screenshot vaza pixels. Um agente de árvore vaza texto estruturado, muito mais fácil de indexar, de buscar e de commitar por acidente. Se você registra trajetórias do agente para depurar, está registrando o que estava na tela naquele momento, num formato que um grep encontra.

A parte que vai envelhecer bem

A Vercel Labs já entregou dois desses: agent-browser para a web, agent-desktop para aplicativos locais, os dois em Rust, os dois em alta na mesma semana. O padrão que eles compartilham é uma recusa: não fazer o modelo executar um trabalho que o sistema operacional já fez.

A ideia útil está aí, mais do que em qualquer comando específico. Um modelo de visão lendo um screenshot está inferindo uma estrutura que já existe numa árvore de acessibilidade, e paga por essa inferência em latência, tokens e taxa de erro. Ler a árvore custa quase nada e devolve algo que o agente pode verificar.

Os agentes que vão parar em produção não serão os que enxergam melhor. Serão os que deixaram de precisar olhar.

Artigos relacionados