> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone agent

> Give a task in plain words and let Appeeky's agent work through it on your phone, one step at a time.

With the phone agent you don't send single actions. You write a task, and the agent looks at the screen, picks one action, looks again, and repeats until the screen shows that the task is done.

You can run it from two places:

* The **Agent** panel on the **Phone** page of [Appeeky Desktop](https://docs.appeeky.com/docs/phones/desktop.md).
* `POST /v1/phones/agent`, which streams each step. See below.

> [!NOTE]
>
> The phone agent uses **0 API credits**. Your Mac must be sharing the phone. See [Connect phones](https://docs.appeeky.com/docs/phones/connect-phones.md).

***

## How a run works

1. The agent takes an observation of the phone.
2. It chooses one action: tap, type, swipe, scroll, press a key or open an app.
3. The action runs on the phone. A tap on a button like Post, Send or Buy waits for your approval first.
4. Steps 1 to 3 repeat until the agent reports that it is done, or it reaches the step limit.

| | |
| - | - |
| **Step limit** | 30 steps per run |
| **Task length** | Up to 2,000 characters |
| **Keys it can press** | `home`, `back`, `enter`, `delete`, `app_switch` |
| **What it can't do** | Long press, list apps, or push media. Copy media to the phone first with [`push_media`](https://docs.appeeky.com/docs/phones/actions#push-media) |

### Rules the agent follows

* If you deny an approval, or it expires, the agent stops and explains. It does not look for another way to do the same thing.
* It never enters passwords, codes or payment details that you didn't include in the task.
* It leaves text that a field already holds, such as a signature or a draft, unless the task says to remove it.
* It reads the state of a switch or checkbox before tapping it, and leaves it alone when it is already right.
* It reports the task as done only after the newest screen shows it.

***

## Run a task with the API

```
POST /v1/phones/agent
```

| Field | Type | Description |
| - | - | - |
| `task` | string | Required. 1 to 2,000 characters |
| `device` | string | Optional device id. Needed when more than one phone is online |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -N -X POST https://api.appeeky.com/v1/phones/agent \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Open TikTok and post the newest video in the gallery with the caption Week 3 and still going",
    "device": "Studio-MacBook/adb:39111FDJH00ABC"
  }'
```

The response has the content type `application/x-ndjson`. Each line is one JSON event:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"type":"screen","step":1,"image":"<base64>","mimeType":"image/jpeg"}
{"type":"step","step":1,"action":"open_app","text":"","detail":{"appId":"com.zhiliaoapp.musically","result":"opened com.zhiliaoapp.musically"}}
{"type":"screen","step":2,"image":"<base64>","mimeType":"image/jpeg"}
{"type":"step","step":2,"action":"tap","text":"The upload button is at the bottom.","detail":{"element":14,"result":"tapped"}}
{"type":"done","summary":"The profile screen shows the new video at the top of the grid.","steps":9}
```

| `type` | Fields | Meaning |
| - | - | - |
| `screen` | `step`, `image`, `mimeType` | The screenshot the agent looked at before this step |
| `step` | `step`, `action`, `text`, `detail` | The action it took. `text` is the agent's short note, which can be empty. `detail` holds the action's parameters and a `result` string |
| `done` | `summary`, `steps` | The run ended. `summary` says what the last screen shows, or why the agent stopped |
| `error` | `message`, `code` | The run failed, for example because no phone is online. `code` is present for some errors |

The stream ends after a `done` or `error` event.

### How runs end

| Ending | What you see |
| - | - |
| Task finished | `done` with the agent's summary |
| You denied an approval, or it expired | `done` with a summary that starts with `Stopped:` |
| Step limit reached | `done` with `Reached the 30-step limit.` |
| An action failed | The run continues. The failure is in that step's `detail.result`, and the agent tries another way |
| The phone or Mac went offline | `error` |

To stop a run, close the connection. The agent stops before its next step.

> [!NOTE]
>
> A request with a missing or too long `task` returns a normal JSON error with status `400` and the code `INVALID_REQUEST`. After the stream has started, the HTTP status is `200` and problems arrive as `error` events.

***

## Write good tasks

* **Name the app and the result.** *Open Instagram and post the newest photo in the gallery with the caption "Launch day"* is better than *post my photo*.
* **Give the exact text.** Captions, messages and search terms should be in the task word for word.
* **Prepare the phone.** Unlock it, sign in to the app yourself, and put the media in the gallery before the run.
* **One goal per task.** Thirty steps go fast. Split long jobs into several tasks.
* **Stay near the dashboard.** A post or send needs your approval within 10 minutes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.