Como o agente melhora com o uso, sempre com aprovação

A nota que andava sozinha

A nota de confiabilidade de um agente nosso foi de 4,18 para 4,37 entre duas avaliações seguidas. Ninguém tinha mexido em nada. Mesmo agente, mesma configuração, nenhuma conversa nova relevante no intervalo.

Fui olhar a causa. A cada rodada, o sistema sorteava 8 das 18 conversas do período e mandava o juiz avaliar. Conversas diferentes davam nota diferente. E cada rodada pagava de novo para julgar o que já tinha sido julgado: em oito rodadas, 94% do custo da avaliação era rejulgamento.

Esse é o problema de quase todo projeto de “agente que aprende”. Antes de falar em melhoria contínua, você precisa de uma medida que não se mexa quando o mundo não se mexe. Sem isso, qualquer “melhorou” ou “piorou” é sorteio.

Este artigo conta como montei o ciclo de melhoria dos agentes da OrganIA: o que observa, o que propõe, quem decide e como a decisão volta com prova. E conta também o que quebrou no caminho, porque foi isso que definiu o desenho.

A tese: o sistema propõe, o dono aprova, o resultado volta medido

Agente que “evolui sozinho” troca um problema por outro. O comportamento muda e ninguém sabe por quê. Numa empresa, isso é pior do que um agente que não aprende nada, porque o dono perde a capacidade de explicar o que a ferramenta dele faz.

A regra que adotei cabe numa frase:

O sistema acha e propõe. O dono decide. O que foi aprovado volta com prova.

Na prática, o ciclo tem seis etapas, e três delas moram numa caixa só, que chamamos de Evoluir:

 OBSERVAR ──> ACHAR ──> PROPOR ──> PROVAR ──> DECIDIR ──> MEDIR
 juiz das     18         cartão     bateria    o dono      placar em
 conversas    detectores com        de testes  clica       14 a 30 dias
 + sinais     + garimpo  impacto    por tipo   aplicar ou  piorou: proposta
 do rastro    de lições  escrito    de tarefa  recusar     de reverter
              └──────────── caixa Evoluir ─────────┘

Quatro regras seguram esse ciclo, e cada uma tem um mecanismo no código que a faz valer:

Regra	O que garante	Como se cumpre
O sistema propõe, nunca aplica	Nenhuma mudança de comportamento entra sem o clique do dono	O curador só grava propostas. Quem escreve na skill é um caminho único, que exige a proposta pendente e o clique
Uma conversa é julgada uma vez	A mesma conversa dá sempre a mesma nota e não se paga duas vezes pelo mesmo julgamento	O veredito fica guardado com a marca do tamanho da conversa. Só volta ao juiz o que cresceu ou nunca foi visto
A caixa é fila de trabalho	O Evoluir mostra só o que pede ação	Detector só abre cartão de defeito, nunca de escolha deliberada. Cartão descartado vira lápide e não volta
Nada aprovado fica sem prova	Toda aprovação diz o que espera e volta com o resultado	Ao aplicar, a linha de base é gravada. O veredito é calculado depois de 14 dias

A linha que não se cruza: nada que muda o comportamento do agente acontece sem clique. O que roda sozinho só observa, organiza ou desfaz o que já deixou de valer.

Observar: um juiz que julga uma vez

A avaliação lê as conversas de um período e dá três notas, de 1 a 5. Uso LLM-as-judge com temperatura 0, e o modelo de avaliação é escolhido pela empresa, com troca possível por agente.

Nota	O que mede	Como calcula
Experiência	A resposta foi relevante, completa, correta e no tom certo?	Um exame por conversa. Pesos: 0,30 exatidão, 0,25 relevância, 0,25 completude, 0,20 tom
Confiabilidade	As ferramentas funcionaram? O agente andou em círculos?	Sucesso das ferramentas (0,45) + saúde do raciocínio: loops, becos sem saída, estouro de passos (0,40) + juízes de trajetória quando ligados (0,15)
Segurança	Houve vazamento de dado pessoal, viés, ofensa, tentativa de burlar o agente?	Seis verificações por conversa. Tentativa que o agente resistiu não desconta

Repare que a confiabilidade é quase toda contagem. Ferramenta que falhou e loop não precisam de modelo para serem vistos. Uso o juiz onde não há outra forma de medir, e só ali.

Depois do caso dos 4,18 e 4,37, três regras mudaram a avaliação:

Julgar uma vez por unidade que não muda mais. Uma execução encerrada, ou uma conversa até a mensagem N. Rejulgar fato congelado não traz informação nova, só traz número diferente. O teste de aceite foi exatamente esse: duas avaliações seguidas sem mudança precisam dar nota idêntica. Deram, e a segunda custou zero.

Versionar o juiz. Quando o critério muda, sobe a versão, e o que ainda está na janela é rejulgado uma única vez. Hoje o juiz de segurança está na versão 4.

Declarar a cobertura. Toda nota sai com “X de Y conversas examinadas · N sem material”. “Nenhum alerta” e “ninguém olhou” não podem ter a mesma cara na tela. No primeiro dia, essa linha mostrou que conversas de uma única troca nunca tinham passado pela análise de segurança: 4 de 11 conversas reais, 36%. Justamente o caso em que repetir um dado pessoal é mais provável.

Fora da avaliação, cada execução é marcada ao terminar com os sinais de problema que deixou: ferramenta que falhou, repetição com os mesmos argumentos, freio da plataforma, ação sem efeito, resposta descartada. Cada sinal aponta o passo exato. O mesmo problema em duas conversas vira cartão no Evoluir.

Achar: 18 detectores sem modelo

O Evoluir abre e roda 18 funções de regra fixa. Nenhuma chama modelo. A razão é dupla: custo zero por proposta e nenhum número inventado. Uma sugestão de melhoria que cita um ganho estimado que não se sustenta destrói a confiança em todas as outras.

Alguns exemplos, com os limiares que estão no código:

Família	Detecta	Limiar
Otimização	Ferramenta que não foi usada	≥ 2 ferramentas ociosas
Skill	Skill da empresa parada	90 dias
Conhecimento	Base sem consulta, ou com respostas fracas	0 consultas em 30 dias, ou ≥ 10 consultas com nota média < 0,35
Alertas	Regra que dispara e ninguém olha	≥ 10 em 7 dias com ≥ 80% ignorados
Qualidade	Queda da nota em uma dimensão	≥ 8 conversas em cada janela de 30 dias; queda ≥ 0,7 moderada, ≥ 1,2 grave
Contexto	Janela do modelo quase cheia	≥ 80% da janela
Problema recorrente	O mesmo sinal do rastro em várias conversas	≥ 2 conversas; entrega parcial já na 1ª

Cada cartão mostra o impacto em linguagem de negócio antes do clique (“esta ferramenta atualiza o painel X”) e os bloqueios. Com bloqueio, o botão fica desligado e diz qual dependência. No clique, o sistema confere de novo se o mundo mudou desde a proposta. Se mudou, recusa sem tocar em nada.

Dois estados que muita gente confunde ficaram separados de propósito. Resolvida é verificada: o sistema mediu de novo e a condição sumiu do banco. Descartada é decisão do dono, e vira lápide permanente: o detector vê a marca e não sugere o mesmo de novo, mesmo que a condição continue verdadeira. Se o dono recusou sabendo da condição, insistir é ruído. E caixa que repete o que você já recusou é caixa que você aprende a ignorar.

Uma medição que mudou um detector: enquanto achados de segurança no estado “atenção” também viravam cartão, 3 de 4 cartões eram escolhas deliberadas do dono, como deixar o agente navegar em qualquer site. Hoje só entra o grave.

Aprender: a correção vira skill

Este é o pedaço que chamamos de Live Skills no código e de Aprendizado na tela. A pergunta que ele responde: quando alguém corrige o agente no chat, como essa correção deixa de valer só para aquela conversa?

Passo 1, o garimpo, sem modelo. Quando a caixa abre, uma consulta no banco monta a lista de conversas candidatas dos últimos 30 dias. Cada conversa soma pontos:

Sinal	Peso
O juiz viu uma lição	4,0
Alguém recusou uma ação do agente e escreveu o motivo	3,0 (até 3 vezes)
Nota de Experiência ≤ 3,5	2,0
Correção na fala (“não é isso”, “na verdade”, “errado”)	1,0 (até 4 vezes)

Para entrar na lista, a conversa precisa de um sinal que ensina. Nota baixa sozinha não basta: diz que foi mal e não diz o que fazer. Isso foi medido. A única conversa com lição real tirou 4,80; três sem lição tiraram entre 2,5 e 3,5. Se eu usasse nota baixa como porta, o garimpo traria exatamente as conversas erradas.

Passo 2, o curador, sob clique. O dono clica em “Aprender com esta”. Só então um modelo lê a conversa, as skills do agente, o que o juiz apontou, quantas vezes o mesmo tipo de tarefa apareceu em 90 dias e as sugestões que o dono já recusou, com o motivo. Ele responde: ajustar uma skill, criar uma nova ou nada.

Passo 3, regras fixas depois do modelo. O modelo propõe; o código filtra. Skill protegida não é tocada. Skill da plataforma não é alterada (cria-se uma calibração da empresa por cima). Skill nova parecida com uma existente vira ajuste da existente, porque duas skills sobre o mesmo assunto competem na hora de carregar. Skill nova de verdade só com recorrência: o mesmo tipo de tarefa em 1, 2 ou 3 conversas, conforme o perfil escolhido. Resumo com mais de 420 caracteres é descartado, nunca cortado. Regra cortada no meio é ordem incompleta.

Passo 4, aplicar. Um caminho único faz tudo na ordem: confere que a skill não mudou desde a proposta, guarda a versão anterior, escreve, arquiva as memórias que repetiam a mesma regra, grava a linha de base do placar e atualiza as instruções do agente.

Esse arquivamento de memórias tem motivo. Memória é o que o agente sabe; skill é como ele trabalha. “O prazo para casos críticos é 4 horas” é memória. “Sempre que listar chamados, mostre o código como link” é skill. Antes dessa régua, a mesma lição entrou em cinco lugares em três horas. Duas ordens divergentes no mesmo pedido fazem o comportamento virar sorteio, e é isso que o usuário descreve como “às vezes ele faz certo, às vezes não”.

O Aprendizado vem desligado por empresa. E tem um portão medido para um dia rodar sem clique: só quando 60% ou mais das sugestões forem aprovadas, depois de pelo menos 10 sugestões reais. Ainda não chegamos lá, e está tudo bem.

O placar: a prova depois

No clique de aplicar, o sistema grava o que vai comparar: o tipo de tarefa afetado e a nota média desse tipo nos 30 dias anteriores. Depois de 14 dias, fecha o veredito com os números do banco.

Veredito	Quando
Melhorou	A nota do tipo de tarefa subiu 0,3 ou mais
Estável	Ficou entre −0,5 e +0,3
Piorou	Caiu 0,5 ou mais. Gera uma proposta de reverter, nunca reverte sozinho
Sem evidência	Menos de 5 conversas do tipo, ou sem linha de base
Sem oportunidade	Chegou o prazo de 30 dias e o tipo de tarefa nem apareceu

Duas decisões aqui me custaram discussão. Primeira: amostra pequena fecha como “sem evidência”, nunca como veredito. Prefiro uma tela que admite não saber a uma que inventa tendência com três conversas. Segunda: “nunca usada” não vira “piorou”. Uma lição pode valer só pelo resumo da skill, que o agente lê em toda conversa sem precisar abrir a skill inteira. Uso zero não prova nada.

Para ações que não mudam nota (arquivar, reverter), a tela diz “sem placar” em vez de esconder.

O que deu errado, e o que mudou por causa disso

A primeira lição aprovada não mudou nada. Nove testes verdes cobriam a escrita: proposta nasceu, versão guardada, skill alterada. Nenhum media o efeito. Em produção, o agente continuou fazendo o mesmo, por quatro motivos empilhados. A regra foi só para o corpo da skill, e o agente decide se abre a skill lendo apenas o resumo. O resumo chegava ao modelo dentro de um índice e era lido como rótulo de menu, não como ordem. A tela onde a regra foi pedida não sabia exibir link. E o catálogo de blocos não declarava essa capacidade. Corrigimos os quatro. A regra que ficou: funcionalidade cujo valor é mudar comportamento só é declarada pronta com um teste que peça de novo e confira o comportamento.

O critério que ia bem no teste falhou na produção. No ambiente de teste, 93% das conversas tinham lição. Em produção, 2%. Por isso a régua que separa memória de skill entrou em modo observação: o sistema anota a decisão que tomaria, sem tomar. Mecanismo se valida em teste. Critério de julgamento só se valida com dado que não foi escolhido por quem escreveu o critério.

O motivo da recusa era gravado e ninguém lia. O dono recusava uma sugestão, escrevia por quê, e a mesma lição podia voltar. Hoje as 5 últimas recusas com motivo vão no pedido ao curador.

O juiz de trajetória quase não roda. Na avaliação automática ele vem desligado, porque custa modelo a mais. Consequência: a lista de “conversas que foram mal” se alimenta quase só de dislike. Está registrado como lacuna aberta.

A peça que falta: ensaiar antes de aprovar. Hoje o placar responde se a lição funcionou em 14 a 30 dias e precisa de 5 conversas do tipo. O ideal é saber antes do clique: rodar as perguntas da bateria de testes do mesmo tipo de tarefa com a mudança em memória, nunca no agente vivo, e mostrar “antes × depois” no cartão. A bateria com resposta certa já existe e está testada, ainda não em produção. Ela recalcula a resposta esperada na hora (um “42” escrito no teste fica errado no dia em que o dado muda) e tira do agente as ferramentas que escrevem ou mandam algo para fora: testar não pode mandar e-mail de verdade. O botão de ensaiar no cartão ainda não tem código.

O que mudou no agente e no dono

O efeito mais visível foi na medida. Duas avaliações seguidas sem mudança agora dão a mesma nota, e a segunda custa zero. Antes, 94% do gasto ia para rejulgar.

O segundo efeito foi na confiança do dono. Cada sugestão chega com o impacto escrito e os bloqueios, e cada aprovação volta com um veredito ou com a admissão de que não há evidência. O dono não precisa acreditar no sistema; ele confere.

O terceiro foi na caixa em si. Como resolvida exige medição, descartada é permanente e só defeito vira cartão, o Evoluir continua sendo uma fila de trabalho e não um mural de avisos. Toda funcionalidade nova que gera sugestão é obrigada a entrar nesta caixa. Uma tela paralela de sugestões é proibida, senão o dono precisaria lembrar de conferir cinco lugares.

Como aplicar no seu agente

Se você está montando um agente que precisa melhorar com o uso, esta é a lista que eu seguiria de novo:

Congele a medida antes de tentar melhorar. Julgue cada conversa encerrada uma vez, guarde o veredito e recomponha a nota do período a partir dele. Teste de aceite: duas avaliações sem mudança dão nota idêntica.
Mostre a cobertura junto da nota. “7 de 11 auditadas · 4 sem material” é mais útil que um número limpo.
Versione o juiz. Mudou o critério, sobe a versão e rejulga uma vez. Antes de mexer na régua, confira o que o juiz recebeu.
Use regra fixa onde dá. Ferramenta ociosa, base sem consulta e alerta ignorado são contagens. Guarde o modelo para o que exige leitura.
Uma caixa só para sugestões. Com impacto escrito antes do clique, bloqueio declarado e conferência de corrida no clique.
Separe resolvido de descartado. Resolvido se mede. Descartado se respeita, para sempre.
Lição só entra com sinal que ensina. Correção, recusa com motivo ou lição vista pelo juiz. Nota baixa sozinha não.
Memória e skill em casas diferentes. Ao aprovar a skill, arquive as memórias que repetiam a regra.
Grave a linha de base no clique. Sem linha de base não há placar, e sem placar a aprovação é fé.
Amostra pequena não vira veredito. E piora gera proposta de reverter, nunca reversão automática.
Teste o efeito, não só a escrita. Peça de novo ao agente e confira se o comportamento mudou.

Nada disso exige uma plataforma específica. Exige decidir, antes de escrever código, quem tem a última palavra sobre o comportamento do agente. No nosso caso é o dono, e o sistema trabalha para que ele decida com o número na mão.