Vercel agent-desktop: 스크린샷 없는 AI 데스크톱 자동화
Vercel Labs가 AI 코딩 에이전트에게 데스크톱 앱 조작 권한을 주는 오픈소스 CLI, agent-desktop을 공개했습니다. macOS, Windows, Linux의 네이티브 앱을 읽고 조작할 수 있는데, 화면을 캡처하지 않고 운영체제의 접근성 트리를 읽는 방식입니다. 에이전트는 버튼, 입력란, 메뉴 목록을 JSON으로 받고 항목마다 붙은 ref ID를 지정해 클릭하거나 입력합니다. 비전 모델이 픽셀 좌표를 추측할 필요가 없습니다. 터미널에서 Claude Code, Codex, Cursor를 쓰고 있다면 그 에이전트가 브라우저 밖의 앱까지 다룰 수 있습니다.
핵심 요약
- agent-desktop은 Vercel Labs가 Apache-2.0 라이선스로 공개한 Rust CLI이자 C 라이브러리입니다. Chris Tate가 2026년 10월 31일 "agent-browser를 컴퓨터 전체로 넓힌 것"이라며 발표했습니다(X 게시물).
snapshot명령은 앱의 접근성 트리를 JSON으로 돌려주고 조작 가능한 요소마다 ref를 붙입니다. 에이전트는 ref로 클릭·입력·토글을 한 뒤 다시 스냅샷을 찍어 결과를 확인합니다.- 도구 안에는 LLM도, GUI도, 대화형 프롬프트도 없습니다. 관찰하고 행동하는 루프는 기존 코딩 에이전트가 맡습니다.
- 지원 환경은 macOS 13 이상, Windows 10 1809 이상, Ubuntu 24.04 이상입니다. 2026년 10월 27일 1.0.0에서 Linux 지원이 추가됐고 현재 최신판은 10월 30일 나온 1.0.2입니다.
- 접근성 정보를 내보내지 않는 UI는 볼 수 없고 웹 페이지는 agent-browser 몫입니다. 문서에 샌드박스 설명이 없으므로 가상머신과 테스트 데이터로 쓰는 편이 안전합니다.
agent-desktop은 어떤 도구인가
agent-desktop은 AI 에이전트가 셸에서 호출하는 데스크톱 자동화 도구입니다. GitHub README는 이를 "AI 에이전트를 위한 컴퓨터 유즈: OS 접근성 트리로 데스크톱 앱을 읽고 조작한다"고 소개합니다. 명령 하나가 JSON 응답 하나를 출력하고 끝나기 때문에, 셸 명령을 실행할 수 있는 에이전트라면 어떤 것이든 붙일 수 있습니다.
접근성 트리는 운영체제가 스크린 리더를 위해 이미 제공하는 UI 구조 정보입니다. 버튼, 입력란, 체크박스, 메뉴 항목마다 역할(role)과 이름이 있고 값이 들어 있는 경우도 많습니다. 공식 문서에 따르면 agent-desktop은 플랫폼별 네이티브 API로 이 트리를 읽습니다. macOS는 AX, Windows는 UI Automation, Linux는 AT-SPI입니다.
AGENTS.md는 이 프로젝트를 "에이전트가 아니라 도구"라고 못 박습니다. 관찰·행동 루프는 호출하는 에이전트 쪽에 있고 도구 자체는 모델을 내장하지 않습니다. 발표 이틀 뒤인 2026년 11월 2일 기준으로 저장소 스타는 약 7,100개, 포크는 519개입니다.
agent-desktop 작동 방식: 스냅샷, 실행, 확인
공식 퀵스타트는 루프 전체를 네 단계로 보여 줍니다. 앱 구조를 파악한 뒤 특정 영역으로 들어가 ref로 조작하고 결과를 확인하는 순서입니다.
- 구조 파악.
agent-desktop snapshot --app gnome-calculator --skeleton -i --compact는 복잡한 앱의 윤곽만 간추려 돌려줍니다. - 영역 확장. 윤곽에서 얻은 ref를
snapshot --root에 넘기면 해당 영역만 펼쳐 봅니다. - 조작.
agent-desktop click @s2txcl95uvubmn:e11은 해당 ref의 요소를 누릅니다. - 확인.
agent-desktop wait --element @s2txcl95uvubmn:e6 --predicate value --value 7은 계산기 표시값이 7이 될 때까지 기다립니다.
마지막 확인 단계는 일부러 넣은 것입니다. 문서는 명령이 성공했다고 해서 UI가 실제로 바뀌었다는 보장은 없다고 설명합니다. 설계 문서도 결과를 "전달 확인됨", "전달됐으나 미확인", "전달 안 됨"으로 나누고 코어가 무조건 성공 플래그를 붙이는 일은 없다고 밝힙니다.
ref는 스냅샷에 묶여 있다
모든 ref에는 그 ref를 만든 스냅샷의 ID가 들어 있습니다. @s2txcl95uvubmn:e11 같은 형태입니다. 스냅샷 ID 없이 @e8만 쓰면 INVALID_ARGS 오류가 납니다. 조작 직전에는 프로세스 ID, 역할, 경로, 텍스트, 위치 같은 저장된 근거로 요소를 다시 찾습니다. 일치하는 요소가 없으면 STALE_REF, 여러 개면 AMBIGUOUS_TARGET을 돌려줍니다. 그러면 에이전트는 스냅샷을 새로 찍어야 합니다. 데스크톱에서는 엉뚱한 버튼 하나가 메일 발송이나 파일 삭제로 이어질 수 있으니, 애매할 때 멈추는 쪽이 낫습니다.
기본은 헤드리스 모드
README에 따르면 ref 기반 조작은 접근성 API를 거치므로 "마우스 포인터를 움직이거나 포커스를 빼앗지 않습니다." 에이전트가 다른 창에서 양식을 채우는 동안 사용자는 하던 작업을 계속할 수 있습니다. 접근성 동작만으로 안 되는 앱에서는 전역 옵션 --headed를 주면 실제 마우스·키보드 입력을 씁니다.
명령 60개, 모든 OS에서 같은 이름
CLI에는 명령 이름이 60개 있고 그중 56개가 동작합니다. 용도별로 묶으면 이렇습니다.
- 관찰:
snapshot,find,get,is,screenshot,list-surfaces - ref 조작:
click,type,set-value,select,toggle,check,expand,scroll-to등 - 키보드·마우스:
press,hover,drag,mouse-click,mouse-wheel - 앱·창 관리:
launch,close-app,list-windows,focus-window,resize-window,minimize - 시스템: 알림, 클립보드,
wait,batch,permissions,skills
키나 마우스 버튼을 누른 채로 유지하는 key-down, key-up, mouse-down, mouse-up 네 개는 지금은 실행을 거부합니다. 에이전트가 중간에 죽었을 때 눌린 입력을 풀어 줄 데몬이 생길 때까지는 막아 둔 상태입니다.
agent-desktop과 스크린샷 기반 컴퓨터 유즈 비교
컴퓨터 유즈(computer use)는 AI 모델이 사람처럼 화면을 보고 클릭하고 입력하면서 컴퓨터의 그래픽 인터페이스를 조작하게 하는 기술을 말합니다. Anthropic의 컴퓨터 유즈 도구 같은 스크린샷 방식은 모델에 화면 이미지를 보내고, 클릭할 픽셀 좌표를 돌려받습니다. agent-desktop은 이미지 대신 구조화된 텍스트를 보냅니다.
| 스크린샷 기반 컴퓨터 유즈 | agent-desktop(접근성 트리) | |
|---|---|---|
| 모델이 보는 것 | 전체 화면 이미지 | 역할·이름·값이 담긴 JSON 트리 |
| 대상 지정 방식 | 픽셀 좌표 | 스냅샷에 묶인 ref ID |
| 한 번 볼 때 입력 비용 | 스크린샷 1장에 약 1,000~1,800토큰(Anthropic 문서) | 텍스트만 전송, 크기는 앱 트리에 따라 다름 |
| 마우스 포인터 이동 | 있음 | 기본값은 없음 |
| 대상이 어긋났을 때 | 좌표가 가리키는 곳을 클릭 | STALE_REF나 AMBIGUOUS_TARGET으로 실패 |
| 접근성 정보가 없는 앱 | 화면에 보이면 조작 가능 | 조작 불가 |
| 비전 모델 필요 여부 | 필요 | 불필요 |
Anthropic 컴퓨터 유즈 문서는 스크린샷 한 장이 입력 토큰 1,000~1,800개 정도를 쓴다고 적습니다. 같은 문서에는 "Claude가 결과를 확인하지 않고 동작이 성공한 것처럼 행동할 때가 있다"는 경고도 있습니다. agent-desktop은 텍스트 스냅샷과 명시적인 확인 단계로 두 문제를 모두 겨냥합니다.
대신 적용 범위가 좁습니다. 스크린샷 방식은 게임, 캔버스로 그리는 앱, 원격 데스크톱처럼 화면에 그려지기만 하면 무엇이든 다룹니다. agent-desktop은 앱이 접근성 계층에 알려 주는 것만 봅니다. 구조가 복잡한 앱은 트리가 매우 커질 수 있어서, README는 먼저 --skeleton으로 윤곽을 잡고 --root로 들어가라고 권합니다. 스크린샷 기반 에이전트 사례는 GPT-6.1 Terra의 컴퓨터 유즈 글에서 다룬 적이 있습니다.
agent-desktop과 agent-browser의 관계
agent-desktop의 형제 프로젝트는 Vercel Labs의 브라우저 자동화 CLI인 agent-browser입니다. 2026년 11월 2일 기준 GitHub 스타 약 45,200개, 라이선스는 역시 Apache-2.0이고 MCP 서버로도 실행할 수 있습니다. 페이지의 접근성 트리를 스냅샷으로 찍고 @e2 같은 짧은 ref로 조작한다는 발상이 같습니다.
두 도구는 다루는 대상으로 역할을 나눕니다. agent-desktop 문서는 웹 페이지 자동화는 하지 않는다며 agent-browser를 안내합니다. Chromium이나 Electron 기반 데스크톱 앱이라면 agent-desktop이 DevTools 포트를 열고 agent-browser가 거기에 접속할 수 있습니다. 에이전트 하나가 네이티브 창은 agent-desktop으로, 웹 콘텐츠는 agent-browser로 다루면서 같은 스냅샷·ref 방식을 그대로 쓰는 구조입니다.
agent-desktop 설치와 설정
설치는 npm으로 합니다. Bun, Yarn, pnpm도 됩니다.
npm install -g agent-desktop을 실행합니다. 패키지에 x64와 ARM64용 네이티브 바이너리가 들어 있습니다. 개발자 Flavio Copes의 분석 글에 따르면 Node 18 이상이 필요합니다.agent-desktop status로 설치 상태를 확인합니다.- 권한을 줍니다. macOS는 터미널이나 에이전트를 띄운 앱에 손쉬운 사용(Accessibility) 권한이 필요하고
agent-desktop permissions --guide가 과정을 안내합니다. Windows는 터미널과 같은 무결성 수준의 앱이라면 별도 권한이 필요 없습니다. Linux는at-spi2-core가 있는 그래픽 세션이 필요합니다. agent-desktop skills get desktop을 실행합니다. 에이전트가 가장 먼저 읽어야 할 사용 안내가 출력되며 이 안내는 바이너리에 내장돼 있습니다.
공식 문서 기준 플랫폼 요구 사항을 표로 정리했습니다.
| OS | 최소 버전 | 아키텍처 | 접근성 API |
|---|---|---|---|
| macOS | 13 이상 | Intel, Apple Silicon | AX |
| Windows | 10 1809 이상, Server 2019 이상 | x64, ARM64 | UI Automation |
| Linux | Ubuntu 24.04 이상(glibc 2.35 이상) | x86_64, aarch64 | AT-SPI |
기능 지원 범위는 OS마다 조금씩 다릅니다. README의 기능 표를 보면 macOS의 셸 영역 조작은 아직 계획 단계입니다. Linux에서 마우스 입력을 쓰려면 X11과 --headed가 필요하고, Wayland에서 클립보드를 쓰려면 wl-clipboard가 있어야 합니다.
Claude Code, Codex, Cursor용 공식 플러그인이나 MCP 서버는 아직 없습니다. Ubuntu에서 1.0.2를 시험한 Copes는 스킬 파일이나 AGENTS.md 항목으로 에이전트에 연결했습니다. 그의 측정으로는 npm 설치 스크립트가 막혀 있으면 호출 한 번에 약 146ms, 네이티브 바이너리가 연결된 상태에서는 약 21ms가 걸렸습니다.
출시 일정
변경 기록을 보면 공식 발표 전에 몇 주에 걸쳐 릴리스가 이어졌습니다.
- 0.10.0(2026년 10월 18일): Windows 지원(x64, ARM64). 스냅샷 ID 없는
@eN형식 ref를 없애고 스냅샷에 묶인 ref로 바꿨습니다. - 1.0.0(2026년 10월 27일): AT-SPI 기반 Linux 지원. macOS·Windows·Linux CLI와 C 라이브러리를 1.0으로 함께 내놓았습니다.
- 1.0.2(2026년 10월 30일): macOS 권한 안내를 다듬고 설치 스크립트 차단으로 실행이 느려지면 알려 주는 안내를 추가했습니다.
- 2026년 10월 31일: Chris Tate가 공식 발표했습니다.
쓰기 전에 알아 둘 위험과 한계
데스크톱의 아무 곳이나 클릭할 수 있는 에이전트는 "보내기", "삭제", "결제 승인"도 잘못 누를 수 있습니다.
- README는 스냅샷과 스크린샷에 개인 정보가 들어갈 수 있으니 공개 로그나 업로드에 남기지 말라고 경고합니다. 메일 앱을 스냅샷하면 메일 내용이 그대로 담깁니다.
- 프로젝트의 보안 정책은 취약점 신고 절차만 다루고 샌드박스나 프롬프트 인젝션에 대해서는 아무 말이 없습니다.
- 앱 안의 텍스트(메일, 문서, 채팅 메시지)는 데이터로 모델에 들어가므로 프롬프트 인젝션 통로가 됩니다. Anthropic 컴퓨터 유즈 문서는 모델이 콘텐츠 속 지시를 따를 때가 있다고 경고하면서 전용 가상머신이나 컨테이너, 로그인 정보 차단, 중요한 동작에 대한 사람의 확인을 권합니다. agent-desktop에도 똑같이 적용되는 조언입니다.
- JEV라는 선택형 도우미는 화면 설명을 사용자가 설정한 모델 제공사로 보냅니다. 네이티브 CLI와는 별개이니, 민감한 앱에 쓰기 전에 켜져 있는지 확인해야 합니다.
최근 Cursor 마켓플레이스의 Claude Code 확장 백도어 사건에서 보듯 에이전트 도구 자체가 공격 대상이 되고 있습니다. agent-desktop은 공식 npm 패키지나 GitHub 릴리스에서만 설치하는 것이 좋습니다. 변경 기록에 따르면 릴리스에는 체크섬과 빌드 출처(provenance) 정보가 붙습니다.
agent-desktop이 맞는 사람
이미 터미널 코딩 에이전트를 쓰면서 브라우저 바깥에서 자꾸 막히는 개발자에게 맞습니다. 네이티브 앱의 UI를 테스트하거나, API가 없는 데스크톱 도구에 값을 입력하거나, 빌드한 앱이 실제로 뜨는지 확인하는 일이 대표적입니다. QA 팀이라면 좌표 클릭보다 구조화된 ref와 명시적 확인 단계 쪽을 더 믿을 만하다고 느낄 것입니다. 반대로 게임, 원격 데스크톱 세션, 직접 그리는 캔버스 UI가 대상이라면 여전히 스크린샷 기반 컴퓨터 유즈밖에 방법이 없습니다.
자주 묻는 질문
agent-desktop은 무료인가요?
무료입니다. CLI와 C 라이브러리 모두 Apache-2.0 라이선스의 오픈소스이고 npm install -g agent-desktop 한 줄로 설치합니다. 도구 자체는 모델을 호출하지 않으므로 비용은 원래 쓰던 코딩 에이전트 사용료뿐입니다.
agent-desktop은 스크린샷을 쓰나요?
기본적으로는 쓰지 않습니다. 운영체제의 접근성 트리를 읽어 ref ID가 붙은 JSON으로 돌려주기 때문에, 에이전트는 픽셀 좌표 대신 구조화된 데이터를 보고 조작합니다. 화면을 직접 봐야 할 때를 위한 screenshot 명령은 따로 있습니다.
어떤 AI 에이전트와 함께 쓸 수 있나요?
셸 명령을 실행할 수 있는 에이전트라면 됩니다. Claude Code, Codex, Cursor 에이전트가 모두 해당합니다. 전용 플러그인이나 MCP 서버는 아직 없어서 스킬 파일이나 AGENTS.md 항목으로 연결하며 agent-desktop skills get desktop이 사용 안내를 출력합니다.
agent-desktop과 agent-browser는 무엇이 다른가요?
agent-browser는 브라우저 안의 웹 페이지를, agent-desktop은 macOS·Windows·Linux의 네이티브 앱을 자동화합니다. 둘 다 Vercel Labs가 만들었고 스냅샷과 ref를 쓰는 방식이 같습니다. Chromium이나 Electron 앱에서는 agent-desktop이 DevTools 포트를 열어 agent-browser가 접속하게 할 수 있습니다.
AI 에이전트에게 데스크톱 조작을 맡겨도 안전한가요?
예방 조치를 갖춘 경우에만 그렇습니다. agent-desktop 문서에는 샌드박스에 대한 설명이 없고 앱 콘텐츠를 통해 프롬프트 인젝션이 들어올 수 있습니다. 가상머신이나 테스트 계정에서 실행하고 민감한 앱은 닫아 두십시오. 전송·결제·삭제처럼 되돌리기 어려운 동작에는 사람의 확인을 거치게 하십시오.
