agent-device

项目简介

agent-device 是 Callstack 推出的开源设备层，面向 AI 编程代理。它让代理通过 CLI、MCP 服务器或类型化 Node.js API 检查、控制、调试和验证设备和模拟器上的应用。支持 iOS、Android、HarmonyOS、tvOS、Android TV、Fire TV、Vega OS、Web、macOS 和 Linux，可在本地运行，也可连接远程设备主机。

核心功能

• 代理可通过无障碍快照、引用和选择器检查应用状态，而不是只依赖截图；可点击或按压元素、填写字段、滚动、执行手势、等待、断言状态并处理弹窗；可收集截图、视频、日志、跟踪、网络数据、性能采样、崩溃详情和 React 性能分析等证据；可将成功运行保存为 .ad 重放脚本，供本地或 CI 使用，并按需导出严格的 Maestro YAML；内置 MCP 服务器和类型化 Node.js API 与 CLI 共享同一运行时；会话按 git worktree 隔离，设备占用声明可防止并行代理互相抢占模拟器。

适用场景

• 让编程代理实现一个界面，在 iOS 模拟器和 Android 模拟器上运行并附上截图；复现崩溃或慢屏幕，采集日志和网络数据，并对 React Native 渲染进行性能分析；探索结账流程，将其保存为重放脚本，并在 CI 中运行；在物理设备上验证拉取请求并附上可供审查的证据。

快速开始

• 使用 npm install -g agent-device@latest 安装；在把 CLI 交给代理前先运行 agent-device doctor，再通过 agent-device help workflow 查看指南；如需 MCP，运行 agent-device mcp 启动官方 stdio 服务器；常用 CLI 命令包括 agent-device open Contacts --platform ios、agent-device snapshot -i、agent-device press @e2 --settle 和

部署与要求

• 需要 Node.js 22.12 或更高版本；Web 自动化需要 Node.js 24 或更高版本；运行 agent-device capabilities --platform <platform> 可查看目标平台支持的命令；可在本地针对模拟器、仿真器、物理设备、macOS 和 Linux 运行，也可通过远程代理、设备云和托管设备运行；托管设备支持包括 BrowserStack、AWS Device Farm、TestMu AI、Limrun 以及 EAS 上的 Expo 模拟器。

采用前须知

• 许可证：MIT。在使用、修改或分发项目前，请确认其具体条款。