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

# Architecture

> Understanding the Mobilerun multi-agent system for device automation.

## What is Mobilerun?

Mobilerun uses a **multi-agent architecture** where specialized agents work together to complete tasks. Instead of one agent doing everything, different agents handle planning, execution, and computation.

```
MobileAgent (orchestrator)
├── Reasoning Mode: ManagerAgent → ExecutorAgent
└── Direct Mode: FastAgent
```

## Execution Modes

### Reasoning Mode (`reasoning=True`)

Manager creates plans, Executor takes actions. Best for complex multi-step tasks.

```
Goal → Manager (plan) → Executor (action) → Manager (check) → Executor (next) → ...
```

### Direct Mode (`reasoning=False`)

FastAgent executes immediately via XML tool-calling without planning overhead. Best for simple tasks.

```
Goal → FastAgent (XML tool-calling) → Done
```

## Core Agents

### MobileAgent (Orchestrator)

Main coordinator that routes between agents based on mode.

**Location**: `mobilerun/agent/droid/droid_agent.py`

### ManagerAgent (Planner)

Creates strategic plans and breaks tasks into subgoals. Reasoning mode only.

**Location**: `mobilerun/agent/manager/manager_agent.py`

**Workflow**: `prepare_context()` → `get_response()` → `process_response()` → `finalize()`

### ExecutorAgent (Actor)

Executes atomic actions for each subgoal. Reasoning mode only.

**Location**: `mobilerun/agent/executor/executor_agent.py`

**Workflow**: `prepare_context()` → `get_response()` → `process_response()` → `execute()` → `finalize()`

### FastAgent (Direct Executor)

Uses XML tool-calling for device interaction. Direct mode only.

**Location**: `mobilerun/agent/fast_agent/fast_agent.py`

**Common actions include:**

```python theme={null}
click(index), click_at(x, y), click_area(x1, y1, x2, y2),
long_press(index), long_press_at(x, y),
type(text, index=None, clear=False), type_text(text, clear=False),
type_secret(secret_id, index),
swipe(coordinate, coordinate2, duration=1.0), system_button(button),
wait(duration=1.0), open_app(text | bundle_id | app_id),
complete(success, message)
```

`type_secret` is available when credentials are configured. For `open_app`, use `text` for an Android app name, `bundle_id` for an iOS app, or `app_id` for an exact app ID.

## Configuration

Configure different LLMs per agent:

```yaml theme={null}
llm_profiles:
  manager:
    provider: Anthropic
    model: claude-sonnet-4
  executor:
    provider: OpenAI
    model: gpt-4o
  fast_agent:
    provider: GoogleGenAI
    model: gemini-3.5-flash-lite
agent:
  reasoning: true       # Enable Manager/Executor workflow
  max_steps: 15         # Maximum execution steps (global)
  manager:
    vision: true        # Send screenshots to Manager
  executor:
    vision: true        # Send screenshots to Executor
  fast_agent:
    vision: false
    parallel_tools: true
```

## When to Use Each Mode

**Use Reasoning Mode for:**

* Multi-step tasks (booking flights, configuring settings)
* Tasks requiring planning and adaptation
* Complex workflows across multiple apps

**Use Direct Mode for:**

* Simple actions (screenshots, sending messages)
* Fast execution without planning overhead
* Well-defined single-step tasks

## Shared State

All agents share `MobileAgentState` for coordination:

* Action history and outcomes
* Error tracking and recovery
* Memory and context
* Current plan and progress

## Quick Reference

| Agent | Role | Best For | Mode | Config Key |
| - | - | - | - | - |
| MobileAgent | Orchestrator | Entry point | Both | `agent.*` |
| ManagerAgent | Planner | Strategy, recovery | Reasoning | `agent.manager.*` |
| ExecutorAgent | Actor | Action execution | Reasoning | `agent.executor.*` |
| FastAgent | Direct | Simple tasks | Direct | `agent.fast_agent.*` |


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