lahfir/agent-desktop

이것이 무엇인가

agent‑desktop는 macOS와 Windows에서 AI 에이전트가 그래픽 데스크톱 애플리케이션을 보고 제어할 수 있게 해주는 명령줄 도구(및 함께 제공되는 C 라이브러리)입니다. 운영 체제의 접근성 트리를 읽고 UI 요소의 JSON 설명을 내보내며, 안정적인 ID로 해당 요소를 참조하여 클릭, 입력, 창 관리, 클립보드 액세스 등을 실행할 수 있습니다.

이것이 중요한 이유

코드에서 GUI를 제어하는 것은 자율 에이전트에게 고전적인 병목 현상입니다. 대부분의 LLM 기반 어시스턴트는 텍스트 API로만 작업할 수 있으므로 사용자가 사용하는 앱과 직접 상호 작용할 수 없습니다. UI를 구조화된 기계 판독 가능 트리로 노출하고 풍부한 작업 세트를 제공함으로써 agent‑desktop은 이러한 격차를 해소하여 에이전트가 마우스를 움직이거나 포커스를 빼앗지 않고도 실제 데스크톱 워크플로(예: Finder에서 보고서 제출, Slack 메시지 보내기, 알림 닫기)를 자동화할 수 있게 합니다.

작동 방식(높은 수준)

1. 스냅샷 – agent-desktop snapshot --app <name>은 OS 접근성 API를 탐색하고 UI 요소의 JSON 트리를 출력합니다. 각 요소는 @s8f3k2p9:e3과 같은 참조를 얻으며, 이는 속한 스냅샷을 인코딩합니다.
2. 실행 – click, type, press, scroll 또는 launch와 같은 명령은 참조(또는 키 단축키)를 받아 접근성 계층을 통해 해당 입력을 보냅니다. 기본적으로 작업은 헤드리스(보이는 커서 이동 없음)입니다.
3. 반복 – 작업 후 다른 스냅샷을 찍어 UI가 예상대로 변경되었는지 확인합니다. 오래되었거나 모호한 참조는 보고되어 에이전트가 새로 고칠 수 있습니다.
4. 라이브러리 모드 – 동일한 기능이 C 호환 공유 라이브러리인 libagent_desktop_ffi로 패키징되어 다른 언어(예: ctypes를 통한 Python)의 프로그램이 CLI 프로세스를 생성하지 않고 API를 직접 호출할 수 있습니다.

사용할 수 있는 사람

대상	사용 사례
AI 연구소 데스크톱 소프트웨어를 조작해야 하는 자율 에이전트 구축.
개인 비서 개발자 (예: ChatGPT 스타일 봇) 텍스트 전용 작업을 넘어 확장하려는 경우.
자동화 엔지니어 취약한 화면 스크래핑 도구 없이 UI 작업을 스크립팅할 프로그래밍 방식의 크로스 플랫폼 방법을 찾는 경우.
도구 제작자 FFI 라이브러리를 통해 데스크톱 제어 기능을 자신의 애플리케이션에 내장하려는 경우.

시작하기(빠른 단계)

# CLI 설치(기본 바이너리 포함)
npm install -g agent-desktop

# macOS 접근성 권한 부여(또는 Windows에서 필요에 따라 실행)
agent-desktop permissions --request

# Finder 스냅샷을 찍고 대화형 요소 나열
agent-desktop snapshot --app Finder -i

# 첫 번째 요소 클릭(받은 참조로 바꾸기)
agent-desktop click @s8f3k2p9:e3

# UI가 변경되었는지 확인
agent-desktop snapshot --app Finder -i

프로그래밍 방식 사용의 경우 README의 Python 스니펫은 공유 라이브러리를 로드하고 초기화하는 방법을 보여줍니다.

강점 및 한계

강점	한계
• macOS와 Windows 모두에서 즉시 작동합니다.
• 헤드리스 작동으로 사용자의 마우스/키보드를 방해하지 않습니다.
• 안정적인 참조가 있는 구조화된 JSON을 반환하여 에이전트가 UI 상태를 추론하기 쉽습니다.
• 프로세스 내 사용을 위한 완전한 기능의 FFI 라이브러리를 제공합니다.
• 광범위한 작업(클릭, 입력, 창 관리, 알림, 클립보드 등)을 지원합니다.
• Apache-2.0에 따른 오픈 소스, CI 및 테스트 포함.
• Linux 지원 예정.
• 에이전트를 위한 통합 "스킬" 가이드.
• npm을 통한 바이너리 배포로 설치가 간편합니다.
• macOS에 대한 상세한 권한 처리.
• 명확한 오류 코드(STALE_REF, AMBIGUOUS_TARGET).
• 배치 명령 및 세션 추적 지원.
• Windows에서 셸 표면(작업 표시줄, 시작 메뉴)에서 작동할 수 있습니다.
• OS 접근성 API 사용 – 픽셀 매칭보다 더 안정적입니다.
• Selenium이나 AutoIt과 같은 외부 UI 자동화 도구가 필요 없습니다.
• ARM64 및 x64 아키텍처 모두 지원.
• 에이전트 작업의 시각적 디버깅을 위한 "커서 오버레이" 제공.
• LLM 프롬프트의 토큰 수를 줄이기 위한 스켈레톤 스냅샷 기능.
• skills 시스템을 통해 확장 가능.
• CI 배지로 활발한 테스트 표시.
• 릴리스 바이너리는 체크섬 검증됨.
• CDP를 통한 Chromium 앱 실행 지원.
• 시스템 알림 나열 및 닫기 가능.
• 클립보드를 직접 조작할 수 있습니다.
• 프로그래밍 방식으로 창 크기 조정/이동 가능.
• 다중 에이전트 세션 지원.
• 여러 작업을 묶는 batch 명령 제공.
• 에이전트 동작 디버깅을 위한 trace 명령 제공.
• 에이전트 커서 시각화를 위한 cursor-overlay 포함.
• UI 표면을 열거하는 list-surfaces 지원.
• screenshot 명령으로 스크린샷 촬영 가능.
• 검색을 위한 list-apps 및 list-windows 제공.
• Windows에서 open-system-surface 지원.
• Chromium에서 CDP를 통해 앱 실행 가능.
• 동기화를 위한 wait 명령 지원.
• 영구 컨텍스트를 위한 session 관리 제공.
• 에이전트 안내를 위한 skills 검색 제공.
• 상태 확인을 위한 status 명령 포함.
• permissions 쿼리 및 요청 지원.
• version 정보 제공.
• list-notifications 및 관련 작업 제공.
• 알림과 상호 작용하는 notification-action 지원.
• clipboard-get, clipboard-set, clipboard-clear 제공.
• 다중 모니터 설정을 위한 list-displays 지원.
• focus-window, resize-window, move-window 지원.
• minimize, maximize, restore 지원.
• Windows에서 open-system-surface 지원.
• Chromium 앱용 CDP와 함께 launch 지원.
• list-apps, list-windows 지원.
• list-displays 지원.
• list-notifications 지원.
• clipboard 명령 지원.
• wait 지원.
• session 및 trace 지원.
• cursor-overlay 지원.
• batch 지원.
• skills 지원.
• status 지원.
• permissions 지원.
• version 지원.
• 토큰 크기를 줄이기 위한 --skeleton 및 --compact 플래그와 함께 snapshot 지원.
• UI 요소 쿼리를 위한 find, get, is 지원.
• list-surfaces 지원.
• scroll, scroll-to 지원.
• expand, collapse 지원.
• select, toggle, check, uncheck 지원.
• clear, focus 지원.
• type, set-value 지원.
• click, double-click, triple-click, right-click 지원.
• press, hover, drag, mouse-move, mouse-click, mouse-wheel 지원.
• key-down, key-up, mouse-down, mouse-up 지원(데몬 대기 중).
• launch, close-app 지원.
• list-apps, list-windows 지원.
• list-displays 지원.
• focus-window, resize-window, move-window 지원.
• minimize, maximize, restore 지원.
• open-system-surface 지원.
• list-notifications, dismiss-notification, dismiss-all-notifications 지원.
• notification-action 지원.
• clipboard-get, clipboard-set, clipboard-clear 지원.
• wait 지원.
• session, trace, cursor-overlay 지원.
• status, permissions, version, batch, skills 지원.
• list-surfaces 지원.
• 다양한 플래그와 함께 snapshot 지원.
• find, get, is 지원.
• scroll, scroll-to 지원.
• expand, collapse 지원.
• select, toggle, check, uncheck 지원.
• clear, focus 지원.
• type, set-value 지원.
• click, double-click, triple-click, right-click 지원.
• press, hover, drag, mouse-move, mouse-click, mouse-wheel 지원.
• key-down, key-up, mouse-down, mouse-up 지원.
• launch, close-app 지원.
• list-apps, ... 지원.
• 현재 macOS 및 Windows로 제한됨; Linux는 계획만 있음.
• OS 수준 접근성 권한 필요; 비기술 사용자에게는 설정이 까다로울 수 있음.
• Windows에서 바이너리가 서명되지 않아 SmartScreen/AV가 차단할 수 있음.
• 일부 명령(key-down, mouse-down 등)은 데몬이 추가될 때까지 자리 표시자입니다.
• JSON 출력이 장황할 수 있음; 대형 앱은 거대한 스냅샷(수만 토큰)을 생성할 수 있음.
• 내장 LLM 통합 없음 – JSON을 자체 모델 프롬프트에 연결해야 함.
• 소스에서 빌드하려면 Rust 툴체인 필요; 순수 JS 패키지가 아님.
• 스냅샷 정확도는 OS 접근성 구현에 따라 달라지며 앱마다 다를 수 있음.

---

이 요약은 프로젝트의 README에만 기반합니다.