← 블로그로
Ai약 11 분 읽기

agent-desktop은 스크린샷이 아니라 접근성 트리를 읽어요

게시일 2026년 11월 14일
agent-desktop은 스크린샷이 아니라 접근성 트리를 읽어요

스크린샷으로 움직이는 컴퓨터 사용 에이전트는 모두 같은 비싼 루프를 돌려요. 화면을 찍어요. 버튼이 어디 있는지 비전 모델에 물어봐요. 답을 픽셀 좌표로 바꿔요. 클릭해요. 뭔가 일어났는지 확인하려고 또 찍어요.

됩니다. OCR이 되는 것과 같은 의미로요. 인상적이지만, 손을 떼도 될 만큼 믿을 만했던 적은 없어요. 실패하는 방식은 모두 같은 이야기로 모여요. 사용자 인터페이스의 사진은 사용자 인터페이스의 손실 압축된 표현이라는 것.

Vercel Labs가 공개한 agent-desktop은 다른 길을 가요. 지금 약 23,300 스타이고 지난주에 약 5,400개가 늘었어요. 화면을 보지 않아요. 대상 앱의 접근성 트리를 읽어 JSON으로 돌려주고, 에이전트가 조작할 수 있는 모든 요소에 참조를 붙여요. 에이전트는 그 참조에 클릭이나 입력을 하고, 결과를 확인하려고 UI를 다시 읽고, 이 과정을 반복해요.

어두운 색 기계식 키보드 위로 반투명한 유리 사각형이 여러 층 떠 있고, 층마다 조금씩 어긋나 있어요.

루프는 에이전트 안에 살아요. 바이너리에는 모델이 없어요.

설치와 첫 접촉

패키지는 npm 전역 설치예요.

npm install -g agent-desktop
agent-desktop status

`status`는 플랫폼과 권한, 지원하는 서피스를 알려줘요. 첫 명령으로 이걸 쓰는 게 맞아요. 컴퓨터 사용은 로직 단계보다 권한 단계에서 훨씬 자주 막히거든요. macOS에서 다음 명령은 `agent-desktop permissions --guide`이고, 손잡고 접근성 권한 승인을 안내해 줘요. Homebrew도 macOS와 Linux에서 됩니다. Bun, Yarn, pnpm으로도 같은 패키지가 설치돼요. x64와 ARM64용 네이티브 바이너리가 함께 들어 있어요.

세 명령짜리 루프는 이렇게 생겼어요.

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

`-i` 플래그는 스냅숏을 상호작용 가능한 요소로 좁혀요. 클릭은 그 특정 스냅숏에서 가져온 참조로 해요. 두 번째 스냅숏은 없어도 되는 뒤처리가 아니에요. 클릭이 내가 생각한 대로 동작했는지 알려면 이게 필요해요.

중요한 설계 결정들

이 도구 위에 뭔가를 만들기 전에 알아 둘 만한 선택이 네 가지 있어요.

참조는 자기가 속한 스냅숏에 묶여 있어요. 맨 `@e8`은 `INVALID_ARGS`로 거부돼요. 관찰과 동작 사이에 인터페이스가 바뀌면 동작은 `STALE_REF`나 `AMBIGUOUS_TARGET`을 돌려주고, 맞는 대응은 새 스냅숏을 떠서 그 참조를 쓰는 거예요. 대부분의 자동화 도구보다 엄격하고, 그만큼 조용한 오클릭 한 종류를 통째로 없애요.

요소가 빽빽한 앱에는 두 단계로 훑는 길이 있어요. Slack 같은 앱이라면 문서에 나온 방식은 먼저 `snapshot --skeleton --app Slack -i --compact`로 앱 전체를 지도로 만들고, 다음에 `snapshot --root @s8f3k2p9:e3 -i --compact`로 한 영역을 파고드는 거예요. 이게 없으면 복잡한 앱의 트리 전체는 에이전트가 들고 있기엔 너무 많은 JSON이에요.

기본은 헤드리스예요. 참조 기반 동작은 접근성 API를 지나가고 포인터를 움직이지 않고 포커스도 빼앗지 않아서, 에이전트가 일하는 동안에도 기계를 쓸 수 있어요. 전역 `--headed` 플래그를 주면 실제 입력으로 바뀌어요. 앱이 진짜 이벤트를 검사할 때는 필요하고, 그 외에는 필요 없어요.

비밀 값은 프로세스 인자 밖에 둘 수 있어요. `type`, `set-value`, `clipboard-set`은 `--stdin`을 받아서 파이프로 텍스트를 읽어요. 명령줄 인자는 프로세스 목록에서 보이니까, 이건 비밀번호가 `ps` 출력에 나타나느냐 아니냐의 차이예요. README의 조언은 비밀이 들어간 단계를 별도 명령으로 나누라는 거예요. 몰아서 넘긴 JSON 텍스트는 인자 목록에 다시 나타나니까요.

PowerShell에 관한 각주가 하나 있는데, 누군가의 한 시간을 아껴 줄 거예요. 모든 참조에 따옴표를 붙이세요. 맨 `@token`은 splatting 연산자예요.

플랫폼 계층의 실체

CLI 아래에는 C 라이브러리가 있고, 둘 아래에는 같은 코어가 있어요. 각 바이너리는 운영체제 하나를 위해 컴파일되고 그 시스템의 접근성 API와 이야기해요. macOS에서는 AX API, Windows에서는 UI Automation, Linux에서는 AT-SPI예요. 코어가 OS에 닿는 통로는 `PlatformAdapter` 트레이트 하나뿐이라, 코드베이스 하나가 아주 다른 세 접근성 모델 위에서 같은 JSON 봉투를 내놓을 수 있어요.

이 구조는 도구의 한계도 설명해요. 접근성 트리가 드러내는 것에만 작용할 수 있어요. 자기 인터페이스를 캔버스에 직접 그리고 아무것도 드러내지 않는 앱은 어댑터가 아무리 좋아도 보이지 않거나 거의 보이지 않아요. 스크린샷 기반 에이전트는 그런 앱을 다뤄요. 참조 기반 에이전트는 못 해요. 잘 만든 앱에서의 정확도와 못 만든 앱에 대한 커버리지를 맞바꾸는 거예요.

구체적인 비교

스크린샷 에이전트가 서툴게 처리하는 작은 작업을 생각해 봐요. 데스크톱 파일 관리자에서 파일 열두 개 이름을 바꾸는 일이에요.

스크린샷 에이전트는 창을 보고 파일 이름 라벨 열두 개를 찾아 좌표 열두 쌍을 만들어요. 첫 번째를 클릭하고, 텍스트를 선택하고, 새 이름을 입력하고, Enter를 누르고, 목록이 다시 정렬되기를 기다려요. 이 시점에 나머지 좌표는 모두 낡았어요. 목록 순서가 바뀌었으니까요. 이름을 바꿀 때마다 다시 관찰해야 하고, 그건 비전 호출 열두 번, 엉뚱한 줄을 클릭할 기회 열두 번이에요.

참조 기반 방식은 한 번만 관찰해요. 스냅숏은 각 줄에 참조를 붙인 창 트리와 스냅숏 id를 돌려줘요. 이름 변경은 각각 특정 참조에 대한 동작이고, 동작마다 에이전트는 트리를 다시 읽어 새 이름이 나타났는지 확인해요. 목록이 다시 정렬되면 원래 스냅숏의 참조는 낡고, 도구가 그렇게 말해 줘요. 이게 바로 원하는 동작이에요. 잘못된 파일에 조용히 손대는 대신, 빠르고 분명한 실패가 와요.

신뢰성의 차이는 구조를 어디서 계산하느냐에서 와요. 앞의 경우 모델이 픽셀에서 파일 목록을 재구성하고, 가끔 틀려요. 뒤의 경우 운영체제가 원래 관리하고 있던 파일 목록을 보고하고, 거의 틀리지 않아요.

보안 경고는 상투적인 문구가 아니에요

README에는 그대로 인용할 만한 경고가 있어요. 스냅숏, 클립보드 읽기, 스크린샷, 명령 출력, 디버그 산출물에는 사적인 데스크톱 내용이 들어 있을 수 있으니 공개 로그와 업로드에서 멀리 두라는 것이에요.

이건 실제 위험이고 새로운 위험이에요. 스크린샷 기반 에이전트는 픽셀을 흘려요. 트리 기반 에이전트는 구조화된 텍스트를 흘리고, 이쪽은 색인도 검색도 실수로 커밋하는 일도 훨씬 쉽게 걸려요. 디버깅을 위해 에이전트 궤적을 기록한다면, 그때 화면에 있던 것을 기록하는 거예요. grep이 찾아낼 수 있는 형식으로요.

오래 살아남을 부분

Vercel Labs는 이런 도구를 벌써 두 개 내놨어요. 웹을 위한 agent-browser, 로컬 앱을 위한 agent-desktop이고, 둘 다 Rust로 만들었고 같은 주에 트렌드에 올랐어요. 둘이 공유하는 패턴은 운영체제가 이미 한 일을 모델에게 시키지 않는다는 거부예요.

여기서 쓸모 있는 생각은 그 한 가지이고, 어떤 개별 명령보다 중요해요. 스크린샷을 읽는 비전 모델은 접근성 트리에 이미 있는 구조를 추론하고 있고, 그 추론에 지연과 토큰과 오류율을 치르고 있어요. 트리를 읽는 데는 비용이 거의 들지 않고, 돌려받은 것은 에이전트가 검증할 수 있어요.

결국 프로덕션에 남는 에이전트는 눈이 가장 좋은 쪽이 아니에요. 볼 필요가 없어진 쪽이에요.

관련 글

서버 한 대, AI 스트리머 한 명: 야간 라이브를 돌리는 코드

open-yoki는 매일 밤 Binance Square에서 방송하는 AI 진행자의 프로덕션 코드로, 성격과 목소리, 돈에 닿는 기능은 걷어냈습니다. headless Chrome이 프레임을 그리고 ffmpeg이 RTMP를 밀며, Markdown 폴더가 그녀의 기분과 올릴 글을 정합니다.

Pinky는 agent에게 당신의 폰을 맡기고, 당신이 허용을 누를 때까지 전송 버튼을 붙잡고 있습니다

Pinky는 어떤 MCP agent든 실제 iPhone이나 Android 폰에 연결하고, 승인을 프롬프트가 아닌 자체 게이트웨이에서 강제합니다. 은행 앱은 보이지 않고 비밀번호 입력란은 손댈 수 없으며, Android 13에서는 agent가 숨겨진 두 번째 화면을 받습니다.

인터페이스의 AI 티를 잡아내고 9단계로 고치는 Claude skill

unslop은 Claude Code, Codex, Antigravity에서 도는 skill로, vibecoded 화면이 어디서 싸구려처럼 보이는지를 먼저 이름 붙여 줍니다. 제품에서 방향을 잡고 나면 디자이너가 redline review를 하듯 패스를 겹쳐 고칩니다. star는 19,413개이고, slop이 무엇인지에 대한 답도 분명합니다.

세계의 법을 git에 넣은 사람들, 이제 법조문도 blame할 수 있다

global-law는 각국 법령을 git 저장소로 보관하고, 커밋 하나가 특정 날짜에 시행된 법 하나에 대응한다. 조문에 log, blame, show, diff를 돌릴 수 있고, 어느 날 각국에서 시행 중이던 법을 확인하고, 코퍼스 전체를 MCP로 어시스턴트에 넘길 수 있다.