# AI エージェントで Android を自動操作: MAS Agent

> Android の自動操作タスクを文章で伝えると、MAS Agent がエミュレータやクラウドデバイス上でアプリを探索し、Studio で編集できる検証済みの Python マクロを生成します。

Source: https://automationmacro.com/ja/docs/agent (MAS Agent, updated 2026-09-05)

MAS Agent は、Macro Automation Studio (MAS) に内蔵された、スマホや Android エミュレータを自動操作する AI エージェントです。作業を普通の文章で説明すると、エージェントがデバイス上でアプリを探索し、画面の地図を作り、必要なボタンや表示をライブ画面から取り込み、テンプレート画像と OCR 領域を備えた標準的な MAS の Python マクロを書きます。その後、同じデバイスで 3 回の検証実行を行ってマクロを検証し、あなたに渡します。以降、マクロはモデルを介さず、クレジットゼロで再生されます。

## 始める前に

- MAS がインストール済みでサインインしており、無料トライアルか有料プランがあること。[インストール](/docs/install) を参照してください。
- エージェントが操作できるデバイス: **デバイスグループ** に追加した起動中のエミュレータ、または **Ready** 状態のクラウドデバイス。
- 自動化したいアプリがそのデバイスにインストールされ、ログイン画面を過ぎていること。
- アカウントに AI クレジットがあること。クレジットの仕組みは [お支払い](/docs/billing) ページで説明しています。

## AI エージェントでスマホ自動操作のセッションを始める

1. サイドバーで **エージェント** を開きます。
2. **デバイス** を選びます。一覧には **ローカルエミュレータ** と **クラウドデバイス** の 2 グループがあります。起動したばかりのエミュレータが見当たらなければ **デバイスを更新** をクリックします。
3. **プロバイダー** と **モデル** を選びます。**クラウドモデル** は MAS のサーバーで動き、AI クレジットから課金されます。
4. プロンプト欄に作業を入力し (例: 「デイリー報酬を受け取って、ポップアップをすべて閉じて」)、**作成** をクリックします。

セッションがどこで動くかはデバイスによります。

- **ローカルエミュレータ**: MAS があなたのマシンでエージェントエンジンを起動します (「Starting the agent engine...」)。エンジンは adb でエミュレータと通信するので、エミュレータとアプリは開いたままにします。
- **クラウドデバイス**: セッションはデバイスの隣の MAS サーバーで始まります (「Running on our servers」)。アプリを閉じて後で確認できます。会話はアカウントに保存されます。クラウドデバイスは常に **クラウドモデル** を使います。

1 台のデバイスで同時に動くエージェントは 1 つです。同じデバイスで別のチャットが動作中なら、MAS は **そのチャットへ移動** か **停止してここで続ける** を提示します。

## フェーズ: エージェントがプロンプトからマクロを生成する流れ

**概要** タブに現在のフェーズが表示され、**進捗** チェックリストが平易な言葉で追跡します。

| フェーズ | エージェントの作業 | 表示されるマイルストーン |
|---|---|---|
| SCOUT | アプリを探索し、画面を学習する | チャット内のメモ |
| PLAN | 計画を書き、承認を求める | 「Planning the automation...」 |
| HARVEST | ライブ画面でテンプレート画像を切り出し、OCR 領域を測る | 「Capturing the buttons and readouts the macro will need...」 |
| CODIFY | Python プロジェクトを書く | 「Writing your macro...」 |
| REVIEW | 観察した内容と照らして下書きを読む | 「Reviewing the generated code against what I observed...」 |
| VALIDATE | あなたのデバイスでマクロを実行する | 「Testing the macro on your device...」 |
| REPAIR | テストで見つかった問題を直し、HARVEST か CODIFY に戻る | 「Fixing an issue found during testing...」 |
| DONE | 結果カードを渡す | 「Done」、すべての実行が合格なら「graduated」 |

質問カードが開いている間、フェーズは WAITING_FOR_USER と表示され、セッションの時計は止まります。修復は回数ではなく進捗で区切られます。変更のないコードで同じ失敗が繰り返されると、エージェントが新しい診断を出すか質問するまで検証は一時停止します。ループし続けるセッションは、25 回の修復サイクルという上限で終了します。

## 質問、計画、指示

エージェントは推測せずに質問します。画面の読み方が 2 通りある場合や、あるステップが何かを消費または破壊する場合、止まってあなたに質問します。

- **エージェントが入力を必要としています** という質問カードには 1 から 4 個の質問が入ります。選択肢を選ぶか自由に答えを入力し、**回答を送信** をクリックします。
- 計画はセッションの契約です: 目標、メインループ、成功の確認方法。ゲーム内での消費には、エージェントがアプリ内で何かを使う前にあなたが承認する上限が必要です。
- 実行中に方向を変えるには、動作中にコンポーザーに入力して **指示** をクリックします。メッセージはエージェントの次の判断に反映されます。
- **停止** はセッションを即座に終えます。作業は保存されます。同じチャットで続きのメッセージを送ると再開できます。

## 予算とクレジット

**予算** パネルには、セッションのステップ数、クレジット (またはコスト)、トークン、ゲーム内消費が表示されます。予算 0 は上限なしを意味し、すべての軸でそれが既定です。実際の上限はクレジット残高です。残高がゼロになると、MAS はそれ以上のモデル呼び出しを拒否し、セッションはそこまでの成果で止まります。

クレジットはエージェントが探索、記述、テストしている間だけ消費されます。完成したマクロはどのデバイスでもクレジットゼロで動きます。エージェントページの **クレジット** 表示はセッション中に更新され、**クレジットを追加** でサブスクリプションページが開きます。仕組みは [お支払い](/docs/billing) ページに、レートは [料金ページ](/pricing) にあります。

## メニューマップ

マップは、エージェントが持つアプリの記憶です: 見たことのあるすべての画面と、それらをつなぐボタン。エージェントの作業中に自動で育ち、**マップ** タブにグラフとして、画面、遷移、タップ、未探索ボタンの数とともに表示されます。

- **このアプリをマップ** はメニューを意図的に巡回します (約 8 分)。**詳細パス** はより深いメニューを開きます (約 20 分)。どちらもナビゲーションだけで、エージェントは何かを販売するものからは引き返します。
- **マップを共有** は、同じアプリをマップしている他のアカウントとあなたのパスを共有します。提供内容は別のアカウントが裏付けるまで非公開で、**マイコントリビューション** から取り消せます。共有をオフにしても、あなたのマップは自分のセッションの役に立ちます。

## マイマクロに追加

結果カードに **Done** と表示されたら、**マイマクロに追加** をクリックします。MAS はプロジェクトフォルダーにプロジェクトを作り、すべてのテンプレート画像を画像ライブラリの `agent/` フォルダーにアップロードし、コード内の画像 ID を書き換え、git を初期化します。その後チャットは **IDE で開く**、同じデバイスでの **テスト実行**、スケジュールカード (**1 回**、**毎日**、**毎週**、そして **スケジュールを作成**) を提示します。スケジュール実行はデバイスカードに保存された引数を使います。

後でマクロを変更するには、ワークスペース一覧の **改善** でそのマクロを選び、追加や変更したい内容を説明します。エージェントは既存のプロジェクトから始めて、その場で更新します。

## プロジェクトの中身

| ファイル | 目的 |
|---|---|
| `src/app.py` | マクロ本体: `mas.images({...})` の登録、画面ごとの関数、メインループ |
| `src/script_args.py` | 引数フォームから生成された引数パーサー |
| `script_runner.uibproj` | UI Builder 用の引数フォーム |
| `images/manifest.json` | 取り込んだすべてのテンプレートの名前とファイルの対応表。ファイルはインストール後も残ります |
| `task.yaml` | 検証の仕様 |
| `agent_session.json` | プロジェクトを作成したセッション。後の改善セッションが使います |
| `README.md` | 目標と引数の表 |

`task.yaml` には、タスク名、プロンプト、アプリのパッケージ、デバイス、開始時の前提条件 (開始時に見えているべきテンプレート)、タイムアウト、`script_runs: 3`、テスト引数、チェックが記録されます。チェックの種類は `exit_code`、`template`、`ocr_region`、`storage`、`adb_shell`、`element_visible`、`element_text` で、それぞれ `when: active`、`idempotent`、`always` を持ちます。検証はスモークテストで、メインループは 2 回の反復に制限されます。Studio のランタイムは `task.yaml` を読みません。

インストール後は他のプロジェクトと同じように編集します: `src/app.py` のフローは完全な SDK で、テンプレート画像は [Asset Lab](/docs/asset-lab) と画像ライブラリで、OCR 領域はコード内で、引数フォームは [UI Builder](/docs/ui-builder) で。[Studio ツアー](/docs/studio) ではエディター、実行、デバッガーを説明しています。

## スマホゲームを遊ぶ AI、そしてあらゆる画面上のルーチン

MAS Agent は、エミュレータとクラウドデバイス上の画面主導のルーチンを扱います: 探索中に出会ったポップアップや割り込み、マクロが待機やスキップを判断できるよう OCR で読むカウンターとタイマー、そしてデバイスグループ全体でスケジュール実行する同じルーチン。画面から読み取れない判断、開始前の予算、破壊的な操作や何かを購入する操作の前には、あなたに確認します。

画面だけを使って動きます。APK を改変したりゲームのメモリを読んだりすることはなく、見ることのできるデバイスが必要です。100%リスクのない自動化ツールは存在しないため、自動化は責任を持って、ご自身の判断で行ってください。

同じエージェントは、[MCP サーバー](/docs/mcp) を通して Claude Code、Cursor、Codex などのクライアントからも利用でき、`author_macro`、`get_agent_session`、`answer_agent_session`、`stop_agent_session`、`get_map` を公開しています。

## トラブルシューティング

### エージェントが質問して待っている

セッションは意図的に一時停止しており、時計も止まっているので、何も消費されません。**チャット** タブを開き、カードに答えて **回答を送信** をクリックします。「Question expired」と表示されたカードは終了したセッションのものです。代わりにコンポーザーで返信すると、会話全体を引き継いで続きが始まります。

### 検証が失敗し続ける

チャットで失敗したチェックを読みます: 一度も表示されなかったテンプレート、一致しなかった OCR パターン、マクロが保存しなかったストレージ値。分かっていることでエージェントに指示するか、質問に答えます。エミュレータがクラッシュした場合、エージェントはデバイスエラーが 5 回連続で起きると止まります。エミュレータを再起動し、チャットにメッセージを送って続けてください。

### 予算に達した

設定した予算を使い切ったか、クレジット残高がゼロになったためセッションが終了しました。作業は保存されています。サブスクリプションページでクレジットを追加するか予算を上げてから、同じチャットで続きを送ってください。