이 가이드로 하는 것 클로드 코드에 에이전트 데스크톱(agent-desktop)을 연동하고, 마우스 포인터를 움직이거나 창을 가리지 않으면서 컴퓨터 앱을 직접 조작하게 합니다.
매일 반복되는 업무 속에서 수많은 창을 띄워 두고 일일이 마우스로 버튼을 누르며 값을 복사해 넣다 보면 피로가 쌓이기 마련입니다.
인공지능이 코드를 대신 짜주고 긴 문서를 요약해 주는 시대가 되었지만, 정작 내 컴퓨터 화면 위에 떠 있는 일상적인 앱들을 다루는 일은 여전히 사람의 손끝을 벗어나지 못하고 있습니다.
마우스를 움직이거나 창을 앞으로 가져오지 않으면서, 프로그램의 버튼을 누르고 필요한 값을 입력해 주는 도구가 있습니다.
버셀 랩스(Vercel Labs)에서 공개한 오픈소스 도구인 에이전트 데스크톱(agent-desktop)입니다. 화면 사진이나 픽셀 매칭 없이, 운영체제가 알려 주는 앱의 요소 구조를 읽어 앱을 조작합니다.
1. 에이전트 데스크톱(agent-desktop)이란 무엇인가
에이전트 데스크톱(agent-desktop)은 인공지능 에이전트가 데스크톱 애플리케이션을 직접 보고 조작할 수 있도록 설계된 컴퓨터 사용(Computer use) 오픈소스 도구입니다.
버셀 랩스(Vercel Labs)의 제품으로 소개되어 있으며, 누구나 쓸 수 있는 오픈소스입니다. 라이선스는 아파치 라이선스 2.0(Apache-2.0)을 따릅니다.
깃허브 저장소(vercel-labs/agent-desktop) 기준(2026년 11월 9일)으로 이 프로젝트는 별(stargazer) 19,697개, 포크(fork) 1,462개를 기록하고 있습니다.
에이전트 데스크톱은 터미널에서 실행하는 CLI(명령줄 인터페이스)와 다른 프로그램 안에서 직접 호출할 수 있는 C 라이브러리(libagent_desktop_ffi) 형태로 함께 배포됩니다.
공식 README 문서에 따르면 에이전트 데스크톱에는 총 60개의 명령 이름이 정의되어 있으며, 이 가운데 56개는 즉시 실행 가능한 동작 명령입니다. 나머지 4개 명령(key-down, key-up, mouse-down, mouse-up)은 눌려 있는 키나 마우스 버튼을 안전하게 해제할 수 있는 데몬 환경이 갖춰질 때까지 실행이 보류되도록 설계되어 있습니다.
2. 어떻게 동작하는가 (공식 README 기준)
공식 README 문서에 설명된 에이전트 데스크톱의 동작 원리는 이렇습니다. 에이전트 데스크톱은 화면 사진(스크린샷)이나 픽셀 매칭을 쓰지 않습니다. 대신 각 운영체제에 내장된 접근성 트리(accessibility tree)를 직접 읽어 JSON 형식의 데이터로 변환합니다.
접근성 트리는 창 안에 어떤 버튼과 텍스트 필드, 메뉴 항목이 있는지를 운영체제가 구조로 알려 주는 정보입니다. 에이전트 데스크톱은 이를 읽어 들여 에이전트가 조작할 수 있는 모든 대화형 요소에 고유한 참조 번호인 ref_id(예: @s8f3k2p9:e8)를 부여합니다.
동작 순서는 다음과 같은 단계로 이어집니다.
- 앱의 접근성 트리를 읽어 각 요소에 ref가 부여된 JSON 스냅샷을 생성합니다.
- 에이전트가 해당 ref를 지정하여 클릭(
click)하거나 값을 입력(set-value,type)합니다. - 작업이 끝나면 UI의 상태를 다시 읽어 결과를 점검합니다.
- 목표한 작업이 끝날 때까지 이 과정을 반복합니다.
여기서 한 가지 주목해야 할 특징은 에이전트 데스크톱 자체에는 인공지능 모델이 전혀 포함되어 있지 않다는 점입니다(agent-desktop has no model inside). 무엇을 누르고 어떤 값을 넣을지 판단하며 과정을 이끌어가는 루프는 클로드 코드와 같은 에이전트 측에 존재합니다(The loop lives in your agent).
또한 에이전트 데스크톱은 기본적으로 헤드리스(Headless by default) 방식으로 동작합니다. 마우스 포인터를 직접 이동시키거나 대상 창의 포커스를 화면 맨 앞으로 강제로 가져오지 않고, 접근성 API를 통해 백그라운드에서 직접 명령을 전달합니다. 만약 물리적인 마우스 움직임이나 키보드 입력이 필요한 특수한 상황이라면 전역 플래그인 --headed를 주어 실제 입력을 허용할 수도 있습니다.
3. 지원 환경 (공식 README 기준)
에이전트 데스크톱은 맥, 윈도우, 리눅스 주요 운영체제를 모두 지원합니다. 각 플랫폼별 요구 사항과 사용하는 접근성 API는 공식 README 문서에 다음과 같이 정리되어 있습니다.
| Platform | Requirement | Accessibility API |
|---|---|---|
| macOS | macOS 13 or later, Intel or Apple Silicon | AX API |
| Windows | Windows 10 1809 or later, x64 or ARM64 | UI Automation |
| Linux | Ubuntu 24.04 or later, x86_64 or aarch64, X11 or Wayland | AT-SPI |
각 운영체제별 빌드는 해당 환경의 고유한 접근성 API를 직접 호출하도록 구현되어 있습니다. macOS 환경에서는 AX API를 사용하고, Windows에서는 UI Automation을 거치며, Linux에서는 AT-SPI를 통해 앱 내부의 요소를 파악합니다.
4. 설치 및 에이전트 연동
에이전트 데스크톱을 컴퓨터에 설치하고 클로드 코드와 같은 에이전트에 연결하는 과정은 명확하게 정리되어 있습니다.
패키지 설치
Node.js 환경이 갖추어져 있다면 터미널에서 다음 명령어로 전역 설치를 진행합니다.
npm install -g agent-desktop
공식 설명에 따르면 Bun, Yarn, pnpm 패키지 관리자를 통해서도 동일한 패키지를 설치할 수 있습니다. 설치 패키지 안에는 x64 및 ARM64 아키텍처에 맞춘 네이티브 바이너리와 플랫폼 헬퍼가 함께 포함되어 있습니다.
상태 확인 및 권한 점검
설치가 완료된 후 터미널에 다음 명령을 입력하여 현재 시스템 상태와 접근성 권한을 확인합니다.
agent-desktop status
운영체제 플랫폼 종류, 접근성 권한 부여 여부, 제어 가능한 서피스 목록이 JSON 형태로 출력됩니다. macOS 사용자의 경우 시스템 설정의 접근성 권한을 부여하는 과정이 필요하므로, 공식 문서에서는 안내에 따라 진행할 수 있도록 다음 명령어를 제공합니다.
agent-desktop permissions --guide
클로드 코드(Claude Code) 스킬 연동
클로드 코드 환경에서 에이전트 데스크톱을 도구로 활용하려면 스킬을 등록해 주어야 합니다. 터미널에서 다음 한 줄의 명령어로 공식 스킬을 추가할 수 있습니다.
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop
아울러 에이전트가 작업할 때 참고할 수 있도록 프로젝트의 AGENTS.md 파일에 아래 안내 문구를 추가하는 방법이 공식 README에 권장되어 있습니다.
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.
MCP(Model Context Protocol) 설정
표준 입출력(stdio)을 통해 도구를 호출하는 MCP 서버 형태로 사용하고자 할 때는 설정 파일에 아래 JSON 구문을 추가합니다.
{ "mcpServers": { "agent-desktop": { "command": "agent-desktop", "args": ["mcp"] } } }
agent-desktop mcp 명령은 에이전트 데스크톱이 제공하는 모든 명령을 MCP 도구 형태로 제공합니다.
5. 직접 다뤄 보기: 윈도우 문자표 조작 예시 (실제 실행 자료 기준)
실제 데스크톱 환경에서 에이전트 데스크톱이 어떻게 명령을 내리고 결과를 받아오는지, 2026년 11월 8일 Windows 11에서 윈도우 기본 보조프로그램인 '문자표'(charmap)를 대상으로 실행한 명령과 결과를 단계별로 살펴보겠습니다.
1) 시스템 상태 점검
먼저 agent-desktop status 명령을 실행하여 현재 윈도우 환경의 권한 상태를 점검합니다.
실행 결과 ok: true, platform: "windows", permissions.accessibility.state: "granted"가 반환되었으며, 지원되는 서피스(supported_surfaces)로는 window, focused, sheet, menu, start-menu, taskbar, system-tray, system-tray-overflow, action-center가 표시되었습니다. 도구 버전은 1.2.0이며 CLI 출력 봉투의 버전은 2.6으로 나타났습니다.
2) 앱 실행하기
제어할 대상 앱을 실행하기 위해 launch 명령을 내립니다.
agent-desktop launch charmap
명령이 실행되면 ok: true와 함께 charmap.exe 프로세스가 실행되고 창 제목이 "문자표"로 인식됩니다.
여기서 한 가지 참고할 사항이 있습니다. 윈도우 환경에서 실행 파일 이름만으로 곧바로 실행할 수 있는 대상은 System32 폴더나 Windows 폴더에 위치한 프로그램들입니다. 예를 들어 mspaint는 APP_NOT_FOUND 오류가 나왔고, 이럴 때는 실행 파일의 절대 경로를 전달하거나 System32 또는 Windows 폴더에 있는 프로그램 이름을 쓰라는 안내 메시지가 나타납니다.
3) 앱 화면 읽기 (스냅샷 생성)
실행된 문자표 앱의 내부 구조를 읽기 위해 대화형 요소를 중심으로 스냅샷을 생성합니다.
agent-desktop snapshot --app charmap -i --compact
이 명령을 내리면 총 17개의 대화형 요소(ref_count: 17)가 JSON 트리로 추출됩니다. 추출된 요소의 예시는 다음과 같습니다.
@<snapshot_id>:e1: 텍스트 필드 "복사할 문자(A):" (사용 가능한 동작: SetValue, SetFocus)@<snapshot_id>:e2: 버튼 "선택(S)" (사용 가능한 동작: Click)@<snapshot_id>:e3: 버튼 "복사(C)" (비활성화 상태)@<snapshot_id>:e4: 체크박스 "고급 보기(V)" (사용 가능한 동작: Toggle)@<snapshot_id>:e5: 콤보박스 "글꼴(F):" (현재 값 Arial)@<snapshot_id>:e8: 링크 "도움말(H)"
각 요소에는 현재 스냅샷 고유 식별자가 접두어로 붙은 참조 번호(@<snapshot_id>:e1)가 부여됩니다.
4) 값 입력하기
문자표의 텍스트 입력칸인 e1 요소를 대상으로 텍스트를 입력합니다.
agent-desktop set-value '@<snapshot_id>:e1' "hello"
명령을 수행하면 ok: true와 함께 disposition.delivery: "delivered_verified", post_state.value: "hello"가 반환됩니다. 동작 방식은 윈도우 접근성 체계의 ValuePattern.SetValue(semantic_api)를 통해 이루어집니다. 이후 다시 스냅샷을 찍어 확인해 보면 입력칸의 값이 "hello"로 반영되어 나타납니다.
여기서 중요한 주의점이 하나 있습니다. 파워셸(PowerShell) 환경을 사용할 때는 @ 기호가 스플래팅(splatting) 연산자로 동작하기 때문에, ref 인자를 전달할 때 반드시 '@<snapshot_id>:e1'처럼 작은따옴표로 감싸서 입력해야 합니다.
5) 창 화면 캡처 및 앱 종료
입력 결과가 정상적으로 반영되었는지 시각적으로 보존하기 위해 캡처 명령을 실행할 수 있습니다.
agent-desktop screenshot --app charmap charmap_hello.png
전체 모니터 화면이 아니라 문자표 창 영역만 정확히 556x528 픽셀 크기의 PNG 이미지로 저장되며, 입력칸에 "hello"가 적힌 상태를 보관할 수 있습니다.
작업이 모두 끝난 뒤에는 아래 명령으로 앱을 안전하게 닫습니다.
agent-desktop close-app charmap
결과로 delivered_verified와 process_instance_exited가 반환되며 실행되었던 창이 종료됩니다.
5-2. 설정 스위치, 확인 팝업, 앱 열고 닫기, 웹 검색창 (윈도우 11 실행 결과)
문자표 말고도 일상에서 마주치는 화면들을 같은 방식으로 조작해 보았습니다. 모두 2026년 11월 9일 윈도우 11에서 실행한 결과입니다.
윈도우 설정의 스위치 켜고 끄기
설정 앱의 디스플레이 화면에서 야간 모드 스위치, 체크박스, 선택칸이 모두 요소 목록으로 읽혔습니다. 스위치는 click이 아니라 toggle 명령으로 바꿔야 상태가 바뀌었습니다.
agent-desktop toggle '@<snapshot_id>:e47'
agent-desktop is '@<snapshot_id>:e47' --property checked
두 번째 명령으로 상태를 읽으면 false에서 true로, 다시 한 번 toggle하면 false로 돌아오는 것을 확인할 수 있습니다.
확인 팝업의 버튼 누르기
엑셀 같은 앱이 띄운 알림 창은 별도의 창으로 잡힙니다. list-windows로 창 번호를 확인한 뒤 그 창의 스냅샷에서 "확인" 버튼의 번호표를 찾아 click을 보내면 팝업이 닫힙니다.
agent-desktop click '@<snapshot_id>:e1'
앱 열고 닫기
System32나 Windows 폴더에 있는 프로그램은 이름만으로 launch 할 수 있고, 그 밖의 프로그램은 실행 파일의 전체 경로를 넘기면 열립니다. 닫을 때는 close-app을 쓰는데, 저장하지 않은 문서가 있으면 앱이 "저장하시겠습니까?" 창을 띄우고 기다립니다. 이 창의 "저장 안 함" 버튼도 같은 방식으로 눌러 주면 앱이 끝까지 종료됩니다.
웹 페이지 검색창
크롬을 접근성 옵션(--force-renderer-accessibility)을 켜고 열면 웹 페이지 안의 검색창과 버튼이 요소 목록에 잡힙니다. 검색창에 set-value로 글자를 넣고, 검색 버튼에 click을 보내면 결과 링크의 글자와 주소까지 목록으로 읽어 올 수 있습니다.
6. 사용하기 전에 알아 둘 주의사항 (공식 README 기준)
에이전트 데스크톱을 일상 업무나 개발 워크플로에 도입하기 전에 숙지해 두어야 할 몇 가지 사항이 있습니다.
참조 번호(ref)의 유효 범위와 화면 갱신
모든 참조 번호(ref)는 해당 스냅샷에 종속되어 있습니다. 스냅샷 식별자가 빠진 단독 번호(예: @e8)를 넘기면 INVALID_ARGS 오류가 발생하며 거절됩니다.
또한 프로그램 화면이 바뀌거나 팝업이 뜨는 등 UI 구성에 변화가 생기면 기존 참조 번호는 무효화되어 STALE_REF 또는 AMBIGUOUS_TARGET 오류가 반환됩니다. 대상 앱의 화면 상태가 달라졌을 때는 새로운 스냅샷을 다시 생성하여 새로 발급된 ref를 사용해야 합니다.
다중 창 환경에서의 대상 지정
하나의 프로그램에서 여러 개의 창이 동시에 열려 있는 경우 대상을 명확히 특정할 수 없어 AMBIGUOUS_TARGET 오류가 반환될 수 있습니다. 이때는 스냅샷 명령의 오류 상세 내역(error.details)에 나열되는 후보 창 식별자 목록을 확인한 뒤, --window-id 옵션을 붙여 원하는 특정 창을 명시적으로 지정해 주어야 합니다.
단순 반복을 도구에 넘기고 내 저녁을 지키기
우리가 컴퓨터 환경에서 새로운 자동화 도구를 찾아서 설치하고 다루는 이유는, 기술 그 자체에 얽매이기 위해서가 아닙니다. 매일 모니터 앞에서 수많은 창을 마우스로 일일이 누르고 값을 복사해 넣느라 늦은 시간까지 야근에 쫓기던 무의미한 반복을 줄이고, 내 집중력과 소중한 저녁 시간을 지켜내기 위해서입니다.
클로드 코드와 에이전트 데스크톱을 결합하면, 마우스를 뺏기거나 화면을 가리는 불편함 없이도 컴퓨터 앱에 필요한 작업을 조용히 맡길 수 있습니다. 사람이 일일이 화면을 쳐다보며 클릭하던 과정을 인공지능 에이전트가 접근성 트리를 통해 차분하게 처리하도록 넘겨줄 수 있습니다.
오늘 저녁 터미널을 열고 에이전트 데스크톱의 상태를 점검한 뒤, 클로드 코드에 스킬을 연결해 보세요. 머릿속으로만 생각했던 일상의 작은 조작들을 에이전트에게 맡겨 보면서 내 시간을 지키는 방식을 경험해 보시기 바랍니다.
내 업무에 적용하고 싶다면
가이드를 읽고도 내 업무에 어떻게 적용할지 막막하시다면, 홈페이지 문의 폼으로 상담을 신청해 주세요. 문의 분야에서 '생성형 AI 실무 교육·특강' 또는 '기타 제휴 및 솔루션 도입'을 고르시면 됩니다.
출처 및 참고 자료
- 공식 깃허브 저장소: https://github.com/vercel-labs/agent-desktop
- 공식 문서 사이트: https://agent-browser.dev/desktop
