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

# Monitoring

> Watch tasks live, fetch steps, and debug with snapshots.

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`](/api-reference/tools/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.

<Tip>
  The monitor loop is your integration's heartbeat: monitor → check → monitor
  again. Never substitute a tight
  [`phone_task_status`](/api-reference/tools/phone-task-status) polling loop.
</Tip>

## 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](/guides/use-cases/app-testing).

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

## Lens 3: device state (environment)

[`phone_get_state`](/api-reference/tools/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`](/api-reference/tools/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`](/api-reference/tools/phone-task-message).

## A debugging session, end to end

1. Task seems stuck → [`phone_task_status`](/api-reference/tools/phone-task-status):
   what state is it actually in?
2. `pending` → [`phone_device_status`](/api-reference/tools/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](/guides/concepts/task-lifecycle#terminal-outcomes) has the
   move; the task's `error` object has the details.
5. Behavior still odd → [`phone_get_state`](/api-reference/tools/phone-get-state):
   accessibility running, right app in foreground, sane battery/network?

## Related

<CardGroup cols={2}>
  <Card title="Task lifecycle" icon="arrows-spin" href="/guides/concepts/task-lifecycle">
    States and outcomes the monitor reports
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/troubleshooting">
    When monitoring reveals a problem
  </Card>
</CardGroup>