AI 에이전트가 스크린샷 없이 데스크톱 앱을 직접 조작하게 만드는 방법
AI 에이전트가 화면을 보고 마우스를 움직이는 대신, 운영체제가 제공하는 접근성 트리에서 정보를 읽어 앱을 제어하는 흐름을 경험해 보세요. 에이전트가 화면을 캡처하거나 픽셀을 매칭하는 대신, 앱의 구조를 JSON으로 받아 클릭이나 입력을 수행하고 결과를 확인하는 루프를 돌립니다. 이 도구는 모델 자체를 포함하지 않으며, 에이전트가 이 루프를 실행하도록 돕는 CLI와 C 라이브러리를 제공합니다.
접근성 트리를 통한 조작 방식
agent-desktop은 스크린샷이나 픽셀 매칭을 사용하지 않고, 데스크톱 앱의 접근성 트리를 읽어 JSON 형태로 반환합니다. 각 요소에는 에이전트가 조작할 수 있는 참조(ref)가 부여되며, 에이전트는 이 참조를 이용해 클릭이나 텍스트 입력을 수행합니다. 조작 후 다시 UI를 읽어 결과를 검증하는 과정이 반복되며, 이 루프는 사용자의 에이전트 코드에서 실행됩니다. 도구 자체에는 AI 모델이 내장되어 있지 않아, 외부 에이전트와 결합해 사용해야 합니다.
플랫폼별 요구 사항과 설치
macOS 13 이상, Windows 10 1809 이상, Ubuntu 24.04 이상을 지원합니다. 각 플랫폼은 자체 접근성 API(AX API, UI Automation, AT-SPI)를 사용하며, macOS에서는 접근성 권한을 부여해야 합니다. npm install -g agent-desktop 명령으로 설치할 수 있으며, agent-desktop status로 현재 플랫폼과 권한 상태를 확인할 수 있습니다. Windows는 터미널의 무결성 레벨에 해당하는 앱에 대해 권한이 필요 없으며, Linux는 사용자의 그래픽 세션에서 at-spi2-core와 함께 실행해야 합니다.
에이전트 통합과 명령어 구조
CLI는 60개의 명령어 이름을 가지며, 관찰, 조작, 키보드/마우스, 앱/창 관리, 알림, 클립보드, 대기, 세션, 시스템 관리로 그룹화됩니다. snapshot 명령으로 현재 UI 상태를 JSON으로 받아 참조 ID를 확인하고, click이나 type 명령으로 해당 참조를 조작합니다. UI가 변경되면 이전 참조는 STALE_REF 오류를 반환하므로, 새로운 스냅샷을 찍어 참조를 갱신해야 합니다. 에이전트 하네스에 스킬을 추가하거나 AGENTS.md에 지침을 넣어 에이전트가 이 도구를 올바르게 사용하도록 설정할 수 있습니다.
보안과 데이터 처리 주의점
스냅샷, 클립보드 읽기, 스크린샷, 명령 출력, 디버그 아티팩트는 모두 개인적인 데스크톱 내용을 포함할 수 있습니다. 이러한 데이터가 공개 로그나 업로드에 포함되지 않도록 주의해야 합니다. 동작은 기본적으로 헤드리스(headless)로 수행되어 포인터 이동이나 포커스 변경이 일어나지 않으며, 물리적 입력이 필요할 때만 --headed 옵션을 사용합니다. PowerShell에서는 참조를 따옴표로 감싸야 하며, 그렇지 않으면 스플래팅 연산자로 해석되어 오류가 발생할 수 있습니다.
적용 전 확인 사항
이 도구는 AI 모델이 아닌, 에이전트가 데스크톱을 조작하기 위한 인터페이스를 제공합니다. 따라서 에이전트 로직을 직접 구현하거나 기존 에이전트 프레임워크에 통합해야 합니다. Apache-2.0 라이선스로 배포되며, C 라이브러리를 통해 프로세스 내에서 직접 호출할 수도 있습니다.
