Skip to main content
A phone task is one natural-language instruction executed on a real device. The difference between a flaky task and a reliable one is almost always the prompt. Five principles cover most of it.

​
1. One errand per task

Size each phone_run_task to a single errand, and chain follow-ups in the same session. ✅ Good - focused:
❌ Bad - a whole afternoon in one prompt:
Oversized tasks burn their timeout, risk terminal: "iteration_limit", and lose all progress on failure. Several tasks in one session get separate timeout budgets and keep completed results. See Cross-app workflows.

​
2. Name apps and targets precisely

The agent operates the real UI - ambiguity on a phone means tapping the wrong thing.
  • Name the app as it appears on the device. When unsure what is installed, check first with phone_get_state - it lists launchable apps with label and package name.
  • Spell out contact names, account names, and which screen or tab to use.
  • Give the agent an explicit escape hatch: “if you’re unsure, stop and ask me” - that surfaces as a handoff instead of a wrong guess.

​
3. Gate anything that acts

Reading is safe to automate; sending, buying, deleting, and changing settings deserve a confirmation gate in the prompt:
Sensitive moments the phone detects itself - logins, confirmations, CAPTCHAs - always come back as needs_user_control regardless. The gate covers the judgment calls above that bar. See Security.

​
4. Specify the output you want

The task’s result is your return value - define its shape:
Structured results make the next task’s prompt (and your client’s reasoning) precise. Ask for “not found” to be reported explicitly so silence never has to be interpreted.

​
5. Set boundaries for read-only work

Tell the agent what not to do, so observation doesn’t become action:

​
Quick checklist

  • One errand, not a workflow
  • Apps, contacts, and screens named exactly
  • Confirmation gate on anything that sends, buys, deletes, or changes settings
  • Output format specified, including the “not found” case
  • Read-only boundaries stated
  • “Ask me if unsure” escape hatch included

Task lifecycle

What happens after you press go

Performance

Timeouts and task sizing