agent-device 是 Callstack 开发的命令行工具，让 AI 代理能统一控制 iOS、Android 等移动设备。通过会话管理、UI 快照和可重放脚本，实现确定性自动化。本页提供项目介绍、安装指南、使用方法和架构说明，适用于自动化测试、UI 探索等场景。
agent-device 是一个专为 AI 代理设计的跨平台移动设备控制 CLI，通过会话管理、UI 快照和可重放脚本，实现 iOS、Android 等设备的确定性自动化操作。
agent-device 是一个专为 AI 代理设计的跨平台移动设备控制命令行工具（CLI），由 Callstack 维护。它提供统一的接口来控制 iOS、tvOS、macOS、Android 和 AndroidTV 设备，核心用途是使 AI 代理能够以结构化、可重放的方式理解和操作移动应用界面。与通用自动化工具不同，agent-device 从设计之初就考虑了代理工作流的需求：输出紧凑的 UI 快照而非原始截图，使用基于可访问性树的引用（Refs）和选择器（Selectors）进行交互，并将会话状态持久化。这使得代理可以在多轮对话中保持对设备状态的理解，同时将操作历史转化为可复现的脚本。项目定位为"代理驱动的移动自动化层"，填补了 AI 代理与物理/虚拟移动设备之间的操作鸿沟。
agent-device 主要解决四大问题：一是代理可理解的 UI 表示，传统自动化依赖图像识别或坐标，token 消耗大且不稳定，而本项目输出结构化的可访问性树快照，包含元素类型、文本、标识符等语义信息；二是确定性交互与可重放性，引入会话（Session）概念，操作基于相对当前快照的选择器而非绝对坐标，并支持将操作序列保存为 .ad 脚本；三是跨平台统一抽象，iOS 和 Android 的自动化机制差异巨大，本项目提供一致的 CLI 命令和输出格式，屏蔽底层差异；四是效率与可靠性，通过默认快照文本过滤、智能滚动发现以及元数据感知的重试机制，在保证可靠性的同时控制 token 使用。
agent-device 适用于：AI 代理自动化测试，代理可自动探索应用、执行测试用例、验证 UI 状态；移动端 UI 探索与调试，通过快照快速了解界面结构，定位元素；可重放的操作录制，将用户操作或测试流程录制为脚本用于回归测试；会话感知的设备控制，如登录流程、数据录入等需要保持状态的多步骤操作；跨平台设备统一管理，在混合 iOS/Android 环境中使用同一套命令。项目特别适合集成到 AI 编码助手、自动化测试平台、设备农场管理或任何需要程序化控制移动设备的代理系统中。
基础安装：确保 Node.js 22+，运行 npm install -g agent-device 全局安装，即可使用 agent-device 命令。平台依赖方面，iOS/tvOS/macOS 需 macOS 系统、Xcode 及 xcrun 工具链，物理设备需启用开发者模式；Android 需配置 adb 环境并启用 USB 调试。从源码构建需 pnpm、Swift 工具链和 Xcode，执行 pnpm install 后运行 pnpm build:all 构建 Node 部分和 XCUITest 运行器。验证安装可运行 agent-device --help 或 agent-device apps --platform ios 检测设备。仓库中未明确给出 Windows 或 Linux 对 iOS 的支持说明。
核心流程遵循发现-打开-快照-交互-验证-关闭模式：使用 agent-device apps 发现设备或应用；agent-device open 启动应用建立会话；agent-device snapshot -i 获取 UI 可访问性树快照，包含 @eX 引用；使用 press、fill、scroll、rotate 等命令基于引用或选择器交互；diff snapshot 比较 UI 变化；close 结束会话。脚本功能：添加 --save-script 保存操作为 .ad 文件，replay 回放脚本，test 运行脚本套件并支持重试和超时。性能监控通过 agent-device perf --json 获取启动时间、CPU 和内存数据。非 JSON 模式下，关键操作会打印成功确认以区分实际执行与静默跳过。
项目采用模块化架构：TypeScript 核心位于 src/，包含 CLI 解析、客户端抽象、会话与快照管理；平台实现位于 src/platforms/（android、ios、linux 等）；ios-runner 是 Swift 编写的 XCUITest 运行器应用，负责 iOS 设备通信；macos-helper 是 Swift 工具，提供进程级 CPU/内存采样。关键设计包括：会话确保状态连续；Refs（临时引用）与 Selectors（持久查询）分离，兼顾探索与回放；平台差异由适配层屏蔽；输出支持 JSON 模式便于代理解析；提供 skills/ 目录下的 SKILL.md 为代理提供紧凑操作指南。测试覆盖单元测试（vitest）和跨平台集成回放测试。
它是专为 AI 代理设计的移动设备控制 CLI，提供会话化、可重放的自动化能力。适合需要自动化测试移动应用、进行 UI 探索或集成 AI 代理到设备控制流程中的开发者和团队。
支持 iOS、tvOS、macOS（模拟器与物理设备）、Android 和 AndroidTV。iOS 相关平台依赖 Xcode 和 xcrun，Android 依赖 adb 和 USB 调试。
在 Node.js 22+ 环境下运行 npm install -g agent-device 全局安装。使用流程：agent-device apps 发现设备，agent-device open 打开应用，agent-device snapshot -i 查看 UI，press/fill 等命令交互，agent-device close 结束会话。详细命令参考官方文档或 skills/ 目录。
agent-device 专为 AI 代理优化：输出结构化可访问性树而非截图，降低 token 消耗；使用选择器（Selectors）确保脚本跨设备可重放；提供会话管理和轻量级脚本录制；CLI 设计简洁，适合集成到代理循环。相比 Appium 更轻量、更聚焦代理友好性。
支持物理设备。iOS 物理设备需启用开发者模式并通过 Xcode 连接，性能采样使用 xcrun xctrace，可能比模拟器稍慢；Android 需 USB 调试授权，通过 adb 直接通信。项目 README 指出物理 iOS 设备的 perf 命令会额外耗时，但日常操作响应正常。