Automação Desktop

Quando o alvo não é uma página web: automatize aplicativos desktop nativos (Win32, Electron, Java Swing) com scripts Python numa etapa de Regra Customizada.

Automação web × Automação desktop

A automação via navegador já vem integrada nativamente na plataforma: as etapas Navegar, Preencher e Obter Informação controlam o browser diretamente, por seletor CSS/XPath, sem precisar de código. O gravador também faz parte dessa integração, e grava cliques e preenchimentos dentro do navegador.

Nenhuma dessas ferramentas alcança um aplicativo desktop (um programa Windows nativo, uma janela Electron, uma tela Java Swing etc.). São superfícies completamente diferentes de um navegador, sem seletor CSS/XPath e sem DOM.

Para automatizar um processo com apps desktop no browserMate, o caminho é utilizar as etapas de Regra Customizada com scripts Python que controlam o mouse, o teclado e as janelas do sistema operacional diretamente.

Bibliotecas Python para automação desktop

Os scripts rodam em Python 3.14, embarcado no runtime. Escolha versões das bibliotecas compatíveis com essa série (veja Versões de Node.js e Python).

Em NodeJS, o equivalente é robotjs ou nut.js (mouse/teclado) e child_process (abrir o executável). A etapa de Regra Customizada aceita as duas linguagens, veja Código Inline.

Fluxo básico

1. Crie uma etapa Regra Customizada e escolha Python como linguagem (veja Código Inline).
2. Se o script precisa de algum dado do processo, leia com bm.get('{variavel}', default).
3. Escreva a lógica de automação com as bibliotecas acima.
4. Finalize sempre com bm.done(resultado, updates), inclusive para devolver algo capturado na tela para as etapas seguintes.

Exemplo prático

Abrir a Calculadora do Windows, digitar uma conta e capturar o resultado de volta para o processo:

import os, subprocess, tempfile, time
import pyautogui
import pygetwindow as gw

# Abre a Calculadora e aguarda a janela aparecer
subprocess.Popen('calc.exe')
time.sleep(1.5)

janela = gw.getWindowsWithTitle('Calculadora')[0]
janela.activate()

# Digita a conta e captura o resultado
valor = bm.get('{valor_a_somar}', '10')
pyautogui.write('25+' + valor)
pyautogui.press('enter')
time.sleep(0.5)

resultado_tela = pyautogui.screenshot(region=(janela.left, janela.top, janela.width, 100))

# Caminho ABSOLUTO: a pasta onde o script roda é temporária e é apagada quando
# a etapa termina. O caminho volta como variável para as etapas seguintes.
evidencia = os.path.join(tempfile.gettempdir(), 'calculadora.png')
resultado_tela.save(evidencia)

janela.close()

bm.bmLog('{application_success} Calculadora automatizada com sucesso')
bm.done('ok', {
    '{conta_realizada}': '25+' + valor,
    '{evidencia_calculadora}': evidencia,
})

Esse script roda como qualquer outro código Python na plataforma: mesma API bm (API de contexto do processo), mesmas regras de log (Logs Customizados) e mesma proteção de variáveis de sistema (Padrões de segurança).

Várias etapas no mesmo aplicativo

Um processo desktop de verdade raramente cabe numa etapa só: uma abre o sistema, outra lança os registros, outra encerra. E aqui aparece o ponto que mais confunde quem está começando, porque não tem nada a ver com Python.

Cada etapa de Regra Customizada roda num processo isolado, que nasce e morre com a etapa. O aplicativo que uma etapa abriu continua aberto, porque quem o sustenta é o sistema operacional. Mas o objeto que o representava no código morreu junto com a etapa. A etapa seguinte não recebe a janela: ela reconecta ao aplicativo que já está lá.

Por isso, quem abre devolve o identificador, e quem usa reconecta por ele:

import subprocess
from pywinauto import Application

processo = subprocess.Popen(r'C:\Program Files\CRM\crm.exe')
app = Application(backend='uia').connect(process=processo.pid, timeout=60)
app.window(title_re='.*CRM.*').wait('ready', timeout=60)

bm.done('aberto', { '{crm_pid}': str(processo.pid) })

from pywinauto import Application

pid = bm.get('{crm_pid}')
try:
    app = Application(backend='uia').connect(process=int(pid), timeout=30)
except Exception:
    app = Application(backend='uia').connect(title_re='.*CRM.*', timeout=30)

janela = app.window(title_re='.*CRM.*')
janela.set_focus()
# A etapa pode estar voltando de uma nova tentativa, com a tela em qualquer
# lugar. Normalize antes de digitar, nunca assuma onde a execução parou.

Sobre o tamanho das etapas: quebre por fase do processo (abrir, processar, encerrar), não por micro-ação. Clicar, digitar e salvar um mesmo registro são a mesma etapa. E dentro de um laço, deixe uma etapa por registro: cada etapa sobe um interpretador novo, então três etapas por registro triplicam o custo sem nenhum ganho.

O Copilot escreve o script para você

O Copilot do Agent Builder reconhece pedidos de automação desktop e escreve o script Python (ou NodeJS) diretamente. Basta descrever qual aplicativo e qual ação você quer automatizar. Ele sabe, por padrão:

• Que automação desktop é sempre feita por script numa etapa de Regra Customizada, e nunca sugere o gravador nem inventa uma função de etapa para abrir o app.
• Quais bibliotecas Python/NodeJS usar para cada tipo de interação (mouse/teclado, janelas, abrir processos).
• Como estruturar o script com bm.get()/bm.done() para integrá-lo ao restante do fluxo.

Ainda assim, revise o script gerado antes de publicar. Automação desktop depende do estado exato da tela (janela em foco, resolução, elementos visíveis) no ambiente onde o runtime realmente vai rodar, algo que o Copilot não tem como verificar sozinho.

Cuidados e limitações

• Sensível a resolução e posição de janela. Cliques por coordenada fixa (pyautogui.click(x, y)) quebram se a janela mudar de tamanho ou posição, ou se o ambiente runtime rodar numa resolução diferente da usada para desenvolver o script. Prefira pywinauto (por nome/classe do controle) quando o app permitir.
• Precisa da tela visível. Automação desktop não funciona com o ambiente rodando totalmente headless/em segundo plano sem sessão gráfica: o sistema operacional precisa ter uma sessão de área de trabalho ativa para o mouse/teclado simulado surtir efeito.
• Evidência de tela não cobre a janela desktop. O recurso de Screenshot das etapas captura a página do navegador controlada pelo Puppeteer, e não a janela do aplicativo desktop. Para evidência de uma automação desktop, capture a tela manualmente no script (como no exemplo acima) e trate o arquivo salvo como um dado do processo.
• Uma execução desktop por vez em cada máquina. Mouse, teclado e janela em foco são um só por máquina, e o runtime não impede duas execuções desktop ao mesmo tempo: as duas disputam a tela e uma desfaz o que a outra digita. Isso acontece sempre que duas execuções caem juntas no mesmo runtime (dois agendamentos, Disparar por cada item de uma lista com todos ao mesmo tempo, um lote distribuído). No Ambiente Runtime dessa máquina, ligue Enfileirar Jobs com 1 execução ao mesmo tempo; no plano Free o ambiente já roda assim. O teto do agente em 1 (Execuções ao mesmo tempo) separa só as execuções daquele agente. Em lote distribuído: Balancear Carga dos Agentes → O que a fila do runtime muda.
• Teste no ambiente real. Valide o script no mesmo Ambiente Runtime (ou um equivalente) onde ele vai rodar em produção. Diferenças de resolução, tema do Windows ou versão do app mudam onde os elementos aparecem na tela.
• Nenhum objeto atravessa a etapa. O aplicativo continua aberto, o objeto que o representava não. Etapa seguinte reconecta pelo identificador, como em Várias etapas no mesmo aplicativo. O mesmo vale para arquivo salvo: caminho absoluto, sempre.
• Defina o Limite de Tempo do Script. Cada etapa diz por quantos segundos o seu script pode rodar. O padrão de 1 hora é folgado demais para uma etapa que lança um registro: se ela travar esperando uma janela que não abriu, a execução fica presa a noite inteira. Para uma etapa dentro de um laço, esse tempo se multiplica por registro. Veja Timers.
• Interromper deixa a tela como estava. O botão Parar encerra o script na hora, mas não desfaz nada: o aplicativo fica aberto onde estava, possivelmente com um formulário pela metade. Por isso uma etapa de desktop deve começar normalizando a tela, e não assumindo onde a execução anterior parou.
• Fechar o runtime não encerra um script em andamento. Quem cronometra o script e quem atende o botão Parar é o próprio ambiente runtime. Se ele for fechado pela bandeja ou derrubado no meio de uma execução, o script continua rodando sozinho na máquina, segurando o aplicativo que abriu. Pare a execução pelo painel antes de encerrar o runtime, e se algo ficar órfão, encerre o processo pelo Gerenciador de Tarefas.