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

# Session Management

> Sessions, devices, and workflow boundaries done right.

Sessions group related tasks on one device. Managed well, they make multi-step workflows coherent; managed badly, they cause `session_not_found_or_inactive` errors and tasks landing on the wrong phone. The rules are few.

## Let the server manage sessions

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

1. Start the first task with just a prompt.
2. Pass the returned `session_id` on related follow-ups.
3. Call [`phone_session_end`](/api-reference/tools/phone-session-end) when the
   whole workflow is done - not after every task.

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

## Respect workflow boundaries

| Do                                                                                          | Don't                                  |
| ------------------------------------------------------------------------------------------- | -------------------------------------- |
| Reuse one session for one workflow's tasks                                                  | Start a new session per task           |
| End the session when the workflow finishes                                                  | End it after each successful task      |
| Cancel a single bad task with [`phone_task_cancel`](/api-reference/tools/phone-task-cancel) | End the whole session to stop one task |
| Start fresh after `phone_session_end`                                                       | Reuse an ended session                 |

Remember that ending a session **cancels every remaining task in it** - it is a workflow-level action.

## Handle expiry

`phone_session_start` returns `expires_at`. Once passed, task calls fail with `session_not_found_or_inactive`: start a new session (or just call `phone_run_task`, which will create one) and continue. Long-running orchestrations should treat this as a normal, recoverable event, not an error.

## Multiple devices

* Sessions never span devices. After a session starts, its `session_id`
  determines the target phone; task controls use the device that owns the
  `task_id`.
* Set a default once with
  [`set_default_device`](/api-reference/tools/set-default-device) instead of
  passing `device_id` everywhere. Changing the default does **not** reroute
  existing sessions or tasks.
* Before starting a workflow, confirm the intended device is online and not
  paused with [`phone_device_status`](/api-reference/tools/phone-device-status).
* Parallel workflows need parallel devices: each device runs one task at a
  time, and a new `phone_run_task` on a device displaces its current MCP task.

## The execution lane

One task per device, always:

* A new MCP task **cancels** any pending, running, or paused MCP task on that
  device (`terminal: "stopped_by_user"`).
* Tasks started from the phone app itself are not cancelled - they hold the
  lane and can keep your MCP task `pending` until they finish. If tasks
  routinely queue, raise `queue_wait_timeout_s` (default 60 s, max 300) or
  check the device before dispatching.

## Related

<CardGroup cols={2}>
  <Card title="Devices & Sessions" icon="mobile" href="/guides/concepts/devices-and-sessions">
    The underlying model
  </Card>

  <Card title="Error handling" icon="shield-halved" href="/guides/best-practices/error-handling">
    Recovering from expiry and displacement
  </Card>
</CardGroup>