← Zurück zum Blog
Aica. 6 Min. Lesezeit

agent-desktop liest den Accessibility-Baum, nicht den Screenshot

Veröffentlicht 14. Nov. 2026
agent-desktop liest den Accessibility-Baum, nicht den Screenshot

Jeder Computer-Use-Agent, der mit Screenshots arbeitet, dreht dieselbe teure Schleife. Ein Bild vom Bildschirm machen. Ein Vision-Modell fragen, wo der Button liegt. Die Antwort in Pixelkoordinaten umrechnen. Klicken. Noch ein Bild machen, um zu sehen, ob etwas passiert ist.

Es funktioniert, so wie OCR funktioniert: beeindruckend, und nie verlässlich genug, um es einfach laufen zu lassen. Die Fehlerbilder sind alle Varianten desselben Themas: Ein Bild einer Benutzeroberfläche ist eine verlustbehaftete Darstellung einer Benutzeroberfläche.

agent-desktop, veröffentlicht von Vercel Labs und bei rund 23.300 Sternen, davon etwa 5.400 in der letzten Woche, nimmt den anderen Weg. Es schaut nicht auf den Bildschirm. Es liest den Accessibility-Baum der Zielanwendung und gibt ihn als JSON zurück, mit einer Referenz für jedes Element, auf dem der Agent handeln kann. Der Agent klickt oder tippt auf eine Referenz, liest die Oberfläche erneut, um das Ergebnis zu prüfen, und wiederholt das.

Über einer dunklen mechanischen Tastatur schweben mehrere durchscheinende Glasrechtecke in leicht versetzten Schichten.

Die Schleife lebt in Ihrem Agenten. Das Binary enthält kein Modell.

Installation und erster Kontakt

Das Paket wird global mit npm installiert:

npm install -g agent-desktop
agent-desktop status

`status` meldet Plattform, Berechtigungen und unterstützte Oberflächen. Das ist der richtige erste Befehl, weil Computer Use viel häufiger am Berechtigungsschritt scheitert als an der Logik. Unter macOS ist der nächste Befehl `agent-desktop permissions --guide`, der durch die Freigabe für Bedienungshilfen führt. Homebrew funktioniert unter macOS und Linux ebenfalls. Bun, Yarn und pnpm installieren dasselbe Paket; native Binaries für x64 und ARM64 sind enthalten.

Die Schleife aus drei Befehlen sieht so aus:

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

Das Flag `-i` beschränkt den Snapshot auf interaktive Elemente. Der Klick verwendet eine Referenz aus genau diesem Snapshot. Der zweite Snapshot ist kein optionales Aufräumen. Er ist der Weg, auf dem Sie erfahren, ob der Klick getan hat, was Sie glauben.

Die Designentscheidungen, die zählen

Vier Entscheidungen in diesem Werkzeug lohnen sich, bevor Sie etwas darauf bauen.

Referenzen gehören zu ihrem Snapshot. Ein bloßes `@e8` wird mit `INVALID_ARGS` abgelehnt. Ändert sich die Oberfläche zwischen Beobachtung und Aktion, liefert die Aktion `STALE_REF` oder `AMBIGUOUS_TARGET`, und die richtige Antwort ist, einen neuen Snapshot zu machen und dessen Referenzen zu verwenden. Das ist strenger als die meisten Automatisierungswerkzeuge und beseitigt eine ganze Klasse stiller Fehlklicks.

Dichte Anwendungen bekommen einen zweistufigen Weg. Für etwas wie Slack ist der dokumentierte Ansatz `snapshot --skeleton --app Slack -i --compact`, um die Anwendung zu kartieren, dann `snapshot --root @s8f3k2p9:e3 -i --compact`, um in einen Bereich einzusteigen. Ohne das ist ein vollständiger Baum einer komplexen App sehr viel JSON für einen Agenten.

Standardmäßig läuft es ohne Oberfläche. Aktionen per Referenz gehen über die Accessibility-API, ohne den Zeiger zu bewegen oder den Fokus zu stehlen, die Maschine bleibt also benutzbar, während der Agent arbeitet. Das globale Flag `--headed` schaltet auf physische Eingabe um. Das wollen Sie, wenn die Anwendung auf echte Ereignisse prüft, und sonst nicht.

Geheimnisse können aus den Prozessargumenten draußen bleiben. `type`, `set-value` und `clipboard-set` akzeptieren `--stdin` für Text aus einer Pipe. Da Kommandozeilenargumente in der Prozessliste sichtbar sind, ist das der Unterschied zwischen einem Passwort, das in der Ausgabe von `ps` auftaucht, und einem, das es nicht tut. Die Empfehlung im README lautet, Schritte mit Geheimnissen als eigene Befehle auszuführen, weil gebündelter JSON-Text in der Argumentliste wieder auftaucht.

Es gibt eine PowerShell-Fußnote, die jemandem eine Stunde spart: Setzen Sie jede Referenz in Anführungszeichen, denn ein bloßes `@token` ist der Splatting-Operator.

Was die Plattformschicht wirklich ist

Unter dem CLI liegt eine C-Bibliothek, und unter beiden liegt derselbe Kern. Jedes Binary ist für ein Betriebssystem kompiliert und spricht mit dessen Accessibility-API: AX API unter macOS, UI Automation unter Windows, AT-SPI unter Linux. Der Kern erreicht das System nur über ein Trait `PlatformAdapter`, weshalb eine Codebasis einen einzigen JSON-Umschlag über drei sehr unterschiedliche Accessibility-Modelle legen kann.

Diese Architektur erklärt auch die Obergrenze des Werkzeugs. Es kann nur auf das wirken, was der Accessibility-Baum freilegt. Anwendungen, die ihre Oberfläche selbst auf ein Canvas zeichnen und nichts freilegen, bleiben unsichtbar oder fast unsichtbar, so gut der Adapter auch sein mag. Screenshot-basierte Agenten decken diese Fälle ab. Referenzbasierte Agenten können das nicht. Der Tausch lautet Genauigkeit bei gut gebauten Apps gegen Abdeckung schlecht gebauter.

Ein durchgerechneter Vergleich

Nehmen Sie eine kleine Aufgabe, die Screenshot-Agenten schlecht lösen: zwölf Dateien in einem Dateimanager umbenennen.

Ein Screenshot-Agent schaut auf das Fenster, findet zwölf Dateinamen und erzeugt zwölf Koordinatenpaare. Er klickt das erste an, wählt den Text aus, tippt einen neuen Namen, drückt Enter und wartet, bis die Liste neu sortiert ist. Jede weitere Koordinate ist jetzt veraltet, weil sich die Reihenfolge geändert hat. Der Agent muss nach jeder Umbenennung neu beobachten, also zwölf Vision-Aufrufe und zwölf Gelegenheiten, die falsche Zeile zu treffen.

Der referenzbasierte Ansatz beobachtet einmal. Der Snapshot liefert den Baum des Fensters mit einer Referenz pro Zeile, dazu eine Snapshot-ID. Jede Umbenennung ist eine Aktion auf einer bestimmten Referenz, und nach jeder Aktion liest der Agent den Baum erneut, um zu bestätigen, dass der neue Name erschienen ist. Sortiert die Liste neu, werden die Referenzen des ursprünglichen Snapshots ungültig, und das Werkzeug sagt es. Genau das ist das gewünschte Verhalten: ein schneller, ausdrücklicher Fehlschlag statt einer stillen Aktion auf der falschen Datei.

Der Unterschied in der Zuverlässigkeit kommt daher, wo die Struktur berechnet wird. Im ersten Fall rekonstruiert ein Modell eine Dateiliste aus Pixeln und liegt manchmal falsch. Im zweiten Fall meldet das Betriebssystem die Dateiliste, die es ohnehin führt, und liegt so gut wie nie falsch.

Der Sicherheitshinweis ist keine Floskel

Im README steht eine Warnung, die man zitieren statt umschreiben sollte: Snapshots, Zwischenablage-Lesevorgänge, Screenshots, Befehlsausgaben und Debug-Artefakte können private Desktop-Inhalte enthalten und sollten aus öffentlichen Logs und Uploads herausbleiben.

Das ist eine echte Gefahr, und eine neue. Ein Screenshot-Agent verliert Pixel. Ein baumbasierter Agent verliert strukturierten Text, und der lässt sich viel leichter indizieren, durchsuchen und versehentlich committen. Wer Agentenverläufe zum Debuggen protokolliert, protokolliert das, was gerade auf dem Bildschirm war, in einem Format, das ein grep findet.

Der Teil, der gut altern wird

Vercel Labs hat inzwischen zwei davon ausgeliefert: agent-browser für das Web, agent-desktop für lokale Anwendungen, beide in Rust, beide in derselben Woche im Trend. Das Muster, das sie teilen, ist eine Weigerung: das Modell keine Arbeit machen lassen, die das Betriebssystem schon erledigt hat.

Darin liegt die nützliche Idee, mehr als in jedem einzelnen Befehl. Ein Vision-Modell, das einen Screenshot liest, leitet eine Struktur ab, die im Accessibility-Baum bereits existiert, und bezahlt diese Ableitung mit Latenz, Tokens und Fehlerquote. Den Baum zu lesen kostet fast nichts und liefert etwas, das der Agent prüfen kann.

Die Agenten, die in Produktion landen, werden nicht die mit dem besten Sehvermögen sein. Es werden die sein, die aufhören konnten, hinzusehen.

Verwandte Artikel