Agentes de IA Autônomos (RAG)

Nível de acesso requerido

Admin, Modelador ou Super Admin — os agentes moram na aba Agentes de IA da definição, em Desenho de processos.

Até onde o agente pode chamar

Um agente que usa a ferramenta de chamada HTTP deve declarar os hosts permitidos, no formulário do agente — um por linha:

erp.cliente.com.br
*.parceiro.com.br

*.parceiro.com.br alcança api.parceiro.com.br e não alcança parceiro.com.br. A porta é ignorada na comparação.

Por que isso existe: o agente usa credencial sem enxergá-la (ver Variáveis do Tenant), mas sem lista ele podia enviar essa credencial para qualquer endereço externo que compusesse. Como agentes leem documento de fornecedor, registro de CMS e base de conhecimento — conteúdo que vem de fora — um modelo induzido por esse conteúdo pode compor a requisição errada. A lista limita o alcance.

Instalação nova: AI_HTTP_TOOL_DEFAULT_POLICY=deny

Com allow (padrão, por compatibilidade), agente sem lista chama qualquer endereço externo. Com deny, agente sem lista não faz chamada externa nenhuma, e cada agente que precisa da rede declara onde. Chamada para endereço interno da rede continua bloqueada nos dois casos.

A outra metade do mesmo controle é a dos Webhooks: lá a lista é do tenant, e não do webhook, porque o webhook é o destino. Mesmo formato de host, mesmo curinga, mesma recusa.

O que são Agentes de IA?

Um Agente de IA é um cadastro que reúne o que a plataforma precisa para chamar um modelo de linguagem dentro de uma etapa: qual modelo do catálogo usar, com que temperatura, sob qual prompt de sistema e com quais ferramentas por padrão. Um Robô clássico executa um JAR com lógica programada; o agente recebe texto — o documento anexado, o que as etapas anteriores gravaram, os trechos recuperados das bases de conhecimento — e devolve texto, que a plataforma grava na variável de resultado da etapa.

Três limites que valem saber antes de desenhar:

• Quem decide o caminho é o diagrama, não o agente. Ele grava a variável; o gateway (num processo) ou a condição de entrada (num caso) é que lê essa variável e escolhe a etapa seguinte.
• Quando falha, a etapa falha. Resposta vazia, ferramenta que não executou ou impedimento declarado pelo agente param a etapa com a causa escrita — a plataforma não deixa a variável em branco e segue.
• Toda chamada é cobrada, inclusive a que não deu certo. O provedor cobra pelo prompt que processou. Resposta vazia, erro do provedor e impedimento entram no consumo do tenant em Governança de IA como qualquer chamada bem-sucedida.

Usos típicos: auditar nota fiscal, revisar peça jurídica, triar ticket de suporte, classificar documento anexado.

Esta lista mostra só os agentes deste tenant

Um processo que veio de um Template Global pode usar agentes da plataforma. Eles executam normalmente aqui, mas não aparecem nesta tela — quem os cadastra e edita é o Super Admin, na aba Agentes de IA do template. Se um processo global usa IA e esta lista está vazia, é esse o motivo.

Estratégia BYOK (Bring Your Own Key)

O Flowi Agentic é software Self-Hosted: a plataforma não cobra taxa sobre o consumo de tokens. Quem fatura é o provedor do modelo (OpenAI, Google, Anthropic), direto para quem cadastrou a credencial.

A chave é da instalação, não de cada tenant. Quem a cadastra é o Super Admin, uma vez, no catálogo de modelos — não existe tela em que um administrador de tenant informe uma chave própria. Na prática, a organização que mantém a instalação recebe a fatura do provedor e usa a Governança de IA para ver quanto cada tenant consumiu e repassar.

Onde o modelo e a chave são cadastrados

Provedor e chave de API não ficam no agente. Eles vivem no catálogo de modelos, em Plataforma → Configurações de IA, onde cada modelo é registrado uma vez com o provedor, a credencial e a URL base. O agente apenas escolhe um modelo desse catálogo.

A separação é proposital: a credencial é da plataforma e de quem responde por ela, e um agente novo não deveria pedir que alguém cole uma chave de API de novo — nem multiplicar o número de lugares onde ela existe.

Editar um modelo não pede a chave de novo. Na edição, o campo de API Key vem vazio e o que estiver guardado é mantido; preencha apenas quando a intenção for trocar a credencial.

Modelo em uso não é excluído nem desativado

Se algum agente aponta para o modelo, se ele ocupa uma função do Copilot ou se é o substituto de um modelo aposentado, a plataforma recusa a exclusão e a desativação, dizendo quem depende dele. É proteção contra um estrago silencioso: apagar o modelo desfaz a ligação no banco, e cada um desses agentes passa a falhar em toda chamada, sem que nada na tela do agente indique o que mudou. Aponte os agentes para outro modelo antes.

Preço do modelo

O preço é cadastrado com o modelo, na mesma tela, na seção Preço: entrada, entrada em cache (opcional — vazio cobra como entrada), saída, moeda (USD, BRL ou EUR) e vale a partir de (vazio é agora). Os valores são por um milhão de tokens, como os provedores publicam. Na lista do catálogo cada modelo mostra entrada / saída; quem não tem preço aparece com o selo Sem preço.

O preço não se edita, se anexa. Ao editar um modelo com preço, a seção mostra o preço em vigor, um preço agendado se houver, o histórico e o botão Novo preço. Um preço novo precisa valer depois do último registrado — preço retroativo reescreveria o custo de chamadas já feitas, e a plataforma recusa. Uma data futura agenda o preço: até lá vale o anterior. Só um preço que ainda não entrou em vigor pode ser removido; para corrigir um que já vigorou, registre outro a partir de agora.

Cada chamada guarda o custo calculado uma vez, pelo preço em vigor no instante da chamada. Trocar o preço amanhã não muda o custo de ontem. O custo é casado pelo modelo do catálogo que montou a chamada, e não pelo nome que o provedor devolve: a OpenAI responde gpt-4o-2024-08-06 para um modelo cadastrado como gpt-4o, e antes essas chamadas ficavam sem preço.

O primeiro preço preenche o passado como estimativa

Quando um modelo recebe o primeiro preço, as chamadas anteriores dele que estavam sem custo recebem o custo por esse preço, marcadas como estimado nos relatórios. Uma chamada que já tinha custo nunca é tocada, e o segundo preço em diante não preenche nada.

Um modelo que já cobrou chamadas não pode ser excluído — o custo daquelas chamadas precisa continuar explicável; desative-o. Um modelo cadastrado por engano, que nunca atendeu uma chamada, sai com o histórico de preços junto.

O preço do embedding (bases de conhecimento e busca RAG) fica na aba Banco de Vetores (RAG): só entrada e moeda, com o mesmo histórico. Trocar o modelo de embedding cria uma configuração nova, que começa sem preço — o preço do modelo anterior continua com as chamadas que ele atendeu.

Funções do Copilot

No topo de Plataforma → Configurações de IA, o cartão Funções do Copilot diz qual modelo responde os dois copilotos — o do modelador e o de execução (quadro e tarefa). Nada disso é fixo no código: é o Super Admin quem escolhe.

• Modelo do Copilot — o padrão dos dois copilotos. Sem ele, vale o modelo marcado como padrão no catálogo e, sem padrão, o primeiro ativo.
• Modelo de contingência — responde uma vez por turno quando o provedor do primeiro falha por limite de taxa, cota do provedor, indisponibilidade (5xx), demora ou modelo aposentado, antes de qualquer texto aparecer ou de qualquer ferramenta rodar. Precisa ser um modelo diferente do modelo do Copilot; pode ser do mesmo provedor, e a tela avisa que uma queda daquele provedor derruba os dois.
• Selecionável no Copilot — chave no formulário do modelo. Os modelos marcados aparecem, junto com o modelo do Copilot, no seletor dos chats. A pessoa vê só o nome do modelo: nem preço, nem provedor.

A contingência nunca entra por recusa da requisição (400, 401, 403, 422), pela cota do próprio tenant nem depois que parte da resposta já apareceu ou uma ferramenta já alterou algo — repetir ali duplicaria o efeito. Cada tentativa paga o próprio token: um turno com troca grava duas linhas de uso com a mesma correlação, a primeira com o modelo que falhou e contagem zero, a segunda com o modelo de contingência. Nenhum turno grava mais de duas, e o cliente do provedor no caminho do copiloto tenta no máximo uma vez a mais por baixo.

Ciclo de vida do modelo

Cada modelo do catálogo tem um estado, mostrado na lista ao lado do status:

Estado	Responde	Novos vínculos	Quando usar
Em dia	sim	sim	o normal
Depreciado	sim	sim, com aviso	o provedor anunciou o fim; a data de desligamento é opcional
Aposentado	não, como ele mesmo	recusados	as chamadas vão para o substituto ou falham

O estado depreciado e a data se escolhem no formulário do modelo. Aposentar é uma ação própria — Substituir ou Aposentar —, porque ela mostra antes quem depende do modelo. Um modelo aposentado pode voltar a Em dia, e a volta fica registrada.

A plataforma nunca aposenta um modelo sozinha. Ela confere a lista de modelos do provedor ao cadastrar ou editar um modelo, todo dia às 03:00 e quando alguém clica em Verificar agora — sem gastar token, pela listagem de modelos da API. A coluna Lista do provedor mostra o resultado: Listado, Fora da lista (pode ser um alias — confira antes de aposentar), Sem como conferir (típico de URL base compatível que não publica a lista) ou Conferência falhou. Quando o provedor responde numa chamada que o modelo não existe mais, o modelo fica marcado como Não encontrado numa chamada, a falha diz "o provedor não serve mais o modelo X; escolha um substituto em Plataforma → Configurações de IA" e a etapa não é retentada.

Substituir um modelo

Na linha do modelo, Onde é usado lista, cruzando todos os tenants, os agentes que apontam para ele (com tenant e processo), os agentes dos templates globais agrupados por processo, as funções do Copilot que ele ocupa, as classes de modelo de que ele é membro e os modelos que o têm como substituto. Substituir abre a escolha do substituto em uma ação só, registrada no Histórico do modelo:

• a plataforma sugere um substituto — mesmo provedor, em dia e listado — mas não aplica nada até a confirmação. A sugestão só vem marcada se estiver na lista de escolha (ativo e em dia); senão o campo fica vazio e você escolhe;
• Marcar como aposentado aposenta o modelo no mesmo passo;
• Mover os agentes para o substituto reescreve o modelo de cada agente dependente, de tenant e do global, e registra cada agente movido. Sem marcar, os agentes continuam apontando para o modelo antigo e são redirecionados enquanto o substituto estiver definido — dá para desfazer.

Instâncias em andamento pegam o substituto na próxima chamada. O consumo passado nunca é reescrito; as chamadas novas guardam o modelo vinculado e o modelo chamado, e o custo é o do modelo chamado.

Avisos e publicação

O cartão Modelos que pedem atenção aparece no topo da tela quando há modelo depreciado com desligamento nos próximos 30 dias e alguém dependendo dele, modelo aposentado sem substituto com dependentes, modelo que o provedor não lista mais ou não encontrou numa chamada, ou função do Copilot apontando para modelo aposentado. Publicar uma versão cuja etapa de agente aponta para um modelo aposentado sem substituto é recusado, nomeando a etapa, o agente e o modelo; com substituto, a publicação passa e o agente responde pelo substituto.

Classes de modelo

Uma classe de modelo é um tipo de trabalho — Extrair (ler documentos e devolver campos), Raciocinar (analisar e decidir com as regras do processo) e Redigir (escrever textos e resumos) vêm cadastradas, vazias. Cada classe é uma lista ordenada de modelos do catálogo, montada pelo Super Admin no cartão Classes de modelo de Plataforma → Configurações de IA: adicionar, tirar, subir e descer membros e Salvar ordem. Dá para criar classes novas (o código é permanente) e renomear as existentes; toda mudança fica registrada.

Um agente aponta ou para uma classe ou para um modelo específico, nunca os dois. O agente ligado a uma classe é atendido pelo primeiro modelo da lista que puder ser chamado (e pelo seguinte quando o primeiro estiver no limite — veja a ordem de troca): um membro desligado ou aposentado sem substituto é pulado, e um membro aposentado com substituto responde pelo substituto. Trocar a ordem da classe troca o modelo de todos os agentes daquele tipo de uma vez, de todos os tenants e dos templates globais. Os agentes que já existiam continuam presos ao modelo que tinham.

• Ligar um agente a uma classe que ainda não tem nenhum modelo que responda é recusado.
• Uma classe que agentes usam não pode ser apagada, nem ficar sem nenhum modelo que responda.
• Um modelo que é membro de alguma classe não pode ser removido do catálogo; Onde é usado mostra as classes dele. Desativá-lo é permitido: a classe só passa a pulá-lo.
• O cartão Modelos que pedem atenção avisa quando uma classe usada por agentes não tem nenhum modelo que responda, quando tem um só (não há para onde ir se ele falhar) e quando um membro foi aposentado sem substituto.
• Publicar uma versão cuja etapa usa um agente de classe sem nenhum modelo que responda é recusado, nomeando a etapa, o agente e a classe.

A ordem de troca: se o primeiro estiver no limite, a etapa usa o seguinte

A etapa de IA de um agente de classe começa cada tentativa pelo primeiro modelo da lista que está disponível agora neste servidor, e troca para o seguinte entre tentativas — nunca no meio de uma (as rodadas de ferramenta de uma tentativa ficam todas no mesmo modelo).

O que aconteceu com o modelo	O que a etapa faz
A cota do provedor acabou (cota diária, de plano ou de faturamento)	vai na hora ao seguinte da lista; o modelo fica marcado como esgotado neste servidor por 60 minutos (ou pelo tempo que o provedor indicar), e as próximas etapas já começam pelo seguinte
Limite de taxa (429), provedor fora do ar (5xx), demora (408) ou rede	vai ao seguinte se ele tiver vaga agora; senão espera e tenta o mesmo modelo, como antes
O provedor diz que o modelo não existe mais	vai ao seguinte se ele tiver vaga agora
Sem vaga neste servidor antes de chamar	vai na hora ao seguinte, sem gastar tentativa e sem cobrança; se todos estiverem sem vaga, espera
Requisição recusada (400, 401, 403, 422), impedimento, resposta vazia, bloqueio de segurança	não troca: o seguinte falharia igual

• A troca gasta uma tentativa do teto da etapa. Com o teto padrão de 2 tentativas, a etapa troca de modelo uma vez.
• Agente com modelo específico não troca. Ele só segue o substituto de um modelo aposentado; a cota esgotada continua sendo falha final.
• Ferramentas externas podem rodar de novo. As variáveis que a tentativa que falhou ia gravar são descartadas, mas uma chamada HTTP, um processo iniciado ou um cartão criado por ela acontecem de novo na tentativa seguinte, como em qualquer retentativa.
• Onde ver. No detalhe da etapa na instância aparece o Modelo usado e, quando foi o seguinte da classe, um aviso com o nome do primeiro modelo e o motivo da troca (sem preço). A linha em Com erro de uma tentativa que falhou nomeia o modelo que falhou e o que responde a seguir.
• A marca de cota esgotada vale por servidor: numa instalação com vários servidores, cada um descobre sozinho na primeira chamada que falhar.

Modelos de raciocínio do Gemini

Modelos Gemini aceitam um orçamento de raciocínio (thinking budget) por modelo, no cadastro do catálogo:

Valor	O que acontece
vazio	usa o padrão da plataforma (AI_GOOGLE_THINKING_BUDGET, hoje 0)
-1	o campo não é enviado e o modelo decide — é o que a família pro exige
0	raciocínio desligado, que é como os modelos flash já rodam
> 0	teto explícito de tokens de raciocínio

O campo existe porque 0 é um valor válido para o flash e inválido para o pro: registrado com o padrão da plataforma, um gemini-pro-latest responde 400 em toda chamada. Deixe -1 nesses modelos e não mexa nos demais — o padrão continua sendo o que os modelos flash já recebiam.

Por isso o cadastro recusa um modelo Gemini da família pro (gemini-2.5-pro, gemini-pro-latest, gemini-3.1-pro-preview…) com o orçamento vazio ou 0: a tela mostra a mensagem, que começa por thinkingBudget: e diz os dois valores aceitos — -1 ou um orçamento positivo, como 2048. "Vazio" é lido como o padrão da instalação: se ele não for 0, o vazio é aceito. A recusa vale para a criação e para a edição; modelos já cadastrados não são alterados, e um modelo antigo nessa situação ainda pode ser editado (desativado, renomeado) enquanto o provedor, o modelo e o orçamento ficarem como estão.

Raciocínio desligado em agente que grava no processo

No formulário do agente aparece um aviso quando o modelo escolhido está com raciocínio desligado (orçamento 0, explícito ou herdado do padrão) e o agente tem uma ferramenta que grava no processo — setProcessVariablesTool ou routeProcessDecisionTool. Sem raciocínio, uma conta de vários passos é feita "de cabeça": num teste com o gemini-2.5-flash, o valor gravado errou em cinco de cinco execuções, sem sinal nenhum. O aviso não muda nada sozinho — escolha um modelo com -1 ou orçamento positivo para esse tipo de agente. Num agente ligado a uma classe de modelo, o aviso olha o primeiro modelo que a classe chama hoje.

Raciocínio é token cobrado

Tokens de raciocínio entram no consumo do tenant como qualquer outro, cobrados como saída — vale também para o Gemini, cujos thoughts a plataforma soma à saída na cota e no custo. Um orçamento alto aparece na Governança de IA como custo maior por chamada.

O editor de agente avisa do ciclo de vida

Ao escolher o modelo do agente, um modelo depreciado mostra a data em que o provedor vai encerrá-lo, e um modelo aposentado some da lista. Um agente que ainda aponta para um modelo aposentado mostra quem responde no lugar — ou, sem substituto, que a etapa falha e a publicação é recusada até outro modelo ser escolhido.

Configurando o Agente

Agentes pertencem a um processo. Não há tela global de agentes: você os cadastra dentro da definição, em Catálogo de Processos → o processo → aba Agentes de IA. Isso é estrutural, não apenas organização de menu — todo agente carrega a chave do processo a que serve, e é o que permite um processo ter vários agentes, cada um com seu prompt de sistema, seu modelo e sua temperatura.

No formulário:

• Nome do Agente e Descrição — a descrição é opcional e serve a quem for manter o processo.
• Classe de modelo ou Modelo específico — a classe segue a ordem montada em Classes de modelo, e a lista mostra os modelos dela na ordem; o modelo específico é escolhido do catálogo descrito acima. Alternar entre as duas opções enquanto edita não perde a escolha: voltar para Modelo específico traz de volta o modelo que estava marcado. Se a classe gravada no agente foi apagada, o campo aparece vazio e o formulário pede uma classe ou um modelo antes de salvar.
• Temperatura (0 a 2.0) — grau de liberdade das respostas. Para processo, 0.0 ou 0.1, porque o que se quer é a mesma entrada produzindo a mesma saída.
• Ferramentas de IA (System Tools) — ler anexo, pesquisar na base de conhecimento, consultar coleção do CMS, e assim por diante. Esta lista é o padrão das etapas que não declaram a sua: cada etapa do processo pode escolher as próprias ferramentas, e é lá que a decisão costuma ser tomada — veja O que é do agente e o que é da etapa.
• System Prompt — quem o agente é e as regras que ele aplica. Ex.: "Você é analista sênior financeiro, sempre rejeite propostas em finais de semana."

Uma etapa aponta para o agente pelo campo aiAgentId da Service Task, então etapas diferentes do mesmo processo — ou do mesmo caso — podem usar agentes diferentes.

Integração RAG (Bases de Conhecimento)

A Inteligência Artificial torna-se mais poderosa quando aliada ao RAG (Retrieval-Augmented Generation). No Flow.IA, isso é gerenciado através do módulo de Knowledge Bases (Bases de Conhecimento):

1. Gestão de Bases: Acesse Desenho de processos → Bases de Conhecimento na barra lateral. Você pode criar bases globais (disponíveis para toda a plataforma) ou específicas por Tenant.
2. Vinculação aos Processos: O conteúdo da Base de Conhecimento (Regras, Normativas, Guias) não é misturado de forma cega. Ao desenhar um processo (Workflow), você acessa a aba RAG e explicitamente "linka" quais Bases de Conhecimento aquele processo tem permissão e relevância para usar.
3. Injeção de Regras (System Prompt): No momento em que uma etapa de IA for disparada num processo ou num caso, a engine buscará as descrições das Bases de Conhecimento vinculadas a ele e injetará as regras no System Prompt automaticamente. O vínculo do processo diz quais bases estão ao alcance; cada etapa pode reduzir esse conjunto — veja Bases desta etapa.
4. Documentos (Vector Search): Os arquivos internos em anexo à base (Manuais PDF, planilhas) são varridos, transformados em Embeddings via pgvector, e o contexto semântico mais similar à dúvida atual da tarefa é passado como contexto extra. Ele nunca treina o modelo público.

Busca na base de conhecimento: modo, trechos e piso

No editor do agente, a seção Busca na base de conhecimento decide como a busca roda — na busca automática da etapa e na ferramenta de busca, que usa a mesma configuração e o mesmo escopo da etapa (o modelo não consegue alargar a busca):

Campo	Valores	Padrão
Modo de busca	Vetorial (significado parecido) ou Híbrida (palavra-chave + vetorial: também casa códigos como 8471.30.12 e art. 37-A literalmente)	Híbrida num agente novo; um agente que já existia continua no que tinha
Trechos por busca (topK)	1 a 20; o editor mostra o contexto aproximado (topK × 800 tokens por chamada)	3
Similaridade mínima	vazio (sem piso) ou de 0 a 1; corta só o lado vetorial	vazio

O número de trechos é a alavanca de custo: cada trecho a mais entra nos tokens de entrada de toda chamada da etapa. O modo híbrido em si não custa token — a busca por palavra-chave não chama modelo.

Para escolher entre vetorial e híbrida com número, escreva perguntas de referência na base e compare os dois modos — ver Bases de Conhecimento → Medindo a busca.

A busca devolve poucos trechos, não a base inteira

Cada consulta ao acervo retorna o número de trechos configurado (três, por padrão), independentemente de quantas bases estejam ao alcance da etapa e de quantos documentos elas tenham. Não há cota por base: as vagas ficam com os trechos mais parecidos com a pergunta, venham de onde vierem.

Isso muda o que esperar ao carregar mais conteúdo. Carregar mais não aumenta quanto contexto chega ao modelo — aumenta a chance de os trechos escolhidos serem os certos. Uma pergunta que precisa de três assuntos diferentes não os obtém de uma vez; o agente tem de consultar uma vez por assunto, e só faz isso se o System Prompt mandar.

Duas instruções que valem para qualquer agente que leia uma base grande: uma pergunta por assunto, porque três perguntas estreitas rendem nove trechos pertinentes onde uma pergunta ampla rende três genéricos; e o termo que distingue dentro da pergunta, porque a busca é por semelhança de texto e não filtra por metadado.

Acesso à base de conhecimento

No modal do agente, Acesso à base de conhecimento diz até que nível de documento classificado (Público, Secreto, Ultrassecreto) o agente lê da base — tanto no contexto automático da etapa quanto pela ferramenta de busca. O padrão é Público. É um campo separado do nível de sigilo do CMS: um agente configurado para ler coleções secretas não passa a ler documentos secretos da base.

• Você só escolhe níveis que você mesmo alcança, e só altera um agente cujo acesso você alcança (Modelador → Público, Gerente → Secreto, Administrador → Ultrassecreto).
• Quando a busca encontra um trecho acima do nível do agente, a ferramenta responde que houve negação, com a quantidade e o nível, nunca o nome do documento. O agente deve informar falta de permissão em vez de concluir que a informação não existe.
• O nível limita o que chega ao modelo, não o que o agente escreve no caso: o que ele resumir de um documento Secreto pode ser visto por quem trabalha a próxima tarefa.
• Um Modelador não cria nem edita agente Secreto, mas pode ligar um agente Secreto já existente a uma etapa do processo que desenha — e então a etapa lê material Secreto e pode gravá-lo em variáveis que o Modelador vê ao testar. Se isso não for aceitável, mantenha agentes Secretos fora dos processos que Modeladores editam.

Como classificar os documentos: Quem pode ler cada documento.

Como utilizar no Workflow

Após o seu Agente estar configurado (ex: "Agente de Auditoria"), seus arquitetos de processo (usuários SUPER_ADMIN) já podem utilizar esse agente desenhando uma Tarefa de Execução Automática (Service Task) e escolhendo ✨ Agente de IA na implementação. Isso vale nos dois motores: num processo BPMN e, agora, também dentro de um caso CMMN.

O Delegate cuidará de compilar automaticamente as variáveis dinâmicas do formulário preenchido por humanos anteriormente na linha do tempo, concatenar com as regras das Knowledge Bases vinculadas ao processo, e enviá-lo ao Agente Cognitivo com o Prompt do Tenant em tempo real.

Num caso, o agente escreve uma variável — quem decide é o modelo

Um caso não tem setas. A etapa de IA de um caso não abre a etapa seguinte: ela grava a variável de retorno, e quem decide o que abre é a condição de entrada (sentry) que lê essa variável. É o que mantém o motivo de uma tarefa ter aberto visível no desenho, em vez de escondido dentro de uma chamada que ninguém revisa depois.

Uma condição que lê a resposta da IA precisa tolerar a ausência dela

A variável de retorno não existe até o agente terminar, e o motor avalia a condição antes disso. Escrever ${documentosConformes == 'false'} derruba o caso com Unknown property used in expression. A forma que funciona usa a função de variável do Flowable: ${var:equals(documentosConformes, 'false')}.

Vale para toda condição alimentada por IA, sem exceção — não é otimização, é a única forma que roda.

Antes de existir a etapa de IA no caso, a única saída era o caso chamar um sub-processo BPMN de uma etapa só (Process Task). Isso continua valendo e não foi descontinuado: é a forma certa quando a parte de IA é um fluxo inteiro, e não uma chamada.

Os campos da Service Task

A tarefa carrega oito campos, declarados no modelador — os mesmos nos dois motores:

Campo	O que é
aiAgentId	Qual agente executa a tarefa
aiInstruction	O que ele deve fazer nesta etapa
aiResultVariable	Em qual variável a resposta é gravada (padrão: aiResponse)
aiTools	Quais ferramentas esta etapa oferece ao agente
aiKnowledgeBases	Quais bases de conhecimento esta etapa deixa ao alcance
aiRagTopK	Quantos trechos a busca desta etapa recupera (1 a 20; vazio herda do agente)
aiRagSearchMode	VECTOR ou HYBRID nesta etapa (vazio herda do agente)
aiWritableVariables	Quais variáveis a etapa pode gravar, com tipo e obrigatoriedade
aiPatternTask	De qual tarefa humana a etapa consulta os padrões aprendidos
aiPatternFields	Quais campos dessa tarefa a etapa consulta

Esses campos são lidos só do modelo. Uma variável de processo com o mesmo nome — vinda de um formulário, da API ou gravada por outro agente — não muda a etapa. E há variáveis que nenhum agente grava pela ferramenta Gravar Variáveis (setProcessVariablesTool): aiDecision e aiDecisionJustification (só a ferramenta de decisão), escalateToHuman, escalationReason e escalationUrgency (só a de escalar para humano), os campos de configuração da etapa, a variável de resultado da própria etapa, tenantId e tudo que começa com _ ou ai_ (como a trilha de auditoria ai_audit_trail). Se o agente tentar gravar uma delas, nada daquela chamada é gravado e ele recebe a lista do que foi recusado e por quê. A mesma ferramenta também não grava um valor que seja um identificador interno (UUID), como o id de um anexo, e o agente só enxerga os anexos da própria instância — um id citado num documento não abre o arquivo de outro processo.

Além dessas recusas, que valem para todo processo, a etapa declara o que pode gravar em aiWritableVariables: aí a ferramenta grava só as variáveis declaradas, no tipo declarado, e cada gravação fica registrada com a etapa, o agente e o trecho do documento de onde o valor saiu. Veja O que a etapa grava.

O agente pode consultar o que o processo já decidiu

Entre as ferramentas disponíveis há a Consulta de Padrões Aprendidos (consultarPadroesTool). Habilitada numa etapa, ela deixa o agente perguntar o que este processo historicamente decidiu na tarefa humana que a etapa prepara — e a resposta vem com a frequência exata, já para as condições deste caso: "Tipo de documento: NFS-e em 692 de 692 casos comparáveis, quando Tipo = NFSE". Qual tarefa e quais campos ela consulta é a etapa que declara, não o agente — veja Padrões que a etapa consulta.

A plataforma avisa o agente de que a etapa tem padrões, mas não os injeta: quem decide se vale consultar é ele. Isso é proposital — empurrar o valor majoritário para dentro do prompt enviesaria o agente justamente nos casos em que o documento é a exceção, que numa auditoria são os que importam.

Quando houver exposição suficiente, a resposta traz também quantas vezes as pessoas aceitaram aquela sugestão — a mesma informação da tabela Saúde do aprendizado, com o mesmo limiar. É o que permite ao agente descontar um padrão frequente que os usuários vêm recusando.

A ferramenta é somente leitura e respeita as mesmas exclusões do aprendizado: campo pessoal e campo na lista de exclusão do processo não aparecem, mesmo se o agente pedir pelo nome. Ela também tem teto: cinco consultas por execução da etapa e no máximo dez padrões por resposta — passado o teto, a ferramenta recusa em vez de continuar respondendo, para que um agente em laço não vire custo.

Os três primeiros bastam para uma tarefa funcionar. Os demais são o escopo da etapa, tratado em O que é do agente e o que é da etapa — ferramentas e bases deixadas em branco herdam o padrão; uma etapa que grava variáveis precisa declarar quais.

Cada campo pode ser escrito de duas formas, e a escolha muda o resultado:

• Texto (string) — o valor vai para o agente exatamente como está escrito. Use quando a instrução não depende de nada que aconteceu antes no processo.
• Expressão (expression) — o valor é calculado no momento da execução. É assim que a instrução recebe dados que só existem durante a instância: Analise a nota ${execution.getVariable('arquivoNota')}.

Se a instrução precisa citar algo preenchido em uma etapa anterior, ela tem de ser expressão. Escrita como texto, o agente receberia o ${...} literal e responderia sobre um marcador — a chamada é cobrada, a resposta chega, e ela não é sobre o seu documento.

Os cinco campos também podem vir de variáveis do processo de mesmo nome. Uma variável tem precedência sobre o que está desenhado, e vale para a instância inteira — se o processo tem duas tarefas de IA, as duas passam a usar a mesma instrução, e o mesmo vale para o escopo de ferramentas e bases. Serve para um caso pontual; não serve como desenho. Num caso a regra é a mesma: o que muda entre os dois motores é onde o campo está escrito, nunca como ele é lido.

Não marque a etapa do agente como assíncrona

Deixe Executar em segundo plano desmarcado, nos dois motores.

A caixa não compra nada: desde 2026-09-09 (processos) e 2026-09-10 (casos), a etapa de IA já sai sozinha da fila de execução assim que começa. Ela reserva o trabalho, devolve a vez, e a plataforma a retoma quando o modelo responde — quem disparou o processo não fica esperando o provedor, e nenhuma conexão de banco fica presa nesse intervalo.

Marcar a caixa só acrescenta um item de fila a mais por etapa, para mover uma espera que já não está ali. Num processo, ainda por cima, ela empurra a etapa para a mesma fila curta que atende timers e retomadas — que é justamente o que essa mudança existe para desocupar.

Processo publicado antes dessa versão continua no comportamento antigo, chamando o provedor na hora e fazendo quem disparou esperar. Para movê-lo: abra a tarefa no modelador, escolha ✨ Agente de IA de novo no campo de implementação e republique. Num caso não há nada a fazer — a mudança vale para todos assim que a versão sobe.

Quando o agente não responde

Se o modelo devolver uma resposta vazia, a tarefa falha e a instância vai para o status Com erro. Ela não segue adiante com a variável de resultado em branco.

Isso é deliberado. Se o valor vazio fosse gravado e o processo seguisse, a tarefa humana seguinte abriria com o campo em branco e não haveria como distinguir "o agente analisou e não encontrou nada a apontar" de "o agente não respondeu". Num processo que audita documento fiscal, o defeito chegaria ao revisor com cara de resultado.

Falhando, a instância aparece na lista de instâncias com erro, com a mensagem dizendo qual variável ficou sem resposta e o que o provedor de IA informou como motivo de encerramento — que é o que permite diferenciar bloqueio de conteúdo, estouro de cota e resposta genuinamente vazia.

Há um caso em que a resposta vazia nem chega a virar resposta: o provedor devolve a chamada sem nenhum candidato, e a conversão falha antes. A mensagem diz exatamente isso, nomeando provedor e modelo. É o mesmo defeito de resposta vazia visto do outro lado — não indica catálogo desatualizado nem exige reiniciar a aplicação.

Um administrador de infraestrutura pode inverter esse comportamento com a variável de ambiente AI_FAIL_ON_EMPTY_RESPONSE=false, e aí a variável de resultado fica em branco em vez de a tarefa falhar. O padrão é falhar.

Quantas vezes a etapa insiste com o provedor

Nem toda falha merece uma segunda chamada, porque a segunda chamada é cobrada igual à primeira. A plataforma separa as duas metades da etapa:

• Antes da resposta — o provedor não devolveu nada. Repetir significa chamar o modelo de novo e pagar de novo. É aqui que vale o limite de tentativas da etapa, que é 2 quando a etapa não diz outra coisa.
• Depois da resposta — o modelo respondeu e a falha foi ao gravar o resultado. A resposta já está guardada como variável do processo, então terminar a etapa não custa nada e não tem limite: a plataforma repete só a conclusão, sem tocar no provedor.

Dentro da metade paga, o limite só é gasto com falhas que podem dar certo da próxima vez:

Falha do provedor	Tenta de novo
Tempo esgotado	sim
Erro do provedor (5xx)	sim
Conexão perdida / rede	sim
401 / 403 — credencial recusada	não
Cota estourada no provedor	não
Conteúdo recusado	não
Requisição malformada	não

Uma falha da coluna não encerra a etapa na primeira tentativa mesmo com limite sobrando, e o motivo — com o código que o provedor devolveu — chega à lista de instâncias Com erro. Insistir ali seria pagar de novo para falhar igual.

O limite é da etapa, não do processo. Duas etapas de IA no mesmo processo não merecem o mesmo número: uma classificação curta contra modelo barato pode insistir, uma geração longa contra modelo caro talvez não deva insistir nenhuma vez. Como o valor mora no desenho do processo, mudá-lo exige republicar — é uma decisão de projeto, não um botão de plantão.

Onde se configura. No modelador, selecione a Tarefa de Execução Automática que usa ✨ Agente de IA e procure o campo Tentativas com o provedor, logo abaixo da Return Variable, no mesmo bloco onde você escolhe o agente e escreve a instrução. Deixar em branco é o normal: a etapa usa o padrão de 2. Digite um número só quando esta etapa merecer tratamento diferente, e republique o processo para o novo valor valer — instância que já está rodando continua com o limite com que nasceu.

Num caso o campo é o mesmo. No modelador CMMN, selecione a tarefa que usa ✨ Agente de IA e o campo Tentativas com o provedor está no mesmo lugar, logo abaixo da Variável de retorno, com a mesma faixa e o mesmo padrão. O que muda é o que acontece quando o limite acaba: num processo a etapa vira item de fila morta, com botão de reprocessar; num caso o plan item continua ativo e a falha aparece no detalhe do caso e na lista Com erro — o caso segue aberto e ninguém precisa reabri-lo. Ali, Tentar de novo executa a etapa outra vez (é uma chamada nova, contada no consumo) e Dispensar tira a falha da lista.

O campo aceita de 1 a 10. 1 significa uma chamada e nenhuma insistência — é o que você escreve numa geração longa contra um modelo caro. Se você digitar um número fora dessa faixa, a tela o traz de volta para o mais próximo permitido assim que você sai do campo, e texto que não é número simplesmente some, deixando a etapa no padrão. O que ficar escrito ali é o que vai rodar.

O teto de 10 é da instalação e vale para todas as etapas: mesmo que um XML publicado à mão peça mais, a plataforma nunca chama o provedor mais de dez vezes numa etapa.

Lendo anexos do processo

Quando o agente tem a ferramenta de leitura de anexos habilitada, ele consegue ler o arquivo da instância mesmo sem saber o identificador dele. Se o processo tem um único anexo, a ferramenta lê esse arquivo e informa ao agente qual foi. Se tem vários, devolve a lista de nomes para o agente escolher — ela nunca adivinha por ele.

Imagem e PDF vão anexados à mensagem; o resto o agente lê pela ferramenta. Modelos aceitam imagem e PDF diretamente, e é assim que esses dois chegam. Qualquer outro formato — XML, JSON, CSV, texto — não é enviado como arquivo: a mensagem informa o nome e o identificador, e o agente usa a ferramenta para ler o conteúdo. Escreva o System Prompt contando com isso, porque um agente instruído a não chamar a ferramenta simplesmente não vê o documento.

Formatos de texto chegam como estão, com a estrutura preservada. XML e JSON não passam por extração de texto — se passassem, os nomes dos campos e os atributos desapareceriam e o agente receberia uma coluna de valores sem saber o que cada um é. PDF, DOCX e imagem continuam passando pelo extrator, que é para o que ele serve.

O documento tem teto de 100.000 caracteres, configurável em AI_ATTACHMENT_MAX_CHARS. Acima disso a ferramenta corta e avisa no próprio texto devolvido, dizendo quantos caracteres o documento tem e quantos chegaram. Instrua o agente a repetir esse aviso na resposta: análise de documento parcial é análise parcial, e quem lê o resultado precisa saber a diferença.

Quando uma ferramenta falha, a tarefa falha

Uma ferramenta pode responder duas coisas muito diferentes, e a plataforma trata cada uma de um jeito.

Respostas vão para o agente como texto, porque ele consegue agir sobre elas: a coleção não existe, nenhum registro casou com o filtro, o processo não tem anexo, o processo tem vários anexos e aqui está a lista, o filtro enviado está mal formado.

Falhas não vão. Se a ferramenta não conseguiu executar — banco fora, armazenamento indisponível, extração quebrada — a tarefa de IA falha, o resultado não é gravado em variável nenhuma, e a instância aparece na lista de instâncias Com erro, com a causa. A chamada já enviada ao provedor entra no relatório de consumo como chamada com zero tokens: o gasto existiu e não pôde ser medido, e é assim que a Governança de IA o registra.

A diferença importa porque o agente não tem como distinguir uma ferramenta quebrada de um resultado vazio. Entregando a falha como texto, ele escreve algo plausível — "o documento não chegou" — e esse texto vira o resultado da etapa, é lido pela etapa seguinte e chega a um humano com a mesma aparência de qualquer tarefa bem-sucedida. Uma auditoria fluente sobre nada é pior que uma tarefa com erro, porque a tarefa com erro alguém conserta.

A regra é de quem é o problema, não de gravidade: filtro mal escrito é erro do agente e volta para ele corrigir; banco fora é problema da plataforma e para o processo.

Quando o insumo não chegou: três opções, e como escolher

A ferramenta quebrada é um caso. O outro, muito mais comum, é o insumo não ter chegado: a nota fiscal que ninguém anexou, a competência que a etapa anterior não preencheu. Se ninguém verificar, o agente responde honestamente "o arquivo não foi recebido", essa frase é gravada como se fosse a transcrição, e a etapa seguinte audita a frase. O revisor abre uma tarefa idêntica a todas as que deram certo.

Existem três formas de impedir isso, e elas não competem — cobrem coisas diferentes.

Opção	O que ela pega	O que custa
Gateway antes da etapa	a variável está vazia, e existe um caminho de negócio para isso	editar o diagrama; nada mais
Listener de variáveis obrigatórias	a variável está vazia ou aponta para anexo inexistente, e isso é erro de modelagem	uma linha no painel de listeners da etapa
Ferramenta de impedimento	o arquivo chegou e é inutilizável — ilegível, do tipo errado, contraditório	conceder a ferramenta ao agente; opcionalmente uma borda de erro

Use o gateway quando faltar documento é normal e alguém resolve. Um gateway exclusivo antes da etapa de IA, com a condição ${empty arquivoNota}, roteia para uma tarefa humana que pede o arquivo. A verificação fica visível no desenho — qualquer pessoa que abrir o processo vê que o caso foi considerado.

Use o listener quando a variável deveria estar sempre lá. No painel de listeners da etapa, adicione um listener de execução no evento start, do tipo Expression, com:

${requiredVariables.check(execution, 'arquivoNota,competencia')}

Ele interrompe a atividade antes de qualquer chamada ao modelo — ou seja, não gasta token nenhum — quando qualquer uma das variáveis está ausente, em branco, ou é um identificador de anexo que não existe mais. Esse último caso é o que mais engana: a variável está preenchida, com um UUID de aparência perfeita, e o arquivo por trás dele é que sumiu.

O listener não é uma capacidade de IA. Ele funciona igual numa tarefa de robô, numa chamada HTTP ou numa decisão DMN — é uma extensão comum de BPMN, e é por isso que ele existe em vez de um campo próprio na etapa de IA.

Ele para a instância em vez de roteá-la: a ausência aqui significa que o processo foi modelado ou integrado errado, e não há caminho sensato para "a etapa anterior não produziu o que prometeu". Se existe caminho, o instrumento certo é o gateway.

Use a ferramenta de impedimento para o que só o modelo julga. O arquivo está lá e está ilegível; é uma nota de serviço onde se esperava uma de produto; dois anexos se contradizem. Nenhum gateway e nenhum listener enxergam isso, porque os dois só sabem se a variável existe.

Ligue Permitir que este agente interrompa o processo com um impedimento no cadastro do agente. Ela nasce desligada: um agente que nunca deve poder abortar um processo simplesmente não recebe a ferramenta, como toda outra capacidade.

O interruptor do agente é o padrão, não um teto. Como qualquer ferramenta, uma etapa que declara a própria lista em Ferramentas desta etapa pode incluir o impedimento mesmo com o interruptor desligado — e uma etapa que declara a própria lista sem ele tira o impedimento de um agente que o tem. Quem responde por isso é quem edita o diagrama.

Com ela concedida, o agente encerra a etapa informando um código curto e estável (DOCUMENTO_AUSENTE, DOCUMENTO_ILEGIVEL, TIPO_NAO_SUPORTADO) e uma frase de motivo. Então:

• a variável de resultado não é escrita — nenhuma prosa entra no lugar do dado;
• o processo recebe um erro de negócio com aquele código. Anexe uma borda de erro à Service Task com esse mesmo código e roteie para uma tarefa humana, uma compensação ou uma notificação;
• o registro da falha guarda o código no lugar do nome de uma exceção. Ele não aparece na tela de Governança de IA, que só mostra cota e consumo: hoje quem quiser a taxa de cada código lê a lista de falhas de IA pela API (GET /a/ai-task-failures, com ?open=true para só as que estão em aberto) ou pergunta pelo copiloto de execução;
• sem borda de erro, a instância para com a causa nomeada. Não é obrigatório tratar todo código.

Três consequências valem ser ditas em voz alta.

Com borda de erro, o motor não retenta o impedimento. Erro de negócio é sinal de fluxo, não falha: repetir a análise de um documento ausente três vezes não muda o resultado e cobra três vezes. Falha transitória — provedor fora do ar, ferramenta quebrada — continua sendo falha comum, que o motor retenta.

Sem borda de erro e com a etapa assíncrona, o motor retenta — e cobra de novo

Essa é a combinação a evitar. Sem ninguém para capturar o código, o motor trata o impedimento como falha qualquer; se a etapa estiver marcada como Executar em segundo plano, ele retenta até a fila morta, e cada tentativa é uma chamada nova ao provedor. O atalho que evita pagar duas vezes pela mesma etapa depende da variável de resultado estar preenchida — e o impedimento é justamente o caso em que ela não está.

Duas defesas, e a primeira já é a recomendação geral desta página: deixe Executar em segundo plano desmarcado; e, para cada código que o agente pode emitir, tenha uma borda de erro ou aceite que a instância pare ali.

O impedimento consome cota. O modelo foi chamado, leu o documento e concluiu que não dá: o token foi queimado no fornecedor e aparece no relatório de consumo do tenant, mesmo com a etapa terminando em erro. O que a cota mede é gasto no provedor, não resultado aproveitado.

Num caso (CMMN) o impedimento não roteia. A etapa de IA de um caso registra o mesmo código e também não escreve a variável de resultado — a condição de entrada que dependia dela não abre —, mas não existe borda de erro em CMMN: para o motor, aquilo é uma falha como outra qualquer, com a retentativa e a recobrança descritas acima. Enquanto isso não mudar, o impedimento com desvio desenhado é recurso de processo BPMN.

Um agente por domínio

Nada obriga um processo a usar um único agente. O agente é um campo da Service Task (aiAgentId), lido a cada execução — cada etapa do fluxo pode apontar para um agente diferente, com prompt de sistema, modelo e temperatura próprios. Um processo que usa o mesmo agente do começo ao fim faz isso porque foi desenhado assim, não porque a plataforma exija.

A diferença aparece quando se mede o prompt. Um agente que serve todas as etapas precisa cobrir todas elas, e o prompt dele cresce por soma: a disciplina comum, mais o vocabulário de cada domínio, mais o catálogo do que está disponível para consulta.

Separe esse texto por assunto e o padrão aparece. A parte que serve a qualquer etapa — quem o agente é, como raciocina, o que conta como resultado — costuma ser a menor. O resto está preso a um domínio ou a um acervo, e num fluxo com trilhas separadas a instância percorre só uma delas: o vocabulário da outra atravessa todas as chamadas sem nunca ser usado.

E esse texto não é enviado uma vez. Ele vai junto em cada chamada do processo — se a instância faz quatro chamadas, ele viaja quatro vezes, byte por byte idêntico.

O agrupamento é por domínio, não por etapa

A reação imediata a esse número costuma ser descer o texto específico para a instrução de cada etapa (aiInstruction) e deixar o agente magro. Não se sustenta: o bloco de NF-e serve às três etapas de NF-e, e descê-lo significa escrever o mesmo texto em três lugares. Na primeira alteração de alíquota alguém atualiza dois e esquece o terceiro — e as três etapas passam a auditar com regras diferentes, sem que nada na plataforma acuse a divergência, porque para ela são três textos livres sem relação entre si.

O corte que se mantém é por domínio: um agente "Auditor NF-e" e um agente "Auditor NFS-e", cada um com a disciplina comum mais o seu bloco tributário, e cada Service Task apontando para o agente da sua trilha. O texto de ICMS continua existindo em um lugar só, e a etapa de NFS-e deixa de recebê-lo. Os agentes são cadastrados por processo e convivem no mesmo processo: criar o segundo é o mesmo trabalho de criar o primeiro, e a escolha de qual roda é feita etapa a etapa.

O que vai no prompt do agente e o que vai na instrução da etapa

A divisão é essa: o prompt do agente guarda o que é comum ao domínio — vocabulário, hierarquia de normas, como consultar a base, o que a base não cobre, em que grau de certeza afirmar algo. A instrução da etapa guarda o que é específico daquela atividade — o que analisar agora, em que formato responder, o que a etapa seguinte espera receber.

Instrução de etapa que repete regra de domínio é duplicação esperando divergir. Prompt de agente que descreve uma atividade específica vai junto em todas as outras etapas do domínio, ocupando espaço e concorrendo com a instrução que de fato vale naquela chamada.

Ferramentas e bases de conhecimento seguem a mesma divisão, só que por campo em vez de por texto: as duas são declaradas na etapa, e é sobre elas o restante desta seção.

Ferramenta disponível é ferramenta usada

Quem decide chamar uma ferramenta é o modelo, chamada a chamada. O desenho não controla se ela vai ser usada; controla apenas se ela existe naquela chamada — e é isso que transforma a lista de ferramentas numa decisão de custo, não só de qualidade.

O caso típico é uma etapa de consolidação: ela recebe em variáveis tudo o que as etapas anteriores produziram e só precisa juntar. Se a leitura de anexo continuar disponível, parte das execuções vai reler o documento inteiro — o modelo tem duas fontes para o mesmo dado e não há por que preferir uma. A chamada que relê custa múltiplas vezes a que não relê, e a diferença não foi decidida por ninguém.

Pedir na instrução para não reler ajuda, mas continua sendo um pedido. Deixar a ferramenta fora da etapa é o que torna a releitura impossível.

A base disponível também é usada

Vale o mesmo para o acervo, e ali o preço não é token.

Uma etapa que consolida pareceres com a legislação ao alcance pode levantar um achado que nenhuma etapa anterior levantou — e fundamentá-lo, porque tem a norma à mão. O resultado tem aparência de rigor: cita artigo, conclui, fecha. Só que a etapa não foi desenhada para auditar; foi desenhada para juntar o que já havia sido auditado.

As duas coisas são a mesma mecânica: o modelo se serve do que está ao alcance, e o alcance é decidido antes de a chamada sair. Por isso o escopo da etapa é imposto, e não pedido — a plataforma monta a chamada com as ferramentas e as bases que a etapa declarou, e o que ficou de fora não está lá para ser usado.

O que é do agente e o que é da etapa

O agente é quem ele é: o papel que desempenha, a disciplina com que raciocina, o modelo que roda e a temperatura. A etapa é o que ela faz: a ação daquela atividade, as ferramentas de que ela precisa e as bases que ela consulta.

A distinção é prática. Enquanto ferramentas e bases moravam no agente, o prompt do agente tinha de antecipar todas as ações possíveis de todas as etapas que fossem usá-lo, e a única forma de tirar uma ferramenta de uma etapa era criar um agente inteiro para isso — um agente que existia por um motivo que nada tem a ver com o papel que ele desempenha.

Ferramentas desta etapa (aiTools)

No modelador, selecione a Service Task (ou o listener), escolha o agente e use Ferramentas desta etapa.

A lista do agente é o padrão, não um teto: a etapa que não declara nada roda com as ferramentas do agente, e a etapa que declara vale pela sua própria lista. O seletor mostra as ferramentas do agente como escolha imediata, mas a etapa não está limitada a elas: qualquer ferramenta válida da plataforma pode ser declarada. Quem desenha o processo sabe o que a etapa precisa para funcionar, e quem edita um diagrama já é administrador do tenant — separar essas duas decisões separaria o que é da mesma pessoa.

No caso do parecer final, basta deixar a leitura de anexo fora daquela etapa. A releitura fica impossível, em vez de apenas desaconselhada.

O que a etapa não decide é alcance de dado sigiloso. O nível de sigilo do CMS continua sendo do agente (veja Tabelas grandes e consulta pelo agente de IA), e isso é de propósito: ferramenta é ação, sigilo é alcance. Se um dia existir um papel de modelador que não seja administrador, quem desenha o diagrama continuará sem poder dar ao agente acesso a conteúdo confidencial que ele próprio não pode ler.

Nome de ferramenta que não existe na plataforma é recusado antes de a chamada sair, com a mensagem dizendo qual nome não resolveu. Uma ferramenta quebrada que está no padrão do agente mas que a etapa não usa não derruba a etapa — só a etapa que a pede é recusada.

Durante a execução, o modelo só consegue chamar as ferramentas que esta etapa oferece. Se pedir outra, a chamada não roda, mesmo que a ferramenta exista na plataforma. Isso vale também para um pedido plantado no texto de um documento ou de um campo de formulário. O modelo recebe a resposta de que a ferramenta não existe, junto com os nomes que pode usar.

Quando a etapa oferece a leitura de variáveis (getProcessVariablesTool), o que volta ao modelo é a mesma visão protegida que a tela mostra, peça ele uma lista de nomes ou tudo: segredo configurado e campo de senha de formulário chegam como ********, e as variáveis da plataforma — aiDecision, escalateToHuman, a configuração da etapa (aiInstruction, aiTools…), tenantId e qualquer nome começado por _ ou ai_, como a trilha ai_audit_trail — simplesmente não aparecem. Um pedido plantado num documento para "ler a senha" recebe a máscara, não o valor.

Bases desta etapa (aiKnowledgeBases)

Mesma sintaxe, alcance diferente: a etapa escolhe entre as bases que o processo vincula. Nada declarado herda todas as bases do processo; uma lista deixa exatamente as listadas; none deixa a etapa sem nenhuma — nem as descrições injetadas no System Prompt, nem os trechos recuperados dessas bases pela busca vetorial.

Base declarada que o processo não vincula é recusada, não ignorada, e a mensagem de erro lista as bases que o processo alcança. Ignorar em silêncio faria a etapa rodar com menos contexto do que quem desenhou pediu, e o resultado sairia com aparência de resultado normal.

Busca nas bases desta etapa (aiRagTopK, aiRagSearchMode)

A etapa pode trocar o número de trechos e o modo de busca do agente — por exemplo, deixar o agente em Vetorial, 3 e ligar Híbrida, 8 só na etapa que confere códigos NCM. Vazio herda do agente. Um valor fora da faixa (aiRagTopK fora de 1 a 20, modo diferente de VECTOR/HYBRID) é recusado na publicação, não cortado: cortar em silêncio faria a etapa rodar com outro contexto do que quem desenhou pediu. A linha de log Escopo da etapa registra o que a busca usou (busca=HYBRID topK=8 piso=nenhum).

O que a etapa grava (aiWritableVariables)

Uma etapa cujo agente usa Gravar Variáveis (setProcessVariablesTool) declara, em Variáveis que a etapa grava, cada variável que ela pode gravar: o nome, o tipo e se é obrigatória. Use o mesmo nome e o mesmo tipo do campo do formulário que vai ler a variável — o botão Adicionar campo de formulário traz os dois prontos.

O que muda com a declaração:

• Só o declarado é gravado. Uma chave fora da lista é recusada, e a recusa diz ao agente quais ele pode gravar. Como antes, uma recusa impede a chamada inteira.
• O tipo é conferido. Moeda e número chegam como número (1074.00, não R$ 1.074,00), data como 2026-10-18, sim ou não como true/false, e uma seleção só aceita uma opção dos formulários do processo. O valor gravado tem o mesmo tipo que o formulário gravaria.
• Obrigatória é obrigatória. Se a etapa termina sem gravar uma variável obrigatória, ela falha com a causa nomeada ("a etapa terminou sem gravar valorReembolsavel") e aparece em Com erro. Ela não volta ao provedor sozinha: repetir a chamada cobraria de novo para falhar igual. O agente é avisado de que, sem o valor, deve registrar o impedimento.
• Cada gravação deixa rastro. A etapa, o agente, o momento e o trecho do documento que o agente informou ficam registrados; a tarefa seguinte mostra o campo como Preenchido pela IA (veja Tarefas). Uma recusa entra na trilha de auditoria da instância com a chave e o motivo, nunca com o valor.

Quatro recusas na mesma execução e a ferramenta manda o agente parar de tentar. Esta etapa não grava variável (none) recusa qualquer gravação. Não é possível declarar aiDecision, escalateToHuman, campos de configuração da etapa nem variáveis ai_* — a publicação recusa.

Uma versão publicada antes desta regra continua rodando como estava, gravando o que o agente mandar (fora as chaves reservadas), com a gravação registrada e um aviso no log. Ao republicar, a declaração passa a ser exigida — veja Publicação.

Tudo isto vale igual para o agente num listener de execução: as ferramentas, as variáveis que ele grava e os padrões que consulta são os declarados no próprio listener, nunca os da tarefa em que ele está pendurado. Até 19/10/2026 o listener rodava ignorando essas declarações — gravava qualquer variável não reservada e oferecia todas as ferramentas do agente; não é preciso republicar para a correção valer.

Padrões que a etapa consulta (aiPatternTask e aiPatternFields)

Quando a etapa oferece Consulta de Padrões Aprendidos, ela declara em Padrões que a etapa consulta a tarefa humana cujos padrões o agente lê — normalmente a próxima tarefa humana do fluxo, que o painel oferece em Usar a próxima tarefa humana — e os campos dessa tarefa que o agente decide. O seletor mostra só campos que o aprendizado minera. Trocar a tarefa, ou voltar para — nenhuma —, limpa os campos escolhidos: eles eram do formulário da tarefa anterior, e ficariam escondidos travando a publicação.

Com isso, a ferramenta deixa de aceitar a etapa e o campo que o agente escolher: ela responde para a tarefa declarada, só para os campos declarados, com o padrão que vale para as condições deste caso, e diz quando o valor que o caso já tem diverge do padrão. Um caso que caiu no grupo de controle do aprendizado não recebe padrão — a resposta pede para decidir pelo conteúdo do caso. E o que a ferramenta mostrou conta como sugestão vista na tarefa que nasce depois, para o aprendizado não contar o próprio eco como decisão humana.

Uma etapa que habilita a ferramenta sem declarar os campos ainda funciona, por uma versão, no formato antigo — e a publicação avisa.

O marcador none

Vale para os campos de escopo e significa a mesma coisa em todos: nenhuma nesta etapa. Ele existe porque campo vazio e campo ausente chegam iguais à engine, e não configurado precisa ser distinguível de configurado para nada.

O marcador aceita maiúscula e espaço em volta (NONE, none), e é recusado quando vem junto de um item real — none, searchKnowledgeBaseTool não diz se a etapa quis tudo ou nada, e adivinhar seria escolher por quem desenhou.

No painel de propriedades os dois campos aparecem assim que um agente está selecionado: um seletor múltiplo e, abaixo dele, uma caixa Nenhuma ferramenta nesta etapa / Nenhuma base nesta etapa, separada da seleção vazia justamente para que a diferença apareça na tela.

Contexto injetado e ferramenta não são a mesma coisa

São dois jeitos de o agente alcançar informação, e eles erram de formas diferentes.

Contexto injetado é material que entra no prompt antes de o modelo pensar: as descrições das bases vinculadas, os trechos recuperados pela busca vetorial, o documento anexado. O modelo se serve dele à vontade, e nada no texto separa "isto é referência" de "isto é o caso em análise". Num lote medido, um parecer citou o município de uma tabela de referência como se fosse o município da nota: o dado estava no prompt, era plausível, e o modelo o usou.

Ferramenta é pergunta e resposta. O modelo pergunta, recebe o que perguntou, e o que volta chega identificado como resposta de uma consulta. Custa uma ida a mais e traz menos texto de volta.

Para o desenho, a consequência é prática: material grande de referência — tabelas de códigos, cadastros, listas de alíquotas — fica mais seguro atrás de uma ferramenta do que injetado ao lado do documento. E quanto mais o material injetado se parecer com o documento em análise (mesmos campos, mesmos formatos, mesmos números), maior a chance de um virar o outro na resposta.

Casos de referência

Um caso de referência é uma entrada conhecida com a resposta certa: a instrução da etapa, as variáveis que ela viu, os anexos que ela leu e as checagens que dizem se uma resposta está correta. Eles existem para que trocar o modelo, a classe ou o prompt de um agente deixe de ser palpite: guardar e conferir um caso não chama modelo nenhum nem gasta cota, e a comparação entre modelos roda esses casos nos modelos que você escolher.

Onde ficam. Ao editar um agente existente (em Definições → processo → Agentes de IA, ou no template global para o Super Admin), o diálogo ganha a aba Casos de referência: a lista, com a origem de cada caso (etapa ou manual), e o editor. Cada agente guarda até 50 casos. Quem mantém os casos é quem desenha o processo — ADMIN e MODELER do tenant; os casos de um agente global são só do Super Admin. Apagar o agente apaga os casos dele.

Salvar a partir de uma etapa. Na tela da instância, selecione uma etapa de IA concluída e clique em Salvar como caso de referência. O caso vai para o agente daquela etapa com:

• a instrução da etapa, com os marcadores de variável preservados;
• as variáveis do processo como estavam quando a etapa começou — segredos e campos de senha nunca são copiados, nem mascarados: simplesmente ficam de fora, assim como a trilha de auditoria da IA;
• os ids dos anexos que a instância já tinha quando a etapa começou — nunca o conteúdo; arquivo enviado depois fica de fora, porque o modelo não o leu;
• a resposta que essa etapa deixou como resultado esperado: se ela for um JSON, uma checagem por campo; se for texto, uma checagem de igualdade. Revise as checagens depois, na aba do agente.

Se a variável de resultado mudou depois da etapa — outra etapa de IA gravou na mesma variável (como aiResponse) ou alguém a editou — e o histórico não guarda o valor que a etapa deixou, o botão recusa com essa explicação em vez de salvar a resposta errada. Nesse caso, crie o caso à mão na aba do agente.

Uma etapa que escolhe o agente por expressão (${...}) não pode ser salva, porque o agente só é conhecido na execução. Etapas de caso (CMMN) ainda não oferecem o botão.

Quais anexos um caso aceita. Só anexo de instância de processo de uma instância que você enxerga — ADMIN e MANAGER enxergam todas; MODELER só as que iniciou ou em que teve tarefa. Documento de base de conhecimento, anexo apagado ou arquivo de uma instância alheia são recusados ao salvar, porque o modelo leria o arquivo na comparação e a resposta ficaria visível para quem abre o resultado. A conferência se repete quando a comparação roda, para quem a pediu: um anexo apagado depois, ou de uma instância que essa pessoa deixou de enxergar, fica de fora daquele caso, sem derrubar a rodada. Caso de agente global não leva anexo — instância é sempre de uma empresa, e o arquivo de uma empresa não vai para a camada que todas usam.

As checagens. O caso passa quando todas passam.

Checagem	Passa quando
Igual (exato)	a resposta, sem espaços nas pontas, é igual ao esperado — maiúsculas contam
Contém	a resposta contém o trecho, ignorando acento, maiúscula e espaços repetidos
Número	o primeiro número da resposta está dentro da tolerância do esperado (padrão 0). Lê 1.074,00 e 1,074.00
Campo JSON	a resposta é JSON, o ponteiro (ex.: /itens/0/valor) chega no campo, e ele bate como igual ou como número. Se o campo é um número JSON, o esperado é lido como número JSON: 1.234 contra {"taxa": 1.234} passa — a leitura de milhar do pt-BR (1.234 → 1234) só vale para texto

Avaliar modelos com casos de referência

Na aba Casos de referência, o botão Comparar modelos roda os casos do agente em até cinco modelos do catálogo e mostra, lado a lado, quantos cada um acertou. Use antes de trocar o modelo de um agente: a resposta deixa de ser "parece melhor" e vira "acertou 18 de 20 casos, com metade dos tokens".

Como rodar.

1. Clique em Comparar modelos, marque os modelos (o tenant vê só o nome, nunca o preço) e os casos — todos vêm marcados. Cada par caso × modelo é uma chamada; o limite é 100 pares.

2. Clique em Estimar. A tela mostra quantas chamadas ao provedor esperar, quantos tokens — pela média das últimas execuções do próprio agente — e quanto sobra da cota de IA do tenant. Se o agente ainda não rodou, a estimativa de tokens diz que não sabe em vez de inventar. Enquanto a estimativa é calculada, a escolha de modelos e casos fica travada: o que você confirma é exatamente o que foi estimado. Mudou a escolha depois? A estimativa some e é preciso estimar de novo.

3. Confira e clique em Confirmar e rodar. A avaliação entra numa fila própria, com duas execuções ao mesmo tempo na instalação inteira, e a lista Avaliações de modelo acompanha o andamento.

   Se o servidor reiniciar no meio, a avaliação que estava na fila ou rodando não fica "rodando" para sempre: na subida seguinte, a que está parada há mais de uma hora sem gravar resultado aparece como Falhou, com o motivo interrompida por reinício. Os pares que já tinham rodado continuam visíveis; rode a avaliação de novo para ter o resultado completo.

O que a avaliação não faz. Ela não abre instância nenhuma, não dispara webhook nem e-mail e não grava variável de processo: cada caso roda numa etapa em memória, com o mesmo prompt, as mesmas bases de conhecimento, a mesma busca RAG e a mesma checagem de ferramentas da etapa real, e a instrução montada com as variáveis do caso. O modelo lê só os anexos guardados no caso. Cada par roda uma vez, sem retentativa — um erro do provedor vira um resultado Erro e a avaliação segue. Um agente com ferramenta que age fora da etapa — chamada HTTP, webhook, notificação, subprocesso, atribuição de tarefa — é recusado, e a mensagem nomeia as ferramentas: avaliá-lo chamaria essas ferramentas de verdade. Para comparar modelos nesse caso, avalie uma cópia do agente sem elas.

Cota. A avaliação é um gasto opcional e por isso respeita a cota: a cada chamada a cota do tenant (e a individual de quem pediu) é conferida. Se a cota acabar no meio, os pares restantes ficam como Não rodou, a avaliação termina Parcial, e o que já foi gasto continua contado. Sem cota configurada, ou com a cota já esgotada, a avaliação é recusada ao confirmar, com a explicação, em vez de rodar sem que nenhum par aconteça. Para os agentes de um template global, a cota consultada é a da camada global (__global__), que não é criada sozinha: o Super Admin precisa configurá-la antes da primeira avaliação. Na fila do modelo, a avaliação espera como uma etapa de processo — nunca passa na frente da produção — e usa o mesmo limite de chamadas do modelo que a produção, porque o limite é do provedor. Como cada servidor roda no máximo duas avaliações ao mesmo tempo, elas ocupam no máximo dois lugares da fila de cada modelo por servidor. O consumo aparece em Governança de IA como MODEL_EVALUATION, com o nome do caso no lugar da etapa.

O resultado. Em Ver resultado, cada modelo é uma coluna com: acerto (casos que passaram em todas as checagens), média de tokens de entrada e de saída, chamadas ao provedor por caso, latência mediana (p50) e máxima, falhas e pares que não rodaram. Abaixo, uma grade caso × modelo com Passou, Falhou, Erro ou Não rodou; clique numa célula para ver, checagem a checagem, o esperado e o obtido, e a resposta inteira do modelo. O Super Admin vê também uma linha de Custo por modelo. Cada agente guarda as 20 avaliações mais recentes.

Se um modelo escolhido foi aposentado depois que você pediu a avaliação, quem responde é o substituto, e a coluna mostra os dois nomes (Antigo → Novo). Se o substituto também estava entre os escolhidos, ele não roda duas vezes: a coluna do modelo aposentado repete o resultado do substituto, sem gastar token de novo.

Quem roda é quem mantém os casos: ADMIN e MODELER do tenant; para os agentes de um template global, o Super Admin, que gasta a cota da plataforma.

Autoaprendizado

O autoaprendizado é configurado por processo, não por agente: um processo com vários agentes tem uma só configuração, válida para todos eles, e o formulário do agente não tem campo de aprendizado nenhum. A aba fica em Desenho de processos → Catálogo de Processos, e está documentada em Catálogo de Processos → Autoaprendizado.

Os padrões que essa contagem produz alimentam dois lugares, com o mesmo número nos dois: o preenchimento automático do formulário e o copiloto de execução, que responde sobre o que costuma ser preenchido em uma etapa citando "em 641 de 645 casos comparáveis". Desligar o autoaprendizado de um processo tira os dois: o copiloto continua respondendo sobre o processo e a instância, mas passa a dizer que não tem histórico daquele campo — nunca a estimar um. O que o copiloto recebe está descrito em Tarefas → O que o copiloto sabe sobre a tarefa aberta.