mobile-use — агент, который управляет телефоном на естественном языке

mobile-use — это открытый AI-агент, который управляет смартфоном на естественном языке. Вы пишете обычную фразу вроде «открой Gmail, найди три непрочитанных письма и покажи отправителей», а агент сам смотрит на экран, нажимает кнопки и приносит результат. Проект написан на Python, распространяется под лицензией Apache 2.0, и на момент публикации набирает больше трёх тысяч звёзд на GitHub.

Главная идея простая: у телефонов нет API, через который можно было бы выполнить обычную команду агента. Приложение закрывает свой интерфейс от внешнего мира. mobile-use решает эту задачу так же, как это сделал бы человек: смотрит на экран, принимает решение и нажимает. Никаких специальных интеграций с каждым приложением не нужно.

Что умеет

Отдельно авторы проекта предупреждают: с играми агент работает плохо. Игры не отдают дерево доступности, поэтому агенту просто не из чего понять, что происходит на экране. Это ограничение касается именно игр, обычные приложения с настройками доступности работают нормально.

Бенчмарк AndroidWorld и научная работа

Проект заявляет, что стал первым агентным фреймворком с результатом 100% на бенчмарке AndroidWorld. Это набор задач, где агент должен сам пройти сценарии в приложениях Android: настройки, почта, записи в календаре. Подробности есть на странице проекта — https://minitap.ai/benchmark. Официальная таблица с результатами лежит в Google Sheets.

Команда также выпустила научную работу: «Do Multi-Agents Dream of Electric Screens? Achieving Perfect Accuracy on AndroidWorld Through Task Decomposition». Она описывает, как была получена такая точность. Основной приём в ней — разбиение задачи на части, то есть декомпозиция: вместо одного агента, который делает всё сразу, работает несколько, и каждый отвечает за свой кусок. Работа доступна на arXiv — https://arxiv.org/abs/2602.07787.

Если вы используете проект в исследованиих или в коммерческом продукте, авторы просят сослаться на эту работу и указать компанию Minitap.

Какие устройства поддерживаются

Здесь важно сразу обозначить границы, чтобы не тратить время:

• Настоящие телефоны на Android — подключаются по USB, в настройках разработчика включается отладка по USB.
• Эмуляторы Android — настраиваются через Android Studio.
• Эмуляторы iOS — работают только на macOS.
• Настоящие iPhone — пока не поддерживаются.

Последний пункт — это ограничение самого проекта, а не вашей настройки. Поддержка физических iOS-устройств в README не заявлена.

Быстрый старт через Docker

Это самый короткий путь, но только для Android. Нужен установленный Docker, устройство подключено по USB с включённой отладкой либо запущен эмулятор.

На Linux и macOS:

chmod +x mobile-use.sh
bash ./mobile-use.sh \
  "Open Gmail, find first 3 unread emails, and list their sender and subject line" \
  --output-description "A JSON list of objects, each with 'sender' and 'subject' keys"

На Windows скрипт запускается через PowerShell:

powershell.exe -ExecutionPolicy Bypass -File mobile-use.ps1 `
  "Open Gmail, find first 3 unread emails, and list their sender and subject line" `
  --output-description "A JSON list of objects, each with 'sender' and 'subject' keys"

Флаг --output-description — самое интересное здесь. Вы описываете словами, в каком виде хотите получить данные, и агент собирает результат именно в этом виде. Не нужно писать схему или код разбора.

Если телефон подключён физически, на экране появятся запросы на соединение по ADB — их нужно подтвердить.

Установка вручную

Если вы хотите разбираться в коде или доработать проект, окружение ставится вручную. Менеджер пакетов здесь uv — он же создаёт виртуальное окружение.

Сначала клонируем репозиторий и заводим ключи в .env:

git clone https://github.com/minitap-ai/mobile-use.git && cd mobile-use
cp .env.example .env

Дальше создаём виртуальное окружение и ставим зависимости. Файл .python-version указывает версию Python, поэтому uv подберёт её сам:

# create the virtual environment and activate it
uv venv

# install dependencies with locked versions
uv sync

Активация окружения зависит от системы:

# macOS and Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate

Для iOS понадобится ещё Xcode и fb-idb от Facebook — это мост для работы с симуляторами iOS. Ставится через Homebrew:

# Install via Homebrew (macOS)
brew tap facebook/fb
brew install idb-companion

После установки должен быть доступен idb_companion, и его путь должен попадать в PATH.

Как запустить задачу

Работает агент так же просто, как любая консольная программа: команда передаётся аргументом.

Простая задача:

python ./minitap/mobile_use/main.py "Go to settings and tell me my current battery level"

Сбор данных с разбором в JSON:

python ./minitap/mobile_use/main.py \
  "Open Gmail, find all unread emails, and list their sender and subject line" \
  --output-description "A JSON list of objects, each with 'sender' and 'subject' keys"

Если модель в конфиге не задана, агент спросит, какую выбрать, из списка доступных.

Выбор модели

По умолчанию берутся настройки из файла llm-config.defaults.jsonc. Свой вариант удобно положить рядом — скопируйте шаблон и правьте его:

cp llm-config.override.template.jsonc llm-config.override.jsonc

Что важно знать про провайдеров:

Ключ для Anthropic выглядит так: переменная ANTHROPIC_API_KEY в файле .env, а сам пресет anthropic копируется из файла с настройками по умолчанию в ваш файл переопределения. Тот же принцип у MiniMax — только с ключом MINIMAX_API_KEY.

Отдельно поддерживаются локальные модели и любой сервис, который говорит по протоколу OpenAI. Для этого достаточно указать OPENAI_BASE_URL и OPENAI_API_KEY в .env, а в настройках выбрать провайдера openai для нужных узлов агента.

Для Google Vertex AI есть условие: либо у окружения уже настроены нужные права (например, gcloud, workload identity), либо путь к файлу сервисного аккаунта нужно положить в переменную GOOGLE_APPLICATION_CREDENTIALS.

Если что-то не работает

Скрипт подключается к устройству по IP, поэтому телефон и компьютер должны быть в одной сети Wi-Fi. Отсюда типичные ошибки:

Could not get device IP — скрипт не нашёл ни один из обычных интерфейсов Wi-Fi на устройстве. Посмотрите, какой интерфейс использует телефон, командой adb shell ip addr show up, и передайте скрипту ключ --interface с его именем.

Failed to connect to <DEVICE_IP>:5555 inside Docker — почти всегда закрывает файрвол. Простого решения нет: нужно открыть доступ на нужный порт.

Не удаётся скачать образы из ghcr.io — у вас истёкший токен от прошлых экспериментов с приватными репозиториями. Помогает команда docker logout ghcr.io, после неё скрипт запускают заново.

Лицензия и вклад в проект

Проект распространяется под лицензией Apache 2.0, текст лежит в файле LICENSE. В README отдельно просят указывать компанию Minitap, Inc., если вы используете код или вдохновляетесь архитектурой проекта.

Сам проект авторы называют быстро меняющимся и прямо просят присылать идеи и сообщения о багах. Правила оформления вклада описаны в CONTRIBUTING.md. Есть и обсуждения в Discord — https://discord.gg/6nSqmQ9pQs.

Документация по SDK лежит отдельно: https://docs.minitap.ai/mobile-use-sdk/quickstart. Пакет также опубликован на PyPI под именем minitap-mobile-use.