> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent

> Configure and run the Mobilerun agent to automate tasks on your devices.

The Mobilerun agent is an AI-powered automation system that executes tasks on Android devices. Configure the agent with a prompt and settings, then run it on any connected device.

## Overview

The agent:

* Interprets natural language instructions
* Interacts with device UI elements
* Executes multi-step workflows autonomously
* Returns results and structured output

## Configuration

### Task Prompt

The prompt describes what the agent should do. Write clear, specific instructions for best results.

```
Open the Settings app, navigate to Display settings, and enable dark mode
```

### Model Selection

Choose the LLM model that powers the agent. Different models offer different tradeoffs:

| Model Type | Characteristics |
| - | - |
| **Faster models** | Lower latency, lower cost per step, good for simple tasks |
| **Advanced models** | Better reasoning, higher accuracy, ideal for complex workflows |

Pass one of the following identifiers as the `llmModel` parameter in the REST API or the SDK, or
select it in the Playground. This table is the canonical catalog of models available for cloud
agent tasks.

| Model | `llmModel` identifier |
| - | - |
| Mobilerun Mobile Agent (Fast) | `mobilerun/mobile-agent-fast` |
| Mobilerun Mobile Agent (Thinking) | `mobilerun/mobile-agent-thinking` |
| Anthropic Claude Opus 4.6 | `anthropic/claude-opus-4.6` |
| Anthropic Claude Opus 4.8 | `anthropic/claude-opus-4.8` |
| Anthropic Claude Sonnet 4.6 | `anthropic/claude-sonnet-4.6` |
| Google Gemini 3.1 Flash Lite | `google/gemini-3.1-flash-lite` |
| Google Gemini 3.1 Pro (Preview) | `google/gemini-3.1-pro-preview` |
| Google Gemini 3.5 Flash | `google/gemini-3.5-flash` |
| Moonshot Kimi K2.6 | `moonshotai/kimi-k2.6` |
| OpenAI GPT-5.4 | `openai/gpt-5.4` |
| OpenAI GPT-5.4 Mini | `openai/gpt-5.4-mini` |

<Tip>
  The model lineup changes over time. To see the live list your account can use, call
  `GET /v1/models`, or use `client.models.list()` in the SDK. That endpoint is the source of truth
  whenever an identifier here returns a "model unavailable" error.
</Tip>

<Note>
  This model list applies to Mobilerun Cloud. For the open source Framework, choose a provider and
  model in the [Framework configuration](/framework/sdk/configuration#llm-configuration).
</Note>

### Execution Limits

| Setting | Description |
| - | - |
| **Max Steps** | Maximum number of actions the agent can take (1-10,000) |
| **Execution Timeout** | Time limit in seconds before the task is stopped |
| **Temperature** | Deprecated and ignored; sampling is controlled by the model provider |

### Features

<CardGroup cols={2}>
  <Card title="Reasoning Mode" icon="brain">
    Enables logical thinking and step-by-step analysis. The agent will reason through complex tasks before acting.
  </Card>

  <Card title="Vision" icon="eye">
    Allows the agent to process and understand visual content on screen. Required for most UI automation tasks.
  </Card>

  <Card title="Stealth" icon="ghost">
    Enable human-like device interactions for automations where detection matters.
  </Card>
</CardGroup>

### Platform Settings

| Setting | Description |
| - | - |
| **Device** | Choose a [device](/device-types) from your account |
| **Apps** | Select which [apps](/apps) should be available on the device |
| **Credentials** | Attach [credentials](/credentials) for authenticated workflows |
| **VPN Country** | Route traffic through a specific country |

### Structured Output

Define a JSON schema to receive structured responses from the agent. This is useful for:

* Data extraction tasks
* Validation workflows
* Integration with downstream systems

When a schema is defined, the agent formats its output to match the specified structure.

### Task Recording

Set `recordingEnabled: true` when you create a task to capture a video of the device screen for the whole run. Recording starts when the task enters the `running` state and stops when the task completes, fails, or is cancelled.

Once the recording has started, the task's status, list, and detail responses include two extra fields:

| Field | Description |
| - | - |
| `recordingId` | ID of the task's video recording |
| `recordingDeviceId` | ID of the device the recording was captured on |

Both fields are `null` while the task is still queued, when recording is disabled, or if the recording could not be started. Recording is best-effort. A recording failure never changes the task outcome.

Recording requires a device that supports video capture. If you create a task with `recordingEnabled: true` on a device that does not support recording, the API rejects it with a `400` response and a `DEVICE_RECORDING_UNSUPPORTED` error. Set `recordingEnabled` to `false` or choose a device that supports recording. If the device reports the unsupported capability only after the task has started, the task fails instead of silently running without a recording.

## Running the Agent

### Via Playground

Use the [Playground](/playground) for interactive testing:

1. Configure your task and settings
2. Select a device
3. Click **Run**
4. Monitor execution in the task stream

### Via API

Run tasks programmatically using the [API](/api-keys):

```json theme={null}
{
  "task": "Open Settings and enable dark mode",
  "deviceId": "<DEVICE_ID>",
  "llmModel": "mobilerun/mobile-agent-fast",
  "maxSteps": 50,
  "executionTimeout": 300,
  "temperature": 0.5,
  "reasoning": true,
  "vision": true,
  "stealth": true,
  "recordingEnabled": true,
  "continueOnFailure": false,
  "apps": ["com.android.settings"],
  "credentials": [],
  "outputSchema": {
    "type": "object",
    "properties": {
      "success": { "type": "boolean" },
      "darkModeEnabled": { "type": "boolean" }
    }
  }
}
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `task` | string | required | The prompt describing what the agent should do |
| `deviceId` | string | required | UUID of the device to run the task on |
| `llmModel` | string | `openai/gpt-5.6-luna` | LLM model identifier such as `"mobilerun/mobile-agent-fast"`. See the [model catalog](#model-selection) for the full list. |
| `maxSteps` | integer | `100` | Maximum number of actions the agent can take |
| `executionTimeout` | integer | `1000` | Time limit in seconds before the task is stopped. Accepts 1 to 2700 (45 minutes). |
| `temperature` | number | `0.5` | Deprecated and ignored; sampling is controlled by the model provider |
| `reasoning` | boolean | `true` | Enable step-by-step reasoning mode |
| `vision` | boolean | `false` | Enable visual understanding of screen content |
| `stealth` | boolean | `false` | Enable stealth mode for human-like device interactions |
| `recordingEnabled` | boolean | `false` | Record device video for the whole task. See [Task Recording](#task-recording) |
| `continueOnFailure` | boolean | `false` | Keep this task queued if the preceding task on the same device fails; otherwise it is cancelled |
| `apps` | string\[] | `[]` | Package names of apps to make available on the device |
| `credentials` | object\[] | `[]` | Credentials to attach for authenticated workflows |
| `outputSchema` | object | `null` | JSON Schema defining the structure of the agent's output |
| `vpnCountry` | string | `null` | Route device traffic through a specific country (`"US"`, `"DE"`, `"JP"`, etc.) |

### Via MCP

Use the [MCP integration](/mcp-server) to run tasks from AI assistants and IDEs.

## Execution Flow

1. **Initialization** - Agent connects to the selected device
2. **Observation** - Agent captures the current screen state
3. **Planning** - Agent determines the next action based on the prompt
4. **Action** - Agent executes the action (tap, type, scroll, etc.)
5. **Repeat** - Steps 2-4 repeat until the task is complete or limits are reached
6. **Output** - Agent returns results and any structured output

## Best Practices

| Practice | Description |
| - | - |
| **Be specific** | Clear prompts lead to more reliable execution |
| **Set reasonable limits** | Use appropriate max steps and timeouts for your task complexity |
| **Use structured output** | Define schemas when you need to process results programmatically |
| **Enable reasoning** | Turn on for complex multi-step tasks that require planning |
| **Attach credentials** | Pre-configure authentication rather than including secrets in prompts |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.