# Automação Android com Python: primeiros passos

> Configure a automação Android com Python no Macro Automation Studio: conecte um dispositivo, rode um bot do Marketplace, use o MAS Agent ou escreva uma macro.

Source: https://automationmacro.com/pt-BR/docs/getting-started (Início, updated 2026-09-05)

A automação Android com Python no Macro Automation Studio (MAS) funciona pela tela: o app olha para um dispositivo, encontra o que precisa e toca. Esta página leva você de uma instalação nova até sua primeira macro Python rodando em um emulador Android, em um dispositivo na nuvem ou no seu celular. Ela é para quem usa o MAS pela primeira vez, no Windows ou no Mac.

## Antes de começar

- O MAS está instalado e você fez login. Veja [Instalar o MAS](/docs/install).
- Você tem onde automatizar: um emulador Android neste computador, um dispositivo na nuvem ou o seu próprio celular. Veja [Dispositivos](/docs/devices).
- Sua conta tem uma assinatura ativa ou o teste gratuito. Toda página do app, exceto o login e **Assinatura**, exige uma. Sem ela, o MAS abre **Assinatura** e para ali. Os planos estão na [página de preços](/pricing).

> [!NOTE]
> O SDK Python já vem instalado. O MAS traz seu próprio ambiente Python 3.13 com o pacote `mas`, então `import mas` funciona no Code Editor sem nenhuma configuração da sua parte.

## Configuração do Macro Automation Studio: escolha um dispositivo

Uma execução tem um dispositivo como alvo. Escolha o tipo que se encaixa:

| Dispositivo | Onde roda | Bom para |
|---|---|---|
| Emulador (BlueStacks, LDPlayer, MuMu Player, MEmu) | Neste computador, via adb | Primeiros passos e testes locais |
| Dispositivo na nuvem | Na nuvem do MAS, transmitido para o app por WebRTC | Execuções que continuam com o computador desligado |
| Seu próprio celular | Neste computador, via adb (avançado) | Apps que só se comportam bem em hardware real |

Para adicionar um emulador:

1. Inicie o emulador e ative o ADB nas configurações dele. Cada guia de emulador mostra onde fica a opção.
2. No MAS, abra **Grupos de dispositivos** e clique em **Criar novo grupo**. Mantenha o tipo **Local**.
3. Abra o grupo e clique em **Adicionar dispositivo**.
4. Digite um **Nome do dispositivo** e escolha a porta do emulador na lista **Porta**. Clique em **Atualizar** se a lista estiver vazia.
5. Clique em **Adicionar dispositivo**.

Dispositivos na nuvem são criados na página **Dispositivos na nuvem** com **Criar** e aparecem como alvos de execução ao lado dos dispositivos locais. O caminho do celular está descrito na página [Dispositivos](/docs/devices).

## Três formas de conseguir uma macro

### Rodar um bot do Marketplace

1. Abra o **Marketplace** e pesquise o app ou o jogo.
2. Abra uma listagem e clique em **Baixar**. O bot aparece em **Macros**, marcado como "Baixado do Marketplace".
3. Em **Grupos de dispositivos**, abra o seu grupo, escolha o bot no seletor **Macro** do dispositivo e clique em **Iniciar**.
4. Acompanhe a aba **Logs** do card do dispositivo. Clique em **Parar** quando terminar.

O passo a passo completo com capturas de tela está em [Como rodar uma macro do Marketplace](/docs/run-macro-from-marketplace). Publicar o seu próprio bot é assunto da página [Marketplace](/docs/marketplace).

### Pedir ao MAS Agent

1. Abra **Agent** e escolha um dispositivo em **Dispositivo**.
2. Descreva a tarefa com suas palavras e clique em **Gerar**.
3. Responda quando o card **O agente precisa da sua resposta** aparecer. O agente para e pergunta em vez de adivinhar.
4. Quando a macro passar em 3 execuções de validação, clique em **Adicionar às minhas macros**.

O resultado é um projeto Python normal, que você pode abrir no Code Editor. Gerar a macro consome créditos de IA; rodar a macro pronta não consome nenhum. Leia mais na página [MAS Agent](/docs/agent).

### Escrever a automação Android com Python

1. Abra **Macros** e clique em **Criar novo projeto**.
2. Escolha **Baseado em código**, defina **Dispositivo alvo** como mobile, dê um nome ao projeto e clique em **Criar projeto**.
3. Abra o projeto. O Code Editor mostra `src/app.py`. Cole o script abaixo.
4. Escolha o seu dispositivo e clique em **Executar** (<kbd>F5</kbd>). **Parar** é <kbd>Shift</kbd>+<kbd>F5</kbd> e **Salvar** é <kbd>Ctrl</kbd>+<kbd>S</kbd>.

A [visão geral do SDK](/docs/sdk) explica os namespaces; a [referência da API](/docs/api-reference) lista todas as funções.

## Seu primeiro script

Este script lê o dispositivo, tira uma captura de tela e roda OCR na tela inteira. Nada muda no dispositivo.

```python
import mas

device = mas.get_device_info()
print(f"Connected to: {device.name}")

screen = mas.get_screen_size()
print(f"Screen: {screen.width}x{screen.height}")

shot = mas.take_screenshot()
print(f"Screenshot: {shot.width}x{shot.height}")

result = mas.read_text()
print(f"Screen text: {result.text[:100]}")

mas.log("First script finished")
```

`mas.log` escreve uma linha com nível no console de execução. Um `print` comum também funciona.

## Padrões comuns

### Encontrar uma imagem e tocar nela

Recorte o botão no Asset Lab para que ele entre na sua Biblioteca de imagens com um ID, depois declare-o com `mas.images`. `find_object_retry` procura até três vezes, com dois segundos de intervalo, e retorna `None` quando nada corresponde.

```python
import mas

images = mas.images({"play_button": 42})

match = mas.find_object_retry(images.play_button, total_tries=3, time_sleep=2.0)
if match:
    mas.click(match.x, match.y, delay_ms=1000)
else:
    mas.log("Play button not found", level="warning")
```

`find_object` compara com um limiar de 0.8 por padrão. `click` espera 1000 ms depois do toque para o app reagir; reduza `delay_ms` em loops apertados.

### Ler texto de uma região

```python
import mas
from mas import Region

score = mas.read_text(region=Region(x1=800, y1=10, x2=1050, y2=60), psm=7)
if score.text.strip().isdigit():
    print(f"Current score: {int(score.text)}")
```

`psm=7` trata a região como uma única linha, o que serve bem para contadores. Desenhe a região no Asset Lab e teste ao vivo antes de copiar as coordenadas.

### Tratar erros

```python
import mas

try:
    match = mas.find_object_retry(42)
    if match:
        mas.click(match.x, match.y)
except mas.DeviceNotConnectedError:
    mas.log("No device connected", level="error")
except mas.ImageNotFoundError:
    mas.log("Image ID is not in your library", level="error")
except mas.TimeoutError:
    mas.log("The device did not answer in time", level="error")
except mas.RPCError as e:
    mas.log(f"RPC error: {e}", level="error")
```

## Solução de problemas

### Could not discover RPC port

O script foi iniciado fora do MAS, ou o app não está aberto. Rode os scripts pelo Code Editor ou por um card de dispositivo; o app os inicia com os dados de conexão.

### O app abre Assinatura em vez da página que cliquei

Sua assinatura está faltando ou expirou. Inicie o teste ou escolha um plano e volte. Veja [Cobrança](/docs/billing).

### Dispositivo não encontrado ou parado em Conectando

O ADB do emulador está desligado, o emulador ainda está iniciando ou ele escuta em outra porta. Veja [Solução de problemas de ADB](/docs/adb-troubleshooting).