agent-desktop 접근성 트리 기반 데스크톱 제어

개요

agent-desktop은 AI 에이전트가 macOS, Windows, Linux의 데스크톱 앱을 조작하도록 지원하는 CLI이자 C 라이브러리이다. 화면 이미지를 분석하는 대신 운영체제의 접근성 트리를 JSON으로 제공한다.

agent-desktop 자체는 에이전트가 아니다. 내부에 AI 모델이 없으므로 판단은 Claude Code나 Codex 같은 호출 측 에이전트가 담당하고, agent-desktop은 화면 구조의 조회와 조작 명령의 실행만 담당한다.

항목	내용
저장소	vercel-labs/agent-desktop
최신 버전	v1.1.0 (1.0.0은 2026년 10월 27일 공개)
구현 언어	Rust
라이선스	Apache-2.0
제공 형태	CLI, C 라이브러리, MCP 서버

저장소는 개발자 lahfir의 개인 저장소로 시작하였고, 이전 주소는 현재 Vercel Labs 저장소로 연결된다.

스크린샷 방식과의 차이

스크린샷 방식의 컴퓨터 유즈는 모델이 화면 이미지에서 버튼의 위치를 판단하여 좌표를 클릭한다. agent-desktop은 앱이 운영체제에 공개한 UI 구조를 읽어 각 요소의 역할과 이름을 그대로 제공한다.

구분	스크린샷 방식	agent-desktop
입력	화면 이미지	접근성 트리 JSON
필요한 모델	이미지 판독 모델	JSON을 처리하는 에이전트
조작 대상 지정	화면 좌표	요소별 ref
대응 범위	화면에 표시되는 대상	접근성 정보를 공개한 UI

대응 범위가 가장 큰 제약이다. 픽셀을 분석하지 않으므로 접근성 트리를 공개하지 않는 UI는 조회할 수 없다. 웹 페이지 자동화도 대상이 아니며, 공식 문서는 웹 페이지에 agent-browser를 안내한다.

소개 문서에는 스크린샷 방식과의 토큰 · 속도 비교 수치가 없다. 도입 효과는 대상 앱과 에이전트 환경에서 별도로 측정할 필요가 있다.

동작 방식

구성 요소

에이전트는 CLI, MCP 서버, C 라이브러리 중 하나로 명령을 전달한다. 명령은 공통 코어와 운영체제별 크레이트를 거쳐 각 운영체제의 접근성 API에 도달하고, 결과는 JSON으로 반환된다.

코어는 플랫폼 크레이트를 직접 참조하지 않으며, 빌드 시점에 해당 운영체제의 크레이트 하나만 선택된다. 세 운영체제에 같은 명령 이름을 제공할 수 있는 구조이다.

관찰 · 조작 · 재관찰 루프

기본 흐름은 세 단계이다.

agent-desktop snapshot --app Finder -i   # 조작 가능한 요소와 ref 조회
agent-desktop click @s8f3k2p9:e8         # 스냅샷의 ref로 조작
agent-desktop snapshot --app Finder -i   # 결과 재확인

아래 그림은 이 루프를 패널 시험대에 비유하여 표현한 것이다. 패널은 앱 창, 헤드의 이동은 접근성 트리 조회, 앞쪽의 표찰은 스냅샷이 발급한 ref에 해당한다. 그림의 예시 값은 설명용이며, 실제 ref 조작은 기본적으로 물리 입력 없이 접근성 API로 실행된다.

마지막 재관찰은 생략할 수 없는 단계이다. macOS 문서는 접근성 API의 성공 응답이 실제 UI 변경을 보장하지 않는다고 명시한다. 조작 성공 여부는 get, is, snapshot으로 다시 조회하여 판단한다.

snapshot 응답

모든 명령은 실행마다 JSON 엔벨로프 하나를 출력한다. 아래는 공식 문서의 응답을 축약한 예시이다.

{
  "version": "2.6",
  "ok": true,
  "command": "snapshot",
  "data": {
    "app": "Finder",
    "snapshot_id": "s8f3k2p9",
    "tree": {
      "role": "window",
      "name": "Downloads",
      "children": [
        { "role": "treeitem", "name": "Documents", "ref_id": "@s8f3k2p9:e8", "available_actions": ["Click"] }
      ]
    }
  }
}

명령이 실패하면 error.disposition.retry를 확인한다. 이 값이 safe일 때만 재시도한다.

ref의 구조

ref는 @스냅샷ID:요소번호 형식이다. 스냅샷 ID가 없는 @e8은 INVALID_ARGS로 실패한다. 어느 시점의 관찰에서 획득한 대상인지 ref 자체에 기록하기 위한 구조이다.

ref는 요소에 직접 연결된 핸들이 아니라 식별 정보의 기록이다. 명령을 실행할 때마다 이 기록으로 대상을 다시 탐색하고, 대상을 하나로 특정할 수 없으면 앱에 입력을 전달하지 않는다.

오류 코드	발생 조건	대응
STALE_REF	대상 요소를 찾을 수 없음	새 스냅샷의 ref 사용
AMBIGUOUS_TARGET	일치하는 요소나 창이 2개 이상	창을 지정하거나 새 스냅샷 사용
SNAPSHOT_NOT_FOUND	스냅샷이 정리되었거나 다른 세션에 속함	같은 세션에서 새 스냅샷 생성

플랫폼별 차이도 존재한다. macOS의 ref는 요소 고유의 접근성 주소를 추적하므로 동일한 컨트롤을 각각 지정할 수 있다. Windows와 Linux에서는 역할과 이름 같은 속성으로 재식별하므로, 동일한 컨트롤 중 하나를 가리키는 ref는 AMBIGUOUS_TARGET을 반환한다.

헤드리스 기본 동작

ref 기반 조작은 기본적으로 접근성 API로 실행되며, 포인터 이동과 포커스 변경이 발생하지 않는다. 물리 입력이 필요한 작업에는 --headed를 지정한다. 다만 헤드리스로 실행 가능한 범위는 운영체제별로 다르다.

동작	macOS	Windows
click, set-value, toggle	헤드리스	헤드리스
type, right-click, focus	헤드리스	--headed 필요
drag, hover, mouse-click	--headed 필요	--headed 필요
앱 종료 단축키	--force 없으면 거부	--force 없으면 거부

Windows의 헤드리스 환경에서 텍스트를 입력할 때는 type 대신 set-value를 사용한다.

설치와 사용 방법

설치

npm 패키지는 Node 18 이상이 필요하며, pnpm, Yarn, Bun으로도 설치할 수 있다. macOS와 Linux에서는 Homebrew도 지원한다.

npm install -g agent-desktop
agent-desktop status

status는 플랫폼, 권한, 지원 대상을 출력한다.

운영체제	요구 사항	접근성 API	준비 사항
macOS	13 이상	AX API	실행 터미널에 손쉬운 사용 권한 부여
Windows	10 1809 이상	UI Automation	대화형 사용자 세션에서 실행
Linux	Ubuntu 24.04 이상	AT-SPI	로그인한 그래픽 세션에서 실행

macOS에서는 agent-desktop permissions --guide로 시스템 설정의 권한 화면을 열 수 있다. screenshot을 사용하려면 화면 기록 권한도 필요하다.

에이전트 연동

연동 방법은 세 가지이다. 첫째는 에이전트에 사용 규칙을 제공하는 방법이다. 내장 가이드는 루프, ref, 재시도 규칙과 운영체제별 차이를 설명한다.

agent-desktop skills get desktop    # 루프, ref, 재시도 규칙
agent-desktop skills get platform   # 현재 운영체제의 차이
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop

프로젝트의 AGENTS.md에 처음 사용하기 전 위 두 가이드를 읽도록 지시하는 방법도 있다.

둘째는 MCP 서버이다. 각 명령이 desktop_snapshot, desktop_click 같은 이름의 도구로 제공된다.

{ "mcpServers": { "agent-desktop": { "command": "agent-desktop", "args": ["mcp"] } } }

셋째는 C 라이브러리이다. 릴리스에 libagent_desktop_ffi가 포함되어 있어 별도 프로세스를 실행하지 않고 프로그램 내부에서 호출할 수 있다.

명령 구성

명령은 60개이며 그중 56개가 동작한다. key-down, key-up, mouse-down, mouse-up은 누른 입력을 해제할 데몬이 준비될 때까지 실행을 거부한다.

분류	주요 명령
관찰	snapshot, find, get, is, screenshot
ref 조작	click, type, set-value, select, toggle, scroll
앱 · 창	launch, close-app, list-apps, list-windows, focus-window
시스템 정보	clipboard-get, list-notifications, status, permissions
실행 제어	wait, batch, session, trace

복잡한 화면에서는 snapshot --skeleton으로 전체 구조를 확인한 뒤 --root로 필요한 영역만 조회한다. 단일 ref 맵의 상한이 1MB이므로, 이를 초과하면 조회 범위를 축소해야 한다.

사용 시 유의 사항

개인 정보

스냅샷, 창 제목, 클립보드, 알림, 스크린샷, 명령 결과에는 데스크톱의 내용이 그대로 포함된다. 공식 문서는 이러한 산출물과 에이전트의 대화 기록을 비공개로 관리하도록 안내한다.

CLI 자체에는 원격 모델 서비스가 필요하지 않다. 그러나 호출 측 에이전트가 클라우드 모델을 사용한다면 조회 결과도 해당 서비스로 전송될 수 있다. 메신저, 메일, 사내 시스템이 열린 환경에서 사용하기 전에 전송 범위를 확인한다.

운영체제별 제약

• Windows · PowerShell: ref를 작은따옴표로 감싼다. 따옴표가 없으면 @가 splatting 연산자로 해석된다. 예: agent-desktop click '@s8f3k2p9:e8'
• Windows · 실행 파일: 바이너리에 서명이 없어 SmartScreen, 백신, Smart App Control이 실행을 차단할 수 있다. 관리자 권한 앱을 조작하려면 터미널도 같은 권한으로 실행해야 한다.
• Electron · Chromium: 첫 조회에서 트리의 일부만 반환될 수 있으며, 콜드 실행에 10~25초가 소요될 수 있다. 이때는 snapshot --timeout-ms 값을 상향한다.
• Linux · 세션: TTY, 세션 변수가 없는 SSH, 버스가 없는 컨테이너에서는 앱이 조회되지 않는다.
• Linux · Wayland: 포인터 제스처와 창 제어를 지원하지 않는다.

---

참고: agent-desktop 저장소 · 공식 문서 · Snapshots and refs · Vercel agent-desktop 사용법(위키독스)