Agent

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`

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.

This model list applies to Mobilerun Cloud. For the open source Framework, choose a provider and model in the Framework configuration.

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

Reasoning Mode

Enables logical thinking and step-by-step analysis. The agent will reason through complex tasks before acting.

Vision

Allows the agent to process and understand visual content on screen. Required for most UI automation tasks.

Natural input

Paces taps, swipes, and typing naturally instead of sending instant input. Set with the stealth parameter.

Platform Settings

Setting	Description
Device	Choose a device from your account
Apps	Select which apps should be available on the device
Credentials	Attach 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 for interactive testing:

Configure your task and settings
Select a device
Click Run
Monitor execution in the task stream

Via API

Run tasks programmatically using the API:

{
  "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 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`	Use natural pacing for taps, swipes, and typing
`recordingEnabled`	boolean	`false`	Record device video for the whole task. See 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 to run tasks from AI assistants and IDEs.

Execution Flow

Initialization - Agent connects to the selected device
Observation - Agent captures the current screen state
Planning - Agent determines the next action based on the prompt
Action - Agent executes the action (tap, type, scroll, etc.)
Repeat - Steps 2-4 repeat until the task is complete or limits are reached
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

Get started

Phones

Apps & networking

Run automation

Integrations

Developer tools

Overview

Configuration

Task Prompt

Model Selection

Execution Limits

Features

Reasoning Mode

Vision

Natural input

Platform Settings

Structured Output

Task Recording

Running the Agent

Via Playground

Via API

Via MCP

Execution Flow

Best Practices

​Overview

​Configuration

​Task Prompt

​Model Selection

​Execution Limits

​Features

Reasoning Mode

Vision

Natural input

​Platform Settings

​Structured Output

​Task Recording

​Running the Agent

​Via Playground

​Via API

​Via MCP

​Execution Flow

​Best Practices

Overview

Configuration

Task Prompt

Model Selection

Execution Limits

Features

Platform Settings

Structured Output

Task Recording

Running the Agent

Via Playground

Via API

Via MCP

Execution Flow

Best Practices