Skip to main content
The most valuable phone-agent workflows span apps: research in one, verify in another, act in a third. The unit of organization is the session - several focused tasks on one device, in sequence, sharing context through your AI client.

​
A complete example

The assistant breaks this into several phone_run_task calls in one session - search, calendar check, message - reusing the same session_id so the whole workflow stays on one device. Logins and payment screens come back as needs_user_control handoffs, so nothing is bought or sent without you.

​
Why several tasks beat one mega-task

The client is the orchestrator: it reads each task’s result, decides the next step, and carries context forward in the next prompt.

​
Session discipline

  • Pass the session_id returned by the first task on every follow-up, so related tasks stay grouped on one phone.
  • Don’t end the session between steps. A successful task completion keeps the session alive; call phone_session_end only when the entire workflow is done.
  • One workflow, one device. Sessions never span devices. For a second phone, start a separate task/session with that device_id.
  • A wrong turn doesn’t kill the workflow - cancel the current task with phone_task_cancel and dispatch a corrected one in the same session.

​
Carrying context between tasks

Each task prompt should stand alone - include what the agent needs from earlier steps:
Have research tasks return structured output (“list each flight as airline / time / price, one per line”) so the next prompt can quote it precisely. See Task design.

Devices & Sessions

The session model in depth

Session management

Boundaries, expiry, and multi-device patterns