IT/AI Tools

Vercel Agent Desktop - AI 에이전트가 Windows와 macOS 데스크톱을 직접 조작하는 방법

sundancekidd 2026. 11. 9. 20:04

 

AI 에이전트가 웹사이트를 열고 정보를 검색하거나 브라우저에서 버튼을 클릭하는 기능은 이제 익숙한 기술이 되었다.

그렇다면 브라우저가 아닌 일반 데스크톱 프로그램도 AI가 직접 조작할 수 있을까?

예를 들어 파일 탐색기에서 폴더를 열고, 메모장에 내용을 입력하거나, 데스크톱 애플리케이션의 메뉴를 선택하는 작업이다.

Agent Desktop은 이러한 작업을 AI 에이전트가 수행할 수 있도록 지원하는 오픈소스 프로젝트다.

Vercel Labs에서 공개한 이 프로젝트는 macOS, Windows, Linux의 운영체제 접근성 API를 이용해 데스크톱 애플리케이션의 UI를 읽고 조작한다.

단순히 화면을 캡처한 다음 좌표를 추측하는 방식이 아니라, 버튼이나 입력창 같은 UI 요소를 구조화된 데이터로 가져와 식별하고 조작한다는 점이 핵심이다.

이번 글에서는 Agent Desktop의 작동 원리와 주요 기능, Windows 설치 방법, Codex와 MCP 연결, 실제 활용 예시까지 살펴본다.

1. Agent Desktop이란?

Agent Desktop은 AI 에이전트에 데스크톱 제어 기능을 제공하는 CLI(Command Line Interface) 및 라이브러리다.

일반적인 AI 모델에는 운영체제의 화면이나 마우스, 키보드를 직접 조작할 권한이 없다. 따라서 실제 컴퓨터에서 작업을 수행하려면 별도의 도구가 필요하다.

Agent Desktop은 이 역할을 담당한다.

AI 에이전트가 Agent Desktop에 명령을 전달하면 운영체제의 접근성 API를 통해 현재 애플리케이션의 UI 구조를 읽고, 원하는 요소를 찾아 클릭하거나 텍스트를 입력한다.

주요 기능은 다음과 같다.

  • 데스크톱 애플리케이션과 창 목록 조회
  • 버튼, 입력창, 메뉴 등의 UI 요소 탐색
  • 마우스 클릭과 키보드 입력
  • 텍스트 입력 및 선택
  • 창 이동, 크기 변경, 최소화 및 최대화
  • 클립보드 읽기와 쓰기
  • 알림 조회 및 닫기
  • 스크린샷과 UI 상태 확인
  • MCP를 통한 AI 에이전트 연동

Agent Desktop 자체에는 AI 모델이 포함되어 있지 않다. 실제 작업의 판단과 계획은 Codex, Claude Code 등 연결된 AI 에이전트가 담당하고, Agent Desktop은 운영체제와 에이전트 사이에서 데스크톱 제어를 수행한다.

2. 기존 화면 자동화와 무엇이 다른가?

기존 데스크톱 자동화는 화면의 특정 좌표를 클릭하거나 이미지 패턴을 찾아 동작하는 방식이 많았다.

예를 들어 화면에서 특정 버튼이 오른쪽 아래에 있다면 좌표를 지정해 클릭하는 식이다.

하지만 창 크기가 바뀌거나 버튼 위치가 이동하면 기존 자동화가 실패할 수 있다.

Agent Desktop은 운영체제의 접근성 트리를 활용한다.

좌표 기반 자동화

일반적인 좌표 기반 자동화의 흐름은 다음과 같다.

  1. 화면을 캡처한다.
  2. 버튼의 위치를 찾는다.
  3. 버튼의 X, Y 좌표를 계산한다.
  4. 해당 좌표를 클릭한다.
  5. 화면을 다시 확인한다.

Agent Desktop 방식

Agent Desktop은 UI 요소를 구조화된 정보로 읽는다.

  1. 대상 애플리케이션의 UI 정보를 가져온다.
  2. 버튼이나 입력창 등의 요소를 식별한다.
  3. 각 요소에 고유한 참조 ID(ref)를 부여한다.
  4. 해당 ref를 이용해 클릭하거나 텍스트를 입력한다.
  5. UI 상태를 다시 읽어 작업 결과를 확인한다.

예를 들어 화면의 버튼을 다음과 같은 구조로 인식할 수 있다.

{
  "role": "button",
  "name": "Save",
  "ref_id": "@s8f3k2p9:e8",
  "available_actions": ["Click"]
}

AI는 화면에서 버튼의 위치를 추측하는 대신 Save라는 이름과 참조 ID를 이용해 해당 버튼을 조작할 수 있다.

이 방식은 UI 요소가 접근성 API에 제대로 노출되어 있다는 전제에서 좌표 기반 자동화보다 안정적인 작업 흐름을 구성하는 데 유리하다.

다만 모든 데스크톱 프로그램이 접근성 정보를 충분히 제공하는 것은 아니다. 접근성 트리에서 요소를 찾지 못하거나 일부 사용자 지정 UI가 노출되지 않는 경우에는 별도의 조작 방식이 필요할 수 있다.

3. 운영체제별 지원 방식

Agent Desktop은 운영체제마다 다른 접근성 API를 사용한다.

운영체제지원 버전접근성 API

macOS macOS 13 이상 AX API
Windows Windows 10 1809 이상 UI Automation
Linux Ubuntu 24.04 이상 AT-SPI

운영체제마다 UI 정보를 읽는 방식은 다르지만, AI 에이전트가 사용하는 명령과 반환 데이터는 공통된 구조로 제공된다.

따라서 동일한 에이전트 워크플로를 여러 운영체제에서 활용할 수 있다.

단, 모든 기능이 모든 운영체제에서 똑같이 동작하는 것은 아니다. 스크린샷, 창 관리, 알림, 시스템 메뉴 등은 운영체제별 지원 범위가 다르므로 실제 환경에서 확인해야 한다.

4. Agent Desktop의 주요 기능

Snapshot - 현재 화면의 UI 구조 읽기

snapshot은 현재 애플리케이션의 UI 구조를 가져오는 명령이다.

agent-desktop snapshot --app "Notepad" -i

결과에는 애플리케이션의 창과 버튼, 입력창 등의 정보가 포함된다.

-i 옵션은 상호작용 가능한 요소를 포함해 조회하는 데 사용한다.

AI 에이전트는 이 결과를 분석해 다음 작업에 필요한 요소를 선택한다.

Ref - UI 요소를 식별하는 참조 ID

Snapshot 결과에 포함되는 ref_id는 특정 UI 요소를 조작하기 위한 참조값이다.

예를 들어 다음과 같은 요소가 있다고 가정하자.

Window: Notepad

Text Editor
  ref: @s8f3k2p9:e1

Save Button
  ref: @s8f3k2p9:e2

AI는 이 참조값을 이용해 입력창에 텍스트를 입력하거나 버튼을 클릭할 수 있다.

agent-desktop click '@s8f3k2p9:e2'

중요한 점은 ref가 해당 Snapshot에 종속된다는 것이다.

UI가 변경되거나 새로운 Snapshot을 가져오면 기존 ref를 더 이상 사용할 수 없을 수 있다. 이 경우 새로운 Snapshot을 생성하고 최신 ref를 사용해야 한다.

Find - 원하는 UI 요소 검색

find는 UI 트리에서 특정 요소를 찾을 때 사용한다.

버튼 이름이나 UI 요소의 속성을 기준으로 검색할 수 있어, 복잡한 애플리케이션에서 원하는 요소를 찾는 데 도움이 된다.

Click과 Type - 실제 UI 조작

UI 요소를 찾았다면 클릭하거나 텍스트를 입력할 수 있다.

agent-desktop click '@s8f3k2p9:e1'
agent-desktop type '@s8f3k2p9:e1' --text "Hello Agent Desktop"

실제 CLI 버전에서 사용하는 인수는 다음 명령으로 확인할 수 있다.

agent-desktop click --help
agent-desktop type --help

Clipboard - 클립보드 제어

클립보드의 내용을 가져오거나 새로운 내용을 설정할 수 있다.

agent-desktop clipboard-get
agent-desktop clipboard-set --text "Hello from AI Agent"

이를 이용하면 다른 프로그램에서 복사한 데이터를 읽거나, AI가 생성한 내용을 클립보드에 넣는 작업을 구성할 수 있다.

Window Management - 창 관리

애플리케이션과 창을 조회하고 관리할 수 있다.

대표 명령은 다음과 같다.

  • list-apps: 실행 중인 애플리케이션 조회
  • list-windows: 창 목록 조회
  • focus-window: 특정 창 활성화
  • resize-window: 창 크기 변경
  • move-window: 창 위치 변경
  • minimize: 창 최소화
  • maximize: 창 최대화
  • restore: 창 복원

이 기능을 활용하면 여러 데스크톱 프로그램을 오가는 자동화도 구성할 수 있다.

5. Windows 설치 방법

Agent Desktop은 npm 패키지로 설치할 수 있다.

Windows 환경에서 설치하기 전에 Node.js 18 이상이 준비되어 있어야 한다.

① Node.js 설치 확인

PowerShell을 열고 다음 명령을 실행한다.

node -v
npm -v

Node.js가 설치되어 있지 않다면 공식 홈페이지에서 LTS 버전을 설치한다.

https://nodejs.org/

② Agent Desktop 설치

다음 명령으로 전역 설치한다.

npm install -g agent-desktop

설치가 끝나면 버전을 확인한다.

agent-desktop version

③ 시스템 상태 확인

agent-desktop status

현재 운영체제와 지원되는 기능, 권한 상태 등을 확인할 수 있다.

Windows에서는 현재 터미널과 동일한 무결성 수준에서 동작하는 애플리케이션에 대해 별도의 접근성 권한 승인이 필요하지 않은 것이 기본이다.

다만 관리자 권한으로 실행되는 프로그램 등 권한 수준이 다른 대상은 접근이 제한될 수 있다.

④ 설치 확인

다음 명령을 실행한다.

agent-desktop --help

명령 목록이 출력되면 기본 설치가 완료된 것이다.

6. 실제 사용 예시 - 메모장 자동화

설치가 끝났다면 Windows 메모장을 대상으로 간단한 테스트를 진행해 볼 수 있다.

① 메모장 실행

agent-desktop launch --app "Notepad"

애플리케이션 실행이 끝나면 현재 UI를 조회한다.

agent-desktop snapshot --app "Notepad" -i

② 입력창 확인

Snapshot 결과에서 텍스트 편집 영역을 찾는다.

실제 ref는 실행 환경에서 반환된 값을 사용해야 한다.

③ 텍스트 입력

agent-desktop type '<실제-ref>' --text "Hello, Agent Desktop!"

④ 결과 확인

agent-desktop snapshot --app "Notepad" -i

텍스트가 정상적으로 입력되었는지 확인한다.

이처럼 Snapshot → UI 요소 식별 → 입력 → 재확인의 순서로 작업을 진행한다.

7. Codex와 연결하기

Agent Desktop은 독립적인 CLI로 사용할 수도 있지만, AI 에이전트에 연결하면 활용도가 높아진다.

Codex와 같은 에이전트가 작업을 계획하고 Agent Desktop이 실제 데스크톱을 조작하는 구조다.

① Agent Desktop Skill 설치

프로젝트에서 제공하는 Skill을 설치한다.

npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop

Skill은 AI 에이전트가 명령을 어떤 순서로 사용해야 하는지, Snapshot과 ref를 어떻게 관리해야 하는지 알려주는 지침이다.

② 에이전트에 사용 방법 전달

프로젝트의 AGENTS.md에 다음 내용을 추가할 수도 있다.

Use agent-desktop to see and operate desktop apps.

Before the first use, run:

agent-desktop skills get desktop
agent-desktop skills get platform

Follow the instructions returned by these commands.

이렇게 하면 에이전트가 처음 사용할 때 기본 작업 방식과 운영체제별 차이를 확인하도록 유도할 수 있다.

③ 실제 작업 요청

Codex에 다음과 같이 요청할 수 있다.

Use agent-desktop to:

1. Open Windows Notepad.
2. Inspect the current UI.
3. Enter the following text:

   Agent Desktop is working!

4. Read the UI again.
5. Verify that the text was entered correctly.

Codex가 작업을 계획하고 Agent Desktop 명령을 호출하는 방식이다.

8. MCP 서버로 연결하기

Agent Desktop은 MCP(Model Context Protocol) 서버로도 사용할 수 있다.

MCP를 이용하면 AI 에이전트가 Agent Desktop의 기능을 도구 형태로 호출할 수 있다.

서버 실행 명령은 다음과 같다.

agent-desktop mcp

MCP 클라이언트의 설정 파일에는 다음과 같은 서버 구성을 추가한다.

{
  "mcpServers": {
    "agent-desktop": {
      "command": "agent-desktop",
      "args": ["mcp"]
    }
  }
}

이후 MCP를 지원하는 AI 에이전트에서 서버를 연결하면 명령을 도구 형태로 사용할 수 있다.

대표적인 도구 이름은 다음과 같다.

  • desktop_snapshot
  • desktop_click
  • desktop_session_start

CLI의 명령을 MCP 도구로 제공하기 때문에 별도의 기능 구현 없이 기존 데스크톱 제어 기능을 AI 에이전트에 연결할 수 있다.

--session, --headed, --trace 같은 전역 옵션도 MCP 실행 시 전달할 수 있다.

9. 고급 기능 - C 라이브러리와 FFI

Agent Desktop은 CLI뿐 아니라 C ABI 기반 라이브러리도 제공한다.

이를 이용하면 매번 외부 프로세스를 실행하지 않고 애플리케이션 내부에서 Agent Desktop 기능을 호출할 수 있다.

지원 언어 및 환경은 다음과 같다.

  • C / C++
  • Python
  • Swift
  • Go
  • Ruby
  • Node.js

예를 들어 Python에서는 ctypes 등을 이용해 네이티브 라이브러리를 호출할 수 있다.

이 구조는 자체 AI 에이전트 프레임워크를 개발하거나, 데스크톱 자동화 기능을 기존 애플리케이션에 통합할 때 유용하다.

C 라이브러리는 npm 패키지에 포함되지 않으며, 각 릴리스에서 별도로 제공되는 라이브러리를 사용해야 한다.

10. 활용할 수 있는 분야

Agent Desktop은 단순한 화면 자동화보다 AI 에이전트가 실제 컴퓨터를 사용하는 환경을 만드는 데 적합하다.

사무 작업 자동화

  • 문서 편집 프로그램 실행
  • 데이터 입력 및 수정
  • 파일 탐색기에서 폴더 이동
  • 클립보드 기반 데이터 전달
  • 여러 프로그램 간 반복 작업

QA 및 소프트웨어 테스트

  • 데스크톱 프로그램 실행
  • 버튼과 메뉴 탐색
  • 입력값 테스트
  • 특정 UI 상태 확인
  • 작업 전후 결과 비교

특히 UI 요소를 구조적으로 확인할 수 있어 반복적인 테스트 절차를 에이전트에 맡기는 데 활용할 수 있다.

게임 개발 도구 자동화

게임 개발 환경에서도 활용 가능성이 있다.

예를 들어 Godot 에디터나 다른 데스크톱 도구에서 반복적인 UI 작업을 수행하거나, 특정 설정 화면을 열고 값을 변경하는 작업을 자동화할 수 있다.

다만 에디터의 사용자 지정 UI가 접근성 트리에 얼마나 노출되는지에 따라 자동화 범위가 달라질 수 있다.

개인 PC 관리

  • 실행 중인 프로그램 조회
  • 특정 프로그램 실행 및 종료
  • 창 정리
  • 클립보드 내용 관리
  • 알림 확인

이런 기능을 다른 시스템 정보 수집 도구와 연결하면 개인 PC 관리용 AI 에이전트로 확장할 수 있다.

11. 사용 시 주의사항

Agent Desktop은 실제 데스크톱에 접근하는 도구이므로 보안과 권한 관리가 중요하다.

UI 데이터의 개인정보

Snapshot, 클립보드, 스크린샷에는 개인 문서, 이메일, 계정 정보 등이 포함될 수 있다.

디버그 로그나 외부에 업로드하는 파일에 민감한 정보가 포함되지 않도록 주의해야 한다.

ref의 유효 기간

ref는 해당 Snapshot에 종속된다.

UI가 변경된 뒤 이전 ref를 계속 사용하면 STALE_REF 또는 AMBIGUOUS_TARGET 오류가 발생할 수 있다.

이런 경우 무조건 같은 명령을 반복하기보다는 새로운 Snapshot을 가져와 요소를 다시 식별해야 한다.

자동화 작업의 안전성

파일 삭제, 이메일 발송, 결제, 시스템 설정 변경처럼 실제 결과에 영향을 주는 작업은 AI가 임의로 실행하지 않도록 별도의 승인 절차를 두는 것이 좋다.

Agent Desktop의 오류 응답에는 재시도 가능 여부와 복구 힌트가 포함될 수 있다. 재시도는 오류의 안내를 확인한 뒤 안전하다고 판단되는 경우에만 수행해야 한다.

12. 마무리

Agent Desktop은 AI 에이전트가 브라우저를 넘어 일반 데스크톱 애플리케이션까지 다룰 수 있도록 지원하는 프로젝트다.

특히 운영체제의 접근성 API를 활용해 UI 요소를 구조적으로 읽고, 참조 ID를 기반으로 조작한다는 점이 인상적이다.

단순히 화면의 좌표를 클릭하는 자동화가 아니라, 현재 UI의 상태를 읽고 작업을 수행한 뒤 다시 확인하는 구조이기 때문에 AI 에이전트의 컴퓨터 사용 능력을 확장하는 데 유용하다.

Codex나 Claude Code와 연결하면 자연어로 작업을 요청하고 실제 데스크톱 프로그램을 조작하는 자동화 환경을 구성할 수 있다.

앞으로 AI 에이전트가 코드 작성뿐 아니라 문서 편집, 데이터 입력, 프로그램 테스트, 데스크톱 관리까지 수행하는 방향으로 발전한다면 Agent Desktop과 같은 도구의 활용 범위도 넓어질 것으로 보인다.

공식 프로젝트 및 참고 자료

저작자표시 비영리 변경금지 (새창열림)