Computer use CLI for AI agents

代理桌面

AI 代理的计算机使用：通过操作系统辅助功能树查看和操作 macOS、Windows 和 Linux 上的桌面应用程序。

agent-desktop 为 AI 代理计算机提供使用，无需屏幕截图或像素匹配。它读取桌面应用程序的辅助功能树并将其作为 JSON 返回，并为代理可以操作的每个元素提供引用。代理单击或键入参考，再次读取 UI 以检查结果，然后重复。循环存在于你的代理中； agent-desktop 内部没有模型。它作为 _TERM 和 C Library 提供。

快照、剪贴板读取、屏幕截图、命令输出和调试工件可以包含私有桌面内容。让它们远离公共日志和上传。

＃＃安装

npm install -g agent-desktop
agent-desktop status                # platform, permissions, supported surfaces
agent-desktop permissions --guide   # macOS: walks you through the Accessibility grant

Bun、Yarn 和 pnpm 可以安装相同的包。它包括适用于 x64 和 ARM64 的本机二进制文件和平台帮助程序。要在没有 JavaScript 启动器的情况下直接执行，请从以下位置下载匹配的本机存档 GitHub 版本并将其帮助程序放在可执行文件旁边。

在 macOS 和 Linux 上，Homebrew 也可以使用：“brew install agent-desktop”。目前还没有官方的 Scoop 包。存储库不再维护自定义 Homebrew Tap 或 Scoop 存储桶。

安装中介绍了发布档案和从源代码构建。

快速开始

agent-desktop snapshot --app Finder -i      # interactive elements, each with a ref
agent-desktop click @s8f3k2p9:e8            # act on a ref from that snapshot
agent-desktop snapshot --app Finder -i      # observe again to verify

每个命令都会打印一个 JSON 信封。修剪后的快照：

{
  "version": "2.6",
  "ok": true,
  "command": "snapshot",
  "data": {
    "app": "Finder",
    "snapshot_id": "s8f3k2p9",
    "ref_count": 59,
    "complete": true,
    "tree": {
      "role": "window",
      "name": "Downloads",
      "children": [
        { "role": "treeitem", "name": "Documents", "ref_id": "@s8f3k2p9:e8", "available_actions": ["Click"] }
      ]
    }
  }
}

Refs 带有他们的快照 ID。裸露的“@e8”失败并显示“INVALID_ARGS”。
如果 UI 发生更改，操作将返回“STALE_REF”或“AMBIGUOUS_TARGET”。拍摄新快照并使用其参考。
默认情况下，操作是无头的：没有指针移动，没有焦点变化。通过“–headed”进行物理输入。
在 PowerShell 中，引用每个引用 ('@s8f3k2p9:e8')，因为裸露的 @token 是splatting 运算符。

完整的演练位于快速入门。

它是如何工作的

您的代理在处理中调用或 C Library。两者都运行相同的核心，仅通过“PlatformAdapter”到达操作系统。每个二进制文件都是为一个操作系统构建的，并与该操作系统的可访问性 TERM_ 进行对话。

对于人工智能代理

该二进制文件带有与其版本匹配的指南：

agent-desktop skills get desktop      # the loop, refs, verification and retry rules
agent-desktop skills get platform     # what differs on the OS you run on
agent-desktop <command> --help        # flags for one command

从 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”为“安全”时重试失败的命令。有关信封、错误代码和退出代码，请参阅 JSON 输出。

MCP

agent-desktop mcp 将每个命令作为基于 stdio 的 MCP 工具提供服务。工具以其命令（“desktop_snapshot”、“desktop_click”、“desktop_session_start”）命名，接受该命令的参数，并返回其 JSON 信封：

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

赋予“mcp”的全局标志，例如“–session”、“–headed”或“–trace”，适用于每个调用。

命令

agent-desktop有60个命令名称，56个操作命令。其他四个（“key-down”、“key-up”、“mouse-down”、“mouse-up”）拒绝运行，直到守护程序可以释放按住的键或按钮。命令记录了每一项。

集团	命令
观察	`快照`、`查找`、`获取`、`是`、`屏幕截图`、`列表表面`
根据参考采取行动	`单击`、`双击`、`三击`、`右键单击`、`类型`、`设置值`、`清除`、`焦点`、`选择`、`切换`、`选中`、`取消选中`、`展开`、`折叠`、`滚动`、`滚动到`
键盘和鼠标	`按`、`悬停`、`拖动`、`鼠标移动`、`鼠标单击`、`鼠标滚轮`、`按下键`、`按下键`、`按下鼠标`、`松开鼠标`
应用程序和窗口	`启动`、`关闭应用程序`、`列表应用程序`、`列表窗口`、`列表显示`、`焦点窗口`、`调整窗口大小`、`移动窗口`、`最小化`、`最大化`、`恢复`、`开放系统表面`
通知	`列表通知`、`关闭通知`、`关闭所有通知`、`通知操作`
剪贴板	`剪贴板获取`、`剪贴板设置`、`剪贴板清除`
等等	`等待`
会议	`会话`、`跟踪`、`光标覆盖`
系统	`状态`、`权限`、`版本`、`批次`、`技能`

平台支持

平台	要求	辅助功能__学期_
macOS	macOS 13 或更高版本、Intel 或 Apple Silicon	AX _术语
Windows	Windows 10 1809 或更高版本、x64 或 ARM64	用户界面自动化
Linux	Ubuntu 24.04 或更高版本、x86_64 或 aarch64、X11 或 Wayland	AT-SPI

每个平台页面都会列出什么可以无头工作，什么需要“–headed”，什么拒绝。

C Library

每个版本都附带“libagent_desktop_ffi”，因此程序可以在进程中调用代理桌面。请参阅 C Library 文档。

import ctypes
lib = ctypes.CDLL("./lib/libagent_desktop_ffi.dylib")
lib.ad_adapter_create.restype = ctypes.c_void_p
lib.ad_adapter_destroy.argtypes = [ctypes.c_void_p]
assert lib.ad_init(7) == 0  # AD_RESULT_OK when the header's AD_ABI_VERSION_MAJOR matches the library
adapter = lib.ad_adapter_create()
lib.ad_adapter_destroy(adapter)

发展

每个平台适配器仅在其自己的操作系统上构建，因此将货物范围限定为主机的软件包。在 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-windows 而不是 agent-desktop-macos；在 Linux 上，“agent-desktop-linux”。 CONTRIBUTING.md 列出了每个门。