> ## 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.

# Devices & Sessions

> How work is organized: devices, the default device, sessions, and the execution lane.

Three nouns organize all phone agent work: **devices** (phones), **sessions** (workflows), and **tasks** (instructions). This page covers the first two; tasks get [their own page](/guides/concepts/task-lifecycle).

## Devices

A device is an Android phone running the AGI Android app, signed in to your account, with Accessibility and overlay permissions granted. Registered devices appear in [`list_devices`](/api-reference/tools/list-devices) with online/offline status.

### The default device

One device is the **default**. Tools with an optional `device_id` - `phone_run_task`, `phone_session_start`, `phone_get_state`, and the device tools - fall back to it when the parameter is omitted. Set it once with [`set_default_device`](/api-reference/tools/set-default-device); it persists until changed.

<Note>
  Changing the default never reroutes existing work. After a session starts,
  its `session_id` determines the target phone, and task controls use the
  device that owns the `task_id`.
</Note>

### The execution lane

Each device executes **one task at a time**. Two consequences:

* Starting a new `phone_run_task` on a device **cancels any existing pending,
  running, or paused MCP task** on that device.
* Tasks started from the phone app itself are *not* cancelled - they occupy
  the lane and can keep a new MCP task `pending` until they finish.

### Pausing a device

[`phone_device_pause`](/api-reference/tools/phone-device-pause) is a safety switch: new tasks are rejected with `device_paused` until you call [`phone_device_resume`](/api-reference/tools/phone-device-resume). In-flight tasks keep running - pair it with [`phone_task_cancel`](/api-reference/tools/phone-task-cancel) if you need to stop current work too.

## Sessions

A session groups related tasks on **one device** so a multi-step workflow stays together.

### You rarely manage them

[`phone_run_task`](/api-reference/tools/phone-run-task) creates or reuses a session automatically and returns its `session_id`. The default pattern:

1. Start your first task with just a prompt - note the returned `session_id`.
2. Pass that `session_id` on related follow-up tasks so the workflow stays on
   one phone.
3. Call [`phone_session_end`](/api-reference/tools/phone-session-end) only when
   the entire workflow is finished - it also cancels every remaining task in
   the session.

Reach for [`phone_session_start`](/api-reference/tools/phone-session-start) directly only when you want the session in hand before dispatching work, or need `force_new: true` for an intentionally separate workflow.

### Session expiry

`phone_session_start` returns `expires_at`. Once it has passed, task calls against the session fail with `session_not_found_or_inactive` - start a new session and continue.

## Choosing boundaries

| Situation                                   | Do this                                                                           |
| ------------------------------------------- | --------------------------------------------------------------------------------- |
| Follow-up on the same workflow              | Reuse the `session_id`                                                            |
| Unrelated new errand                        | Let `phone_run_task` handle it, or `force_new: true` for explicit separation      |
| Workflow finished                           | `phone_session_end`                                                               |
| One task went sideways, workflow still good | [`phone_task_cancel`](/api-reference/tools/phone-task-cancel) - keeps the session |
| Different phone needed                      | New task with the other `device_id` - sessions never span devices                 |

## Next

<Card title="Task Lifecycle" icon="arrows-spin" href="/guides/concepts/task-lifecycle">
  What happens inside a task: states, terminal outcomes, and handoffs
</Card>