# MobiAgent for Android GUI Automation: Setup, Models, and Limits

> MobiAgent is a Python-based framework for controlling Android phones through ADB, with separate planner, decider, and grounder model roles. It is best suited to engineers who need configurable GUI-agent experiments, execution traces, and evaluation workflows, rather than users seeking only a ready-made Android app.

**IPADS-SAI/MobiAgent** — The Intelligent GUI Agent for Mobile Phones

- Repository: https://github.com/IPADS-SAI/MobiAgent
- Stars: 1,924 · Forks: 231
- Language: Python
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/ipads-sai-mobiagent

## What MobiAgent Solves on Android

MobiAgent targets the problem of asking an AI system to operate a phone's graphical interface rather than limiting the system to a fixed API. Its intended users are engineers and researchers who want to build or customize mobile agents, collect execution data, evaluate GUI behavior, or connect an agent to real Android applications. The repository description calls it “The Intelligent GUI Agent for Mobile Phones,” while the README presents it as a systematic framework for customizable mobile agents.

The repository is broader than a single runner. It contains the MobiMind agent model family, AgentRR for agent acceleration, MobiFlow for benchmark evaluation, data collection and annotation tools, an Android app, deployment files, and phone-facing runners. The `runner/` component connects to a phone through ADB, executes tasks, and records execution traces. That trace capability is important for development because it gives an engineer a record of what the agent attempted, although the README does not specify a trace format or a rollback mechanism.

MobiAgent is therefore aimed at a development and evaluation workflow. It is not presented as a general-purpose Android automation library with a stable, narrowly documented API. The available instructions focus on configuring model services and preparing a physical Android device. Users who only want to issue fixed ADB commands or automate a few deterministic UI actions may find the framework more involved than necessary.

## MobiAgent's Planner, Decider, and Grounder Roles

The documented model deployment separates the agent into at least three model roles. The decider and grounder are served by MobiMind, while the planner is served by `Qwen/Qwen3-VL-4B-Instruct`. The README's deployment example uses one port for the decider or grounder service and another port for the planner service.

This separation reflects a task flow in which planning, action selection, and visual grounding have different responsibilities. The repository includes prompts and runner components, but the visible README does not provide the complete request schema or a complete configuration file showing how every role is connected. As a result, the exact internal message sequence cannot be confirmed from the README alone. The architecture image is linked as `assets/arch.png`, but its contents are not represented in the available text.

The framework also documents newer execution features. The news section identifies multi-task execution, user profile memory enabled with `--user_profile on`, experience memory, and support for custom workflows with a raw-data cleaning pipeline. These additions indicate that MobiAgent can carry state or workflow information beyond a single immediate screen interaction. They do not, however, provide enough detail to claim how memory is scoped, when it is retrieved, or how stale information is removed.

For evaluation, MobiFlow is described as an agent benchmark based on a milestone DAG. That suggests task progress can be represented through milestones rather than requiring every step to be judged in isolation. The README does not publish the benchmark's task format, dependency rules, or scoring implementation in the available instructions.

## Installing the Python Runner and Connecting an Android Phone

The shortest documented Python setup targets the runner alone. Create the documented Python environment, activate it, and install the simplified dependency file. The README uses `python=3.10`, so that version is the documented starting point rather than a claim about every supported Python release.

```bash
conda create -n MobiMind python=3.10
conda activate MobiMind
pip install -r requirements_simple.txt
```

This command sequence creates a conda environment, selects Python 3.10, and installs the dependencies needed for the simplest runner path. The full pipeline requires more setup, including OmniParser weights, an embedding model, and optional OCR utilities. The full dependency file contains packages such as `torch`, `paddleocr`, `transformers`, `openai`, `uiautomator2`, `fastapi`, `ui-tars`, `mem0ai`, and `pymilvus`.

The phone must be prepared as an ADB-controlled Android device. The README instructs users to install ADBKeyboard, enable Developer Options, allow USB debugging, and connect the phone with a USB cable. It does not document emulator use, wireless ADB, device-specific exceptions, or permission handling, so physical-device behavior should be checked against the runner documentation before adoption.

The model services are launched separately with vLLM. The documented commands are shown below. Replace the angle-bracket port markers with the ports selected for the local services; the README does not prescribe fixed port numbers.

```bash
vllm serve MobiMind-Reasoning-4B --port <decider/grounder port>
vllm serve Qwen/Qwen3-VL-4B-Instruct --port <planner port>
```

The model checkpoints must be downloaded before these services are started. The README links MobiMind-1.5-4B checkpoints on Hugging Face and ModelScope, but the model-deployment example names `MobiMind-Reasoning-4B`. That distinction should be resolved before running the commands, because the documentation presents several MobiMind variants.

## A First ADB-Based Agent Task

The README's visible instructions stop after model deployment at the heading “Agent Me,” so it does not provide a complete, copy-paste command for submitting a first task through the Python runner. The repository structure does identify `runner/` as the executor that connects to a phone through ADB, executes tasks, and records execution traces. That is enough to identify the intended execution path, but not enough to reproduce the exact CLI invocation from the available text.

A practical first use would therefore begin by confirming the two documented service roles are reachable, confirming that ADB sees the prepared phone, and then following the runner-specific README for task submission. The documented mobile app offers a separate direct-use route: download the MobiAgent app from the v1.0.1 release page. The README does not state whether the app uses the same three-model arrangement, whether it requires the Python runner, or which local services it contacts.

The multi-task example demonstrates the intended scope rather than a stable command-line syntax. Its task asks the agent to find a camera recommendation in Xiaohongshu, search for that camera on Taobao, and send the brand, name, and price to a contact named Xiao Zhao through WeChat. This example crosses applications and preserves information between steps. It is useful as a capability description, but it is not a test result and should not be interpreted as proof that every app, account state, screen layout, or language is supported.

For an initial evaluation, keep the task small and inspect the recorded trace. The README documents trace recording but not retry semantics, confirmation dialogs, timeout handling, or recovery after an app update. Those details determine whether a demonstration task can be turned into dependable automation.

## Workflows, Memory, and MobiFlow Evaluation

MobiAgent has expanded beyond a basic single-task runner. The news section states that multi-task execution is supported, with details in `runner/mobiagent/multi_task/README.md`. It also documents a user profile memory system controlled by `--user_profile on`, with additional documentation under `runner/README.md`. The news entry for experience memory and the later announcement about custom workflows show that state and workflow data are separate areas of development.

The custom-workflow support is paired with a raw-data cleaning pipeline. That pairing matters for engineers who collect phone interactions and need to turn raw traces into usable training or evaluation data. The available text does not define the raw-data schema, cleaning rules, supported destinations, or whether cleaning is reversible. Therefore, an engineer should not assume that collected screenshots, actions, and model outputs can be exported into an arbitrary format without checking the workflow documentation.

MobiFlow provides the evaluation side of the framework. Its stated basis is a milestone DAG, which offers a way to represent dependencies among task milestones. The repository includes the `MobiFlow/` directory, but the README does not document how to add a task, install the benchmark, run it against a model, or interpret its score. The evaluation claims shown in the README are images rather than text that can be independently described here, so they are not used as evidence of performance.

A related trade-off appears in AgentRR. The `agent_rr/` directory is described as an Agent Record & Replay framework, and the news section labels AgentRR as an agent acceleration framework. The README includes a demo comparing a first task with a subsequent task, but it does not explain record validity, replay assumptions, cache invalidation, or the conditions under which replay is unsafe after an app changes.

## Where MobiAgent Is the Wrong Choice

The clearest limitation is setup complexity. The Python route requires a Python environment, Android device preparation, ADBKeyboard, model checkpoints, and vLLM services. The full route adds OmniParser weights, an embedding model, and optional OCR installation. This is a substantial boundary for an engineer who needs a small script rather than a research-oriented agent system.

The documentation also lacks several operational details needed for production automation. It does not specify a public API for task submission, supported Android versions, device performance requirements, behavior when apps change their layouts, or how to handle login, payment, permission, and irreversible actions. The multi-task example includes shopping and messaging, but the README does not claim that those operations are safe to automate or that credentials are handled securely.

The direct Android app is a practical alternative when the goal is to try MobiAgent without writing Python. The difference is concrete: the app is downloaded from the release page and used through the mobile app experience, while the Python scripts require ADB, a connected device, local dependencies, and separately served models. Neither route should be selected solely from the demo videos. Confirm what the app needs and what the Python runner's deployment and logging path actually support.

Licensing is comparatively clear at the repository level: the repository identifies its license as Apache-2.0. That permits use and modification under the license's conditions, including preservation of notices and handling of warranty disclaimers. It does not automatically grant rights to third-party model checkpoints, datasets, apps, or external services, so those resources require separate review.

## Maintenance, Releases, and Adoption Boundaries

The repository is not archived. Its last push was on 2026-07-17, so the available history indicates continued changes after the v1.0.1 release dated 2025-12-22. The repository also contains a `CHANGELOG.md`, although its contents are not included here. Recent changes listed in the README include custom workflows, raw-data cleaning, GUI mobile-agent work, on-device inference support, and a unified runner for multiple models.

That combination creates a compatibility question for adopters. The README names `MobiAgent`, `UI-TARS`, `AutoGLM`, `Qwen-VL`, and `Gemini` in connection with the unified runner, while the model deployment instructions use MobiMind and Qwen model names. A project can expose several components without making them interchangeable. The exact runner branch, configuration file, model revision, and expected service contract must be checked together.

MobiAgent is most appropriate for engineers building or studying Android GUI-agent systems who can maintain device access and model services. It is less appropriate for a deployment that needs documented production support, a stable automation API, or a complete rollback story. The first verification should be the documented Python 3.10 and `requirements_simple.txt` path against one controlled phone and one downloaded checkpoint. After that, inspect `runner/`, the relevant model configuration, the generated trace, and the exact command or workflow that submits the task.

## Conclusion

Adopt MobiAgent when you need an extensible Android GUI-agent runner with ADB control, model separation, traces, custom workflows, or MobiFlow evaluation. Do not choose it as a zero-setup application replacement, because the Python path requires a phone connection, model deployment, and additional dependencies. Verify first that your Android device, ADBKeyboard installation, model checkpoints, vLLM services, and chosen runner documentation match your intended workflow. The repository is not archived, and the last push was on 2026-07-17, while the latest listed release is v1.0.1 from 2025-12-22.

## FAQ

### What is MobiAgent used for?

MobiAgent is a customizable mobile agent system for executing tasks through Android phone interfaces. The repository includes model components, an ADB-connected runner, data collection tools, execution traces, and the MobiFlow benchmark.

### How do I install MobiAgent for Android?

For the Python runner, the README documents creating a conda environment with Python 3.10 and installing `requirements_simple.txt`. You also need an ADB-enabled Android phone, ADBKeyboard, model checkpoints, and vLLM model services.

### Which models does MobiAgent use?

The deployment example uses `MobiMind-Reasoning-4B` for the decider or grounder service and `Qwen/Qwen3-VL-4B-Instruct` for the planner service. The README also lists several MobiMind model variants, so the exact checkpoint must match the runner configuration.

## Sources

- [IPADS-SAI/MobiAgent on GitHub](https://github.com/IPADS-SAI/MobiAgent)
- [Issues](https://github.com/IPADS-SAI/MobiAgent/issues)
- [License: Apache-2.0](https://github.com/IPADS-SAI/MobiAgent/blob/main/LICENSE)
- [README](https://github.com/IPADS-SAI/MobiAgent/blob/main/README.md)
- [Releases](https://github.com/IPADS-SAI/MobiAgent/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ipads-sai-mobiagent