> ## 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>
  These provider prefixed identifiers are specific to the **cloud** API. The open source
  [Framework](/framework/quickstart) selects models in a different way, by provider class and model
  ID such as `GoogleGenAI` with `gemini-3.1-flash-lite-preview`. See the
  [SDK configuration](/framework/sdk/configuration#llm-configuration) for details.
</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**       | Controls response randomness (0-2). Lower values are more deterministic |

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

  <Card title="Memory" icon="brain-circuit">
    Cross-task memory personalization. Use `memoryNamespace` to isolate memory between different workflows.
  </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.

## 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",
  "llmModel": "mobilerun/mobile-agent-fast",
  "maxSteps": 50,
  "executionTimeout": 300,
  "temperature": 0.5,
  "reasoning": true,
  "vision": true,
  "stealth": true,
  "memoryNamespace": "my-workflow",
  "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                                                                             |
| `llmModel`          | string    | required    | 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                                                                           |
| `temperature`       | number    | `0.5`       | Controls response randomness (0-2)                                                                                         |
| `reasoning`         | boolean   | `false`     | 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                                                                     |
| `memoryNamespace`   | string    | `"default"` | Memory namespace for cross-task personalization                                                                            |
| `continueOnFailure` | boolean   | `false`     | Whether the agent should keep executing if an individual action fails, instead of stopping the task                        |
| `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 |