AI Agent for Android Automation: From Prompt to Macro

MAS Agent is the AI agent for Android automation inside Macro Automation Studio (MAS). You describe a task in plain English. The agent explores the app on a device, builds a map of its screens, captures the buttons and readouts it needs from the live screen, and writes a standard MAS Python macro with template images and OCR regions. It then validates the macro with 3 validation runs on the same device and hands it to you. From then on the macro replays without a model in the loop, at zero credits.

Before you start

• MAS installed and signed in, on the free trial or a paid plan. See Install.
• A device the agent can drive: a running emulator added in Device Groups, or a cloud device in the Ready state.
• The app you want automated installed on that device and past its login screen.
• AI credits on your account. The Billing page explains how credits work.

Start an Android automation session with the agent

1. Open Agent in the sidebar.
2. Pick the Device. The list has two groups, Local emulators and Cloud devices. Click Refresh devices if an emulator you just started is missing.
3. Pick the Provider and Model. Cloud models run on MAS servers and are billed from your AI credits.
4. Type the task in the prompt box, for example “Collect the daily reward and close every popup”, and click Author.

Where the session runs depends on the device:

• Local emulator: MAS starts the agent engine on your machine (“Starting the agent engine…”). The engine talks to the emulator over adb, so the emulator and the app stay open.
• Cloud device: the session starts on MAS servers next to the device (“Running on our servers”). You can close the app and check back later; the conversation is saved on your account. A cloud device always uses Cloud models.

One agent runs per device at a time. If another chat is busy on the same device, MAS offers Go to that chat or Stop it, continue here.

Phases: how the agent generates a macro from a prompt

The Overview tab shows the current phase, and the Progress checklist tracks it in plain words.

While a question card is open the phase reads WAITING_FOR_USER and the session clock pauses. Repair is bounded by progress, not by a count: when the same failure repeats on unchanged code, validation pauses until the agent brings a new diagnosis or asks you. A hard backstop of 25 repair cycles ends a session that would otherwise loop.

Questions, the plan and steering

The agent asks instead of guessing. When two readings of the screen are possible, or a step would spend or destroy something, it stops and puts the question to you.

• A question card titled The agent needs your input holds one to four questions. Pick a choice or type a custom answer, then click Send answers.
• The plan is the contract for the session: the goal, the main loop and the success check. Any in-game spending needs a limit you approve before the agent spends anything in the app.
• To redirect it mid-run, type in the composer while it works and click Steer. The message lands in the agent’s next decision.
• Stop ends the session at once. Work is saved; send a follow-up message in the same chat to continue.

Budgets and credits

The Budgets panel shows steps, credits (or cost), tokens and in-game spend for the session. A budget of 0 means no limit, and that is the default on every axis: your credit balance is the real limit. When the balance reaches zero, MAS refuses further model calls and the session stops with what it has.

Credits are spent only while the agent explores, writes and tests. A finished macro runs at zero credits on every device. The Credits readout on the Agent page updates while a session runs, and Top up credits opens the Subscription page. Mechanics are on the Billing page; rates are on the pricing page.

The menu map

A map is the agent’s memory of an app: every screen it has seen and the buttons that connect them. It grows by itself while the agent works, and the Map tab shows it as a graph with counts for screens, transitions, taps and unexplored buttons.

• Map this app walks the menus deliberately (about 8 minutes); Deep pass opens deeper menus (about 20 minutes). Both are navigation only: the agent backs out of anything that sells.
• Share my maps pools your passes with other accounts mapping the same app. Contributions stay private until another account corroborates them, and you can retract one under My contributions. With sharing off, your maps still help your own sessions.

Add to My Macros

When the result card shows Done, click Add to My Macros. MAS creates the project in your projects folder, uploads every template image to your Image Library under an agent/ folder, rewrites the image ids inside the code, and initializes git. The chat then offers Open in IDE, Test run on the same device, and a schedule card (Once, Daily or Weekly, then Create schedule). Scheduled runs use the arguments saved on the device card.

To change a macro later, pick it under Improve in the workspace list and describe what to add or change. The agent starts from the existing project and updates it in place.

What the project contains

task.yaml records the task name, the prompt, the app package, the device, an entry precondition (a template that must be visible at start), a timeout, script_runs: 3, the test arguments and the checks. Check kinds are exit_code, template, ocr_region, storage, adb_shell, element_visible and element_text, each with when: active, idempotent or always. Validation is a smoke test: the main loop is limited to two iterations. Studio’s runtime never reads task.yaml.

After install you edit like any other project: the flow in src/app.py with the full SDK, template images in Asset Lab and the Image Library, OCR regions in the code, and the argument form in UI Builder. The Studio tour covers the editor, runs and the debugger.

An AI that plays mobile games and any other screen routine

MAS Agent handles screen-driven routines on emulators and cloud devices: the popups and interruptions it met during exploration, counters and timers read with OCR so the macro can wait or skip, and the same routine across a device group on a schedule. It asks you for decisions it cannot read off the screen, for the budget before it starts, and before anything destructive or anything that buys something.

It works from the screen only. It never modifies an APK or reads a game’s memory, and it needs a device it can see. No automation tool is 100% risk-free, so automate responsibly and at your own discretion.

The same agent is reachable from Claude Code, Cursor, Codex and other clients through the MCP server, which exposes author_macro, get_agent_session, answer_agent_session, stop_agent_session and get_map.

Troubleshooting

The agent asks a question and waits

The session is paused on purpose and the clock is stopped, so nothing is spent. Open the Chat tab, answer the card and click Send answers. A card marked “Question expired” belongs to a session that has ended; reply in the composer instead, and the follow-up starts with the full conversation.

Validation keeps failing

Read the failing check in the chat: a template that never became visible, an OCR pattern that did not match, or a storage value the macro never saved. Steer the agent with what you know, or answer its question. If the emulator crashed, the agent stops after five device errors in a row; restart the emulator and message the chat to continue.

Budget reached

The session ended because a budget you set was used up, or because your credit balance reached zero. Work is saved. Top up credits from the Subscription page, or raise the budget, then send a follow-up in the same chat.