Vercel Labs agent-desktop: 접근성 트리로 데스크톱을 조작하는 에이전트 도구

AI 에이전트가 데스크톱 앱을 다루려면 화면에서 버튼을 찾고 클릭한 뒤 결과를 확인해야 한다. Vercel Labs의 오픈소스 도구 agent-desktop은 운영체제가 노출하는 접근성 트리를 읽어 이 과정을 돕는다. 공식 저장소에 따르면 CLI와 C 라이브러리를 제공하며 macOS, Windows, Linux를 지원한다.

GitHub 릴리스에 공개된 v1.0.2의 배포 시각은 2026년 10월 30일 UTC다. 이 프로젝트가 그날 처음 등장한 것은 아니다. 릴리스에는 문서 정비와 npm 실행기 관련 안내 등이 포함됐다.

화면을 읽고 참조로 조작하기

도구의 기본 흐름은 관찰, 동작, 재관찰이다. snapshot은 앱의 접근성 요소와 상호작용 가능한 요소의 참조를 JSON으로 반환한다. 에이전트는 해당 참조를 사용해 클릭 같은 동작을 요청하고 다시 스냅샷을 읽어 변화를 확인한다. 저장소는 이 흐름에서 픽셀 매칭을 사용하지 않는다고 설명한다. 에이전트의 판단 루프는 별도로 구현해야 한다.

예를 들어 macOS의 Finder에서 대화형 요소를 살피는 명령은 다음과 같다.

agent-desktop snapshot --app Finder -i

이후 출력에 담긴 실제 참조를 agent-desktop click <참조>에 전달하고 다시 스냅샷을 확인한다. 참조는 예시 문자열을 고정해서 쓰기보다 해당 실행의 출력에서 받아야 한다. 접근성 트리에 노출되지 않거나 조작할 수 없는 요소가 있다면 같은 방법으로 처리하기 어려울 수 있다. 앱마다 지원 범위를 직접 시험해야 한다.

설치와 운영 환경

공식 설치 문서는 npm 패키지 이름을 agent-desktop으로 안내한다. 설치 후 버전을 확인한다.

npm install -g agent-desktop
agent-desktop version

패키지에는 x64와 ARM64용 네이티브 실행 파일과 플랫폼 도우미가 포함된다. macOS에서는 접근성 권한이 필요하고 Linux에서는 사용자의 그래픽 세션과 at-spi2-core가 필요하다. Windows에서는 터미널과 같은 무결성 수준의 앱을 다룰 때 별도 권한 부여가 필요 없다고 저장소가 설명한다. 실제 권한과 앱의 접근성 구현은 환경마다 확인해야 한다.

에이전트에 연결할 때 살필 점

스냅샷과 클립보드, 스크린샷, 디버그 산출물에는 데스크톱의 민감한 정보가 담길 수 있다. 공식 저장소도 이런 데이터를 공개 로그나 업로드에 남기지 않도록 안내한다. 자동화 대상 계정의 권한을 제한하고 결과 확인 단계를 두는 편이 안전하다. 저장소는 헤드리스 호출에서 포그라운드 활성화와 합성 입력을 금지한다고 설명하므로 실행 방식에 따른 제약도 살펴야 한다.

이 글의 기능과 지원 범위는 공식 문서와 릴리스 기록을 바탕으로 정리했다. 실제 앱에서의 성공률이나 속도는 별도로 실험하지 않았다.