Agent Desktop, OS 접근성 트리의 참조값으로 데스크톱 앱 조작

본문

Vercel Labs 계정의 공개 저장소 agent-desktop은 에이전트가 데스크톱 앱을 운영체제의 접근성 트리로 읽고 조작하도록 돕는 CLI와 C 라이브러리입니다. 운영체제가 접근성 API로 노출하는 요소를 JSON으로 가져와 대상을 지정합니다. 에이전트는 이 구조에서 대상을 고르고 명령을 실행한 뒤 새 스냅샷을 읽어 결과를 확인합니다.

예를 들어 Finder의 대화형 요소를 스냅샷으로 요청하면 창 이름과 요소의 역할, 이름, 가능한 동작이 JSON으로 반환됩니다. 요소마다 스냅샷 ID가 포함된 ref가 붙습니다. 에이전트는 이 ref를 클릭 명령에 넣고 다시 스냅샷을 받아 UI 상태를 확인합니다. 프로젝트가 안내하는 기본 흐름은 관찰하고, ref로 동작한 다음, 다시 관찰하는 방식입니다. 명령은 한 번에 하나의 JSON 응답을 내보내며 에이전트는 그 응답을 작업 흐름에 연결합니다.

ref는 특정 스냅샷 안에서만 유효합니다. UI가 달라져 기존 ref가 더는 유효하지 않으면 STALE_REF 오류가 반환되고, 대상이 여러 요소와 일치하면 AMBIGUOUS_TARGET 오류가 납니다. 이때 에이전트는 새 스냅샷을 읽고 거기서 받은 ref를 사용합니다. 같은 앱에 창이 여럿 있어 대상 창을 정할 수 없을 때도 모호성 오류가 나며, 명령에 창 ID를 지정해 범위를 좁힙니다. 에이전트의 다음 동작은 최신 스냅샷에 포함된 ref를 기준으로 합니다.

재시도도 모든 오류에 똑같이 적용하지 않습니다. 각 JSON 응답에는 오류 코드와 함께 명령이 전달됐는지, 다시 실행해도 안전한지를 나타내는 정보가 들어갑니다. 명령이 앱에 전달되지 않은 오류는 안전한 재시도로 분류될 수 있지만, 동작이 이미 전달됐거나 전달 여부가 불분명하면 안전한 재시도로 취급하지 않습니다. 예를 들어 일부 마우스·창 조작은 호출이 전달됐더라도 결과 상태를 읽어 검증하지 못한 상태로 응답할 수 있습니다. 성공 응답에는 작업의 전달 여부와 사후 검증 상태가 따로 담깁니다. 에이전트는 오류 종류와 전달 상태에 따라 새 스냅샷을 요청하거나 재실행을 보류하는 식으로 처리합니다.

ref를 이용한 기본 조작은 접근성 API를 거치므로 포인터를 움직이거나 앱 창에 포커스를 주지 않고 실행됩니다. 전역 --headed 옵션은 물리 입력 경로를 허용합니다. 프로젝트에는 스크린샷과 마우스 조작 명령도 있어 접근성 트리와 물리 입력 경로를 함께 제공합니다. 운영체제별 지원에도 차이가 있습니다. macOS는 접근성 권한이 필요하고, Windows에서는 터미널과 같은 무결성 수준의 앱에 별도 권한 없이 접근합니다. Linux는 사용자의 그래픽 세션과 at-spi2-core가 필요하며 마우스 입력은 X11에서, 화면 캡처는 X11 창이나 Wayland 포털을 이용합니다.

저장소는 npm으로 설치하는 CLI와 에이전트 실행 환경에 추가하는 skill을 안내합니다. 프로그램 내부에서 CLI를 매번 실행하지 않으려는 경우에는 릴리스에 포함된 C ABI 라이브러리를 직접 호출할 수 있습니다. 에이전트는 같은 접근성 트리와 ref 기반 동작을 CLI 명령이나 라이브러리 호출로 이용합니다. 저장소는 스냅샷과 클립보드 내용, 스크린샷, 명령 출력, 디버그 자료에 데스크톱의 사적인 내용이 포함될 수 있다고 설명합니다. 선택 사항인 JEV 도우미는 화면 설명을 설정된 모델 제공자에 보내며 기본 네이티브 CLI와는 별도 구성요소입니다. 저장소의 라이선스는 Apache-2.0입니다.

자료: GitHub / 정리·해설: Trawling