mobilerun

The Mobilerun SDK provides APIs for building mobile automation workflows using AI agents. The core architecture consists of the following components:

• MobileAgent: The main agent coordinator responsible for multi-agent orchestration.
• AndroidDriver: An Android device driver that operates via ADB.
• IOSDriver: A driver for iOS device automation.
• DeviceDriver Base: The foundational layer containing the Base class, StateProvider, UIState, ActionContext, and ToolRegistry.

Mobilerun provides several key capabilities for building production-ready mobile automation:

• Structured Output: Extract typed data using Pydantic.
• Credential Management: Securely store and manage API keys.
• App Cards: Provide app-specific guidance to agents.
• Custom Tools: Extend the framework's capabilities by implementing custom functions.

MobileAgentState is a Pydantic model that acts as the central coordination mechanism for Mobilerun's multi-agent workflows. Instead of using complex message passing between agents (such as the Manager, Executor, and FastAgent), all agents read from and write to this single shared data structure.

It is used for:

• Cross-agent communication: Sharing information about actions, results, and errors.
• Progress tracking: Monitoring step counts, action history, and visited apps/screens.
• Memory management: Storing agent memory, custom variables, and user session data.
• Error coordination: Managing error flags, escalation thresholds, and error descriptions.

Mobilerun uses a multi-agent architecture coordinated by MobileAgent. It supports two primary operational modes:

1. Reasoning mode (reasoning=True): Uses a Manager-Executor loop. The Manager plans the steps, and the Executor performs the actions until the task is complete.
2. Direct mode (reasoning=False): Uses CodeActAgent to generate and execute Python code directly to achieve the goal.

Choose between the local Framework and the managed Cloud service based on your needs:

Cloud Device Types:

• Personal: Your own hardware connected to Mobilerun Cloud.
• Cloud Phone (Hosted): Instantly available cloud-hosted phone.
• Physical Phone (Hosted): Real hardware for workflows requiring high device authenticity and trust.

App cards are app-specific instruction guides (cheat sheets) that provide agents with knowledge about UI navigation, buttons, shortcuts, gestures, and search syntax. They improve success rates for complex tasks and reduce token usage by preventing trial-and-error exploration.

App cards are automatically loaded by the Manager Agent when running in reasoning mode. They are enabled by default.

Follow these steps to get Mobilerun running on an Android device (ensure ADB is installed and USB debugging is enabled):

1. Install the Portal: Run mobilerun setup to install the Mobilerun Portal app and enable accessibility services on your device.
2. Verify Connection: Run mobilerun ping to confirm the Portal is accessible.
3. Configure LLM: Run mobilerun configure to select your provider, auth method, and model. Alternatively, set environment variables like GOOGLE_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY.
4. Run a Command: Use mobilerun run "<command>" to execute a task.

uv tool install mobilerun
mobilerun setup
mobilerun configure
mobilerun run "Open settings and turn on dark mode"

To allow a Docker container to control your Android device via USB, you must configure your host system with a static udev rule and ensure ADB is not running on the host.

1. Verify ADB Connection: Run adb devices. The device should appear as device. If it shows unauthorized, accept the prompt on the phone.
2. Check ADB Keys: Ensure $HOME/.android contains adb.5037, adbkey, and adbkey.pub.
3. Create Static USB Mapping:
   • Find your device's idVendor and idProduct using lsusb.
   • Create /etc/udev/rules.d/51-android.rules and add a rule to map the device to a static path (e.g., phone1/phone).
   • Reload rules with sudo udevadm control --reload-rules and sudo udevadm trigger.
4. Stop Host ADB: Kill the host ADB server so the container can claim the connection: adb kill-server.

App cards are only utilized by the Manager Agent when running in reasoning mode. To use them via the CLI, include the --reasoning flag. If using the SDK, ensure reasoning: true is set in your configuration.

Direct execution mode (without the --reasoning flag) does not use app cards.

# App cards enabled (Manager uses them for planning)
mobilerun run "Archive all unread emails" --reasoning

# App cards not used (direct execution mode)
mobilerun run "Tap the button"

Use the following gestures and UI elements to navigate Gmail:

• Folders: Access Inbox, Sent, Drafts, Trash, etc., via the hamburger menu in the top-left.
• Compose: Tap the floating action button (bottom-right) to start a new email.
• Quick Actions: Swipe left or right on emails in the list to archive or delete them.

You can initialize a MobileAgent using minimal defaults or by loading a configuration from a YAML file. The agent requires a goal parameter representing the task description.

from mobilerun import MobileAgent, MobileConfig

# Minimal (uses defaults)
agent = MobileAgent(goal="Open settings")
result = await agent.run()

# Load from config.yaml
config = MobileConfig.from_yaml("config.yaml")
agent = MobileAgent(goal="Open settings", config=config)
result = await agent.run()