agent-desktop: jak AI ovládá počítač přes strom přístupnosti

agent-desktop je příkazová řádka a knihovna v Rustu, přes kterou AI agent čte a ovládá nativní aplikace na macOS, Windows a Linuxu. Nekliká podle souřadnic na obrazovce. Pracuje s prvky, které operační systém zpřístupňuje čtečkám obrazovky, a výsledek každé akce ověří dalším čtením rozhraní.

Co je agent-desktop a jak AI ovládá počítač?

agent-desktop je nástroj pro ovládání počítače AI agentem, který místo obrazu obrazovky čte strukturu rozhraní z accessibility API operačního systému. Agent proto ví, co je tlačítko, jak se jmenuje a co s ním jde udělat.

Projekt vydala skupina Vercel Labs. Repozitář vercel-labs/agent-desktop vznikl 19. února 2026, k 2. listopadu 2026 má 7 778 hvězd a 557 forků a vychází pod licencí Apache License 2.0. Hlavním jazykem je Rust. Kromě CLI každý release obsahuje i C knihovnu libagent_desktop_ffi, takže ji lze volat přímo z jiného programu.

Rozdíl proti klasickému computer use je v tom, co agent „vidí“. Anthropic Computer Use posílá modelu obraz obrazovky a model odpovídá akcemi typu screenshot, left_click nebo type na souřadnicích. Nástroj od Vercel Labs modelu předá textový popis rozhraní a akce míří na konkrétní prvek. Okno posunuté o kus vedle proto kliknutí nerozbije.

Princip agent-desktop popisujeme podle README projektu, u ostatních nástrojů uvádíme jejich obecně známý způsob práce.

Jak funguje ovládání přes strom přístupnosti

Nástroj má pro každý systém samostatný adaptér nad nativním rozhraním: na macOS je to Accessibility API (AX), na Windows UI Automation a na Linuxu AT-SPI. Výstup je na všech třech systémech stejný, agent se proto nemusí učit tři různá API.

Co přesně agent dostane

Příkaz snapshot vrátí JSON obálku se stromem prvků. Každý ovladatelný uzel má roli (role), název (name), referenci (ref_id) a seznam akcí (available_actions). Ukázka níže je zkrácený snapshot Finderu z dokumentace. Pole ref_count říká, že okno obsahuje 59 prvků s referencí, a complete potvrzuje, že strom je úplný.

{
  "version": "2.5",
  "ok": true,
  "command": "snapshot",
  "data": {
    "app": "Finder",
    "window": { "id": "w-204749", "title": "Downloads" },
    "snapshot_id": "s8f3k2p9",
    "ref_count": 59,
    "complete": true,
    "tree": {
      "role": "window",
      "name": "Downloads",
      "children": [
        { "role": "treeitem", "name": "Documents", "ref_id": "@s8f3k2p9:e8", "available_actions": ["Click"] }
      ]
    }
  }
}

Reference @s8f3k2p9:e8 se skládá z ID snapshotu a ID prvku. Díky tomu se stará reference nemůže potichu namapovat na jiný prvek ve změněném rozhraní.

U hustých aplikací by celý strom zahltil kontext modelu. Pro ně nástroj nabízí dvoufázový postup:

• snapshot --skeleton --app Slack -i --compact vrátí jen kostru aplikace s hlavními oblastmi,
• snapshot --root @s8f3k2p9:e3 -i --compact pak rozbalí jedinou vybranou oblast,
• přepínač -i omezí výstup na interaktivní prvky a --compact zkrátí zápis.

Textový strom je obvykle menší než obrázek a k jeho čtení stačí běžný jazykový model bez vizuálních schopností. Kolik tokenů se tím ušetří, závisí na konkrétní aplikaci a hloubce stromu, proto úsporu změřte na cílové aplikaci.

Headless a headed režim

Výchozí je headless režim. Akce na ref jdou přes accessibility API, kurzor se nepohne a aplikace nepřevezme fokus, takže uživatel může u počítače dál pracovat. Globální přepínač --headed povolí fyzický vstup myší a klávesnicí. Ten je nutný například pro tažení nebo pro aplikace, které na sémantické akce nereagují.

Cyklus snapshot, akce a ověření

Každá interakce má tři kroky: přečíst rozhraní, provést akci na referenci z tohoto čtení a rozhraní přečíst znovu. Teprve druhý snapshot potvrdí, že akce opravdu proběhla.

V příkazové řádce celý cyklus vypadá takto:

# Pozorování: jen interaktivní prvky, každý s ref
agent-desktop snapshot --app Finder -i
# Akce: ref musí pocházet z posledního snapshotu
agent-desktop click @s8f3k2p9:e8
# Ověření: nový snapshot ukáže skutečný stav UI
agent-desktop snapshot --app Finder -i
# Více oken vrátí AMBIGUOUS_TARGET; id okna je v error.details
agent-desktop snapshot --app Finder -i --window-id w-204749

Pravidla pro chyby jsou přísná, ale pro agenta srozumitelná. Ref patří ke svému snapshotu, takže holé @e8 nástroj odmítne s kódem INVALID_ARGS. Pokud se rozhraní mezi snapshotem a akcí změní, přijde STALE_REF nebo AMBIGUOUS_TARGET a jediná správná reakce je nový snapshot. Když má aplikace otevřených víc oken, vrátí snapshot v error.details seznam kandidátů a agent jedno vybere přes --window-id.

Každý příkaz vypíše jednu obálku s polem ok a buď data, nebo error. Chyba nese code, disposition a obvykle i suggestion. Akci lze opakovat jen tehdy, když má error.disposition.retry hodnotu safe. Tuto podmínku doporučujeme v agentovi vynutit kódem, ne jen promptem.

Celá smyčka zůstává v agentovi. Nástroj nic neplánuje, nerozhoduje o dalším kroku a sám nic neopakuje. Je to ovladač, logiku dodává model a kód kolem něj.

Instalace a podporované systémy

Nástroj se instaluje z npm jedním příkazem a běží na macOS, Windows i Linuxu. Balík obsahuje nativní binárky pro x64 i ARM64.

npm install -g agent-desktop
agent-desktop version

Stejný balík nainstaluje i Bun, Yarn nebo pnpm. Kdo nechce JavaScriptový spouštěč, stáhne nativní archiv z GitHub Releases a pomocný program nechá vedle spustitelného souboru. Poslední release v1.0.2 vyšel 30. října 2026.

Tabulka vychází z přehledu podpory platforem v repozitáři. Na Linuxu je podpora užší a závisí na tom, jestli běží X11, nebo Wayland.

Zapojení do vlastního agenta

Nástroj nabízí 60 názvů příkazů, z nichž 56 je funkčních. Pokrývají pozorování, akce na ref, okna, notifikace, schránku, čekání a dávkové spouštění.

Pro agenta je důležité, že binárka nese vlastní instrukce odpovídající své verzi:

# Smyčka, refy, ověřování a pravidla pro opakování
agent-desktop skills get desktop
# Rozdíly na systému, kde nástroj právě běží
agent-desktop skills get platform
# Vstupní body C knihovny, vlastnictví paměti, vlákna
agent-desktop skills get ffi

Jednodušší cesta je volat CLI z agenta jako nástroj a parsovat JSON. Druhá cesta je C knihovna libagent_desktop_ffi, kterou program načte do svého procesu a nemusí pro každý příkaz spouštět nový proces. Volat ji lze například z Pythonu přes ctypes.

Samotný ovladač je jen jedna vrstva. Pro firemní nasazení je potřeba dořešit orchestraci, oprávnění, logování a předání úloh člověku. Tomu se věnujeme v rámci služby AI agenti a automatizace.

Jaká oprávnění vyžaduje a jaká jsou rizika?

Na macOS potřebuje oprávnění Accessibility, na Windows obvykle žádné zvláštní a na Linuxu běžící grafickou relaci s AT-SPI. Hlavní riziko nespočívá v nástroji, ale v rozsahu toho, co agent smí dělat.

macOS, Windows a Linux

Na macOS se oprávnění Accessibility uděluje aplikaci, která nástroj spouští, tedy Terminalu, iTerm2 nebo VS Code. Když agent poběží z jiného terminálu, potřebuje ten terminál vlastní oprávnění. Průvodce nastavením spustí agent-desktop permissions --guide. Pro screenshoty je navíc nutné Screen Recording a pro otevírání Notification Center oprávnění Automation.

Na Windows nástroj podle README nepotřebuje žádné povolení pro aplikace se stejnou úrovní integrity, jakou má terminál. Aplikaci spuštěnou jako správce dokáže číst, ale vstup do ní pošle jen agent, který také běží se zvýšenými právy. Spouštět agenta jako správce proto doporučujeme jen výjimečně.

Na Linuxu stačí uživatelská grafická relace s balíkem at-spi2-core.

Druhé riziko je méně viditelné. Reference zaručují, že agent klikne na správné tlačítko, ale nástroj nehlídá, jestli ho kliknout má. Špatně instruovaný nebo zmanipulovaný agent tedy pošle zprávu, smaže soubor nebo změní nastavení stejně přesně jako dobře instruovaný. Volitelný pomocník pro popis obrazovky navíc posílá data nakonfigurovanému poskytovateli modelu, takže opouštějí počítač.

Zavedení agentních nástrojů do vývojového týmu je stejně tak otázka pravidel jako techniky. Postup a hranice pomáháme nastavit v rámci AI transformace pro vývojáře.

Kde strom přístupnosti selhává

Platí jednoduché pravidlo: co aplikace do accessibility API nevystaví, agent nevidí. Kvalita výsledku tedy závisí na tom, jak pečlivě autoři aplikace přístupnost implementovali.

Typické slabé oblasti jsou tyto:

• hry a herní enginy, které kreslí vlastní scénu přímo na GPU,
• aplikace postavené na canvasu, kde je celé plátno jediným prvkem,
• vlastní renderovací toolkity, které nepoužívají nativní ovládací prvky,
• vzdálené plochy a streamované aplikace, kde systém vidí jen obrazové okno,
• dynamická rozhraní, ve kterých refy zastarávají rychleji, než agent stihne jednat.

Electron a Chromium

Electron a Chromium aplikace mají webový obsah ve vlastním rendereru a jeho strom přístupnosti se zapíná až na požádání. Nástroj tuto vrstvu aktivuje sám, když je to potřeba. Pro webový obsah dokáže také otevřít DevTools port, ke kterému se připojí sesterský nástroj agent-browser. Nativní rámeček okna tak obslouží accessibility API a obsah stránky protokol prohlížeče.

Funguje to ale aplikaci od aplikace. V issue trackeru projektu je zdokumentováno, že snapshot prohlížeče Arc na macOS selhával s chybou „Renderer did not enable accessibility activation“, zatímco Chrome fungoval. Pokud plánujete automatizaci desktopu nad konkrétní Electron aplikací, ověřte si nejdřív jediný snapshot.

Otevřené chyby ukazují, že ani nativní aplikace nejsou bez problémů. Issue z 2. listopadu 2026 popisuje, že snapshot nevrací tělo dokumentu ve Wordu, takže prázdný a plný dokument vypadají stejně. Jiná otevřená issue hlásí, že list-apps a list-windows na Windows 10 minou část oken nejvyšší úrovně.

U dynamických rozhraní pomáhá příkaz wait, vyšší --max-depth a hlavně nový snapshot po každé změně. Agent, který si refy ukládá napříč kroky, bude narážet na STALE_REF častěji než agent, který před každou akcí čte rozhraní znovu.

Kdy zvolit screenshoty a kdy strom přístupnosti

Strom přístupnosti zvolte jako výchozí u nativních aplikací s dobrou přístupností. Screenshoty nechte tam, kde strom chybí nebo lže.

Nejrozumnější architekturou je podle nás hybrid: strom přístupnosti jako první volba a obraz jako záloha. Nástroj k tomu nabízí vlastní příkaz screenshot a nepovinného pomocníka, který obrazovku popíše přes model. Agent tedy může přepnout na obraz, aniž by musel měnit nástroj.

Výrobce neuvádí obecný násobek zrychlení ani úspory proti screenshotovému přístupu. Doporučujeme proto krátký test na vaší cílové aplikaci. Pusťte stejnou úlohu oběma způsoby a porovnejte úspěšnost, počet kroků a spotřebu tokenů. Teprve pak má smysl rozhodnout, který přístup postavit do produkce.

Časté otázky

Je agent-desktop zdarma?

Ano, agent-desktop je open-source projekt pod licencí Apache License 2.0 a instaluje se zdarma z npm. Licence povoluje komerční použití, úpravy i začlenění do vlastních produktů, pokud zachováte licenční a autorská upozornění. Platíte jen za jazykový model, který agenta řídí, a případně za poskytovatele modelu u volitelného pomocníka pro popis obrazovky.

Funguje agent-desktop na Linuxu a Windows, nebo jen na macOS?

Funguje na všech třech systémech, ale ne všude ve stejném rozsahu. macOS a Windows mají plnou podporu čtení stromu, akcí, myši, screenshotů i správy oken. Linux čte strom přes AT-SPI. Ovládání myši, screenshoty a správa oken jsou tam omezené podle toho, jestli relace běží na X11, nebo na Waylandu.

Potřebuje agent-desktop vizuální model?

Pro základní práci ne. Snapshot je textový JSON s rolemi, názvy a referencemi prvků, takže ho zpracuje běžný jazykový model. Vizuální model se hodí jen jako záloha pro aplikace bez použitelného stromu přístupnosti. Nástroj pro tyto případy nabízí příkaz screenshot a nepovinného pomocníka, který obrazovku popíše přes nakonfigurovaný model.

Dá se agent-desktop použít z vlastního kódu, ne jen z příkazové řádky?

Ano. Každý release obsahuje C knihovnu libagent_desktop_ffi pro macOS, Windows i Linux. Program ji načte do vlastního procesu a nemusí pro každý příkaz spouštět CLI. Knihovnu lze volat z jakéhokoli jazyka s podporou C rozhraní, například z Pythonu přes ctypes. Pravidla pro paměť a vlákna vypíše příkaz agent-desktop skills get ffi.

Jak se agent-desktop liší od agent-browser?

agent-browser ovládá webový obsah přes protokol prohlížeče, agent-desktop ovládá nativní aplikace přes accessibility API systému. Oba nástroje se doplňují. U Chromium a Electron aplikací může agent-desktop otevřít DevTools port, ke kterému se agent-browser připojí. Nativní okno pak řeší jeden nástroj a webový obsah uvnitř druhý.