agent-desktop 소개
AI 에이전트가 컴퓨터를 직접 조작하는 것은 자율 에이전트 연구에서 핵심 과제 중 하나입니다. 웹 브라우저 자동화 도구들이 이미 성숙한 반면, 운영체제 수준의 데스크톱 애플리케이션 제어는 여전히 복잡하고 불안정한 영역으로 남아있습니다. agent-desktop은 이 문제를 운영체제의 접근성 API(Accessibility API)를 통해 해결하는 Rust 기반 CLI 도구입니다. 스크린샷 기반의 불안정한 컴퓨터 비전 접근 대신, 운영체제가 제공하는 접근성 트리(Accessibility Tree) 구조를 직접 탐색하여 애플리케이션의 UI 요소를 정확하게 식별하고 제어합니다. 시각 장애인 보조 기술에서 사용하던 접근성 API를 AI 에이전트 자동화에 재활용하는 발상의 전환이 돋보입니다.
이 도구의 핵심 차별점은 결정론적 요소 참조(Deterministic Element Refs)와 구조화된 JSON 출력입니다. 일반적인 컴퓨터 사용 AI 에이전트는 화면 캡처를 비전 모델로 분석한 뒤 픽셀 좌표를 기반으로 클릭 위치를 결정합니다. 이 방식은 해상도나 테마 변경에 취약하고 비결정론적입니다. agent-desktop은 운영체제가 각 UI 요소에 부여하는 고유한 접근성 식별자를 사용하므로, 동일한 버튼은 해상도나 위치에 관계없이 항상 같은 참조값으로 식별됩니다. AI 에이전트가 이를 활용하면 더 안정적이고 재현 가능한 자동화가 가능해집니다.
Rust로 구현되어 성능과 메모리 안전성이 뛰어나며, macOS의 Accessibility API를 1차 지원 대상으로 합니다. 또한 MCP(Model Context Protocol) 서버로도 동작할 수 있어 Claude, GPT-4 등의 LLM 기반 에이전트와 직접 연동이 가능합니다. Apache-2.0 라이선스로 공개되어 있어 자유로운 활용이 가능합니다.
agent-desktop의 구조 및 동작 예시
agent-desktop의 구조는 다음과 같습니다:
이제 agent-desktop은 OS 접근성 트리를 JSON 구조로 내보내고, AI 에이전트가 이를 기반으로 정확한 UI 조작을 수행하는 동작을 예시로 살펴보겠습니다:
┌─────────────────────────────────────────────────────┐
│ AI 에이전트 (LLM) │
│ "Save 버튼을 클릭해주세요" │
└────────────────────┬────────────────────────────────┘
│ MCP / JSON API
▼
┌─────────────────────────────────────────────────────┐
│ agent-desktop CLI │
│ - 접근성 트리 탐색 │
│ - 요소 식별 및 JSON 직렬화 │
│ - 결정론적 ref 생성 │
└────────────────────┬────────────────────────────────┘
│ Accessibility API
▼
┌─────────────────────────────────────────────────────┐
│ macOS Accessibility Framework │
│ - NSAccessibility API │
│ - AXElement references │
└────────────────────┬────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 실제 데스크톱 애플리케이션 │
│ (Safari, Finder, Xcode, 터미널 등) │
└─────────────────────────────────────────────────────┘
agent-desktop의 주요 기능
접근성 트리 덤프: 현재 실행 중인 애플리케이션의 전체 UI 구조를 JSON으로 내보냅니다. 버튼, 입력 필드, 메뉴 항목 등 모든 UI 요소와 그 속성을 계층 구조로 표현합니다.
결정론적 요소 참조: 각 UI 요소에 안정적인 고유 식별자를 부여합니다. 화면 레이아웃이 바뀌어도 동일한 버튼은 동일한 참조값을 유지합니다.
MCP 서버 모드: AI 에이전트 프레임워크와의 연동을 위한 MCP 서버로 동작합니다. Claude 같은 LLM이 직접 tool call로 데스크톱을 제어할 수 있습니다.
# 접근성 트리 덤프
agent-desktop dump --app "Safari"
# 출력 예시 (JSON)
# {
# "role": "window",
# "title": "Safari",
# "ref": "ax:window:0x7f8b1c00",
# "children": [
# {
# "role": "button",
# "label": "새 탭",
# "ref": "ax:button:0x7f8b1c08",
# "enabled": true
# }
# ]
# }
설치 및 사용법
Rust 환경에서 소스를 빌드합니다:
git clone https://github.com/lahfir/agent-desktop.git
cd agent-desktop
cargo build --release
또는 cargo install로 설치:
cargo install agent-desktop
기본 사용 예시:
# 전체 접근성 트리 탐색
agent-desktop dump
# 특정 앱의 UI 트리만 출력
agent-desktop dump --app "Finder"
# 특정 요소 클릭 (ref 사용)
agent-desktop click --ref "ax:button:0x7f8b1c08"
# 텍스트 입력
agent-desktop type --ref "ax:textfield:0x7f8b2000" --text "Hello, World"
# MCP 서버 모드로 실행
agent-desktop mcp-server --port 3000
AI 에이전트 연동 예시 (Claude MCP 설정):
{
"mcpServers": {
"agent-desktop": {
"command": "agent-desktop",
"args": ["mcp-server"]
}
}
}
라이선스
이 프로젝트는 Apache-2.0 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용하고 수정할 수 있습니다.
agent-desktop GitHub 저장소
더 읽어보기
-
ShowUI, GUI 에이전트를 위한 경량화된 시각-언어-실행(Vision-Language-Action) 모델에 대한 연구 (feat. ShowLab)
-
ScreenEnv: 데스크탑 에이전트를 위한 Docker 기반 풀스택 자동화 환경 (feat. Hugging Face)
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 