Robôs de Automação

Nível de acesso requerido

Admin ou Super Admin

O que é um robô?

Um robô é um programa automatizado que executa tarefas sem intervenção humana. Robôs podem:

• Iniciar processos automaticamente em horários agendados
• Buscar dados de sistemas externos e alimentar o Flowi Agentic
• Executar etapas que não dependem de uma pessoa
• Integrar com ERPs, sistemas fiscais e outras plataformas

Cada robô é um arquivo JAR compilado previamente enviado para a plataforma, operando mediante agendamento CRON.

Atenção: Robôs ≠ Agentes

Os "Robôs" tratam de integração sistêmica rígida (código). Se o que você precisa é de uma automação cognitiva (ler PDFs, interpretar formulários livres ou decidir caminhos flexíveis com base em IA), acesse o manual de Agentes de IA.

Listando robôs

Acesse Automação → Robôs na barra lateral.

A tela exibe:

• Nome do robô
• Status (ativo / inativo)
• Próxima execução agendada
• Resultado da última execução (sucesso / falha)

Cadastrando um novo robô

1. Clique em Novo robô
2. Preencha:
   • Nome — identificação do robô
   • Agendamento — expressão cron (ex.: 0 8 * * MON = toda segunda às 8h)
   • Arquivo JAR — faça o upload do arquivo compilado
   • Parâmetros — configurações opcionais em formato JSON
3. Clique em Salvar

Expressão cron

Formato: minuto hora dia-do-mês mês dia-da-semana
Exemplos:

• 0 8 * * * — todo dia às 8h
• 0 8 * * MON — toda segunda às 8h
• */30 * * * * — a cada 30 minutos

Ativando e desativando

Use o toggle de ativo/inativo na listagem para controlar se o agendamento está em execução. Um robô desativado não é executado, mas permanece cadastrado.

Executando manualmente

Clique em Executar agora para disparar o robô fora do agendamento. Útil para testes.

Monitorando execuções

O histórico de execuções de cada robô exibe:

• Data e hora de início e fim
• Status: SUCESSO ou FALHA
• Log de saída ou mensagem de erro

Em caso de falha

Falhas de robôs são registradas no log mas não interrompem outros processos. Verifique o log para diagnosticar o problema e corrija o JAR antes de reativar.

Desenvolvimento do JAR (Native API)

Para garantir segurança e performance, os robôs do Flow.IA rodam isolados através de Sandbox (URLClassLoader) dentro da mesma máquina virtual do sistema.

Neste ambiente de sandbox, a execução do robô tem regras estritas:

• Sem acesso irrestrito ao File System local do servidor,
• Sem injeção de dependências pesadas do Spring,
• Os robôs recebem apenas o objeto RobotContext que atua como uma fachada de comunicação segura.

O RobotContext fornece acesso a recursos globais da plataforma sem necessidade de chamadas REST ou autenticação via Tokens. As operações disponíveis englobam o escopo do Tenant do robô.

Acessando Dados, CMS e Variáveis de Processo (JSONB)

Os robôs podem interagir de forma rica com os dados de instâncias de processos (utilizando variáveis estruturadas em JSON/JSONB), e também com o banco de dados sem esquema do Flow.IA (CMS).

Para criar o seu robô, implemente a interface FlowIaRobot:

import ia.flow.engine.FlowIaRobot;
import ia.flow.engine.RobotContext;
import java.util.Map;

public class MeuRobo implements FlowIaRobot {
    @Override
    public void execute(RobotContext context) {
        context.log("Iniciando varredura no CMS...");

        // 1. Acesso aos parâmetros estáticos configurados na tela do robô
        Map<String, String> params = context.getParameters();
        
        // 2. Acesso Native API: Consumir ou escrever no CMS do Tenant
        context.getCms().getRecordsByCollectionSlug("faturas")
               .forEach(record -> {
                   context.log("Processando fatura: " + record);
               });

        // 3. Acesso Native API: Iniciar novos processos
        // É possível passar variáveis complexas (JSONB) diretamente no mapa de inicialização.
        Map<String, Object> processVariables = Map.of(
            "origem", "robo_agendado",
            "detalhesProcessamento", Map.of("urgente", true, "categoria", "A") // Variável que será convertida em JSONB
        );
        context.getProcesses().startProcess("faturamento-workflow", processVariables);

        // 4. Acesso Native API: Consultar membros do tenant e dados gerais
        var members = context.getTenant().getMemberEmails();
        context.log("Membros notificados: " + members.size());

        // 5. Acesso Native API: Fazer upload de arquivos 
        // Ideal para casos em que o robô baixa arquivos externos e inicia processos com anexos
        byte[] pdfContent = new byte[]{ /* ... bytes do arquivo baixado ... */ };
        java.util.UUID attachmentId = context.getStorage().uploadAttachment(
            "instance", "uuid-da-instancia-criada", "fatura.pdf", "application/pdf", pdfContent
        );
        context.log("Fatura anexada com sucesso: " + attachmentId);
    }
}

O RobotContext é sua fachada isolada para o Flow.IA. Ele garante que qualquer operação (como getCms(), getProcesses() ou getStorage()) esteja restrita apenas aos dados pertencentes ao Tenant do robô ativo, prevenindo que um robô vaze dados de empresas vizinhas na plataforma. Você tem autonomia para consultar processos públicos do tenant, membros, etc., com segurança e agilidade.