# Agente de IA para Android: do prompt à macro

> Descreva uma tarefa Android, deixe o MAS Agent explorar o app em um emulador ou dispositivo na nuvem e receba uma macro Python validada, pronta para editar.

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

O MAS Agent é o agente de IA para Android dentro do Macro Automation Studio (MAS). Você descreve uma tarefa com suas próprias palavras. O agente explora o app em um dispositivo, monta um mapa das telas, captura na tela ao vivo os botões e as leituras de que precisa e escreve uma macro Python padrão do MAS, com imagens template e regiões de OCR. Depois valida a macro com 3 execuções de validação no mesmo dispositivo e entrega para você. A partir daí, a macro repete sem nenhum modelo no circuito, a custo zero de créditos.

## Antes de começar

- MAS instalado e com login feito, no teste gratuito ou em um plano pago. Veja [Instalação](/docs/install).
- Um dispositivo que o agente possa controlar: um emulador em execução adicionado em **Grupos de dispositivos**, ou um dispositivo na nuvem no estado **Pronto**.
- O app que você quer automatizar instalado nesse dispositivo e já passado da tela de login.
- Créditos de IA na sua conta. A página [Cobrança](/docs/billing) explica como os créditos funcionam.

## Inicie uma sessão de automação Android com o agente

1. Abra **Agent** na barra lateral.
2. Escolha o **Dispositivo**. A lista tem dois grupos, **Emuladores locais** e **Dispositivos na nuvem**. Clique em **Atualizar dispositivos** se um emulador que você acabou de abrir não aparecer.
3. Escolha o **Provedor** e o **Modelo**. Os **Modelos na nuvem** rodam nos servidores do MAS e são cobrados dos seus créditos de IA.
4. Digite a tarefa na caixa de prompt, por exemplo "Colete a recompensa diária e feche todos os pop-ups", e clique em **Gerar**.

Onde a sessão roda depende do dispositivo:

- **Emulador local**: o MAS inicia o motor do agente na sua máquina ("Iniciando o motor do agente..."). O motor fala com o emulador por adb, então o emulador e o app ficam abertos.
- **Dispositivo na nuvem**: a sessão começa nos servidores do MAS, ao lado do dispositivo ("Rodando nos nossos servidores"). Você pode fechar o app e voltar depois; a conversa fica salva na sua conta. Um dispositivo na nuvem sempre usa **Modelos na nuvem**.

Um agente roda por dispositivo de cada vez. Se outro chat estiver ocupado no mesmo dispositivo, o MAS oferece **Ir para esse chat** ou **Parar e continuar aqui**.

## Como o agente de IA para Android gera uma macro a partir de um prompt

A aba **Visão geral** mostra a fase atual, e a lista **Progresso** acompanha em palavras simples.

| Fase | O que o agente faz | O marco que você vê |
|---|---|---|
| SCOUT | Explora o app e aprende as telas | Anotações no chat |
| PLAN | Escreve o plano e pede sua aprovação | "Planejando a automação..." |
| HARVEST | Recorta imagens template e mede regiões de OCR na tela ao vivo | "Capturando os botões e as leituras de que a macro vai precisar..." |
| CODIFY | Escreve o projeto Python | "Escrevendo sua macro..." |
| REVIEW | Relê o rascunho contra o que observou | "Revisando o código gerado contra o que observei..." |
| VALIDATE | Roda a macro no seu dispositivo | "Testando a macro no seu dispositivo..." |
| REPAIR | Corrige o que o teste encontrou e volta para HARVEST ou CODIFY | "Corrigindo um problema encontrado no teste..." |
| DONE | Entrega o card de resultado | "Concluído", com "graduada" quando todas as execuções passaram |

Enquanto um card de pergunta está aberto, a fase mostra WAITING_FOR_USER e o relógio da sessão pausa. O reparo é limitado pelo progresso, não por uma contagem: quando a mesma falha se repete com o código inalterado, a validação pausa até o agente trazer um diagnóstico novo ou perguntar a você. Um limite rígido de 25 ciclos de reparo encerra uma sessão que, de outro modo, ficaria em loop.

## Perguntas, o plano e o direcionamento

O agente pergunta em vez de adivinhar. Quando a tela admite duas leituras, ou um passo gastaria ou destruiria algo, ele para e faz a pergunta a você.

- Um card de pergunta com o título **O agente precisa da sua resposta** traz de uma a quatro perguntas. Escolha uma opção ou digite uma resposta própria e clique em **Enviar respostas**.
- O plano é o contrato da sessão: o objetivo, o loop principal e a verificação de sucesso. Qualquer gasto dentro do jogo precisa de um limite que você aprova antes de o agente gastar qualquer coisa no app.
- Para redirecioná-lo no meio da execução, digite na caixa de texto enquanto ele trabalha e clique em **Direcionar**. A mensagem entra na próxima decisão do agente.
- **Parar** encerra a sessão na hora. O trabalho fica salvo; envie uma mensagem de continuação no mesmo chat para prosseguir.

## Orçamentos e créditos

O painel **Orçamentos** mostra passos, créditos (ou custo), tokens e gasto dentro do jogo da sessão. Um orçamento 0 significa sem limite, e esse é o padrão em todos os eixos: seu saldo de créditos é o limite de verdade. Quando o saldo chega a zero, o MAS recusa novas chamadas ao modelo e a sessão para com o que tem.

Os créditos são gastos só enquanto o agente explora, escreve e testa. Uma macro pronta roda a custo zero de créditos em qualquer dispositivo. O indicador **Créditos** na página do Agent atualiza enquanto a sessão roda, e **Recarregar créditos** abre a página de Assinatura. A mecânica está na página [Cobrança](/docs/billing); os valores estão na [página de preços](/pricing).

## O mapa de menus

Um mapa é a memória que o agente tem de um app: toda tela que ele já viu e os botões que as conectam. Ele cresce sozinho enquanto o agente trabalha, e a aba **Mapa** o mostra como um grafo com contagens de telas, transições, toques e botões ainda não explorados.

- **Mapear este app** percorre os menus de propósito (cerca de 8 minutos); **Passagem profunda** abre menus mais fundos (cerca de 20 minutos). Os dois são só navegação: o agente recua de qualquer coisa que venda algo.
- **Compartilhar meus mapas** junta as suas passagens com as de outras contas que mapeiam o mesmo app. As contribuições ficam privadas até outra conta confirmá-las, e você pode retirar uma em **Minhas contribuições**. Com o compartilhamento desligado, seus mapas continuam ajudando as suas próprias sessões.

## Adicionar às minhas macros

Quando o card de resultado mostrar **Concluído**, clique em **Adicionar às minhas macros**. O MAS cria o projeto na sua pasta de projetos, envia todas as imagens template para a sua Biblioteca de imagens em uma pasta `agent/`, reescreve os ids de imagem dentro do código e inicializa o git. O chat então oferece **Abrir no IDE**, **Execução de teste** no mesmo dispositivo e um card de agendamento (**Uma vez**, **Diário** ou **Semanal**, depois **Criar agendamento**). As execuções agendadas usam os argumentos salvos no card do dispositivo.

Para mudar uma macro depois, escolha-a em **Melhorar** na lista do espaço de trabalho e descreva o que adicionar ou mudar. O agente parte do projeto existente e o atualiza no lugar.

## O que o projeto contém

| Arquivo | Finalidade |
|---|---|
| `src/app.py` | A macro: o registro `mas.images({...})`, uma função por tela, o loop principal |
| `src/script_args.py` | O parser de argumentos gerado a partir do formulário de argumentos |
| `script_runner.uibproj` | O formulário de argumentos para o UI Builder |
| `images/manifest.json` | Mapa de nome para arquivo de cada template capturado; os arquivos ficam depois da instalação |
| `task.yaml` | A especificação de validação |
| `agent_session.json` | Qual sessão criou o projeto, usado por sessões de melhoria posteriores |
| `README.md` | O objetivo e a tabela de argumentos |

O `task.yaml` registra o nome da tarefa, o prompt, o pacote do app, o dispositivo, uma pré-condição de entrada (um template que precisa estar visível no início), um tempo limite, `script_runs: 3`, os argumentos de teste e as verificações. Os tipos de verificação são `exit_code`, `template`, `ocr_region`, `storage`, `adb_shell`, `element_visible` e `element_text`, cada um com `when: active`, `idempotent` ou `always`. A validação é um teste de fumaça: o loop principal fica limitado a duas iterações. O runtime do Studio nunca lê o `task.yaml`.

Depois da instalação, você edita como qualquer outro projeto: o fluxo em `src/app.py` com o SDK completo, as imagens template no [Asset Lab](/docs/asset-lab) e na Biblioteca de imagens, as regiões de OCR no código e o formulário de argumentos no [UI Builder](/docs/ui-builder). O [tour pelo Studio](/docs/studio) cobre o editor, as execuções e o depurador.

## Uma IA para jogar jogos mobile e qualquer outra rotina de tela

O MAS Agent cuida de rotinas guiadas pela tela em emuladores e dispositivos na nuvem: os pop-ups e as interrupções que encontrou na exploração, contadores e timers lidos com OCR para a macro esperar ou pular, e a mesma rotina em um grupo de dispositivos em um agendamento. Ele pergunta a você sobre decisões que não consegue ler na tela, sobre o orçamento antes de começar e antes de qualquer coisa destrutiva ou que compre algo.

Ele trabalha só a partir da tela. Nunca modifica um APK nem lê a memória de um jogo, e precisa de um dispositivo que consiga ver. Nenhuma ferramenta de automação é 100% livre de riscos, por isso automatize com responsabilidade e a seu próprio critério.

O mesmo agente pode ser acessado pelo Claude Code, Cursor, Codex e outros clientes por meio do [servidor MCP](/docs/mcp), que expõe `author_macro`, `get_agent_session`, `answer_agent_session`, `stop_agent_session` e `get_map`.

## Solução de problemas

### O agente faz uma pergunta e fica esperando

A sessão está pausada de propósito e o relógio está parado, então nada é gasto. Abra a aba **Chat**, responda ao card e clique em **Enviar respostas**. Um card marcado como "Pergunta expirada" pertence a uma sessão que já terminou; responda na caixa de texto, e a continuação começa com a conversa completa.

### A validação continua falhando

Leia a verificação que falhou no chat: um template que nunca ficou visível, um padrão de OCR que não bateu, ou um valor de armazenamento que a macro nunca salvou. Direcione o agente com o que você sabe, ou responda à pergunta dele. Se o emulador travou, o agente para depois de cinco erros de dispositivo seguidos; reinicie o emulador e mande uma mensagem no chat para continuar.

### Orçamento atingido

A sessão terminou porque um orçamento que você definiu foi consumido, ou porque seu saldo de créditos chegou a zero. O trabalho fica salvo. Recarregue créditos na página de Assinatura, ou aumente o orçamento, e então envie uma continuação no mesmo chat.