Monitoring

Everything a phone task does is observable: its state, its recorded steps (screenshots and agent thinking), and the device it runs on. Good monitoring is knowing which of the three lenses to use.

​

Lens 1: the monitor (waiting)

phone_task_monitor is the wait primitive - it returns the moment something actionable happens:

• monitor_timed_out: false → the task is paused or completed. Act.
• monitor_timed_out: true → still pending/running. Call it again.

It catches every actionable event: successful completion (terminal: "ok"), user-input handoffs (needs_user_control from confirmation/login/CAPTCHA actions), errors, cancellations, timeouts, queue expiry, offline devices, expired sessions, and iteration limits.

​

Lens 2: steps (progress detail)

Both the monitor and phone_task_status accept:

• include_steps: true - include the task’s recorded steps: screenshots and agent thinking.
• since_step: N - only steps newer than step N, for incremental fetching.

Use steps to:

• Show live progress in your UI while a long task runs (poll status with since_step between monitor calls if you need finer granularity).
• Debug agent behavior - the screenshots show exactly what the agent saw when it made a decision.
• Build QA reports - see App testing.

Skip steps when you only need outcomes; payloads stay small and fast.

​

Lens 3: device state (environment)

phone_get_state reads the phone itself - battery, network, accessibility status, current app package, launchable apps. Pass task_id or session_id to inspect the exact device that owns existing work. Use it when behavior doesn’t make sense: an agent that “can’t find the app” (is it installed?), a sluggish run (battery? network transport?), a task that never starts (is the Accessibility service running?). Also useful: phone_device_status for the quick online/paused/last-seen check before and between workflows.

​

And the screen itself

Execution is visible on the device’s screen in real time. For supervised or high-stakes workflows, watching the phone is the most direct monitor there is - and you can steer mid-run with phone_task_message.

​

A debugging session, end to end

1. Task seems stuck → phone_task_status: what state is it actually in?
2. pending → phone_device_status: online? paused? lane held by an in-app task?
3. running but slow → monitor with include_steps: true + since_step: what is the agent doing right now?
4. completed with a surprising terminal → the terminal table has the move; the task’s error object has the details.
5. Behavior still odd → phone_get_state: accessibility running, right app in foreground, sane battery/network?

​

Related