A imagem que representa o agente. Escolha uma do catálogo disponível. Ela acompanha o agente em toda a plataforma.
Criação de Agente
Tudo que define como o agente se comporta: quem ele é, quanto pode executar, qual navegador usa, quanto tempo espera e quem ele avisa.
Um agente novo já nasce funcionando: todos os campos desta página têm valor padrão. Você não precisa passar por eles antes de montar o primeiro fluxo. Volte aqui quando quiser ajustar um comportamento específico, e use esta página como referência do que cada campo faz.
Nesta página
Identidade do agente
O agente tem um rosto e um nome, e é assim que você o reconhece na lista, nos painéis de acompanhamento e nas notificações que ele envia.
Os três campos de identidade são preenchidos no momento em que você cria o agente:
Depois de criado, esses mesmos dados aparecem no topo da tela do agente. Para mudar qualquer um deles, clique diretamente sobre o item e edite ali. A alteração é gravada na hora, sem precisar confirmar em outro lugar.
Avatar
seleção
Obrigatório
Nick
texto
Obrigatório
Apelido curto do agente, até 25 caracteres. É por ele que você identifica o agente rapidamente numa lista com muitos. Ex.: Lee, Neo.
Propósito do Agente
texto
Obrigatório
O que o agente faz, em uma frase. Ex.: Valida NFs de Fornecedores. É o nome do processo, e aparece nos relatórios e no histórico de execuções.
Descrição do Agente
texto longo
Espaço livre para o contexto que o propósito não cabe: para qual área o agente foi feito, quais regras de negócio ele assume, o que já se sabe que ele não cobre. Visível apenas internamente, para a sua equipe.
Configurações de Execução
Definem os limites dentro dos quais o agente pode trabalhar e o idioma em que ele se comunica. Servem como rede de segurança: mesmo que algo saia do previsto no fluxo, o agente para em vez de rodar indefinidamente.
Limitador de Ações
número
Quantas ações o agente pode executar numa única rodada antes de encerrar sozinho. É a proteção contra um laço que nunca termina.
O mínimo é 1. Aqui o zero não significa "sem limite": significaria "não executa nada", e o agente terminaria antes da primeira etapa.
Mantenha este número no tamanho real do trabalho, sem folga exagerada: além de proteger contra o laço sem fim, ele é o que garante que um agente chamado por outro agente termina em algum momento, e quem o chamou não fica parado esperando. Veja Quando o runtime do agente chamado sai do ar.
Limitador de Exceções
número
Quantos erros não fatais o agente tolera, somados em toda a execução, antes de encerrar. Máximo: 2000.
0 significa ilimitado. Diferente do Limitador de Ações, aqui o zero é uma escolha válida.
Este é um teto global do agente. Cada etapa também tem o seu próprio Limite de Erros, independente deste número, e este teto global prevalece sobre ele. Veja Gestão de Erros e Exceções.
Execuções ao mesmo tempo
número
Quantas execuções deste agente podem estar de pé ao mesmo tempo numa mesma máquina, venham de onde vierem: API, agendamento, webhook, Control Room, execução manual ou outro agente que o chama. É o teto do agente, diferente do teto do ambiente (que vale para todos os agentes da máquina) e do Modo de enfileiramento do disparo da etapa Chamar Agente (que vale para uma lista).
0 significa sem teto, o comportamento de sempre. Com 1, o agente nunca roda duas vezes ao mesmo tempo na mesma máquina: a segunda execução espera a vez na fila do ambiente, sem tomar a vez dos outros agentes, e entra quando a primeira termina. Conta a execução inteira, inclusive enquanto ela espera um agente chamado.
Vale para toda execução que passa pelo seu Ambiente Runtime, inclusive o ▶ do editor (na Sandbox não há fila). Como toda configuração do agente, entra em vigor na produção quando a versão é publicada; o ▶ usa o valor já publicado.
Serve para o sistema de destino que não aceita este agente entrando mais de uma vez: um portal com um login por usuário, um registro que fica travado enquanto alguém o edita, uma API que corta quem passa de certo ritmo. Vale por máquina: com Distribuir entre runtimes, cada runtime aplica o teto na dele. A comparação dos três tetos está em Enfileirar Agentes.
Limites e tetos
| Limite | Valor | O que acontece ao passar | Contorno |
|---|---|---|---|
| Limitador de Ações | Mínimo 1; padrão 500 | O agente encerra sozinho com o status STEP_LIMIT_REACHED, sem terminar o fluxo. | Suba o número para o tamanho real do trabalho; um laço que percorre uma lista longa precisa de folga para cada volta. |
| Limitador de Exceções | 0 é ilimitado; até 2000 | O agente encerra quando a soma de erros não fatais passa do número. | Trate o erro na própria etapa com a Gestão de Erros, para ele não se acumular aqui. |
| Execuções ao mesmo tempo | 0 é sem teto; 1 ou mais | A execução que não cabe espera a vez na fila do ambiente daquela máquina. | Se o sistema de destino aceita mais acessos, suba o número; se precisa de mais máquinas, distribua entre runtimes (o teto é por máquina). |
Idioma do Agente
seleção
Idioma das mensagens, logs e notificações que o agente gera. Português do Brasil, English ou Español.
Onde o agente executa
O ambiente é escolhido no seletor AMBIENTE, no topo da tela do agente. A troca vale imediatamente, e é sempre o dono do agente quem a faz: em um agente compartilhado com você, o campo mostra o runtime do dono e a Sandbox. Veja Ambientes Runtime e Ambiente Sandbox.
Índices de Produtividade
Estes dois campos respondem a uma pergunta que a diretoria vai fazer: quanto essa automação economiza? Informe o esforço que a tarefa custava quando era feita à mão, e a plataforma calcula o ganho a cada execução.
Tempo Médio Humano
horas e minutos
Quanto tempo uma pessoa levava para fazer este mesmo processo manualmente. Ex.: 2 horas e 30 minutos.
A plataforma multiplica esse tempo pelo número de execuções para mostrar as horas economizadas.
Custo Médio do Operador
moeda (R$)
O custo total de uma execução manual completa, e não um valor por hora. Faça a conta antes (custo-hora da pessoa × Tempo Médio Humano) e informe o resultado pronto.
Se a tarefa levava 10 horas e a hora custa R$ 50, o valor aqui é R$ 500,00.
Estime com base em medição, não em impressão
Cronometre três a cinco execuções manuais reais antes de preencher. Números inflados aparecem no relatório que a liderança lê, e a credibilidade do indicador cai junto com eles. Veja como aparecem em Dashboards.
Configurações de Navegador
Valem para agentes que operam sistemas pela tela. Se o seu agente só chama APIs, conectores ou executa código, pode pular esta seção inteira.
São três decisões: como o navegador é aberto, se ele fica visível enquanto trabalha e se guarda login e cache para a próxima execução.
Navegadores suportados
C Chrome
Cr Chromium
E Edge
Rodar o navegador em segundo plano (headless)?
sim ou não
Sim: o navegador trabalha invisível, sem abrir janela na tela. É o indicado para produção, porque consome menos recursos e não atrapalha quem estiver usando a máquina.
Não: a janela abre normalmente e você vê o agente agindo. Útil enquanto desenvolve.
Ao ligar, Como o navegador deve ser iniciado? passa para Usando app nativo. Em segundo plano, o navegador roda com Usando app nativo ou Usando navegador local; Usando conexão com navegador local fica indisponível.
Como o navegador deve ser iniciado?
seleção
Obrigatório
- Usando app nativo: a plataforma abre e controla o próprio navegador, com um perfil interno dedicado a este agente. É a opção padrão e a recomendada para produção: não exige nenhum caminho configurado.
- Usando navegador local: a plataforma abre uma instância nova do navegador indicado em Caminho do Executável, já usando o perfil que você escolher. Do início ao fim, quem controla esse processo é a própria automação, como no App Nativo.
- Usando conexão com navegador local: a plataforma inicia esse mesmo navegador como um processo independente (com a porta de depuração remota aberta) e só então se conecta a ele, em vez de controlá-lo desde a abertura. A porta de depuração é escolhida pelo próprio navegador a cada abertura, então execuções ao mesmo tempo nunca disputam a mesma porta.
Em Navegador Local e Conexão, é o diretório de usuário quem preserva cookies, histórico e login entre execuções do agente, enquanto Manter histórico e cache estiver ligado. A diferença entre os dois modos está em quem sobe o processo do navegador, não em qual sessão fica guardada.
Qual o caminho do executável do navegador?
texto
Obrigatório
Onde o navegador está instalado na máquina que executa o agente. Aparece nos modos Usando navegador local e Usando conexão com navegador local.
Windows: C:\Program Files\Google\Chrome\Application\chrome.exe
Linux: /usr/bin/google-chrome
macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
Para descobrir, abra o navegador, acesse chrome://version e copie o campo Executable Path.
Qual o diretório de usuário padrão?
texto
A pasta onde o navegador guarda cookies, histórico e sessões abertas daquele agente.
Exemplo: C:\AgentProfiles\Validador-NF
Opcional. Sem pasta informada, o runtime usa uma pasta própria para este agente.
Quando o agente roda mais de uma vez ao mesmo tempo, cada execução usa uma pasta só dela, criada a partir desta: veja Várias execuções do agente ao mesmo tempo.
Uma pasta por agente
Dois agentes com a mesma pasta dividem login e cookies: o que um grava, o outro encontra na próxima execução. Dê a cada um a sua.
Manter histórico e cache do navegador?
sim ou não
Decide se o navegador guarda o que a execução deixou (login, cookies, cache) para a próxima. Vale nos três modos de iniciar o navegador. Vem ligado.
- Sim: a pasta do navegador é reaproveitada, com o login e o cache da execução anterior.
- Não: cada execução começa com o navegador limpo, numa pasta nova que é apagada quando ele fecha. Nenhuma execução encontra o login ou o cache de outra, e nada se acumula no disco. O fluxo precisa fazer o login a cada execução.
| Como é o login do sistema | Opção |
|---|---|
| Usuário e senha que o fluxo digita | Não funciona, e cada execução começa limpa |
| Algo que o fluxo não refaz sozinho: código por SMS, segundo fator, certificado | Sim: faça o login uma vez em cada pasta e ele fica guardado |
Uma sessão por usuário
Sistema que aceita uma sessão só por usuário derruba execuções logadas na mesma conta ao mesmo tempo, com qualquer das duas opções. Nesse caso, use uma conta por execução.
Várias execuções do agente ao mesmo tempo
Cada execução do agente abre o próprio navegador, numa pasta só dela. Várias execuções do mesmo agente rodam juntas na mesma máquina, cada uma no seu navegador, sem dividir login, cookies nem porta de depuração. Vale nos três modos de iniciar o navegador.
Para que serve. Dividir um trabalho grande em partes que rodam ao mesmo tempo: um lote de 600 registros em três partes de 200, com três navegadores abertos no mesmo runtime. Serve também para execuções que chegam juntas de lugares diferentes, como API, agendamento e outro agente.
Como habilitar. A pasta de cada execução é escolhida sozinha, sem configuração. Para as execuções rodarem de fato ao mesmo tempo:
- Execuções ao mesmo tempo, na configuração de execução do agente, em
0(sem teto) ou no número de partes; - no Ambiente Runtime, Enfileirar Jobs desligado, ou ligado com Execuções ao mesmo tempo que caiba todas as partes;
- as partes disparadas juntas, por exemplo com Paralelizar Agentes.
Como as pastas são escolhidas. A pasta do agente é o diretório de usuário informado ou, sem ele, a pasta própria que o runtime cria para o agente.
| Manter histórico e cache | Primeira execução | Outras execuções ao mesmo tempo | Quando a execução termina |
|---|---|---|---|
| Sim | A pasta do agente | Pastas ao lado, com o mesmo nome e um número: Validador-NF-2, Validador-NF-3 | A pasta fica, com a sessão daquela pasta. O login feito numa não aparece na outra. |
| Não | Uma pasta nova para cada execução, dentro da pasta do agente | A pasta é apagada | |
Uma pasta numerada que já existe mas não foi criada pelo runtime para este agente, como o diretório de outro agente, é pulada, e o runtime usa o número seguinte.
O navegador de uma execução que termina com erro, ou de um runtime fechado no meio do trabalho, não fica aberto: o runtime o encerra no fim da execução ou quando volta a subir, e apaga a pasta dele quando é uma pasta nova de execução.
Habilitação de Componentes
Recursos extras que o agente pode usar durante a navegação. Vêm desligados, e você liga apenas os que aquele agente precisa.
Quais componentes deseja habilitar?
múltipla seleção
- Contorno de Captcha: resolve automaticamente os desafios de CAPTCHA que aparecerem no caminho. Veja Captcha.
- Simulação de Usuário: imita movimentos de mouse e ritmo de digitação de uma pessoa. Ajuda em portais que barram comportamento automatizado.
- Acesso Anônimo: navega em modo privado, sem guardar cookies entre execuções. Use quando cada execução precisa começar do zero, sem sessão anterior.
Selecione um provedor de Captcha
seleção
Aparece somente com o Contorno de Captcha ligado. Escolha entre 2CAPTCHA e CAPMONSTER.
Você só escolhe o provedor. A credencial de acesso a ele é administrada pela plataforma, então não há nada para contratar por fora nem cadastrar no Cofre.
Velocidade e Limites de Tempo
Quanto o agente espera antes de desistir, e com que velocidade ele age. São os campos que mais resolvem falha intermitente em sistema lento. Todos os valores são em milissegundos.
Atraso na Execução
número (ms)
Pausa entre uma ação e outra, de 0 a 10000. Com um valor alto você acompanha o agente em câmera lenta, o que ajuda a entender onde ele erra. Em produção, deixe em 0.
Limite de Carregamento de Páginas
número (ms)
Quanto esperar uma página terminar de carregar, de 0 a 120000. Passando disso, a etapa falha por tempo esgotado.
0 significa sem limite: o agente espera o tempo que for preciso.
Limite de Busca de Seletores
número (ms)
Quanto esperar um elemento aparecer na tela antes de falhar, de 0 a 60000. Aumente em páginas que carregam conteúdo aos poucos.
0 significa sem limite.
Prefira aumentar o limite de espera a colocar um atraso fixo. O agente segue assim que o elemento aparece, em vez de esperar sempre o tempo cheio. Veja Timers.
Comunicação
Um agente que roda sozinho, de madrugada ou por agendamento, precisa avisar alguém do que aconteceu. Esta seção define quando avisar e quem recebe, e são dois avisos diferentes: o de andamento e o com o log da execução.
As mensagens saem por e-mail. Para avisar em outros canais, use uma etapa de conector dentro do fluxo. Veja Mensageria Padrão.
Aviso de início e fim
Enviar e-mail quando
múltipla seleção
- Agente iniciar as atividades: avisa que a execução começou.
- Agente finalizar as atividades: avisa que terminou, com sucesso ou não.
Quem o agente deve informar?
e-mails
Quem recebe esses avisos. Digite @ para buscar pessoas da sua empresa, ou informe endereços separados por vírgula.
Envio do log da execução
Envio de Logs
múltipla seleção
- Sempre que o Agente finalizar as atividades: manda o log completo ao fim de toda execução.
- Sempre que houver uma falha: manda apenas quando algo dá errado.
Quem o agente deve informar?
e-mails
Quem recebe o log. É uma lista independente da anterior, então dá para avisar o gestor sobre o andamento e mandar o log técnico para quem sustenta a automação.
No mínimo, avise alguém quando falhar
Um agente que falha em silêncio só é descoberto quando alguém sente falta do resultado. Deixe Sempre que houver uma falha ligado com um responsável.
Variáveis Globais do Fluxo - Matrix
Quase toda automação precisa receber alguma informação para começar: o mês a processar, o CNPJ da filial, o e-mail de quem deve ser avisado. Essas informações são as variáveis globais do fluxo, também chamadas de Matrix.
Você cadastra cada variável com um valor padrão, e ela fica disponível em qualquer etapa do fluxo, escrita como {matrix.nome_da_variavel}.
As variáveis ficam numa tela própria, aberta pelo atalho de Matrix, no topo da tela do agente:
Cada linha é uma variável, com o nome, o tipo do dado e o valor que vale quando ninguém informa outro:
| Campo | Descrição |
|---|---|
| Variável | O nome, sem espaços e sem acentos. Ex.: mes_referencia. É como você vai chamá-la no fluxo: {matrix.mes_referencia}. |
| Valor Padrão | O que vale quando a execução não informa nada. Pode ser alterado a cada disparo. |
| Tipo |
Texto: qualquer palavra ou frase Número: inteiro ou decimal, com vírgula decimal ( 2,5)Moeda: valor em dinheiro, com duas casas ( 1.234,90)Verdadeiro/Falso: sim ou não Lista: vários valores separados por vírgula, ou uma lista JSON Objeto: um objeto JSON, como {"nome": "Ana", "idade": 30}Secreto: dado sensível enviado por quem dispara a execução, sem valor padrão e sem aparecer em log. Veja O tipo Secreto |
O tipo vale em todo o fluxo: o valor é convertido pelo tipo quando chega, venha de quem vier, e é usado com esse tipo em fórmula, condição, script e preenchimento de tela. Um valor que não cabe no tipo faz a execução falhar antes da primeira etapa, com o nome da variável no erro. Detalhes de como cada tipo é lido e escrito: Como o tipo é aplicado.
O tipo Secreto
Use Secreto na variável que carrega uma credencial ou um dado pessoal, como uma API Key, um token ou um CPF. No fluxo ela se usa como qualquer outra, com {matrix.nome}, mas o valor é tratado como segredo:
- Sem valor padrão. O campo Valor Padrão fica bloqueado, porque um padrão ficaria guardado em texto puro no cadastro do agente. O valor só existe se quem disparou a execução o enviou.
- Fora do log. O valor aparece como
«•••»e some de todo registro da execução. - Só por API e webhook. No agendamento e na execução manual o campo aparece bloqueado.
Veja o comportamento completo, inclusive onde o valor pode ser informado, em Manipulação de Variáveis e em Dados Sensíveis.
Como usar no fluxo
Em qualquer campo de texto de uma etapa, escreva
{matrix.nome_da_variavel} e ela é trocada pelo valor no momento da execução. Numa URL, por exemplo: https://sistema.com/relatorio?mes={matrix.mes_referencia}
Trocar os valores a cada execução
O valor padrão é só o ponto de partida. Cada disparo pode enviar valores próprios, que valem apenas naquela execução:
| Forma de disparo | Como os valores chegam |
|---|---|
| Execução manual | Ao executar, aparece um diálogo com as variáveis para você revisar e alterar antes de confirmar. |
| Agendamento | O agendamento guarda os seus próprios valores, aplicados a cada disparo automático. |
| Webhook | Os campos do payload recebido alimentam as variáveis, conforme o mapeamento configurado. |
| API | A chamada envia os valores no corpo da requisição. |
Em todos os casos vale a mesma regra: variável enviada substitui o padrão, variável não enviada mantém o padrão, e o cadastro do agente nunca é alterado. Dentro do fluxo, as etapas leem {matrix.variavel} sem precisar saber de onde o valor veio.
Um processo, muitos contextos
É isso que permite um único agente atender várias empresas, filiais ou meses. O fluxo é um só, e cada disparo injeta o contexto daquela vez, sem duplicar o agente.