Skip to main content
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.

​
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 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; it persists until changed.
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.

​
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 is a safety switch: new tasks are rejected with device_paused until you call phone_device_resume. In-flight tasks keep running - pair it with 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 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 only when the entire workflow is finished - it also cancels every remaining task in the session.
Reach for 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

​
Next

Task Lifecycle

What happens inside a task: states, terminal outcomes, and handoffs