This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

使用代理设备让你的 AI 编码助手在本地和远程设备上验证、调试、分析和测试正在运行的 Expo 应用。

agent-device 是 Callstack 出品的开源、原生代理 CLI。它可以让 AI 编码代理操作你正在运行的 Expo 应用，并通过 UI 状态、截图、视频、日志、网络活动、追踪和性能数据来验证结果。

代码检查和自动化测试并不总能显示运行中的应用发生了什么。使用 agent-device，一个代理可以检查屏幕是否渲染、流程是否完成或请求是否触发，然后报告它观察到的情况。这就把行为审查加入到了代理用于实现更改的同一个工作流程中。

🌐 Code inspection and automated tests do not always show what happens in the running app. With agent-device, an agent can check that a screen renders, a flow completes, or a request fires, then report what it observed. This adds behavior review to the same workflow the agent uses to implement the change.

agent-device 可以在 Codex、Claude Code、Cursor 等终端中运行，并可选择集成 模型上下文协议 (MCP)。一个命令模型就能覆盖 Android 模拟器、iOS 模拟器、物理设备、Android TV、tvOS、macOS、Linux 和网页。

常规响应保持简洁。语义快照包括可操作的引用，如 @e3，命令结果会解释在出现故障时如何恢复，更大的输出会被保存为工件。这可以让更多的代理上下文用于处理你的应用。

🌐 Routine responses stay compact. Semantic snapshots include actionable references such as @e3, command results explain how to recover when something fails, and larger outputs are saved as artifacts. This keeps more of the agent's context available for working on your app.

信息 agent-device 由 Callstack 构建和维护，并且可在 MIT 许可证下使用。有关支持的平台和命令的完整列表，请参见 agent-device 文档。

快速开始

🌐 Quick start

Use `agent-device` to open the settings screen in my Expo app on iOS, verify it loaded correctly,
and capture a screenshot as evidence.

agent-device 循环是如何工作的

🌐 How the agent-device loop works

代理打开应用，读取一个简洁的无障碍快照，并根据像 @e2 这样的引用采取行动。已完成的交互可以在同一响应中包含由此产生的 UI 变化。然后，代理通过断言或适合任务的证据（比如截图、聚焦的日志窗口或性能样本）来验证结果。

🌐 The agent opens the app, reads a compact accessibility snapshot, and acts on refs such as @e2. Settled interactions can include the resulting UI changes in the same response. The agent then verifies the result with an assertion or the evidence that suits the task, such as a screenshot, focused log window, or performance sample.

agent-device apps --platform ios
agent-device open MyApp --platform ios
agent-device snapshot -i
# @e1 [heading] "Welcome"
# @e2 [button] "Get Started"
agent-device press @e2 --settle
agent-device screenshot ./artifacts/get-started.png
agent-device close

你的代理会按照已安装 CLI 附带的工作流程指南来选择并执行这些命令。

🌐 Your agent chooses and runs these commands by following the workflow guidance bundled with the installed CLI.

agent-device让你的代理可以做什么

🌐 What agent-device lets your agent do

• **控制与互动：**检查可访问性标签、角色、数值、测试 ID 和交互引用。启动应用、点击、输入、滚动、执行手势、处理提醒、打开深链接以及改变设备状态。可以在本地使用相同命令，也可以通过 设备云 和 远程代理 在 Android、iOS、网页、电视和桌面目标上执行。
• 分析和调试： 检查 React Native 组件、props、hooks、慢提交和重新渲染；通过 Metro 的 Chrome 开发者工具协议（CDP）评估指定的 JavaScript；收集重点日志以及可用的网络请求和响应。在同一个会话中，还可以添加平台支持的本地 CPU、内存、FPS 和帧健康状况、追踪、崩溃、截图、视频和音频证据。
• 测试并重复： 将工作会话记录为确定性的 .ad 脚本，回放它或在 CI 中使用内置测试命令运行，并保留失败运行的工件。使用 agent-device test --maestro 运行支持的 Maestro YAML，或将兼容的 .ad 流导出为 Maestro YAML。

这涵盖了常规的实现检查、探索性 QA、bug 重现以及性能工作。当调查需要实时的原生断点、变量、内存检查或单步调试时，agent-device 可以在 Xcode 或 LLDB 附加到应用进程的同时重现并记录流程。对于版本匹配的诊断和性能分析指导，可以先从 agent-device help debugging、agent-device help react-devtools 和 agent-device help cdp 入手，或者参见 调试和性能分析。

🌐 This covers routine implementation checks, exploratory QA, bug reproduction, and performance work. When an investigation needs live native breakpoints, variables, memory inspection, or stepping, agent-device can reproduce and document the flow while Xcode or LLDB attaches to the app process. For version-matched diagnostic and profiling guidance, start with agent-device help debugging, agent-device help react-devtools, and agent-device help cdp, or see Debugging and Profiling.

示例提示

🌐 Example prompts

设置完成后，描述你想要的结果和证据。例如：

🌐 After setup, describe the outcome and evidence you want. For example:

在 Expo AI 工具中使用 agent-device

🌐 Use agent-device with Expo AI tooling

agent-device 补充了 Expo 自有的代理工具。Expo Skills 教你的代理如何实现功能，Expo MCP 服务器为它提供当前的 Expo 和 EAS 上下文，而 agent-device 则让它可以在运行中的应用中验证结果。

对于自动化拉取请求测试，可以从 Callstack 的 agent-device EAS 工作流模板 开始。它展示了如何针对 Expo 应用运行 AI QA 代理并保留可审核的产物。

🌐 For automated pull request testing, start with Callstack's agent-device EAS Workflow template. It shows how to run an AI QA agent against an Expo app and retain reviewable artifacts.

可选 MCP 设置

🌐 Optional MCP setup

大多数编码代理可以直接通过它们的集成终端使用 agent-device。如果你的客户端支持 MCP，并且你更喜欢结构化工具，可以配置它来启动已安装的 CLI：

🌐 Most coding agents can use agent-device directly through their integrated terminal. If your client supports MCP and you prefer structured tools, configure it to launch the installed CLI:

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

MCP 为相同设备的工作流程提供了结构化工具。保持 CLI 可用，这样代理就可以读取版本匹配的帮助信息并使用仅终端的设置命令。

🌐 MCP provides structured tools for the same device workflows. Keep the CLI available so the agent can read version-matched help and use terminal-only setup commands.

限制与提示

🌐 Limitations and tips

• 可访问性标签、角色和测试 ID 能让代理互动更可靠。可以用截图作为证据或视觉备份，但在操作时最好还是使用 refs 和选择器。
• 将会改变状态的命令在同一个会话中顺序执行。任务完成后关闭会话；当模拟器或模拟器也需要停止时，在 CI 中使用 agent-device close --shutdown。
• 设备级别的UI自动化，包括快照、点击、输入、截图和日志，都可以在开发版本的已安装应用或Expo Go中使用，而且无需向你的项目添加任何库。
• React Native 组件检查和 React 性能分析需要一个开发服务器和兼容的 React DevTools 连接，所以要保持它运行。在 Expo Go 中，本地 CPU、内存和跟踪分析是针对 Expo Go 主进程，而不是特定应用的本地二进制文件，所以要使用开发版本来分析你的本地代码。
• 默认情况下日志是关闭的。让代理打开一个专注的日志窗口来重现问题，而不是收集一个无限的设备日志。
• 物理设备自动化需要特定平台的配对、签名、权限和信任设置。可以先从模拟器或模拟器开始，然后按照安装指南设置物理设备。
• 在 EAS 模拟器 的 Android 会话中，以无界面模式启动模拟器。设置 AGENT_DEVICE_HEADLESS=1，或者将 --headless 传递给 agent-device boot。在这里窗口模式的模拟器无法启动。
• 当任务需要更深入、版本匹配的指导时，运行 agent-device help react-native、agent-device help debugging 或 agent-device help dogfood。