Agentes de IA Autônomos (RAG)

Nível de acesso requerido

Admin ou Super Admin

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.

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 Global (Super Admin) → 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, a plataforma recusa a exclusão e a desativação, dizendo quantos agentes dependem 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.

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.

Raciocínio é token cobrado

Tokens de raciocínio entram no consumo do tenant como qualquer outro. Um orçamento alto aparece na Governança de IA como custo maior por chamada.

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.
• Modelo de IA — escolhido do catálogo descrito acima.
• 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 Conteúdo → 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.

A busca devolve três trechos, não a base inteira

Cada consulta ao acervo vetorial retorna três trechos, independentemente de quantas bases estejam ao alcance da etapa e de quantos documentos elas tenham. Não há cota por base: as três 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 três trechos 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.

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 cinco 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

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 ali — e a resposta vem com a frequência exata: "tipoDocumento = NFS-e em 692 de 692 casos, quando tipoDoc=NFSE".

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 dois últimos são o escopo da etapa, tratado em O que é do agente e o que é da etapa — deixados em branco, a etapa herda o padrão.

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 só na lista Com erro — o caso segue aberto e ninguém precisa reabri-lo.

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) 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.

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.

O marcador none

Vale para os dois campos e significa a mesma coisa nos dois: 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.

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 Modelagem → 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.