Etapas e Ações

Tipos de etapa, ações disponíveis, campos obrigatórios e variáveis de contexto.

Nesta página

Tipos de Etapa
Campos Comuns
Ações por Tipo
Variáveis de Contexto
Tratamento de Erros (Bypass)

Tipos de Etapa

Uma etapa pode ser criada de três formas: manualmente, clicando no + do canvas (no fim do fluxo, sobre a linha de conexão entre duas etapas, ou na linha que sai do início até a primeira etapa), escolhendo o tipo e preenchendo os campos abaixo; por clone, escolhendo Clonar no mesmo menu e apontando uma etapa já existente do fluxo, que é duplicada naquele ponto com campos, mapeamentos, scripts e variáveis; ou automaticamente, pedindo ao Copilot, que já entrega a etapa criada e configurada, inclusive a partir de uma gravação da automação.

O menu do + tem dois grupos. Fluxo do Processo traz os tipos desta página e o Clonar. Orquestração de Agentes traz as etapas que disparam outros agentes: Chamar Agente, Paralelizar Agentes e Aguardar Agentes. Paralelizar Agentes existe a partir do plano Professional; nos outros planos o item aparece travado, com o motivo. Elas nascem como etapas de Execução com a ação já definida e não trocam de tipo; o que se configura é a chamada e, sobretudo, como o fluxo espera por ela.

Menu do + do fluxo com o grupo Fluxo do Processo (Criar Etapa de Execução, Criar Etapa de Decisão de Rota, Criar Etapa de Regra Customizada e Clonar Etapas Existentes) e o grupo Orquestração de Agentes (Chamar Agente, Paralelizar Agentes, Aguardar Agentes e Criar Etapa Agêntica) — O menu do + no fim do fluxo: o grupo Fluxo do Processo, com o Clonar Etapas Existentes, e o grupo Orquestração de Agentes.

Menu do + com o submenu de Clonar Etapas Existentes aberto, listando as etapas do fluxo — Clonar Etapas Existentes abre a lista das etapas do fluxo; a escolhida é duplicada no ponto do +. Etapas de agentes e de Decisão de Rota não entram na lista (ver Clonar uma etapa).

O tipo da etapa é escolhido no menu do +, no grupo Fluxo do Processo. Ele define o que a etapa pode fazer:

Tipo	Ícone	Quando usar
Execução	⚙️	Faz o processo agir e produzir dados: navegar e interagir com páginas, extrair informações da tela, chamar uma API REST diretamente ou através de um conector. A ação concreta muda conforme o que a etapa faz: Navegar em Tela, Preencher Dados, Obter Informação, Integrar com Conectores ou Chamar API Rest.
Decisão de Rota	🔷	Roteamento condicional. Direciona o fluxo para etapas diferentes com base em condições. Veja Decisão.
Regra Customizada	🔢	Executa um script Node.js ou Python inline ou via projeto ZIP, e cria ou altera variáveis do fluxo sem código. Veja Código Customizado e Manipulação de Variáveis.

Campos Comuns a Todas as Etapas

Nome da Etapa texto Obrigatório

Nome único da etapa dentro do processo. Usado em rotas de decisão e nos contornos da Gestão de Erros e Exceções de outras etapas. Não faz parte do nome das variáveis capturadas (veja Variáveis de Contexto). Use nomes descritivos sem espaços especiais.

Descrição da Etapa textarea

Descrição opcional da etapa. Visível no modelador visual ao passar o mouse sobre o card da etapa.

Modo de Navegação na Etapa seleção Obrigatório

Define se a etapa dispara uma navegação nova ou continua na página já carregada pela etapa anterior:

Nova: a etapa navega para a URL — Endpoint informada, carregando a página do zero. É o modo da primeira etapa do processo e de qualquer etapa que precise ir para outro endereço. Só neste modo o campo URL é obrigatório (e só nele ele pode ser preenchido).
Permanente: a etapa não navega para lugar nenhum: ela age sobre a página/sessão que já está aberta, deixada pela etapa anterior. O caso comum de Preencher Dados e Obter Informação agindo numa página que uma etapa Navegar em Tela anterior já abriu.

Chamar API Rest força sempre o modo Nova (toda chamada de integração inicia uma navegação); Integrar com Conectores força sempre Permanente e não usa URL. Nenhum dos dois navega um browser de fato. O campo não aparece em etapas de Decisão de Rota ou Regra Customizada.

URL — Endpoint texto

O endereço para onde a etapa navega quando o Modo de Navegação está em Nova (ex.: https://meusistema.com/login).

Com o modo Permanente o campo fica bloqueado, junto com o seletor { }, e a tela explica o motivo: a etapa continua na página que já está aberta e não navega, então uma URL digitada ali nunca seria aberta. Se a etapa já tinha uma URL gravada, ela continua visível, mas é ignorada. Para informar uma URL, escolha o modo Nova. Ao trocar de modo, o valor do campo não se perde.

Em Chamar API Rest o campo nunca é bloqueado: a URL ali é o endpoint da chamada.

Aceita {variável} ocupando o campo inteiro ou embutida no endereço, como https://meusistema.com/cliente/{id}/detalhe. O seletor { } ao lado do campo lista as variáveis do processo; variável criada em tempo de execução por um script pode ser digitada à mão.

Tipo de Abertura seleção

Mesma Aba reaproveita a aba atual do browser; Nova Aba abre a URL numa aba adicional, mantendo a anterior aberta.

Os três campos a seguir só existem em etapas de navegador Gerar Evidência?, Manter a Evidência em Sessão? e Quebrar mecanismo de Captcha? dependem da página aberta no navegador. Por isso aparecem apenas nas etapas Navegar em Tela, Preencher Dados e Obter Informação. Em Chamar API Rest, Integrar com Conectores, Regra Customizada e Decisão de Rota eles não aparecem, e a etapa é gravada com os três desligados. Ao trocar o tipo da etapa no formulário, eles somem e voltam na hora, sem perder o que você já tinha ligado até salvar.

Gerar Evidência? booleano

Quando ativado, o runtime tira um screenshot da tela do browser ao final da etapa. As evidências são salvas e ficam disponíveis para download no Control Room. Útil para auditoria e debug.

Numa etapa de navegador que lida com dado sensível (um mapeamento marcado), o controle aparece como Bloqueada, e a imagem não é gerada.

Manter a Evidência em Sessão? booleano

Guarda a imagem da evidência em duas variáveis do processo, {NomeDaEtapa.evidence} e {NomeDaEtapa.evidence_BUFFER}, para usar nas etapas seguintes (por exemplo, anexar o screenshot num e-mail). Só tem efeito com Gerar Evidência? ligado. Sem este campo, a imagem existe apenas na Trilha de Auditoria. Detalhes em Screenshot e Evidências.

Quebrar mecanismo de Captcha? booleano

Ativa a tentativa de resolver CAPTCHA nesta etapa. Só funciona em conjunto com a ativação global: o componente Contorno de Captcha precisa estar habilitado no agente, com um provedor selecionado (2CAPTCHA ou CAPMONSTER). Veja Componentes.

Ações por Tipo de Etapa

Na etapa de Execução, o campo Tipo de Ação do Agente define o que ela faz de fato. Decisão de Rota e Regra Customizada têm uma função própria, descrita nas seções abaixo.

Ações disponíveis em Execução (⚙️)

Aba Propriedades de uma etapa de Execução, com o Tipo de Ação do Agente: Navegar em Tela, Preencher Dados, Obter Informação, Integrar com Conectores e Chamar API Rest — As ações do tipo **Execução**, na aba Propriedades da etapa.

Navegar em Tela navegação

Usado para navegação web em geral, como abrir uma página e interagir com elementos. Antes de prosseguir (respeitando o Limite de Carregamento de Páginas configurado no agente).

Além de navegação, o campo Função permite, na mesma etapa, clicar em algo logo depois de navegar (ex.: abrir um menu) ou rodar uma checagem:

Seletor: clica no elemento (CSS) informado em Parâmetro da Função, com Botão do Mouse e Quantidade de Clicks configuráveis. Ex.: abrir um item de menu logo após a navegação.
fastCheck(): faz uma checagem rápida na página (ex.: confirmar que carregou no estado esperado) sem disparar uma ação completa.
Outras funções prontas: hover(), focus(), press().
alert(), confirm() e prompt(): respondem aos diálogos nativos do navegador. Veja Eventos do Navegador.

Para interações por posição de tela (Mouse/Keyboard/Touchscreen), em vez de seletor, o que é útil quando a tela não tem DOM navegável (canvas, componentes gráficos), veja Dispositivo e Interação em Mapeamento de Dados.

Nem toda abertura de página é uma etapa Navegar Outros tipos de etapa também podem abrir uma nova página como efeito colateral de uma ação. Um clique em Preencher Dados que dispara uma navegação, por exemplo. Ainda assim, concentre as aberturas de página propositais na etapa Navegar em Tela sempre que possível: isso mantém a leitura do fluxo íntegra e ordenada, com cada navegação explícita no diagrama em vez de escondida dentro de outra ação.

Preencher Dados interação

Interage com elementos da página: digitar em campos, clicar em botões, selecionar opções em dropdowns, marcar checkboxes. O mapeamento define quais elementos serão afetados e com quais valores.

Seletor: CSS selector ou XPath do elemento
Ação: click, type, select, check, scroll
Valor: texto ou variável a inserir

Obter Informação extração

Extrai dados de elementos da página (texto, atributos, valores) e armazena em variáveis do processo. Configure o mapeamento para definir o que capturar e em qual variável salvar.

Veja Mapeamento de Dados para todos os campos.

Navegar, Preencher e Obter Informação consomem crédito como RPA Para efeitos de consumo de crédito, essas três ações são processadas como RPA, ou seja, interação real com o navegador, e não como chamada de IA ou de API. O custo de execução segue essa classificação, diferente de etapas que chamam um conector de IA ou uma API REST.

Integrar com Conectores conector

Chama um conector configurado (Claude, Gmail, Sheets, etc.). Selecione o conector e a ação desejada. Os parâmetros da ação são preenchidos com valores literais ou variáveis do processo.

O resultado da chamada é armazenado em variáveis mapeadas na seção de mapeamento.

Chamar API Rest API REST

Faz uma chamada HTTP direta a uma API REST sem usar um conector pré-configurado. Configure:

Método HTTP: GET, POST, PUT, PATCH, DELETE
URL do Endpoint: Endpoint da API (aceita variáveis)
Headers: Cabeçalhos HTTP (ex.: Authorization). A linha Content-Type aparece preenchida sozinha quando você escolhe o formato do corpo, e você troca o valor se a API pedir outro
Parâmetros de URL: Parâmetros da requisição
Query Strings: Query params na URL
Root do Body: Formato do corpo enviado. Escolha body (JSON), texto (corpo escrito à mão), form (urlencoded) ou formData (multipart). Deixe em sem corpo para GET e para APIs que não recebem body
Objetos do Body: Campos que compõem o corpo enviado, nos formatos body, form e formData
Corpo: no formato texto, o corpo literal, do jeito que você escrever, para XML, SOAP, CSV e texto puro. Aceita variável no meio do texto
Resultados: Variáveis que armazenarão a resposta. Um cadeado ao lado de cada linha marca o dado como sensível: o valor some dos logs, inclusive da resposta crua da API

Na tabela de Resultados, o campo Path aponta onde está o dado dentro do JSON que a API devolveu:

Resposta da API	Path	Variável
`{"logradouro": "Rua X"}`	`logradouro`	nome da variável
`{"dados": {"endereco": {"rua": "Rua X"}}}`	`dados.endereco.rua`	nome da variável
`{"itens": [{"id": 1}, {"id": 2}]}`	`itens[0].id`	só o primeiro
`{"itens": [{"id": 1}, {"id": 2}]}`	`itens[*].id`	a lista `[1, 2]`
`{"data": [{"1": "A", "2": "101"}]}`	`data[*].2`	a lista `["101"]`

[*] percorre uma lista, e é a única coisa que faz a variável virar lista. Funciona aninhado (pedidos[*].itens[*].sku), e é a mesma notação do Path de um conector. O nome do campo não precisa ser identificador: data[*].2 e content-range são caminhos válidos, porque quem nomeia a variável é sempre a coluna Variável. Quando o Path não existe na resposta, a etapa continua e o log registra um aviso com os campos que a API devolveu.

Decisão de Rota (🔷)

Processar Rota decisão

Avalia condições e direciona o fluxo. Configure as condições no campo Condições para Rotas. Veja a documentação completa em Decisão.

Regra Customizada (🔢)

Aplicação de Regra Customizada script

Reúne, na ordem em que aparecem no painel, as variáveis do fluxo, a iteração de listas, o timer de espera e o código Node.js ou Python. Veja o panorama completo em Python e NodeJS → Visão Geral:

Variáveis do Fluxo: cria variáveis locais ou altera variáveis que já existem, com valor fixo, variável ou fórmula, sem escrever código. Rodam antes dos scripts da etapa. Veja Manipulação de Variáveis
Iterações de Listas: consome um item de uma variável lista a cada passagem pela etapa. Veja Loop
Timer de Espera: slider de segundos, de 0 a 600, que faz o processo aguardar antes de seguir para a próxima etapa. Começa em 0 (sem espera) e roda por último, depois dos scripts. Veja Timers
Qual a linguagem do seu script?: Node.js ou Python
Modo de Execução: Inline (código direto no editor, veja Código Inline) ou Projeto (ZIP enviado, veja Projetos e SDK)
Script Customizado: código a executar no modo Inline. Veja Código Inline
Projeto de Script: projeto ZIP previamente enviado no modo Projeto. Veja Projetos e SDK
Limite de Tempo do Script: por quantos segundos o script desta etapa pode rodar antes de ser encerrado. Padrão de 3600 (1 hora), de 10 segundos a 8 horas. Ao estourar, a etapa conta como erro e entra na Gestão de Erros. Aparece quando a etapa tem código ou projeto; veja Timers
Scripts de Sessão: bloco Node.js à parte, com acesso direto à sessão do navegador. Não passa pelo Limite de Tempo do Script. Veja Scripts de Sessão

Onde marcar Dado sensível em cada tipo de etapa A marca fica na linha que cria a variável, e o lugar depende da etapa. Em Preencher e Obter Informação, na chave Dado sensível? do mapeamento. Em Chamar API Rest, no cadeado de cada linha dos Resultados. Em Conectar Serviços, no cadeado de cada variável de saída do conector. Em Regra Customizada, na opção Dado sensível de cada linha das Variáveis do Fluxo. O valor deixa de aparecer nos logs, no debug e no arquivo de teste dos scripts, e a etapa não gera imagem da tela. As etapas seguintes continuam recebendo o valor real. Para credenciais que você já conhece antes de executar, use o Cofre. Veja Dados Sensíveis.

Variáveis de Contexto

Durante a execução, o processo mantém um contexto com variáveis acessíveis em qualquer campo de texto de qualquer etapa usando a sintaxe {VARIAVEL}. Elas se dividem em quatro tipos: globais (Matrix), locais (Variáveis do Fluxo), automáticas (criadas pelas etapas) e de sistema. Como criar, usar e alterar cada uma está em Manipulação de Variáveis.

Variáveis de Sistema

O runtime mantém automaticamente variáveis de identificação, fluxo, erro e tempo em toda execução. {processName}, {instanceID}, {lastStep}, {errorDescription}, {elapsedSeconds} e outras. A referência completa, agrupada e com exemplos, está em Manipulação de Variáveis.

Resultado de uma Captura

A variável é definida pelo campo Nome configurado na linha de mapeamento (Mapeamento de Dados). Para acessar o valor capturado, use diretamente:

{nome_da_variavel}

Exemplo: se a linha de mapeamento foi nomeada preco, acesse com {preco} em qualquer etapa seguinte.

Parâmetros de Inicialização

Acesse os parâmetros configurados no cadastro do agente sempre com o prefixo matrix.:

{matrix.nome_do_parametro}

Variáveis de Conectores

O resultado de uma etapa Integrar com Conectores vai sempre com o prefixo fixo connector., seguido do Nome dado à linha de saída mapeada. Não do rótulo do conector:

{connector.nome_da_variavel}

Variáveis do Fluxo

Numa etapa de Regra Customizada, a seção Variáveis do Fluxo cria variáveis locais, sem código, e também altera variáveis que já existem. O nome escolhido vale no fluxo inteiro, como qualquer outra variável:

{nome_da_variavel}

O valor pode ser um texto fixo, outra variável ou uma fórmula. O passo a passo, os tipos e as regras estão em Manipulação de Variáveis, Locais.

Gestão de Erros e Exceções

O painel Gestão de Erros e Exceções da etapa define o que acontece quando ela falha. São dois estágios: o que fazer em cada erro enquanto o Limite de Erros não estoura, e o que fazer quando estoura.

Campo	O que controla
Modo de Tratamento de Erros nesta Etapa	Sequencial espera o intervalo e tenta a mesma etapa de novo. Total aciona, a cada erro, o contorno escolhido.
Zerar a contagem quando a etapa passar	Ligado, o limite conta apenas erros seguidos. Desligado, conta todos os erros da etapa na execução.
Limite de Erros	Quantos erros desta etapa cabem antes do estouro. Conta erros: 3 significa 3 execuções. Zero é sem limite.
Intervalo entre Tentativas	Segundos de espera antes de cada nova tentativa. Só aparece quando a configuração repete a etapa.
A cada erro	Só no modo Total: seguir para a próxima etapa, ir para uma etapa, ou recarregar/voltar/avançar/passar o mouse/focar/pressionar tecla e tentar de novo.
Ao estourar o limite	Terminar o processo (padrão), ir para uma etapa de tratamento, ou seguir para a próxima.

Boas práticas Para erro intermitente, deixe o modo Sequencial tentar de novo sozinho. Para erro esperado, como elemento que some numa página dinâmica, use Ao estourar o limite apontando para uma etapa de recuperação, em vez de deixar o processo encerrar sem contexto. Detalhes e exemplos em Gestão de Erros e Exceções.

← Anterior Balancear Carga dos Agentes Próximo → Manipulação de Variáveis