agent-device

---

agent-device

**面向 AI 编码 Agent 的移动应用自动化与验证。**通过命令行、内置 MCP 服务或类型化 Node.js API，为编码 Agent 提供实时应用反馈循环。

让编码 Agent 在运行中的应用里验证其修改。agent-device 让 Agent 能够检查、控制、调试和验证 iOS、Android 与 HarmonyOS 应用（模拟器、仿真器和实体设备），以及 tvOS、Android TV、Fire TV（Fire OS）、Amazon Vega OS TV（Vega Virtual Device）、Web、macOS 和 Linux 应用。Agent 可读取节省 Token 的无障碍快照，而不是只根据屏幕截图进行推理；还可通过 refs 和选择器执行操作，并保存证据供审核。它还可协调并行 Agent 工作树之间的设备访问，并连接远程设备云。

它兼容 Claude Code、Codex、Cursor、Windsurf、Cline、Goose，以及任何能够运行命令行或通过 MCP 连接的 Agent；也可作为你使用 AI SDK 或 Eve 构建的 Agent 的运行时。Expensify、Shopify 和其他团队的开发者都在使用它来验证应用。

agent-device 为以下产品提供移动端自动化能力： e2e 和 T3 Code。

快速开始

安装命令行工具并检查设置。它要求 Node.js 22.12 或更高版本；Web 自动化要求 Node.js 24 或更高版本。有关目标平台要求，请参阅安装。

npm install -g agent-device@latest
agent-device doctor
agent-device help workflow

在将命令行工具交给 Agent 之前，请先自行运行 doctor。help workflow 会链接到调试、回放和性能分析指南。

从命令行驱动应用

在内置的 iOS Contacts 应用中添加联系人：

# Start a session.
agent-device open Contacts --platform ios

# Inspect the screen. The example below shows the output; refs vary.
agent-device snapshot -i
# @e2 [button] "Add"

# Use the ref and wait for the UI to settle.
agent-device press @e2 --settle
# The diff includes:
# + @e7 [text-field] "First name"

agent-device fill @e7 "Ada" --settle
# The next diff shows changed values and current refs:
# - @e7 [text-field] "First name"
# + @e14 [text-field] "Ada"
# = @e15 [text-field] "Last name"

# Capture evidence and close the session.
agent-device screenshot ./contact-form.png
agent-device close

refs 仅在最新输出中有效：运行 --settle 命令后，请使用其差异中的 refs；只有当差异未包含所需内容时，才获取新快照。快照来自应用的无障碍树，因此清晰的标签、角色和测试 ID 能让 Agent 运行更可靠；请将屏幕截图和视频用作证据，或在无障碍数据质量较差时使用。

将 MCP 工具添加到你的 Agent

agent-device mcp 会启动官方 stdio MCP 服务，通过与 CLI 相同的执行路径，将已安装的命令作为结构化工具公开：

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

有关各客户端的设置，以及何时优先使用纯 CLI 而非 MCP，请参阅 AI Agent 设置。

从 Node.js 编写脚本

createAgentDeviceClient() 让 Node.js 代码能够以类型化方式访问相同的命令，可将其作为模型工具用于你自己的 Agent，也可从编排代码中调用：

import { createAgentDeviceClient } from 'agent-device';

const client = createAgentDeviceClient({ session: 'qa-run' });
try {
  await client.apps.open({ app: 'com.apple.Preferences', platform: 'ios' });
  const snapshot = await client.capture.snapshot({ interactiveOnly: true });
  const button = snapshot.nodes.find((node) => node.role === 'button');
  if (button) await client.interactions.press({ ref: button.ref });
} finally {
  await client.sessions.close();
}

请参阅 Node.js API、可运行示例，以及 AI SDK 和 Eve 集成指南。

Agent 可以做什么

• 检查应用状态：通过无障碍快照、引用和选择器检查应用状态，并分析 React Native 渲染，找出交互缓慢的原因。
• 操作可见的 UI：点击或按下元素、填写字段、滚动、执行手势、等待、断言状态并处理提醒。
• 诊断故障：使用屏幕截图、视频、日志、跟踪记录、网络数据、性能样本、崩溃详情和 React 分析数据。
• 重复工作流：将有效步骤保存为 .ad 脚本，以供本地使用或在 CI 中运行。需要时可导出严格格式的 Maestro YAML。

请参阅命令，了解各目标支持的命令和证据类型。

可以让你的 Agent 做什么

安装 CLI 后，以下提示词可以端到端地完成任务：

• “实现引导界面，在 iOS 模拟器和 Android 模拟器上运行，并附上屏幕截图。”
• “重现这个崩溃，并捕获导致崩溃的日志。”
• “检查此次更改是否造成了不必要的 React Native 重渲染。”
• “探索一次结账流程，将其保存为回放脚本，并在 CI 中运行。”
• “在实体设备上验证此拉取请求，并附上可供审查的证据。”

后续步骤

• AI Agent 设置：Cursor、Codex、Claude Code、Windsurf 等工具的技能、项目规则和各客户端设置。
• 快速入门：从命令行打开应用、读取其 UI 并与之交互。
• 回放与端到端测试和调试与分析：可重复测试与漏洞排查。

在哪里运行 agent-device

同一套会话和证据模式适用于每个步骤：Agent 探索应用、采集证据、保存回放，在 CI 中运行，然后转到远程设备上执行。

路径	适用场景	从这里开始
本地	在模拟器、仿真器、实体设备、macOS 和 Linux 上尝试命令并调试应用。	按照快速入门操作。
CI/CD	使用回放脚本和采集的产物，自动验证拉取请求和合并。	试试 EAS 工作流模板。
云端 / 远程	Linux 运行器、托管设备和远程作业。	设置远程代理，连接设备云（BrowserStack、AWS Device Farm、TestMu AI、Limrun），或联系 Callstack 以获取团队 QA 支持。

工作原理

agent-device 在会话中保存设备状态。它使用本地无障碍桥接来获取 iOS Simulator 快照，并使用 XCTest 支持 iOS 交互、实体 iOS 设备和 tvOS；在 Android、Android TV 和 Fire OS 上使用 ADB 和快照辅助工具；在 HarmonyOS 上使用 HDC 和 ArkUI uitest；在 Vega Virtual Device 上使用 Vega CLI/VDA；在 macOS 上使用本地辅助工具，并通过无障碍树支持 Electron 和其他基于 Chromium 的应用；在 Linux 上使用 AT-SPI。

不同目标的支持深度有所不同。某些后端（例如 HarmonyOS 和 Vega OS）仅支持部分命令；运行 agent-device capabilities --platform <platform> 查看目标支持哪些功能。功能支持矩阵展示了各目标、桌面、Web 和云服务提供商支持的命令。

会话限定于调用方的 Git 工作树，主机本地的设备占用声明可防止并行 Agent 接管彼此的模拟器和仿真器。运行 agent-device device status 可在无需守护进程的情况下检查设备归属；运行 agent-device device release --stale 可释放所有者已确定不再运行的占用声明。同样的命令也可管理 BrowserStack、AWS Device Farm、TestMu AI 和 Limrun 上的托管设备。

agent-device 将 Vercel 的 agent-browser 中的“检查-操作-验证”流程用于移动、TV 和桌面应用。基础的 --platform web 支持会在同一会话和回放系统中运行 agent-browser。

常见问题

什么是 agent-device？

agent-device 是一个命令行工具和 MCP 服务，可让 AI 编码 Agent 检查、控制和验证移动应用，并保存证据以供审核。它支持 iOS、Android、HarmonyOS、TV、Web、macOS 和 Linux。

是否有用于自动化移动应用的 MCP 服务？

有。agent-device mcp 会启动官方 stdio MCP 服务。上方的快速入门提供了客户端配置，AI Agent 设置指南则介绍了各客户端的具体配置。

它能用于 React Native、Expo、Flutter 和原生应用吗？

可以。agent-device 支持原生 iOS 和 Android 应用，也支持在受支持目标上运行的 React Native、Expo 和 Flutter 应用。不同目标支持的命令和证据有所不同。

它与移动 MCP 服务有什么区别？

MCP 服务是 CLI 和类型化 Node.js API 所使用的同一运行时的一个入口。会话、设备归属、选择器、证据、回放、CI 工作流和云端路由在这三种方式中保持一致。

我可以基于 agent-device 构建自己的 Agent 或 QA 产品吗？

可以。类型化 Node.js 客户端是同一运行时的公共接口，因此你构建的 Agent 能继承上述所有功能。可从 Node.js API、AI SDK 或 Eve 指南开始。

它与 Appium、Detox 或 Maestro 有什么区别？

使用 agent-device 时，Agent 会读取应用状态，并在运行时选择每条命令。团队使用 Appium、Detox 和 Maestro 编写和维护测试套件。agent-device 可以与它们配合使用：将运行记录保存为 .ad 脚本，或导出为严格格式的 Maestro YAML。

agent-device 能在 CI 中运行吗？

可以。将运行记录为 .ad 脚本，在 CI 中回放，并将屏幕截图和日志作为构建产物保留；EAS 工作流模板提供了一个可运行的示例。

文章和视频

文章

• 使用 EAS Workflows 为 Expo 应用构建 AI QA Agent
• Agent Device：面向 AI Agent 的 iOS 和 Android 自动化
• 使用 Vercel Eve 构建移动端 QA Agent
• 我们如何优化 Agent Device，以实现移动应用自动化

视频

• 使用 agent-device 验证移动应用
• 在 AI 编码工作流中使用 agent-device
• 在真实设备上测试移动应用的云端 Agent

谁在使用 agent-device？

Callstack、JPMorgan Chase、Expensify、Shopify、Kindred、Total Wine & More、LegendList、HerLyfe、App & Flow 等团队和开发者都在使用 agent-device。

文档

• 文档
• 供 Agent 阅读的文档

贡献

请参阅 CONTRIBUTING.md。

由 Callstack 打造

agent-device 是基于 MIT 许可证开源的。访问 agent-device.dev，或联系 Callstack。