Catálogo de Processos

Nível de acesso requerido

Admin, Modelador ou Super Admin

O que é uma definição?

Uma definição é o modelo de processo (BPMN) ou caso (CMMN) publicado na plataforma. A plataforma os divide entre escopo Global e Local.

Definições Locais (Processos do Tenant): O Admin do Tenant vê e gerencia as configurações daquele processo dentro da sua empresa, em Desenho de processos → Catálogo de Processos. Abrir um processo dá acesso às abas Diagrama, Documentação, Versões, Configurações, Variáveis, Base de Conhecimento, Agentes IA, Formulários, Auto-Aprendizado e Consumo de IA.

A aba Consumo de IA mostra o que aquele processo gastou no período, em tokens, por etapa e por modelo. Ao lado dos números há três colunas que dizem por quê: Iterações (quantas idas ao modelo cada execução levou), Contexto (quanto do prompt é texto recuperado das bases) e Desperdício (tokens gastos em chamadas que não responderam nada). Uma etapa marcada com o aviso é uma que vale olhar — e as três colunas apontam correções diferentes: prompt e ferramentas, escopo da base de conhecimento, ou tratamento de erro. Trocar por um modelo mais barato não corrige nenhuma das três. A aba é visível para quem administra e para quem modela.

Catálogo de Processos Globais: O Admin do Tenant também vê, na mesma lista, os processos globais disponíveis na plataforma:

• Ele não pode criar, editar modelos ou visualizar as configurações internas de desenvolvimento dos templates globais.
• Ele pode ativar ou desativar (usando o toggle switch) qualquer processo global para o seu próprio ambiente. Um processo desativado não aparecerá para os usuários iniciarem instâncias no portal ou via API naquele tenant específico.
• Rascunhos: Processos globais que ainda não foram oficialmente publicados aparecerão com o toggle desabilitado. O Admin não conseguirá utilizá-los até que o Super Admin finalize a publicação.

Publicando uma nova definição

Criar uma definição e desenhá-la são dois passos, nesta ordem.

Passo 1 — Criar a definição vazia

1. Acesse Desenho de processos → Catálogo de Processos
2. Clique em Nova Definição e escolha o tipo — BPMN, DMN Template ou CMMN
3. Informe a chave e o nome, e confirme

A definição é implantada na hora, com o desenho mínimo do tipo escolhido: para BPMN, um evento de início; para CMMN, o plano do caso vazio. Nenhum modelador abre nesse momento — a primeira versão aparece na aba Versões como Disponível, e publicar é um passo à parte.

Passo 2 — Desenhar no modelador

1. Abra a definição na lista
2. Clique em Editar / Nova versão — o modelador abre com o XML da versão atual carregado
3. Modele, e clique em Nova versão para publicar — enquanto a versão é salva, Fechar fica desabilitado, para que uma recusa do servidor apareça com o desenho ainda aberto

Em BPMN, o modelador traz também Revisar com IA, que analisa o desenho antes de publicar.

Caminho alternativo — enviar um XML pronto

Quem já tem o arquivo desenhado não precisa passar pelos dois passos acima.

1. Acesse Desenho de processos → Catálogo de Processos
2. Clique em Importar XML, no alto da tela, ao lado de Nova Definição
3. Escolha o arquivo — são aceitos .bpmn, .bpmn20.xml, .cmmn, .cmmn.xml e .dmn

O arquivo é implantado assim que você confirma a escolha; não há uma janela de confirmação. Se o XML for recusado, a mensagem do servidor aparece no aviso vermelho logo abaixo do cabeçalho. Um motivo comum em XML escrito fora do modelador é um campo de etapa com texto declarado como expressão — veja Java Delegates → O que a plataforma recusa.

O mesmo envio continua disponível pela API, em POST /api/a/definitions/deploy com o arquivo no campo file — veja Referência da API.

No modelador CMMN, o painel de propriedades muda conforme o que você seleciona:

Selecionado	O que o painel oferece
Plano do caso (retângulo externo)	Conclusão automática e o formulário de início do caso
Tarefa humana	Formulário, responsável, usuários candidatos, papéis candidatos, prazo e prioridade
Estágio interno	Conclusão automática
Tarefa de serviço	Implementação (classe, delegate, expressão ou ✨ Agente de IA), variável de resultado, execução em segundo plano e os parâmetros do delegate
Tarefa de serviço com Agente de IA	Agente, instrução, variável de retorno, ferramentas desta etapa e bases desta etapa — os mesmos controles do modelador BPMN

Responsável e candidatos aceitam tanto uma pessoa da lista quanto uma expressão como ${gestor} — nesse caso, quem preenche o valor é o formulário de início.

Os painéis de propriedades do BPMN e do CMMN seguem o idioma da interface. O que fica igual em qualquer idioma é o que o motor lê como está: o ID do elemento, os eventos de listener (start, end, take), os formatos de resultado da tabela DMN (singleEntry, resultList…) e os exemplos técnicos dos campos, como P30D, groovy ou com.example.MyDelegate.

O que o painel não edita, o modelador não apaga mais

Um caso pode chamar um processo ou outro caso e passar variáveis para ele — o bloco <flowable:in> / <flowable:out>, escrito à mão no XML. O painel continua sem campo para isso: quem quiser essa ligação escreve no arquivo e faz upload. O que mudou é que abrir e salvar o mesmo caso no modelador preserva esse trecho — antes ele desaparecia calado, e o caso voltava a rodar sem receber variável nenhuma.

A opção DMN Template faz coisas diferentes conforme o papel

Para o Super Admin, ela cria um template DMN global — a base a partir da qual cada tenant implanta a sua própria tabela de decisão. Para o Admin do tenant, ela implanta uma tabela de decisão diretamente no tenant, que passa a aparecer em Decisões DMN.

Editando uma definição existente

Para criar uma nova versão de uma definição já publicada:

1. Abra a definição e vá à aba Versões
2. Clique em Editar / Novo na linha da versão que serve de ponto de partida
3. O modelador abre com o XML daquela versão pré-carregado
4. Faça as alterações e clique em Nova versão para publicar

Rascunho do que ainda não foi publicado

Enquanto você edita, o modelador guarda um rascunho neste navegador a cada pausa na edição, e também ao clicar em Fechar ou ao recarregar a página. Se você fechar sem publicar — ou se a publicação for recusada e você sair —, na próxima vez que abrir Editar / Nova versão da mesma definição o modelador mostra o aviso Rascunho não publicado, com a data em que foi salvo:

• Restaurar rascunho carrega o diagrama do rascunho, e é ele que Nova versão publica;
• Descartar apaga o rascunho e fica com a versão publicada.

Se você começar a editar com o aviso aberto, isso conta como resposta: o aviso fecha e uma nota avisa que o rascunho anterior foi deixado de lado e que o que você editar agora passa a ser o novo rascunho. Mudou de ideia? O botão Restaurar o rascunho anterior na nota traz o rascunho de volta. No modelador BPMN, desfazer todas as edições até voltar ao diagrama publicado também apaga o rascunho; nos modeladores DMN e CMMN o rascunho some ao descartar, ao publicar ou quando o diagrama volta a ser idêntico ao publicado.

Se alguém publicou outra versão depois que o rascunho foi escrito, o aviso fica amarelo e diz de qual versão ele partiu (v3 → v4): restaurar publica por cima de mudanças que o rascunho não contém, então confira o diagrama antes. O rascunho é apagado quando a publicação dá certo. Ele fica só neste navegador, separado por organização, por pessoa e por processo — não vai para o servidor e não aparece para outra pessoa que use o mesmo navegador. Ao clicar em Sair, todos os rascunhos deste navegador são apagados. Se a sessão só expirar, o seu rascunho continua guardado e volta quando você entrar de novo; quando outra pessoa entra neste navegador, os rascunhos que não são dela são apagados. Eles também somem se você limpar os dados do site. Criar uma definição nova pelo catálogo ainda não guarda rascunho.

Na mesma aba, cada linha mostra o estado da versão — Publicada, Disponível ou Suspensa — e uma versão ainda não publicada traz o botão Publicar.

Versionamento

Ao publicar um arquivo com a mesma chave de processo, uma nova versão é criada automaticamente. Instâncias em andamento continuam na versão anterior; novas instâncias usam a versão mais recente.

O que a publicação confere nas etapas de agente

Ao publicar, a plataforma confere o que cada etapa de agente declara gravar e consultar (veja Agentes → O que a etapa grava). Um erro recusa a publicação e a mensagem nomeia a etapa; um aviso publica e fica no log. O assistente de IA do modelador recebe os mesmos erros ao fim de cada turno.

Código	Quando	Efeito
AGENT_WRITES_UNDECLARED	a etapa pode gravar com Gravar Variáveis e não declara o que grava	erro (aviso quando o agente é escolhido por expressão)
AGENT_WRITES_RESERVED	a declaração inclui aiDecision, escalateToHuman, campo de configuração ou ai_*	erro
AGENT_WRITES_INVALID	a declaração não é legível, repete um nome ou usa um tipo que o agente não grava (anexo, consulta, senha)	erro
AGENT_WRITES_TYPE_MISMATCH	um formulário do processo tem o campo com outro tipo	erro
AGENT_WRITES_TOOL_MISSING	declarou, mas a ferramenta de gravação não está na etapa	aviso
AGENT_WRITES_UNREAD	nenhum formulário nem expressão lê a variável	aviso
AGENT_WRITES_OPTIONS_DIVERGE	dois formulários têm opções diferentes para o mesmo campo	aviso
PATTERN_TASK_UNKNOWN	a tarefa de padrões não é uma tarefa humana do modelo	erro
PATTERN_TOOL_MISSING	declarou campos de padrão sem a ferramenta de padrões	erro
PATTERN_FIELD_NOT_IN_FORM	o campo não está no formulário da tarefa	aviso
PATTERN_FIELD_NEVER_LEARNED	o campo é de um tipo que o aprendizado não minera	aviso
PATTERN_SCOPE_UNDECLARED	a ferramenta de padrões está na etapa sem tarefa e campos declarados	aviso

Migrando uma etapa antiga. Uma versão já publicada continua rodando como estava. Para levá-la à regra nova: abra a versão em Editar / Novo, selecione a etapa de agente, preencha Variáveis que a etapa grava com as variáveis que ela de fato grava (o log da plataforma registra legacy undeclared write com as chaves de cada gravação de uma etapa sem declaração) e publique a nova versão.

Assistente de IA no modelador

O modelador tem um assistente que trabalha sobre o processo aberto. Além de desenhar o diagrama, ele configura o que existe em volta dele: pode criar e alterar formulários, criar bases de conhecimento e ligá-las ao processo, criar coleções de CMS, criar agentes de IA e vinculá-los a uma etapa.

Antes de configurar uma etapa automática ele consulta o que o tenant tem: o catálogo de ferramentas de agente, para dar a cada etapa só as ferramentas de que ela precisa, e a lista de conectores — tabelas de decisão, delegates Java e caixas de entrada de e-mail que iniciam processo. Com isso ele pode ligar uma tarefa de serviço a uma tabela de decisão (dmn, a chave da tabela) ou a um delegate Java (delegateClass, a classe), em vez de um agente, usando só chaves e classes que aparecem na lista. Robôs aparecem na lista como agendados: não viram etapa do diagrama.

Quatro coisas valem saber antes de usar:

• Ele diz o que fez. Cada formulário, base ou agente criado aparece listado na conversa, com nome e link. Quando uma instrução não pôde ser aplicada — uma conexão cujos elementos não existem, por exemplo — ele avisa em vez de seguir em silêncio.
• Ele não publica. Nada do que o assistente cria entra em um processo em execução: publicar a definição é uma ação sua, e é onde você confere o resultado rodando uma instância.
• Ele não edita um agente existente. Um agente já usado por um processo publicado passaria a valer na próxima execução sem publicação e sem teste. Para mudar de comportamento, crie outro agente e vincule a etapa a ele.
• A conversa sobrevive ao recarregamento. O histórico fica guardado por processo, neste navegador. Ele não vai para o servidor, não é compartilhado com outra pessoa e desaparece se você limpar os dados do site — é o raciocínio que você acabou de ter, não um registro de auditoria.

O assistente lê a descrição do processo antes de propor qualquer coisa, e pode propor uma descrição nova ao fim da conversa. A proposta é exibida ao lado do texto atual — a descrição só muda quando você aceita, porque ela não tem histórico de versões para desfazer. A proposta fala das etapas e dos formulários pelo nome: onde o modelo escreveu um id técnico (Task_…, Gateway_…, a chave de um formulário), a proposta mostra o nome do elemento, e o id que não tem nome conhecido é retirado. Uma chave que é uma palavra comum (review, reembolso) só é trocada onde aparece como identificador — entre crases ou logo depois de "formulário" —; escrita como palavra no meio da frase, fica como está. A chave do próprio processo nunca é alterada. O texto salvo ao aceitar é exatamente o que a proposta mostrou.

Escopo

O assistente trabalha no escopo em que você está. Editando um Template Global, ele lê e escreve os dados globais; dentro de um tenant, os do tenant. Ele não mistura os dois na mesma conversa.

Lendo o XML de uma versão

Na lista do Catálogo de Processos, cada linha traz Exportar XML, ao lado de Detalhes. O arquivo é baixado com a chave da definição no nome e a extensão do tipo — .bpmn, .cmmn ou .dmn. É o mesmo conteúdo que o modelador carrega quando você abre a versão em Editar / Novo, e é a versão que a lista está exibindo.

O botão exige o mesmo papel do resto da tela: Admin do tenant ou Super Admin. Pela API, o endereço é GET /api/a/definitions/{chave}/versions/{id}/xml.

Exportar e Importar XML formam o par que move um processo entre ambientes: exporte no tenant de homologação, importe no de produção.

Documentação do processo

A aba Documentação, logo depois do Diagrama, guarda um texto em Markdown escrito para pessoas: para que serve o processo, quem são os envolvidos, o que dispara cada caminho, o que fazer quando algo dá errado.

O diagrama mostra a forma do fluxo e não diz nada sobre a intenção. Sem esse texto, quem entra na equipe herda um desenho sem a razão dele.

O editor tem duas abas, Escrever e Pré-visualizar. O texto é salvo na hora e vale imediatamente — não depende de publicar versão nova nem de novo deploy. Documentação muda mais do que diagrama, e exigir um deploy para corrigir uma frase seria a troca errada.

Não confunda com Base de Conhecimento

Esta documentação é lida por pessoas. Ela não é enviada para a IA, não é fatiada em trechos e não é recuperada por busca vetorial. O que alimenta o agente são as Bases de Conhecimento — veja Bases de Conhecimento (RAG) mais abaixo.

Processos vindos de template global

Se o processo veio de um template global, a documentação é escrita pelo Super Admin no painel de Templates Globais e aparece aqui somente para leitura, com uma faixa indicando a origem. Não há editor, e isso é proposital: um processo global também não tem diagrama, agentes nem formulários editáveis pelo tenant. Um texto local que divergisse descreveria um fluxo que ninguém pode alterar.

Se o template ainda não traz documentação, a aba diz isso — em vez de convidar você a escrever algo que não seria salvo.

Quem pode escrever

Apenas Administrador ou Gerente do tenant. Os demais usuários leem. Quem não pode escrever não vê o editor desabilitado: simplesmente não vê editor.

Papéis de processo

Cada processo pode declarar papéis específicos (ex.: Solicitante, Aprovador). Após publicar a definição, você pode visualizar os papéis extraídos automaticamente do arquivo BPMN/CMMN.

Esses papéis são usados para atribuir tarefas às pessoas corretas em cada execução. Membros do tenant com o papel de processo correspondente receberão as tarefas automaticamente.

Template de Business Key

A Business Key é o identificador de negócio da instância — o número da nota, o código do pedido, o que liga a execução ao documento que a originou. Na aba Configurações da definição você define um template com variáveis do processo, por exemplo ${tipoDoc}-${emissao}-${cnpjEmissor}.

Variável ausente não vira chave

Se as variáveis do template não forem enviadas ao iniciar a instância, a instância não é criada: a plataforma responde 422 dizendo quais variáveis do template faltaram.

Recusar na entrada é deliberado. Uma instância que nascesse sem chave rodaria inteira e produziria resultado, e só muito depois se descobriria que não há como referenciá-la — nem responder se aquele documento já foi processado. O erro imediato e legível custa menos que semanas de instâncias órfãs.

A recusa vale para qualquer variável do template que não resolva, não só para o caso de todas faltarem. Uma chave como NFSE--, com só o tipo do documento preenchido, é igual para toda nota daquele tipo — ela colide por construção, e uma chave que colide não é chave.

Duas saídas quando a variável pode legitimamente faltar:

• dê um valor padrão no próprio template: ${cnpjEmissor:-SEM-CNPJ};
• ou envie businessKey diretamente na criação, que dispensa o template.

Definição sem template também ganha chave. A plataforma aplica um padrão embutido, DOC-${date:yyyyMMdd}-${random:4}, e toda instância iniciada sem businessKey explícito nasce com algo como DOC-20260813-A7K2. Não existe instância sem chave por omissão.

Esse padrão nunca cai na recusa acima, porque data e sufixo aleatório sempre resolvem. Ele só não significa nada para o negócio: se você quer uma chave que identifique o documento, declare o template; caso contrário a plataforma garante ao menos um identificador datado.

Prazo de conclusão e escalonamento

Na aba Configurações da definição, a seção Prazo de conclusão e escalonamento tem dois campos, ambos opcionais e escritos como duração ISO-8601 (PT8H = 8 horas, P3D = 3 dias, P2W = 2 semanas, P1M = 1 mês):

Campo	O que faz
Meta de conclusão	Em quanto tempo, a partir do início, uma instância deve terminar. Passou disso, quem iniciou e quem segura as tarefas abertas recebem Instância acima da meta. Vazio = sem meta
Escalar após	Quanto tempo depois de um prazo vencido — da tarefa ou da meta — Gerentes e Administradores são avisados, no sino e por e-mail. Vazio = sem escalonamento

O prazo de cada tarefa continua vindo do modelador (campo Due date da tarefa); o escalar após desta seção vale também para elas.

• O valor mínimo é 1 minuto. Um valor fora do formato é recusado e nada é gravado.
• Mudar a meta vale para as instâncias em andamento: o prazo de cada uma é recalculado como início + nova meta. Apagar a meta tira as instâncias da vigilância. Se a meta nova (ou o escalonamento novo) deixa uma instância já atrasada, ela passa calada para atrasada ou escalada — conta no Monitor, sem notificação nem e-mail.
• Execuções de teste nunca contam nem geram aviso.
• Os prazos são em horas corridas — sem calendário de dias úteis.

Quem edita: Administrador e Modelador. O resultado aparece no Acompanhamento.

Política de anexos

Na aba Configurações da definição, abaixo do template de Business Key, você define como os anexos daquele processo se comportam.

Como os anexos chegam

Modo	O que acontece
Ad hoc (padrão)	Além do formulário, quem tiver permissão pode anexar direto pelo painel de anexos da tarefa.
Somente formulário	O arquivo entra exclusivamente por um campo de arquivo do formulário. O painel fica só para leitura.

Somente formulário exige campo de arquivo

Nesse modo, um processo cujo formulário não tem campo de arquivo não aceita anexo nenhum. E como a tela de instância não tem formulário, ela deixa de oferecer qualquer caminho de upload — os arquivos passam a entrar apenas durante o preenchimento de uma tarefa.

Quem pode o quê

Três listas, todas preenchidas com papéis de processo:

• Papéis que podem visualizar — quem pode abrir a pré-visualização e baixar.
• Papéis que podem substituir — quem pode trocar um arquivo por uma versão nova.
• Papéis que podem anexar pelo painel — só aparece no modo Ad hoc.

Lista vazia significa "qualquer pessoa com algum papel neste processo" — não significa "todo mundo". Quem não tem papel nenhum na definição não acessa os anexos dela. Administradores sempre passam por todas as verificações.

Excluir não é uma opção

Não existe exclusão de anexo de processo, para nenhum papel, nem para administradores. Corrigir um arquivo é substituí-lo: o anterior sai da lista e permanece como histórico.

Bases de Conhecimento (RAG)

Na página de detalhes de um processo, você terá acesso à aba Base de Conhecimento. Nela, é possível visualizar todas as bases geradas pelos administradores (KBs Globais ou restritas ao Tenant) e habilitá-las para este processo específico.

Ao fazer essa vinculação explícita (Toggling), qualquer agente de IA que atuar nesse processo passará a ter seu System Prompt retroalimentado com as regras das bases habilitadas. Isso previne que a IA aplique regras do setor financeiro num processo do RH, por exemplo.

A base é do processo; a etapa escolhe dentro dele

O vínculo pertence ao processo, e não ao agente: trocar o agente de uma etapa não muda quais bases estão ao alcance dela.

O que o vínculo define é o conjunto disponível. Cada Service Task escolhe dentro dele pelo campo aiKnowledgeBases, e escolhe também as suas ferramentas — duas etapas do mesmo processo podem enxergar bases diferentes. Veja O que é do agente e o que é da etapa e, sobre dividir o prompt entre mais de um agente, Um agente por domínio.

Etapa que chama um Java Delegate

Nem toda etapa precisa de IA. Quando a regra é determinística — ler um layout conhecido, calcular um dígito verificador, normalizar um documento com formato fixo —, um Java Delegate faz o trabalho de forma exata, sem custo de token e sem risco de o modelo inventar um valor.

No modelador, selecione a Service Task e escolha o delegate no campo delegateExpression. A lista traz os delegates que a plataforma tem carregados naquele momento, com o nome da classe ao lado para desempatar nomes parecidos.

Se o delegate existe no ambiente de destino mas não neste, use Digitar manualmente e escreva a expressão à mão. A lista é o caminho padrão, não uma jaula.

Escolher da lista não é só conveniência

O nome do delegate nem sempre é óbvio: vem do @Component("nome") quando a classe tem a anotação, e do nome simples da classe com inicial minúscula quando não tem. Digitar errado publicaria um processo que aceita trabalho e trava na etapa. Por isso a plataforma também recusa o deploy de um processo que cite delegate inexistente, mesmo que o XML tenha vindo de fora do modelador.

Parâmetros

Um delegate pode declarar parâmetros. Quando declara, os campos aparecem logo abaixo da seleção, já preenchidos com o valor padrão que o autor definiu.

O valor pode ser literal (nfse-v2) ou vir de uma variável do processo, bastando escrevê-la como ${minhaVariavel} — a plataforma reconhece a forma e grava do jeito certo no XML.

Parâmetro marcado como obrigatório e deixado vazio bloqueia o salvamento da definição, nomeando o parâmetro que falta. A checagem acontece no modelador, onde ainda dá para corrigir na hora.

Um parâmetro não guarda segredo: senha, token e chave de API pertencem às variáveis do tenant, pelo motivo em Java Delegates.

Num caso, o delegate é de outro tipo

O motor de casos não executa JavaDelegate. Uma tarefa de serviço dentro de um CMMN precisa de uma classe que implemente PlanItemJavaDelegate (ou PlanItemFutureJavaDelegate); apontar para um JavaDelegate publica um caso que trava na etapa, sem erro no modelador.

Por isso a lista do modelador CMMN mostra apenas os delegates que o motor de casos consegue rodar, e o painel avisa em vermelho quando o caso já aponta para um delegate que só o BPMN executa — situação normal em arquivo escrito à mão ou copiado de um processo.

A seção Tarefa de serviço do painel grava flowable:type="java" junto com a implementação escolhida. Sem esse atributo o Flowable ignora a tarefa inteira, e era exatamente o que acontecia com quem editava o XML à mão e esquecia dele.

A própria plataforma traz um delegate de caso: o da etapa de IA. Escolha ✨ Agente de IA na implementação e o painel passa a pedir agente, instrução, variável de retorno, ferramentas e bases — os mesmos campos do modelador BPMN. Ele não aparece na lista de delegates porque essa lista mostra o que este tenant enviou, e a etapa de IA é da plataforma. Veja Agentes de IA.

Quando o delegate muda

Se você trocar o delegate selecionado, os parâmetros de mesmo nome são preservados e os demais ficam marcados como desconhecidos, em vez de desaparecerem. O mesmo vale para uma expressão que aponta para um delegate que não está carregado neste ambiente: ela continua ali, sinalizada — apagar seria descartar em silêncio uma decisão que alguém tomou de propósito.

Autoaprendizado

Um processo publicado aprende com o próprio histórico: a plataforma conta o que foi decidido em cada campo, em situações comparáveis, e usa essa contagem para sugerir o preenchimento das próximas tarefas. Isso é configurado na aba Autoaprendizado da definição.

Como Funciona

Uma vez por dia, a plataforma percorre o histórico de tarefas concluídas e conta, campo a campo, o que foi decidido em situações comparáveis. É daí que saem as sugestões com índice de confiança e a explicação "34 de 38 casos". Não passa por IA: são contagens sobre decisões reais. O detalhe do funcionamento está em Autocompletar Inteligente. O Super Admin pode refazer a contagem na hora, sem esperar o dia seguinte.

Quando o usuário pede sugestões numa tarefa, os campos com padrão qualificado são preenchidos pela contagem, sem chamar IA nenhuma. A camada 2 é oferecida, com um botão para aplicar e a etiqueta Caso anterior ao lado.

A sugestão é montada em duas camadas, e cada uma só é alcançada quando a de cima não tem resposta para aquele campo:

1. Contagem — campos de escolha (seleção, rádio, checkbox, booleano, lookup, avaliação) e também áreas de texto que se repetem. Se um campo de texto longo tem poucos valores distintos no período, ele é um texto-modelo, não prosa, e entra na contagem normalmente. Custa zero.
2. Caso anterior — para campo de texto sem padrão qualificado, a plataforma devolve o valor passado mais frequente naquele mesmo contexto, literal, para você editar. Também custa zero, e é rastreável: dá para dizer de quantos casos anteriores ele veio. Contar frequência só significa alguma coisa sobre categorias — um parecer diferente a cada documento aparece uma vez só, então sua confiança seria sempre baixa demais para virar sugestão.

O autopreenchimento não chama IA nenhuma

As duas camadas são contagem sobre decisões reais, então o Autopreencher não consome cota de IA. Se um campo de texto genuinamente único não tiver caso anterior parecido, ele simplesmente não recebe sugestão, em vez de receber uma sugestão gerada.

Ficam fora dos dois caminhos, sempre:

• Campos pessoais por tipo declarado — CPF, CNPJ, CEP, e-mail e telefone. Vale o tipo escolhido no construtor de formulários, não o nome do campo: um campo chamado solicitante declarado como texto continua protegido se você declará-lo corretamente, e um nomeDoProduto declarado como seleção é aprendido normalmente.
• Anexos e elementos visuais — arquivo, título, separador e visualizador de markdown não carregam valor sugerível.
• Variáveis internas da plataforma — as que começam com _ ou ai_, além de tenantId.

Campos numéricos, monetários e de data não viram sugestão, mas continuam servindo de condição ("quando o tipo de documento for X..."). Variáveis que o processo cria por fora do formulário seguem a mesma regra: nunca são sugeridas, porque não existem na tela do usuário, mas podem condicionar.

Nada disso vai para a IA também: o campo excluído é removido do que o modelo enxerga, não mascarado.

Não há uma tela onde se escolha o que aprender: quem decide é o tipo escolhido ao montar o formulário.

Tipo do campo	Entra no aprendizado
Escolha, rádio, checkbox, booleano, lookup, avaliação	Sempre
Texto de uma linha	Enquanto o valor tiver até 512 caracteres
Área de texto	Só com até 20 valores distintos no período; acima disso é prosa
Data, número, moeda	Nunca viram sugestão; só condicionam com até 20 valores distintos
CPF, CNPJ, CEP, e-mail, telefone, senha	Nunca — removidos do que o modelo enxerga
Arquivo, título, separador, visualizador de markdown	Nunca — não carregam valor sugerível

Se um campo deveria ser aprendido e não está, o mais provável é que ele esteja declarado como texto livre quando deveria ser uma seleção.

Nome de pessoa e endereço não são protegidos por tipo

A proteção automática da última linha vale por tipo declarado, e não existe tipo "nome de pessoa" nem "endereço" no construtor de formulários — um campo nomeCompleto ou enderecoEntrega declarado como texto é aprendido normalmente.

Para esses, use Campos excluídos do aprendizado. É a única proteção que funciona.

Há uma exceção parcial que não deve ser confundida com garantia: campos que o formulário não declara — as variáveis que o processo cria por fora da tela — passam por uma verificação pelo nome (nome, endereco, nascimento, rg, idade e outros). Isso pega alguns casos e erra nos dois sentidos, e a verificação nunca é consultada para um campo que o formulário declara.

Para excluir um campo específico, liste o nome dele em Campos excluídos do aprendizado, separando por vírgula. É uma lista de exclusão: tudo o mais continua sendo aprendido, e campo novo no formulário passa a ser aprendido sozinho. Ela não reabilita o que já é excluído por tipo — um campo CPF continua fora mesmo que você não o liste.

Não existe gatilho por lote. A micro-análise não dispara ao acumular N tarefas concluídas: contar conclusões pula ou dispara duas vezes quando duas pessoas concluem ao mesmo tempo, e o contador não teria como zerar de forma confiável. Tudo acontece na execução diária.

Os campos da aba

A aba Autoaprendizado fica na própria definição do processo, ao lado das outras. O formulário do Agente de IA não tem nenhum campo de aprendizado — procurar por lá é procurar onde não existe.

A consequência prática vale registrar: um processo com vários agentes tem uma só configuração de aprendizado, válida para todos eles. Trocar o agente de uma etapa não muda o que aquele processo aprende, nem separa o aprendizado por especialidade.

Os campos da tela:

• Autoaprendizado Ativo: Habilita ou desabilita o aprendizado das tarefas. Desligado, a contagem de padrões não é atualizada e nenhuma sugestão nova aparece.
• Janela Temporal (Meses): Quantos meses de histórico recente entram na conta (padrão: 3). Serve para o processo esquecer decisões obsoletas quando a regra de negócio muda.
• Ocultar abaixo de: A confiança mínima para um valor ser sugerido (padrão: 0,80). Abaixo dela, nada aparece. Era o antigo "Limiar de confiança".
• Pré-preencher ao abrir a tarefa: Desligado por padrão. Ligado, pede o limiar Pré-preencher a partir de (o formulário sugere 0,95) e os campos com padrão pelo menos tão forte chegam preenchidos quando a tarefa abre, marcados, com um aviso para a pessoa conferir. O limiar não pode ficar abaixo de Ocultar abaixo de — a tela e o servidor recusam.
• Campos que decidem o caminho: A plataforma lê a versão publicada e lista os campos usados em condições de gateway e nas entradas das tabelas de decisão. Eles nunca são pré-preenchidos, só oferecidos no Autopreencher, a menos que você marque o campo aqui.
• Limiares por etapa: Para cada etapa humana, os mesmos dois limiares; em branco, vale o do processo. A mesma regra vale aqui: o pré-preenchimento efetivo da etapa não pode ficar abaixo do limiar de ocultação efetivo.
• Campos excluídos do aprendizado: Lista de nomes de campos, separados por vírgula, que este processo não deve aprender nem enviar à IA. É uma lista de bloqueio: todo o resto continua sendo aprendido, e um campo acrescentado ao formulário depois passa a ser aprendido sozinho. Ela não reabilita o que já está excluído por tipo — um campo de CPF fica de fora esteja ele listado ou não.

Cada processo publicado tem a sua configuração, e ela vale só para ele. Desligar o aprendizado de um processo não afeta os demais.

Saúde do aprendizado

Abaixo da configuração, na mesma aba, fica a tabela Saúde do aprendizado: cada padrão em uso, com a confiança que ele afirma e a taxa com que os usuários realmente o aceitaram, lado a lado. A coluna Quando diz em que situação o padrão vale, com o rótulo do campo e da opção como aparecem no formulário ("Categoria é Tecnologia e o solicitante é Ana Souza") — nunca a chave interna nem um código de usuário. A aceitação conta só o que o Autopreencher mostrou a uma pessoa; o que um agente de IA consultou ou gravou não entra nela.

Ler as duas colunas juntas é o ponto. Confiança é o que o histórico diz; aceitação é o que as pessoas fizeram quando viram a sugestão. Enquanto as duas andam próximas, o padrão continua valendo. Quando a aceitação despenca e a confiança permanece alta, quase sempre a regra de negócio mudou e o histórico ainda não percebeu — esses padrões aparecem destacados e no topo.

Uma linha só recebe veredicto depois de dez exposições. Antes disso ela mostra "dados insuficientes", porque um padrão recusado duas vezes não é um padrão ruim.

O rodapé informa quantas sugestões foram retidas de propósito (o sorteio explicado em Autocompletar Inteligente). Essa retenção é o que mantém a coluna de confiança confiável: sem pessoas decidindo sem ver sugestão, não haveria com o que comparar.

Precisão por faixa e simulação de limiar

Logo abaixo do resumo do holdout ficam duas tabelas, calculadas sobre as tarefas concluídas dentro da janela de tempo:

• Precisão por faixa — uma linha para cada faixa (pré-preenchido, oferecido, oculto). Mostradas e Mantidas (com inércia) vêm das tarefas que viram a sugestão: um valor pré-preenchido que ninguém olhou conta como mantido, por isso a coluna diz "com inércia". Precisão do holdout vem das tarefas do sorteio, que não viram nada — é o número sem viés. Cobertura é a fatia das decisões do holdout que cai naquela faixa.
• Simulação de limiar (holdout) — para cada limiar entre Ocultar abaixo de e 1,00, quantas decisões do holdout ele teria coberto e com que frequência o valor estaria certo. A linha do limiar de pré-preenchimento atual vem marcada como atual. É a tabela para decidir onde pôr o limiar antes de ligar o pré-preenchimento: as tarefas do holdout gravam também o melhor padrão abaixo do piso, então a simulação enxerga o que ficaria oculto.

Como na tabela de saúde, qualquer taxa com menos de dez amostras aparece como "dados insuficientes".