Skip to content

Commit cf6be5b

Browse files
thymikeeclaude
andcommitted
docs: tighten user-facing docs wording
Apply the writing-user-docs house style across every website docs page, the root README, and the TestMu provider README: second person, active voice, no time-relative or marketing wording, prerequisites up front, goal-oriented headings, and less internal implementation detail. Also close the unterminated selector-helpers snippet in client-api.md and map agent-device/selectors in examples/sdk/tsconfig.json so the snippet compile test covers it. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 0c1ebb3 commit cf6be5b

29 files changed

Lines changed: 811 additions & 802 deletions

‎README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ agent-device doctor
3131
agent-device help workflow
3232
```
3333

34-
Run `doctor` yourself before handing the CLI to an agent; `help workflow` links to the guides for debugging, replay, and profiling, and the installed help always matches the installed version.
34+
Run `doctor` yourself before you hand the CLI to an agent. `help workflow` links to the guides for debugging, replay, and profiling; installed help always matches the installed version.
3535

3636
### Drive an app from the CLI
3737

@@ -61,7 +61,7 @@ agent-device screenshot ./contact-form.png
6161
agent-device close
6262
```
6363

64-
Refs are only valid from the latest output: after a `--settle` command, use the refs in its diff, and take a new snapshot only if the diff omits what you need. Snapshots come from the app's accessibility tree, so clear labels, roles, and test IDs make agent runs more reliable; use screenshots and video as evidence or when accessibility data is poor.
64+
Refs are valid only in the latest output: after a `--settle` command, use the refs in its diff, and take a new snapshot only if the diff omits what you need. Snapshots come from the app's accessibility tree, so clear labels, roles, and test IDs make agent runs more reliable; use screenshots and video as evidence or when accessibility data is poor.
6565

6666
![agent-device demo showing Codex using agent-device to create a new contact in the iOS Contacts app from a simple prompt](./website/docs/public/agent-device-contacts.gif)
6767

@@ -143,9 +143,9 @@ The same session and evidence model works at every step: the agent explores the
143143

144144
`agent-device` keeps device state in sessions. It uses a local accessibility bridge for iOS Simulator snapshots and XCTest for iOS interactions, physical iOS, and tvOS; ADB and the snapshot helper on Android; HDC and ArkUI `uitest` on HarmonyOS; Vega CLI/VDA on the Vega Virtual Device; a local helper on macOS; and AT-SPI on Linux.
145145

146-
Support depth varies by target. Newer backends such as HarmonyOS and Vega OS cover a subset of commands; run `agent-device capabilities --platform <platform>` to see what a target supports.
146+
Support depth varies by target. Some backends, such as HarmonyOS and Vega OS, cover a subset of commands; run `agent-device capabilities --platform <platform>` to see what a target supports.
147147

148-
Sessions are scoped to the caller's git worktree, and host-local device claims stop parallel agents from taking over each other's simulators and emulators. Inspect ownership without a daemon via `agent-device device status`, and settle provably dead owners with `agent-device device release --stale`. The same commands drive hosted devices on [BrowserStack, AWS Device Farm, TestMu AI, and Limrun](https://oss.callstack.com/agent-device/docs/device-clouds).
148+
Sessions are scoped to the caller's git worktree, and host-local device claims stop parallel agents from taking over each other's simulators and emulators. Run `agent-device device status` to inspect ownership without a daemon, and `agent-device device release --stale` to release claims whose owner is provably no longer running. The same commands drive hosted devices on [BrowserStack, AWS Device Farm, TestMu AI, and Limrun](https://oss.callstack.com/agent-device/docs/device-clouds).
149149

150150
`agent-device` uses the inspect-act-verify process from Vercel's [agent-browser](https://github.com/vercel-labs/agent-browser) for mobile, TV, and desktop apps. Basic `--platform web` support runs `agent-browser` in the same session and replay system.
151151

‎examples/sdk/tsconfig.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
"agent-device/android-adb": ["../../src/sdk/android-adb.ts"],
1313
"agent-device/contracts": ["../../src/sdk/contracts.ts"],
1414
"agent-device/finders": ["../../src/sdk/finders.ts"],
15+
"agent-device/selectors": ["../../src/sdk/selectors.ts"],
1516
"agent-device/ai-sdk": ["../../src/ai-sdk/index.ts"]
1617
}
1718
},

‎packages/provider-testmu/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,4 @@ agent-device connect testmu --platform ios --device "iPhone 16" --provider-os-ve
1414
See the [TestMu AI guide](https://agent-device.dev/docs/testmu) for setup and supported operations.
1515
To update the plugin, run `agent-device plugins update @agent-device/testmu`.
1616

17-
After adding or updating a plugin, close your sessions and run `agent-device daemon stop` before reconnecting.
17+
After you add or update the plugin, close your sessions and run `agent-device daemon stop` before reconnecting.

‎website/docs/docs/agent-setup.md‎

Lines changed: 36 additions & 40 deletions
Large diffs are not rendered by default.

‎website/docs/docs/ai-sdk.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ title: AI SDK
44

55
# AI SDK
66

7-
Use `agent-device/ai-sdk` to give an [AI SDK](https://ai-sdk.dev/) agent a typed set of tools for navigating and inspecting an app. The tools run in-process, share one named session, and default to the focused perceive-and-act surface most agents need.
7+
Use `agent-device/ai-sdk` to give an [AI SDK](https://ai-sdk.dev/) agent a typed set of tools for navigating and inspecting an app. The tools run in-process, share one named session, and by default cover the core loop of reading the screen and acting on it.
88

99
```bash
1010
pnpm add agent-device ai
@@ -48,13 +48,13 @@ try {
4848
}
4949
```
5050

51-
Set `AI_MODEL` to a model available through your configured AI SDK provider. The agent sees the available device tools and chooses the calls needed to complete the prompt. The returned `client` targets the same session; keep cleanup in `finally` so the device is released even if generation fails.
51+
Set `AI_MODEL` to a model available through your configured AI SDK provider. The agent decides which device tools to call to complete the prompt. The returned `client` targets the same session; close it in `finally` so the device is released even if generation fails.
5252

53-
## Options
53+
## Choose tools and approvals
5454

5555
`set: 'core'` is the default. It exposes the perceive-and-act loop: open, close, snapshot, click, press, fill, type, get, is, find, wait, back, scroll, swipe, alert, and screenshot.
5656

5757
- Pass `set: 'all'` when the agent also needs device-management or observability commands.
58-
- Pass `approval: { close: 'user-approval' }` to require approval for a command. `createAgentDeviceTools()` returns the map as `toolApproval`, ready to pass to [`ToolLoopAgent`](https://ai-sdk.dev/docs/agents/tool-approvals).
58+
- Pass `approval: { close: 'user-approval' }` to require user approval before a command runs. `createAgentDeviceTools()` returns the map as `toolApproval`, ready to pass to [`ToolLoopAgent`](https://ai-sdk.dev/docs/agents/tool-approvals).
5959

60-
See the [Node.js API](/docs/client-api) when the host application needs deterministic setup or other direct device control outside the agent loop. See the AI SDK reference for [`ToolLoopAgent`](https://ai-sdk.dev/docs/reference/ai-sdk-core/tool-loop-agent).
60+
Use the [Node.js API](/docs/client-api) when your application needs deterministic setup or other direct device control outside the agent loop. See the AI SDK reference for [`ToolLoopAgent`](https://ai-sdk.dev/docs/reference/ai-sdk-core/tool-loop-agent).

‎website/docs/docs/aws-device-farm.md‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@ description: Drive AWS Device Farm remote-access sessions with agent-device.
55

66
# AWS Device Farm
77

8-
Use AWS Device Farm for hosted Android and iOS remote-access WebDriver sessions. The adapter does not route Vega OS or accept a Vega Fire TV ARN. The initial Vega workflow uses a local VVD.
8+
Use AWS Device Farm to run agent-device on hosted Android and iOS devices through remote-access WebDriver sessions. You need an AWS account with a Device Farm project and the AWS CLI installed. AWS Device Farm does not cover Vega OS: agent-device rejects a Vega Fire TV ARN. For Vega, use a local Vega Virtual Device (VVD).
99

10-
## Credentials and connection
10+
## Set credentials and connect
1111

12-
AWS Device Farm uses the AWS CLI credential provider chain. `agent-device` runs `aws devicefarm ...`, so it works with any non-interactive AWS CLI credential source available in CI. It does not require `aws login`. See the [AWS CLI environment variable reference](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) for supported credential sources.
12+
agent-device runs `aws devicefarm ...`, so it uses the AWS CLI credential provider chain and works with any non-interactive AWS CLI credential source in CI. You do not need `aws login`. See the [AWS CLI environment variable reference](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) for supported credential sources.
1313

14-
Use short-lived CI credentials instead of long-lived IAM user keys. In GitHub Actions, use OIDC to assume an IAM role and let the action export standard AWS environment variables. AWS documents [IAM OIDC providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html), and the official [`configure-aws-credentials` action](https://github.com/aws-actions/configure-aws-credentials) documents the GitHub Actions setup.
14+
Use short-lived CI credentials instead of long-lived IAM user keys. In GitHub Actions, use OIDC to assume an IAM role and let the action export the standard AWS environment variables. AWS documents [IAM OIDC providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html), and the official [`configure-aws-credentials` action](https://github.com/aws-actions/configure-aws-credentials) documents the GitHub Actions setup.
1515

16-
For example, a CI job might set:
16+
For example, a CI job can set:
1717

1818
```bash
1919
export AWS_REGION=us-west-2
@@ -30,7 +30,7 @@ export AWS_WEB_IDENTITY_TOKEN_FILE=/path/to/token
3030
export AWS_REGION=us-west-2
3131
```
3232

33-
Connect with the Device Farm project, device, and optional app upload:
33+
Connect with the Device Farm project, the device, and an optional app upload:
3434

3535
```bash
3636
agent-device connect aws-device-farm \
@@ -40,21 +40,21 @@ agent-device connect aws-device-farm \
4040
--aws-app-arn arn:aws:devicefarm:us-west-2:<account-id>:upload:<upload-id>
4141
```
4242

43-
`--aws-app-arn` is optional when the remote-access session does not need an uploaded app. You can also provide the ARNs through environment variables:
43+
Omit `--aws-app-arn` when the remote-access session does not need an uploaded app. You can also pass the ARNs through environment variables:
4444

4545
```bash
4646
export AWS_DEVICE_FARM_PROJECT_ARN=...
4747
export AWS_DEVICE_FARM_DEVICE_ARN=...
4848
export AWS_DEVICE_FARM_APP_ARN=...
4949
```
5050

51-
`AGENT_DEVICE_AWS_DEVICE_FARM_PROJECT_ARN`, `AGENT_DEVICE_AWS_DEVICE_FARM_DEVICE_ARN`, and `AGENT_DEVICE_AWS_DEVICE_FARM_APP_ARN` are accepted as agent-device-specific aliases.
51+
agent-device also accepts `AGENT_DEVICE_AWS_DEVICE_FARM_PROJECT_ARN`, `AGENT_DEVICE_AWS_DEVICE_FARM_DEVICE_ARN`, and `AGENT_DEVICE_AWS_DEVICE_FARM_APP_ARN` as aliases.
5252

53-
`connect` makes read-only `get-project`, `get-device`, and, when supplied, `get-upload` calls. It rejects a device or app for the wrong platform, and an app upload that is not ready. AWS Device Farm does not support app installation after remote-access session allocation. When an app is required, run the printed reconnect command, including `--session <name> --force`, before `open`.
53+
`connect` makes read-only `get-project`, `get-device`, and, when you pass an app, `get-upload` calls. It rejects a device or app for the wrong platform, and an app upload that is not ready. You cannot install an app once the remote-access session is allocated. When an app is required, run the printed reconnect command, including `--session <name> --force`, before `open`.
5454

55-
## CLI workflow
55+
## Run a session from the CLI
5656

57-
Every unscoped `connect` creates a fresh connection. The printed next steps include its generated `--session`. Keep that flag on every command when multiple processes or CI jobs share a host. The active connection is only safe for one sequential workflow. To replace a named connection, run `connect ... --session <name> --force`. An unscoped `--force` creates a new connection and leaves existing sessions untouched.
57+
Every `connect` without `--session` creates a new connection, and the printed next steps include its generated `--session`. Keep that flag on every command when several processes or CI jobs share a host; the active connection is safe only for one sequential workflow. To replace a named connection, run `connect ... --session <name> --force`. `--force` without `--session` creates a new connection and leaves existing sessions untouched.
5858

5959
```bash
6060
export AWS_REGION=us-west-2
@@ -76,11 +76,11 @@ agent-device artifacts --json
7676
agent-device disconnect
7777
```
7878

79-
For MCP-only use, run `connect` in the same effective state directory before starting `agent-device mcp`. MCP exposes operational tools but not provider `connect` commands.
79+
To use AWS Device Farm only through MCP, run `connect` in the same effective state directory before you start `agent-device mcp`. MCP exposes device commands such as `open`, `snapshot`, `close`, and `artifacts`, but not provider `connect` commands.
8080

81-
## Node.js client
81+
## Use the Node.js client
8282

83-
Use direct client configuration when the Node process manages AWS credentials and selectors:
83+
Configure the client directly when your Node process manages the AWS credentials and selectors:
8484

8585
```ts
8686
import { createAgentDeviceClient } from 'agent-device';
@@ -98,16 +98,16 @@ await client.apps.open({ app: 'com.example.app' });
9898
const closed = await client.sessions.close();
9999
```
100100

101-
## Artifacts and troubleshooting
101+
## Get artifacts and troubleshoot
102102

103-
After `close`, AWS Device Farm can return remote-access video and log artifacts after the provider finalizes them. Run `agent-device artifacts --json`, or look up a previous session explicitly:
103+
After `close`, AWS Device Farm returns remote-access video and log artifacts once it finalizes them. Run `agent-device artifacts --json`, or look up an earlier session by its ARN:
104104

105105
```bash
106106
agent-device artifacts <remote-access-session-arn> --provider aws-device-farm --json
107107
```
108108

109-
If `connect` fails, use the reported `aws devicefarm get-*` error to check the credential chain, ARN, region, resource platform, or upload readiness. The provider has not allocated a device yet. If artifacts are pending immediately after `close`, retry the lookup.
109+
If `connect` fails, use the reported `aws devicefarm get-*` error to check the credential chain, ARN, region, resource platform, or upload readiness. A failed `connect` has not allocated a device yet. If artifacts are still pending right after `close`, retry the lookup.
110110

111-
On hosted WebDriver sessions, `fill` checks that the field received focus before it sends keys. If it cannot confirm focus, it fails without typing. Use `snapshot -i` to confirm the target. If the driver cannot expose focus at all, use `press <target>` followed by `type <text>`. That sends text without confirming the destination.
111+
On hosted WebDriver sessions, `fill` checks that the field received focus before it sends keys. If it cannot confirm focus, it fails without typing. Use `snapshot -i` to confirm the target. If the driver cannot report focus at all, use `press <target>` followed by `type <text>`, which sends text without confirming where it lands.
112112

113-
A screen that never goes still — a looping video, a live ticker, continuous animation — gives the provider's driver no quiet moment to read the UI tree, so `snapshot -i` can run out of its read budget on a rented device while `screenshot` of the same screen still returns. Snapshots covers what that failure means and what to do instead; on a metered device the difference matters, because every second of the walk is billed. Take the screenshot, drive from `@refs` an earlier snapshot captured, and remember that `--depth` trims a tree after it arrives, so it cannot shorten a read that never returned.
113+
On a screen that never goes still, such as a looping video, a live ticker, or continuous animation, `snapshot -i` can time out while `screenshot` of the same screen still returns. On a metered device every second of that read is billed, so do not retry the snapshot in a loop. Take a screenshot instead and drive from `@refs` an earlier snapshot captured. `--depth` trims the tree after it arrives, so it cannot shorten a read that never finishes. See [Snapshots](/docs/snapshots) for details.

‎website/docs/docs/batching.md‎

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,10 @@ title: Batching
44

55
# Batching
66

7-
Use `batch` to run multiple commands in a single daemon request.
7+
Use `batch` to run several commands in one daemon request. It saves round trips when you already know
8+
the next sequence of actions.
89

9-
This is useful for agent workflows that already know the next sequence of actions and want to reduce orchestration overhead.
10-
11-
## CLI examples
10+
## Run a batch from the CLI
1211

1312
From a file:
1413

@@ -21,15 +20,15 @@ agent-device batch \
2120
--json
2221
```
2322

24-
Inline for small payloads:
23+
Inline, for small payloads:
2524

2625
```bash
2726
agent-device batch --steps '[{"command":"open","input":{"app":"settings"}},{"command":"wait","input":{"kind":"duration","durationMs":100}}]'
2827
```
2928

3029
## Step payload format
3130

32-
`batch` accepts a JSON array of steps:
31+
Pass `batch` a JSON array of steps:
3332

3433
```json
3534
[
@@ -51,11 +50,11 @@ agent-device batch --steps '[{"command":"open","input":{"app":"settings"}},{"com
5150

5251
Notes:
5352

54-
- `input` is required and uses the same fields as the matching MCP/Node command.
55-
- Unknown top-level step fields are rejected. Supported keys are `command`, `input`, and `runtime`.
56-
- The legacy `positionals`/`flags` step shape was removed in 0.21. Migrate each step to structured input, for example `{"command":"open","input":{"app":"settings","platform":"ios"}}`.
57-
- nested `batch` and `replay` steps are rejected.
58-
- `--on-error stop` is the supported behavior.
53+
- `input` is required and takes the same fields as the matching MCP or Node client command.
54+
- A step can only have `command`, `input`, and `runtime` keys; any other key is rejected.
55+
- Steps written as `positionals`/`flags` are rejected (that shape was removed in 0.21). Rewrite each step with structured input, for example `{"command":"open","input":{"app":"settings","platform":"ios"}}`.
56+
- `batch` and `replay` steps can't be nested inside a batch.
57+
- `--on-error stop` is the only error mode: the batch stops at the first failing step.
5958

6059
## Response shape
6160

@@ -78,7 +77,7 @@ Success:
7877
}
7978
```
8079

81-
In non-JSON mode, `batch` also prints a short per-step summary after the overall completion line.
80+
Without `--json`, `batch` prints the overall completion line followed by a short summary of each step.
8281

8382
Failure:
8483

@@ -102,16 +101,16 @@ Failure:
102101
}
103102
```
104103

105-
## Agent best practices
104+
## Tips for agents
106105

107-
- Batch only one related screen flow at a time.
108-
- After mutating steps (`open`, `click`, `fill`, `swipe`), add a sync guard (`wait`, `is exists`) before critical reads.
109-
- Treat prior refs/snapshots as stale after UI changes.
106+
- Keep each batch to one screen flow.
107+
- After steps that change the UI (`open`, `click`, `fill`, `swipe`), add a `wait` or `is exists` step before reads that matter.
108+
- Treat earlier refs and snapshots as stale after the UI changes.
110109
- Prefer `--steps-file` over inline JSON.
111-
- Keep batches moderate (about 5-20 steps).
112-
- Replan from the failing step using `details.step` and `details.partialResults`.
110+
- Keep batches to about 5-20 steps.
111+
- When a batch fails, use `details.step` and `details.partialResults` to replan from the failing step.
113112

114-
## Canonical recipes
113+
## Example recipes
115114

116115
Open app -> open thread -> type -> send
117116

@@ -150,9 +149,10 @@ Open app -> open action menu -> choose option -> verify
150149
]
151150
```
152151

153-
## Stale accessibility tree risk
152+
## Avoid acting on a stale accessibility tree
154153

155-
Rapid UI changes can outpace accessibility tree updates. Mitigate by inserting explicit waits and splitting long workflows into phases:
154+
The accessibility tree can lag behind fast UI changes. Add explicit waits, and split long workflows
155+
into separate batches by phase:
156156

157157
1. navigate
158158
2. verify/extract

0 commit comments

Comments
 (0)