agent-desktop
AI 에이전트를 위한 컴퓨터 사용: 운영체제(OS) 접근성 트리(accessibility tree)를 통해 macOS, Windows 및 Linux에서 데스크톱 앱을 보고 조작할 수 있게 합니다.
<p>
<a href="https://vercel.com/labs#labs-products"><img alt="Vercel Labs Product" src="https://img.shields.io/badge/LABS-PRODUCT-0a0a0a.svg?style=for-the-badge&logo=Vercel&labelColor=000000" height="28"></a>
<a href="https://www.npmjs.com/package/agent-desktop"><img alt="npm version: agent-desktop" src="https://img.shields.io/npm/v/agent-desktop.svg?style=for-the-badge&labelColor=000000" height="28"></a>
<a href="https://github.com/vercel-labs/agent-desktop/blob/main/LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/github/license/vercel-labs/agent-desktop.svg?style=for-the-badge&labelColor=000000" height="28"></a>
<a href="https://www.npmjs.com/package/agent-desktop"><img alt="npm downloads per month: agent-desktop" src="https://img.shields.io/npm/dm/agent-desktop.svg?style=for-the-badge&labelColor=000000&label=npm%20downloads" height="28"></a>
</p>
agent-desktop은 스크린샷이나 픽셀 매칭 없이 AI 에이전트에게 컴퓨터 사용 기능을 제공합니다. 이 도구는 데스크톱 앱의 접근성 트리를 읽어와, 에이전트가 조작할 수 있는 모든 요소에 대한 참조(ref)를 포함하는 JSON 형태로 반환합니다. 에이전트는 해당 참조를 클릭하거나 입력하고, 결과를 확인하기 위해 UI를 다시 읽은 후 반복합니다. 이 루프는 사용자의 에이전트에 존재하며, agent-desktop 자체에는 모델이 내장되어 있지 않습니다. 이는 CLI(Command Line Interface)와 C 라이브러리 형태로 배포됩니다.
스냅샷, 클립보드 읽기, 스크린샷, 명령어 출력 및 디버그 아티팩트는 개인적인 데스크톱 콘텐츠를 포함할 수 있습니다. 이를 공개 로그나 업로드에서 제외하십시오.
설치 방법
npm install -g agent-desktop
agent-desktop status
agent-desktop permissions --guide
Bun, Yarn 및 pnpm은 동일한 패키지를 설치할 수 있습니다. 이 패키지에는 x64 및 ARM64용 네이티브 바이너리(native binaries)와 플랫폼 헬퍼가 포함되어 있습니다.
JavaScript 런처 없이 직접 실행하려면 GitHub Releases에서 일치하는 네이티브 아카이브를 다운로드하고, 해당 실행 파일 옆에 헬퍼 파일을 보관하십시오.
macOS 및 Linux에서는 Homebrew도 작동합니다: brew install agent-desktop. 현재 공식 Scoop 패키지는 없습니다.
해당 저장소는 사용자 지정 Homebrew tap 또는 Scoop bucket을 더 이상 유지 관리하지 않습니다.
릴리스 아카이브와 소스 코드 빌드에 대한 자세한 내용은 Installation를 참조하십시오.
빠른 시작 (Quick start)
agent-desktop snapshot --app Finder -i
agent-desktop click @s8f3k2p9:e8
agent-desktop snapshot --app Finder -i
각 명령어는 하나의 JSON 엔벨로프(JSON envelope)를 출력합니다. 간소화된 스냅샷은 다음과 같습니다:
{
"version": "2.6",
"ok": true,
...
}
- Ref는 해당 스냅샷 ID를 포함합니다. 단순한
@e8은 INVALID_ARGS 오류와 함께 실패합니다.
- UI가 변경된 경우, 동작(action)은
STALE_REF 또는 AMBIGUOUS_TARGET을 반환합니다. 새로운 스냅샷을 찍고 그 ref를 사용하십시오.
- 기본적으로 동작은 헤드리스(headless)입니다: 포인터 이동이나 포커스 변경이 없습니다. 실제 입력을 위해서는
--headed 플래그를 전달하십시오.
- PowerShell에서는 모든 ref에 따옴표(
'@s8f3k2p9:e8')를 붙여야 합니다. 왜냐하면 단순한 @token은 스플래팅 연산자(splatting operator)이기 때문입니다.
전체 과정은 quick start에서 확인할 수 있습니다.
작동 방식 (How it works)
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/architecture-dark.png">
<img alt="호출하는 에이전트가 agent-desktop CLI 또는 C 라이브러리를 실행합니다. 둘 다 agent-desktop-core와 PlatformAdapter 트루트를 거쳐 컴파일 시간에 선택된 하나의 플랫폼 크레이트(platform crate)로 전달되며, 이 크레이트는 macOS의 AX API, Windows의 UI Automation, 또는 Linux의 AT-SPI를 통해 대상 앱을 읽습니다." src="https://raw.githubusercontent.com/vercel-labs/agent-desktop/HEAD/assets/architecture-light.png" width="720">
</picture>
에이전트는 CLI를 호출하거나 프로세스 내의 C 라이브러리를 사용합니다. 둘 다 동일한 코어를 실행하며, 이 코어는 오직 PlatformAdapter를 통해서만 운영체제(OS)에 접근합니다. 각 바이너리는 하나의 OS용으로 빌드되며 해당 OS의 접근성 API와 통신합니다.
AI 에이전트용
이 바이너리는 버전에 맞는 가이드(guides)를 포함하고 있습니다:
agent-desktop skills get desktop
agent-desktop skills get platform
agent-desktop <명령어> --help
이 스킬을 에이전트 하네스(agent harness)에 설치하려면 skills.sh를 사용하세요:
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop
또는 다음 내용을 AGENTS.md에 추가합니다:
Use `agent-desktop` to see and operate desktop apps. Before the first use, run
`agent-desktop skills get desktop` and `agent-desktop skills get platform`, and follow them.
명령 실패 시에는 error.disposition.retry가 safe일 때만 재시도해야 합니다. 엔벨로프(envelope), 오류 코드 및 종료 코드는 JSON 출력을 참조하세요.
MCP
agent-desktop mcp는 모든 명령을 stdio를 통해 MCP 도구로 제공합니다. 이 도구는 해당 명령어 이름(desktop_snapshot, desktop_click, desktop_session_start)으로 명명되며, 해당 명령어의 인수를 받아 JSON 엔벨로프(JSON envelope)를 반환합니다:
{ "mcpServers": { "agent-desktop": { "command": "agent-desktop", "args": ["mcp"] } } }
mcp에 제공되는 --session, --headed, 또는 --trace와 같은 전역 플래그는 모든 호출에 적용됩니다.
명령어 (Commands)
agent-desktop은 60개의 명령어 이름과 56개의 운영 명령어를 가지고 있습니다. 나머지 네 가지(key-down, key-up, mouse-down, mouse-up)는 데몬(daemon)이 눌린 키나 버튼을 해제할 때까지 실행되지 않습니다. 명령어에서 각각의 명령어를 문서화합니다.
| 그룹 | 명령어 (Commands) |
|---|
| Observe | snapshot, find, get, is, screenshot, list-surfaces |
| ... | |
| 플랫폼 | 요구사항 (Requirement) | 접근성 API (Accessibility API) |
|---|
| macOS | macOS 13 이상, Intel 또는 Apple Silicon | AX API |
| ... | | |
각 플랫폼 페이지에는 헤드리스(headless)로 작동하는 것, --headed가 필요한 것, 그리고 실행되지 않는 것이 나열되어 있습니다. | | |
C 라이브러리 (C library)
각 릴리스는 libagent_desktop_ffi를 포함하므로, 프로그램이 프로세스 내에서 agent-desktop을 호출할 수 있습니다. C 라이브러리 문서를 참조하십시오.
import ctypes
lib = ctypes.CDLL("./lib/libagent_desktop_ffi.dylib")
lib.ad_adapter_create.restype = ctypes.c_void_p
...
개발 (Development)
각 플랫폼 어댑터는 자체 OS에서만 빌드되므로, cargo의 범위를 호스트 패키지에 제한해야 합니다. macOS의 경우:
HOST_PKGS=(-p agent-desktop-core -p agent-desktop-macos -p agent-desktop -p agent-desktop-ffi)
cargo test "${HOST_PKGS[@]}"
cargo clippy "${HOST_PKGS[@]}" --all-targets -- -D warnings
Windows에서는 agent-desktop-macos 대신 agent-desktop-windows를 사용하고, Linux에서는 agent-desktop-linux를 사용합니다. CONTRIBUTING.md에 모든 게이트가 나열되어 있습니다.
문서화 (Documentation)
라이선스(License)
Apache-2.0
