AI 칼럼

업무 자동화@donghyeok99운영진

agent-desktop: 에이전트가 데스크톱 앱을 직접 누르게 하는 CLI

스크린샷 한 장 없이, 에이전트가 Finder나 Slack 창을 JSON으로 읽고 버튼을 누르게 해 주는 CLI예요

snapshot이 Finder 창을 읽어 Documents에 ref e8을 붙이고, click 한 번에 창이 바뀐 뒤 다시 읽어 확인해요. 포인터는 움직이지 않아요.
snapshot이 Finder 창을 읽어 Documents에 ref e8을 붙이고, click 한 번에 창이 바뀐 뒤 다시 읽어 확인해요. 포인터는 움직이지 않아요.
누가
Vercel Labs의 저장소로, 1.2.0의 변경은 모두 lahfir가 올렸어요. 에이전트에게 브라우저 밖 데스크톱 앱 일까지 맡기고 싶은 사람을 위한 도구예요.
언제
저장소는 2026년 2월 19일에 열렸어요. 11월 3일 1.1.0에 이어 11월 5일 1.2.0에서 agent-desktop mcp가 들어왔어요.
어디서
macOS 13 이상, Windows 10 1809 이상, Ubuntu 24.04 이상의 내 컴퓨터에서 돌아요. 셸을 쓰는 에이전트는 CLI로, MCP 클라이언트는 MCP 서버로 붙여요.

이게 불편했어요

에이전트에게 브라우저 밖의 일을 맡기면 금방 막혀요. 설정 창의 체크박스를 바꾸거나 Finder에서 폴더를 여는 일도 화면을 찍어 보고 좌표를 짐작해 눌러야 하고, 제대로 눌렸는지 보려면 또 찍어야 했어요.

그래서 이렇게 풀어요

agent-desktop은 화면 대신 운영체제의 접근성 트리를 읽어요. 앱 창을 JSON으로 돌려주면서 누를 수 있는 요소마다 ref를 붙이고, 에이전트는 그 ref로 click이나 type을 한 뒤 다시 snapshot을 떠서 결과를 확인해요. 기본이 헤드리스라 마우스 포인터를 움직이거나 포커스를 빼앗지 않고, 화면이 바뀌어 ref가 낡으면 누르지 않고 거절해요.

README의 구조도: 에이전트가 CLI나 C 라이브러리를 거쳐 OS별 접근성 API에 닿아요
README의 구조도: 에이전트가 CLI나 C 라이브러리를 거쳐 OS별 접근성 API에 닿아요
agent-desktop snapshot --app Finder -i      # interactive elements, each with a ref{"ok": true,"command": "snapshot","app": "Finder","ref_count": 59,{ "role": "treeitem", "name": "Documents", "ref_id": "@s8f3k2p9:e8", "available_actions": ["Click"] }agent-desktop click @s8f3k2p9:e8            # act on a ref from that snapshotagent-desktop snapshot --app Finder -i      # observe again to verify
README의 실행 예시

이걸로 만든 사람들

flaviocopes.comFlavio Copes2026-11-01

Ubuntu 24.04 XFCE에서 1.0.2를 직접 돌려, Mousepad 편집기의 텍스트 칸을 snapshot으로 찾고 set-value로 바꾼 뒤, 저장 안 된 버퍼만 바뀌고 디스크의 파일은 그대로인 것까지 확인한 기록이에요.

The app was Mousepad, the XFCE text editor.

안에서는 이렇게 돌아가요

  1. 1

    나 → 내 에이전트

    Finder에서 Documents 열어 줘에이전트는 스킬에 적힌 대로 읽고, 누르고, 다시 읽어 확인하는 순서를 따라요.skills/agent-desktop/SKILL.md
  2. 2

    내 에이전트 → agent-desktop CLI

    agent-desktop snapshot --app Finder -iMCP로 붙이면 같은 명령이 desktop_snapshot 도구로 불려요. 도구 목록은 CLI 명령에서 그대로 만들어져요.src/mcp/catalog.rs
  3. 3

    agent-desktop CLI → AX · UI Automation · AT-SPI

    앱의 접근성 트리 읽기macOS에서는 PlatformAdapter가 AX API를 불러요. Windows와 Linux는 각자의 crate가 같은 일을 해요.crates/macos/src/adapter.rs
  4. 4

    agent-desktop CLI → 내 에이전트

    ref가 붙은 JSON 봉투누를 수 있는 요소마다 @s8f3k2p9:e8 같은 ref를 붙여요. ref는 그 snapshot에서만 통해요.crates/core/src/refs/ref_alloc.rs
  5. 5

    내 에이전트 → agent-desktop CLI

    agent-desktop click @s8f3k2p9:e8누르기 전에 그 요소를 다시 찾아 맞는지 보고, 화면이 바뀌었으면 STALE_REF로 거절해요.crates/core/src/refs/resolve_saved_ref.rs
  6. 6

    agent-desktop CLI → 바뀐 앱 창과 JSON 결과

    접근성 호출로 클릭포인터와 포커스는 그대로 두고 눌러요. 에이전트는 같은 창을 다시 snapshot해 결과를 확인해요.crates/core/src/commands/click.rs

넣으면 이렇게 나와요

agent-desktop snapshot --app Finder -iFinder 창의 누를 수 있는 요소마다 ref가 붙은 JSON이 와요. README 예시에서는 ref가 59개예요.
snapshot --skeleton --app Slack -i --compact요소가 많은 앱은 얕은 지도부터 받고, --root로 한 영역만 파고들어요.
agent-desktop mcp모든 명령이 desktop_snapshot, desktop_click 같은 MCP 도구가 돼요.

나한테 맞을까요

이럴 때 좋아요

  • 브라우저가 아닌 Finder, 메모, 설정 창 같은 데스크톱 앱을 에이전트에게 맡기고 싶을 때
  • 에이전트가 앱을 다루는 동안 내 마우스와 포커스를 빼앗기기 싫을 때
  • 쓰던 MCP 클라이언트에 데스크톱 조작 도구를 붙이고 싶을 때
  • macOS, Windows, Linux를 같은 명령으로 다루고 싶을 때

이건 안 돼요

  • macOS에서는 처음에 손쉬운 사용(Accessibility) 권한을 직접 줘야 해요.
  • 더블클릭, 호버, 드래그처럼 실제 입력이 필요한 동작은 --headed를 줘야 하고, 무엇이 헤드리스로 되는지는 OS마다 달라요.
  • snapshot, 클립보드, 스크린샷 결과에 내 화면의 개인 내용이 담길 수 있어 공개 로그에 남기면 안 돼요.
  • Apache-2.0이라 회사에서도 쓰고 고쳐 배포할 수 있어요. 배포할 때는 라이선스 고지를 함께 넣어야 해요.

발행 전에 Devalley 편집자가 검토했어요. 칼럼은 어떻게 만드나요

로그인하면 글을 쓰고 댓글과 좋아요로 참여할 수 있어요.로그인

신고하기

사유

커뮤니티 규칙 보기