Governança de Inteligência Artificial

Nível de acesso requerido

Super Admin

O AI Governance Dashboard (Painel de Governança de IA) é uma ferramenta exclusiva para o Super Administrador da plataforma Flowi Agentic. Seu objetivo principal é fornecer transparência e controle sobre o consumo financeiro da Inteligência Artificial em toda a infraestrutura.

Quem administra apenas um tenant não abre esta tela: mesmo digitando o endereço, é levado de volta ao Dashboard.

Nota

O Flowi Agentic foi projetado em uma arquitetura Single-Client, Multi-Tenant. Isso significa que a organização matriz paga a fatura das APIs de Inteligência Artificial (ex: OpenAI, Google Gemini), e o painel de governança serve para repassar, auditar e controlar os custos de cada departamento ou cliente isolado (Tenants).

O Sistema de Cotas (Quotas)

Para garantir que a fatura da IA não saia do controle, o sistema implementa dois níveis de barreira:

1. Cota do Tenant (Nível 1)

Cada Tenant recebe um limite máximo de tokens mensais (ou por período configurado). Quando esse limite é atingido, o Tenant é imediatamente bloqueado de realizar operações interativas com a IA (como conversas com os agentes ou criação de formulários via IA).

Todo Tenant nasce com cota de 1 milhão de tokens, criada junto com ele. Ajuste o valor em Tenants → (o tenant) → Cota de Tokens de IA.

Tenant sem cota não usa IA — nenhuma

A barreira é a existência da cota, não só o valor dela. Um Tenant sem linha de cota é recusado antes da primeira chamada, com a mesma mensagem de quem estourou o limite. Se um agente responder que não há cota configurada, é isto — e a correção é abrir a tela acima e salvar.

2. Cota de Usuário (Nível 2)

Dentro de um Tenant é possível definir sub-limites para usuários específicos, o que previne que um único colaborador consuma toda a verba mensal destinada ao departamento inteiro. Hoje quem grava esse sub-limite é o Super Admin — a rota que o salva (PUT /api/admin/users/{id}/ai-quota) exige esse papel, e o Admin do tenant não a alcança.

O que conta para o sub-limite de uma pessoa: apenas os copilots das telas. É o gasto que ela escolhe conscientemente — abriu o copiloto, escreveu a pergunta, apertou enviar.

O que uma etapa de IA gasta é do processo, não de quem apertou iniciar. Quem inicia um processo não escolheu o modelo, não escreveu o prompt e não pode reduzir aquela conta; além disso a etapa pode rodar horas depois, retomada por um temporizador, ou ser refeita pela plataforma. Por isso o consumo de etapa entra na cota do Tenant — de onde sai a fatura — e aparece no relatório identificado pelo processo que o gastou, ao lado das pessoas.

Como ler a tabela Consumo por pessoa e por processo

Linhas com nome e e-mail são pessoas, e o que elas gastaram nos copilots. Linhas marcadas como Processo são etapas de IA, somadas por processo. Sem pessoa atribuída sobra apenas para o consumo que não tem nem processo — aquele que chegou ao modelo sem declarar de onde veio, e que é um alerta, não uma categoria normal.

Soft Limits vs Hard Limits

• Hard Limit (Bloqueio Automático): Ações engatilhadas manualmente por humanos (interações no Copilot) são estritamente bloqueadas se a cota acabar.
• Soft Limit (Overage): Ações agendadas ou em andamento executadas de forma invisível pelo sistema (robôs, Java Delegates, ou automações de background) não são interrompidas quando a cota acaba. Isso evita que processos vitais da empresa falhem pela metade. Os tokens gastos além do limite entram no banco como Overage Tokens (Uso Excedente), para posterior acerto de contas.

A validação de BPMN por IA é Hard Limit, e só o administrador do tenant a dispara

O botão de validação semântica do modelador chama o modelo e gasta a cota do tenant como qualquer copiloto. Por isso a rota (POST /a/ai-validation/bpmn) exige Admin do tenant ou Super Admin — gerente e usuário comum recebem 403. Sem cota, a chamada é recusada com 402 e a mensagem nomeia o tenant; ela não volta disfarçada de parecer sobre o diagrama. Se alguém relatar que a validação "não conseguiu concluir a análise", isso é falha do provedor, não cota.

Chamada que não produz resposta também é cobrada

Um agente pode chamar o modelo e receber de volta uma resposta vazia — o provedor recusa, ou termina sem escrever nada. Os tokens de entrada foram cobrados pelo provedor de qualquer forma, porque ele processou o prompt. A plataforma registra essas chamadas e debita a cota do tenant por elas, para que o número do painel não fique abaixo do que o provedor fatura.

Na lista de auditoria isso aparece como consumo sem contrapartida de resultado. Se um tenant tem uso alto e poucos processos concluídos, chamadas estéreis são a primeira coisa a investigar.

Quando a plataforma não consegue contar, o copiloto recusa

Os copilotos respondem em fluxo, e o provedor só informa a contagem de tokens nos últimos pedaços da resposta. Se essa contagem não chegar, a plataforma não entrega a resposta nos copilotos e no playground: sem contar não há como debitar a cota, e um teto que nunca fecha não é um teto. O usuário recebe uma mensagem dizendo exatamente isso, e a chamada é registrada na lista de auditoria com contagem zero e a origem resposta-sem-contagem-de-tokens — o gasto real dela é maior que zero.

Nos processos a decisão é a oposta e pela mesma razão de sempre: a etapa entrega o resultado e a lacuna fica registrada. Parar um processo por causa de um buraco no relatório trocaria um problema de contabilidade por uma parada de produção.

Se esse aviso aparecer com frequência, o provedor configurado em Administração → Modelos de IA é o lugar de olhar primeiro.

O mesmo vale para a etapa que termina em impedimento declarado pelo agente: o modelo leu o documento, concluiu que o trabalho não pode ser feito e encerrou a etapa com um código. A etapa falha, nada é gravado na variável de resultado — e a chamada é contada e debitada como qualquer outra, porque o provedor cobrou por ela. O que a tela não mostra é o código do impedimento: essa lista de falhas é lida hoje pela API, não por aqui.

Chamada interrompida no meio: cobrada pelo provedor, não medida aqui

Há um caso em que a plataforma sabe que gastou e não sabe quanto. Quando uma ferramenta do agente falha no meio da conversa — banco fora, armazenamento indisponível — a chamada é abortada. O prompt já foi enviado e o provedor já cobrou por ele, mas a resposta que carrega a contagem de tokens nunca chega, e não há de onde tirar o número.

Essas chamadas aparecem no relatório com zero tokens e sem produção de saída. O zero não é o consumo real: é a marca de que houve consumo não medido. Preferimos a linha com zero à ausência da linha, porque uma lacuna invisível não se investiga.

O que isso significa para a conciliação

Se a fatura do provedor vier acima do que o painel soma, as chamadas com zero tokens são o primeiro lugar a olhar. Quanto mais falhas de ferramenta um tenant tiver no período, maior a diferença.

Cota recusada é caso diferente e não gera registro nenhum: a verificação acontece antes do envio, então nada foi transmitido e nada foi cobrado.

O desconto de tokens não volta atrás se o processo falhar depois

O desconto na cota acontece em transação própria, separada da transação do processo que disparou a chamada. Na prática: se a tarefa falhar depois que a IA respondeu, os tokens continuam descontados.

É o comportamento correto, e vale explicar por quê. O provedor cobrou no momento em que respondeu — o gasto existiu, independentemente do que aconteceu com o processo em seguida. Se o desconto voltasse atrás junto com a tarefa, o painel mostraria menos consumo do que a fatura, exatamente nos tenants com mais falhas.

Essa separação também é o que permite processar vários documentos ao mesmo tempo: a linha de cota do tenant fica travada apenas pelo instante do desconto. Se ela ficasse travada durante toda a chamada à IA — cerca de vinte segundos —, as demais chamadas do mesmo tenant esperariam em fila, uma de cada vez, por mais threads que houvesse.

Quantas etapas de IA correm ao mesmo tempo

As etapas de IA esperam o provedor numa pool própria, separada da fila de tarefas do motor de processos — enquanto o modelo pensa, a etapa não ocupa vaga de execução nem conexão de banco. Quantas correm ao mesmo tempo é AI_STEP_CORE_SIZE, que vale 8 por padrão.

O teto é por instalação, não por tenant: a mesma pool atende os dois motores, então as vagas são disputadas por todos os tenants, por etapa de processo e etapa de caso juntas. Passando das vagas, as etapas esperam numa fila de 100 (AI_STEP_QUEUE_CAPACITY); passando da fila, a etapa é encerrada como falha e fica disponível para reprocesso, em vez de parar em silêncio.

De onde vem o número de vazão

A conta é etapas simultâneas × 60 ÷ latência da chamada, em segundos. Com as 8 vagas padrão e uma chamada de cerca de 20 s, dá cerca de 24 etapas por minuto na instalação inteira.

É aritmética, não medição da sua instalação. A bancada que produziu os números publicados rodou com o desenho anterior, de 2 vagas, e num teste em que a chamada ao modelo é uma espera artificial de duração fixa: nenhum provedor é contatado, e banco e RAG ficam fora do caminho. Os ~20 s de latência, esses vieram de uma observação real, mas de uma única carga de documentos fiscais, em 2026-08-12.

Use o número como ordem de grandeza para dimensionar, nunca como capacidade contratada: a vazão real depende do modelo, do tamanho do prompt e do que mais estiver rodando na instalação. Antes de prometer um número a alguém, meça com a sua própria carga.

O Dashboard

O teto não é o gasto do tenant

O valor que você configura é o Teto dos Copilots — ele só interrompe as telas assistidas. Os processos continuam rodando depois que o teto é atingido, e o que passa dele entra como Excedente de Processos. Por isso o consumo real de um tenant é usado + excedente, e é esse número que as telas chamam de Consumo Total. Ler o teto como se fosse o total leva à conclusão errada de que processo é de graça.

O painel exibe três métricas globais no topo:

1. Uso Global no Mês (Tokens): soma de tokens de IA no período.
2. Consumo Total (Copilots + Processos): o que a plataforma de fato gastou somando todos os tenants, com o Excedente de Processos logo abaixo, separado.
3. Tenants com Copilots Bloqueados: quantos atingiram o teto — e, na legenda, quantos tenants estão ativos. Bloqueado aqui significa copilots parados, nunca processos parados.

Abaixo vem a lista de auditoria, com uma linha por tenant e três colunas de número: Consumo Total (usado + excedente), Teto dos Copilots e Excedente de Processos.

Redefinição de Cotas

Ações disponíveis:

• Teto dos Copilots (Máximo de Tokens): em Tenants → (o tenant) → Cota de Tokens de IA, aumenta ou diminui o teto das telas assistidas. Não limita processos.
• Force Reset: zera manualmente os contadores do tenant — tokens usados e excedentes voltam a 0 (usado para correções manuais de faturamento ou extensões de cortesia) e o ciclo reinicia.

A mesma leitura vale na tela do usuário (Usuários → (o usuário) → Cota de IA por Tenant): o número configurado ali é o teto dos copilots daquela pessoa, não uma tampa no que os processos podem gastar em nome dela.

Quem está gastando

Abaixo da lista de tenants, no mesmo painel, a tabela Quem está gastando ordena os clientes pelo que consumiram no período, do maior para o menor. É a pergunta que o painel existe para responder: qual cliente cresceu fora da curva.

Cada linha traz quantas pessoas gastaram, chamadas, tokens e custo. Clicar na linha abre o detalhe daquele tenant, onde ficam as pessoas e as etapas — ver Consumo de IA do tenant, abaixo.

Filtro de período

As duas telas filtram por período: atalhos de 7, 30 e 90 dias, mês atual, mês anterior, e um intervalo livre em Personalizado.

A cota não segue o filtro, e isso é proposital

A cota de cada tenant conta o ciclo de faturamento e é zerada na virada do período de reposição. Ela não é uma soma do período que você escolheu no filtro. Ao filtrar sete dias e ver a cota anunciando outro número, os dois estão certos: um diz quanto já foi faturado neste ciclo, o outro quanto foi gasto no período escolhido.

Exportar para Excel

O botão Exportar CSV baixa o que está na tela, para o período filtrado. O arquivo é gerado no servidor e traz o que o banco tem — não apenas as linhas que a página carregou.

O arquivo abre no Excel com duplo clique: é UTF-8 com marca de ordem de byte, para que os acentos apareçam corretamente, e usa ponto e vírgula como separador, que é o que o Excel em português espera. Um campo que contenha ponto e vírgula, aspas ou quebra de linha vem entre aspas.

Consumo de IA do tenant

Dentro de Tenants → (o tenant), a aba Consumo de IA responde a pergunta seguinte: dentro deste cliente, quem e o quê. Ela tem o mesmo filtro de período e duas tabelas, cada uma com seu próprio botão de exportação.

Consumo por pessoa e por processo lista quem gastou naquele tenant, do maior para o menor. Pessoas aparecem com nome e e-mail e respondem pelo que gastaram nos copilots; etapas de IA aparecem somadas pelo processo que as executou.

O gasto do processo nunca é escondido nem colado em alguém

Ele faz parte do total do tenant, e é desse total que sai a fatura. Esconder o consumo automatizado faria o número do cliente ficar menor do que o que o provedor cobrou.

Um id no lugar do nome significa que a pessoa não existe mais no cadastro, ou que quem disparou a chamada não era um usuário da plataforma. A linha é mostrada assim mesmo — gasto que não resolve para um nome continua sendo gasto.

Consumo por etapa do processo é a tabela descrita na seção seguinte, restrita àquele tenant. Ali a coluna Tenant não aparece: dentro da página do cliente, ela seria a mesma em todas as linhas.

Consumo por modelo responde a pergunta que o total sozinho esconde: o cliente custa caro porque usa muito, ou porque usa um modelo caro? São diagnósticos opostos e pedem correções opostas.

Cada linha diz qual modelo cada tarefa usou: processo, etapa, modelo e funcionalidade. Uma mesma etapa aparece duas vezes quando rodou em dois modelos — é assim que uma troca de modelo fica visível, com o antes e o depois lado a lado. O mesmo modelo num copiloto e numa etapa de processo também são linhas separadas: uma pessoa escolheu, a outra roda sozinha.

Por que a etapa aparece na tabela de modelo, e o modelo não aparece na de etapa

As duas tabelas parecem redundantes e não são. A de etapa responde por que esta etapa é cara e carrega Iterações e Contexto, que dividem por execução. A de modelo responde qual modelo esta tarefa usa e carrega apenas somas.

Pôr uma coluna Modelo na tabela de etapa estragaria as duas colunas derivadas: uma execução que atravessa mais de um modelo — um agente que cai para o modelo de reserva depois de uma recusa — seria contada inteira em cada linha, e a média de idas ao modelo sairia inflada nas duas. Somas não têm esse problema, e por isso o caminho inverso funciona.

Um modelo chamado unknown significa chamada que falhou antes de o provedor responder: a plataforma tentou, não soube dizer qual modelo atendeu, e nenhum token foi cobrado. A linha aparece porque a tentativa existiu.

O que o próprio tenant enxerga

O administrador de um tenant tem a sua própria tela: Processos → Consumo de IA. Ela mostra, para o período escolhido, o que aquela operação consumiu — por processo e por pessoa, por etapa e por modelo.

Quem desenha os processos também enxerga, no lugar onde pode agir: a aba Consumo de IA dentro de uma definição mostra o consumo daquele processo, com as colunas que explicam o gasto (iterações, contexto recuperado, desperdício). É para o modelador responder este processo pode gastar menos? — prompt, modelo, ferramentas e base de conhecimento são decisões dele.

O tenant vê tokens, não dinheiro

As telas do tenant mostram consumo em tokens e a cota, nunca valor em moeda. O preço por token é o que a plataforma paga ao provedor; o custo em dinheiro aparece apenas neste painel de governança, para quem paga a fatura. Não é a tela que esconde o número: ele não é enviado ao navegador do cliente.

Consumo por etapa do processo

Esta tabela vive na aba Consumo de IA do tenant. Ela existe porque a contagem de tokens sozinha não diz o que mudar: saber que uma etapa gastou 41 mil tokens não distingue modelo caro de prompt inchado de agente em laço, e as correções são opostas.

Cada linha é uma etapa, ordenada pela mais cara primeiro. A mesma etapa rodando para dois clientes são duas linhas, cada uma na página do seu tenant — nunca uma soma. Etapa aqui é tanto uma tarefa de um processo quanto uma etapa de IA dentro de um caso — a coluna Funcionalidade distingue as duas, AI_DELEGATE para processo e AI_CASE_DELEGATE para caso. Vale reparar nisso antes de procurar a chave da linha no catálogo de processos: numa linha de caso ela é a chave do caso.

Além de chamadas, tokens e custo, três colunas explicam o gasto:

• Iterações — quantas idas ao modelo, em média, uma única execução daquela etapa consumiu. Valor alto significa que o prompt ou a descrição das ferramentas não está levando o modelo aonde ele precisa chegar. Trocar por um modelo mais barato não corrige isso. Uma etapa repetida pelo motor não infla esse número: as retentativas da mesma etapa continuam sendo uma execução só, e o que as separa é o número da tentativa gravado em cada chamada.
• Contexto — quanto do prompt é contexto recuperado da base de conhecimento. Percentual alto aponta o custo para a recuperação, não para o modelo: a correção é buscar menos, ou buscar melhor.
• Desperdício — fração dos tokens gasta em chamadas que não produziram resposta. É o primeiro lugar a olhar, antes de mexer em qualquer prompt.

Linhas que cruzam um limiar de atenção aparecem destacadas com um ícone. As demais ficam neutras de propósito: uma tabela em que toda linha grita não comunica nada.

Quando o custo aparece incompleto

Um ícone de aviso ao lado do custo significa que alguma chamada daquela etapa usou um modelo sem preço cadastrado. O custo mostrado é parcial. Sem esse aviso a etapa pareceria barata justamente por faltar informação, que é o contrário do que o número deveria dizer.

Consumo não atribuído

Se aparecer um aviso de consumo não atribuído, ele significa que chamadas chegaram ao modelo sem declarar de que funcionalidade vieram. Os tokens são reais e foram cobrados; o que faltou foi a marcação de origem, que fica registrada no log da aplicação. É uma falha de instrumentação a reportar, não um erro de cobrança.

Embeddings também aparecem aqui

Os embeddings gerados na ingestão de bases de conhecimento e na busca RAG são medidos e aparecem como um grupo RAG_EMBEDDING na tabela, sem processo nem etapa associados — um embedding não roda dentro de um passo do fluxo. O preço vem da configuração global de embedding, na aba Banco de Vetores (RAG) da tela de Configuração de IA — não do catálogo de modelos de chat: um embedding não tem tokens de saída, então o custo é calculado só sobre os tokens de entrada.