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

**Available Actions**:

```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), type_secret(secret_id, index),
swipe(coordinate, coordinate2), system_button(button),
wait(duration), open_app(text),
remember(information), complete(success, reason)
```

## 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.1-flash-lite-preview
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.*` |