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

# phone_run_task

> Run a natural-language instruction on a phone.

Starts a task: one natural-language instruction executed on the device. Returns `task_id` **immediately** - execution is asynchronous, and you follow up with [`phone_task_monitor`](/api-reference/tools/phone-task-monitor) to wait for the outcome.

This is the workhorse of the API. In most workflows it is the only tool you configure; sessions and device selection are handled for you.

## Parameters

<ParamField body="prompt" type="string" required>
  The instruction to execute, in plain language. See
  [Task design](/guides/best-practices/task-design) for what makes prompts
  execute reliably.
</ParamField>

<ParamField body="session_id" type="string">
  Attach the task to an existing workflow. Omit it and the server creates or
  reuses a session automatically, returning its `session_id`.
</ParamField>

<ParamField body="device_id" type="string">
  Target a specific device. Omit to use your default device. Ignored in favor
  of the session's device when `session_id` is provided - a session is bound
  to one phone.
</ParamField>

<ParamField body="per_call_timeout_s" type="integer" default="300">
  Execution deadline in seconds. Maximum 900. Tasks that exceed it complete
  with `terminal: "timeout"`. Time spent paused does not count.
</ParamField>

<ParamField body="queue_wait_timeout_s" type="integer" default="60">
  How long the task may wait for the phone to start it. Maximum 300. Tasks
  that never start complete with `terminal: "queue_wait_exceeded"`.
</ParamField>

<Note>
  For benchmarking and data-collection runs, `phone_run_task` also accepts
  optional trace tags: `run_id` (string), `run_type` (string), and
  `task_metadata` (object). Leave them unset for normal use.
</Note>

## Response

<ResponseField name="task_id" type="string">
  Returned immediately. Pass it to `phone_task_monitor` to wait for the
  outcome, and to task-control tools to steer, pause, or cancel.
</ResponseField>

<ResponseField name="session_id" type="string">
  The session that was created or reused. Pass it on later calls to keep
  related tasks in one workflow.
</ResponseField>

## Behavior

<Warning>
  Starting a new `phone_run_task` on the same device **cancels any existing
  pending, running, or paused MCP task** on that device (it completes with
  `terminal: "stopped_by_user"`). Tasks started from the phone app itself are
  not cancelled; they occupy the device's execution lane and can keep a new
  MCP task `pending` until they finish.
</Warning>

* One instruction, one task. For a multi-step workflow, run several tasks in
  the same session rather than one enormous prompt - see
  [Session management](/guides/best-practices/session-management).
* Long flows benefit from a higher `per_call_timeout_s`; tasks that hit the
  agent's action limit complete with `terminal: "iteration_limit"` and should
  be broken into smaller steps.

## Example

```json theme={null}
{
  "prompt": "Open Settings and report the current battery percentage.",
  "per_call_timeout_s": 300,
  "queue_wait_timeout_s": 60
}
```

## Related

* [`phone_task_monitor`](/api-reference/tools/phone-task-monitor) - wait for the outcome
* [`phone_task_message`](/api-reference/tools/phone-task-message) - steer or answer the task
* [`phone_task_cancel`](/api-reference/tools/phone-task-cancel) - stop it
* [Task lifecycle](/guides/concepts/task-lifecycle) - states and terminal outcomes