agent-device

机器翻译正文由机器翻译自项目原始文档（英文），排版经程序统一处理，可能存在偏差，请以原项目仓库为准。

代理-设备

用于 AI 编码代理的移动应用自动化和验证。 通过 CLI、内置 MCP 服务器或输入的 Node.js API，为编码代理提供实时应用反馈循环。

让你的编码代理在运行的应用程序中验证其更改。agent-device 允许代理在 iOS、Android 和 HarmonyOS（模拟器、仿真器和物理设备）以及 tvOS、Android TV、Fire TV（Fire OS）、Amazon Vega OS TV（Vega 虚拟设备）、Web、macOS 和 Linux 上检查、控制、调试和验证应用程序。代理读取高效令牌的可访问性快照，而不是仅仅基于截图进行推理，通过 refs 和 selectors 执行操作，并保存证据以供审查。它还协调并行代理工作树之间的设备访问，并连接远程设备云。

可与 Claude Code、Codex、Cursor、Windsurf、Cline、Goose 以及任何能够运行 CLI 或通过 MCP 连接的代理一起使用，或作为你使用 AI SDK 或 Eve 构建的代理的运行时。 Expensify、Shopify 以及其他公司 others 的开发者使用它来验证他们的应用程序。

代理设备在 中驱动移动自动化 e2e 和 T3 代码。

快速开始

安装 CLI 并检查设置。它需要 Node.js 22.12 或更高版本；网络自动化需要 Node.js 24 或更高版本。请参阅 安装 了解目标要求。

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

在将 CLI 交给代理之前，请自己运行 doctor。help workflow 提供了调试、重放和分析的指南链接。

通过 CLI 驱动应用程序

在内置的 iOS 通讯录应用中添加联系人：

# 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

引用仅在最新输出中有效：在 --settle 命令之后，使用其差异中的引用，并且只有在差异中遗漏您需要的内容时才拍摄新的快照。快照来自应用的可访问性树，因此清晰的标签、角色和测试 ID 可以使代理运行更加可靠；当可访问性数据较差时，也可使用截图和视频作为证据。

将 MCP 工具添加到您的代理中

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

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

请参阅 AI 代理设置 了解每个客户的设置，以及何时优先选择普通 CLI 而不是 MCP。

从 Node.js 脚本化操作

createAgentDeviceClient() 为 Node.js 提供了对相同命令的类型化访问，可以作为您自己代理中的模型工具或从编排代码中使用：

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集成指南。

代理能做什么

• 通过可访问性快照、引用和选择器检查应用状态，并分析 React Native 渲染性能，以找出导致交互变慢的原因。
• 对可见的界面进行操作，例如点击或按压元素、填写字段、滚动、进行手势操作、等待、断言状态以及处理提示框。
• 诊断故障，通过截图、视频、日志、跟踪、网络数据、性能样本、崩溃细节和 React 配置文件进行分析。
• 重复工作流程，将可用的操作步骤保存为 .ad 脚本以便本地使用或持续集成（CI）。在需要时导出严格的 Maestro YAML 文件。

参见 Commands，了解每个目标支持的命令和证据类型。

可以问代理的内容

安装 CLI 后，像这样的提示可以端到端运行：

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

下一步

• AI 代理设置：为 Cursor、Codex、Claude Code、Windsurf 等设置技能、项目规则和每个客户的配置。
• 快速开始：打开应用程序、读取其用户界面，并通过命令行进行交互。
• 重放与端到端 和 调试与性能分析：可重复的测试和错误排查。

在哪里运行代理设备

相同的会话和证据模型在每一步都有效：代理探索应用、捕获证据、保存回放、在CI中运行，然后转向远程设备。

工作原理

agent-device 在会话中保持设备状态。它使用本地可访问性桥来获取 iOS 模拟器的快照，并使用 XCTest 进行 iOS 交互，包括物理 iOS 和 tvOS；在 Android、Android TV 和 Fire OS 上使用 ADB 和快照助手；在 HarmonyOS 上使用 HDC 和 ArkUI uitest；在 Vega 虚拟设备上使用 Vega CLI/VDA；在 macOS 上通过本地助手，包括通过可访问性树对 Electron 和其他基于 Chromium 的应用；在 Linux 上使用 AT-SPI。

对不同目标的支持深度不一。一些后端（如 HarmonyOS 和 Vega OS）只覆盖部分命令；运行 agent-device capabilities --platform <platform> 可查看目标支持的内容。功能矩阵 显示了每个目标、桌面、Web 和云提供商支持哪些命令。

会话范围限定在调用者的 git 工作区内，本地主机设备声明防止并行代理接管彼此的模拟器和仿真器。运行 agent-device device status 可在无守护进程情况下检查所有权，运行 agent-device device release --stale 可释放所有权已确定不再运行的声明。相同的命令可在 BrowserStack、AWS Device Farm、TestMu AI 和 Limrun 上驱动托管设备。

agent-device 使用 Vercel 的 agent-browser 提供的 inspect-act-verify 流程来操作移动设备、电视和桌面应用。基本 --platform web 支持在同一会话和回放系统中运行 agent-browser。

常见问题

代理设备是什么？

agent-device 是一个命令行工具和 MCP 服务器，它允许 AI 编码代理检查、控制和验证移动应用，并保存证据以供审查。它支持 iOS、Android、HarmonyOS、电视、Web、macOS 和 Linux。

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

是的。agent-device mcp 启动官方 stdio MCP 服务器。上面的快速入门包含客户端配置，AI 代理设置 涵盖每个客户端的详细信息。

它是否适用于 React Native、Expo、Flutter 和原生应用？

是的。agent-device 支持原生 iOS 和 Android 应用，以及受支持目标上的 React Native、Expo 和 Flutter 应用。命令和证据因目标而异。

它与移动 MCP 服务器有何不同？

MCP 服务器是与 CLI 和类型化 Node.js API 使用的相同运行时的一个入口点。会话、设备所有权、选择器、证据、回放、CI 工作流和云路由在这三者之间保持一致。

我可以在 agent-device 上构建自己的代理或 QA 产品吗？

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

它与 Appium、Detox 或 Maestro 有何不同？

使用 agent-device，代理在运行时读取应用状态并选择每个命令。团队使用 Appium、Detox 和 Maestro 来编写和维护测试套件。agent-device 可以通过将运行保存为 .ad 脚本或导出为严格的 Maestro YAML 来补充它们。

agent-device 可以在 CI 中运行吗？

可以。将运行记录为 .ad 脚本，在 CI 中回放，并将截图和日志保留为工件；EAS 工作流模板 是一个可用示例。

文章和视频

文章

• 使用 EAS 工作流为 Expo 应用构建 AI QA 代理
• 代理设备：针对 AI 代理的 iOS 与 Android 自动化
• 使用 Vercel Eve 构建可审查的移动 QA 代理
• 我们如何优化代理设备以实现移动应用自动化

视频

• 使用代理设备验证移动应用
• 在人工智能编码工作流程中使用代理设备
• 在真实设备上测试移动应用的云代理

谁在使用代理设备？

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

文档

• 文档
• 代理可读文档

贡献

请参阅 CONTRIBUTING.md。

Made by Callstack

agent-device 是在 MIT 许可下的开源软件。访问 agent-device.dev 或 联系 Callstack。