Avaliar e melhorar agentes · ·
Descobrir por que o agente errou
Separe falta de informação, falha de ferramenta e critério de avaliação inadequado.
Este capítulo faz parte do curso gratuito Avaliar e melhorar agentes.
Antes de comprar outro modelo, veja o que faltou na tentativa que falhou. O agente recebeu a informação necessária? Conseguiu usar a ferramenta? A avaliação reconheceria uma resposta correta? Essas perguntas ajudam a escolher uma correção proporcional ao problema.
Ver como texto
Documentação da OpenAI sobre configuração e execução de avaliações, com exemplos de tarefas e resultados.
Você decide aqui, no próximo incidente com código gerado por IA, se o caso é de trocar a ferramenta, de mudar o processo ou de reescrever o incentivo. E decide isso antes de aprovar qualquer compra. Por que a ordem importa: as três causas têm donos, preços e prazos diferentes. Processo se corrige com configuração e política, custa pouco e resolve a maior parte dos casos. Ferramenta se troca com contrato, custa uma migração e uma nova curva de aprendizado. Incentivo se corrige reescrevendo a régua de medição e treinando de novo, e é a mais cara das três. Quem começa perguntando pela ferramenta compra a correção mais cara para o problema mais barato, e repete o incidente com outro fornecedor.
A ambulância que fica parada na porta do pronto-socorro
Um sistema de saúde criou uma meta bem-intencionada: o tempo de espera do paciente começa a contar quando ele entra no pronto-socorro. A meta é razoável, o indicador é fácil de medir e a intenção é boa. O resultado foi ambulância parada na porta com o paciente dentro, esperando para entrar, porque o relógio só começava depois. O indicador melhorou. O atendimento piorou. Ninguém precisou ser mal-intencionado para que isso acontecesse: bastou a medida ser fácil de atingir por um caminho que ninguém tinha pensado em proibir.
Onde a analogia para de valer: no hospital existe um gestor identificável que tomou a decisão de segurar a ambulância, e ele pode ser chamado para responder. No agente, a causa está diluída no treino inteiro e não existe ninguém lá dentro para responsabilizar. A única alavanca é reescrever a régua e treinar de novo, e isso custa dinheiro de verdade. Por isso a triagem que vem a seguir deixa o incentivo por último: é a correção certa em poucos casos e a mais cara em todos eles.
Um registro de execução mostra pedidos, ações, respostas das ferramentas e resultado. Ele permite distinguir um erro de raciocínio de uma dependência indisponível. Sem esse registro, a equipe pode mudar o modelo e conservar exatamente a causa que impediu a entrega.
Ver como texto
Documentação do sistema de permissões do Claude Code, com modos e regras de autorização.
Exemplo: o agente não encontra um pedido porque a conta conectada não tem acesso ao sistema. Reescrever o prompt ou treinar pesos não resolve essa permissão. A correção é liberar a consulta adequada ou informar a limitação. Depois, repita o caso para confirmar que o diagnóstico estava certo.
Ver como texto
Documentação do Promptfoo mostrando verificações determinísticas e métricas avaliadas por modelos.
Ver como texto
As três causas possíveis de um incidente com código gerado por IA, lado a lado: falha de ferramenta, falha de processo e falha de incentivo, cada uma com quem você chama, o que você compra e quanto custa a correção
- Etapa 1 de 3: 1. O agente entregou algo diferente do que foi pedido?
Se o pedido dizia uma coisa e a entrega foi outra, existe falha de ferramenta e o fornecedor tem o que responder. Se o pedido estava vago, ambíguo ou simplesmente errado, e o agente cumpriu o que estava escrito, a ferramenta está inocente e trocar de fornecedor não muda nada. Esta é a pergunta que menos vezes é respondida com sim.
- Etapa 2 de 3: 2. A ação chegou até o fim sem portão, sem isolamento e sem cópia fora do alcance?
Se sim, é falha de processo, e é aqui que mora a maioria dos casos. Portão de confirmação para ação destrutiva, credencial com o escopo mínimo, separação entre teste e produção e cópia de segurança fora do alcance de quem executa. Tudo isso se compra com configuração e política interna, custa pouco e não depende de modelo melhor nenhum.
- Etapa 3 de 3: 3. O que foi premiado no fim do ciclo era o que você queria mesmo?
Se o que rende ao time é fechar o chamado rápido, é isso que o time e o agente vão perseguir, cada um do seu jeito. Falha de incentivo é o caso em que a régua de medição premiou o atalho, e a correção é reescrever a régua e treinar de novo. É rara, é a mais cara das três e é a única que exige orçamento de treino. Deixe por último.
Ver como texto
- 1. O agente entregou algo diferente do que foi pedido?: Se o pedido dizia uma coisa e a entrega foi outra, existe falha de ferramenta e o fornecedor tem o que responder. Se o pedido estava vago, ambíguo ou simplesmente errado, e o agente cumpriu o que estava escrito, a ferramenta está inocente e trocar de fornecedor não muda nada. Esta é a pergunta que menos vezes é respondida com sim.
- 2. A ação chegou até o fim sem portão, sem isolamento e sem cópia fora do alcance?: Se sim, é falha de processo, e é aqui que mora a maioria dos casos. Portão de confirmação para ação destrutiva, credencial com o escopo mínimo, separação entre teste e produção e cópia de segurança fora do alcance de quem executa. Tudo isso se compra com configuração e política interna, custa pouco e não depende de modelo melhor nenhum.
- 3. O que foi premiado no fim do ciclo era o que você queria mesmo?: Se o que rende ao time é fechar o chamado rápido, é isso que o time e o agente vão perseguir, cada um do seu jeito. Falha de incentivo é o caso em que a régua de medição premiou o atalho, e a correção é reescrever a régua e treinar de novo. É rara, é a mais cara das três e é a única que exige orçamento de treino. Deixe por último.
Uma credencial pode permitir uma ação tecnicamente válida e inadequada para a tarefa. Por isso, autorização, ambiente e confirmação precisam ser analisados junto com o pedido. No diagnóstico, registre o que foi solicitado, o que a ferramenta permitia e qual verificação deveria ter reconhecido a falha. Esses dados ajudam a escolher a correção.
No sábado, um agente de código executou uma limpeza de dados que apagou o cadastro de rotas de três clientes. A recuperação levou onze horas e consumiu o fim de semana de quatro pessoas. Apurando, o time descobre que o pedido feito ao agente dizia "remover registros órfãos da tabela de rotas", que a definição de órfão no sistema estava errada havia dois anos, que a credencial usada tinha permissão de escrita em produção porque sempre teve, e que ninguém precisa confirmar operação de remoção em massa. O diretor comercial quer cancelar o contrato da ferramenta hoje.
Qual é a sua recomendação na reunião, e em que ordem?
Triagem do próximo incidente, para abrir na reunião de crise
Pergunta 1: a ferramenta errou? Se sim, você chama o fornecedor
0/3Pergunta 2: o processo deixou passar? Se sim, você compra configuração
0/4Pergunta 3: o incentivo premiou o atalho? Se sim, você reescreve a régua
0/3Classificar o incidente resolve o passado. Para o próximo trimestre, a defesa mais barata é uma rotina de revisão do código gerado, a leitura que um segundo profissional faz da alteração antes de ela entrar, como a conferência de um lançamento contábil. O guia abaixo cabe em qualquer time e custa menos hora sênior do que a revisão feita sem ordem.
Guia prático: revisar o código gerado por IA em cinco passos
Aplique na ordem. Cada passo tira da fila do revisor sênior o que uma máquina ou uma regra resolvem mais barato.
Passo 1: Marque na origem o que a IA escreveu
Toda alteração declara se veio de agente, e o registro da ferramenta serve de prova.
Deu certo quando: A fração gerada por IA aparece no painel sem ninguém estimar de memória.
Erro comum: Aceitar a declaração verbal do autor como dado.
Passo 2: Rode a esteira automática antes de qualquer pessoa ler
Compilação, testes e varredura de segredos (senhas e chaves esquecidas no código) barram o erro barato.
Deu certo quando: O revisor humano só recebe o que passou nas três checagens.
Erro comum: Pedir ao sênior que confira o que uma máquina conferiria de graça.
Passo 3: Leia primeiro o que mudou nos testes
Agente que apaga ou afrouxa um teste para passar deixa rastro no próprio teste.
Deu certo quando: Nenhum teste removido ou enfraquecido sem justificativa escrita.
Erro comum: Revisar só o código novo e ignorar a régua que o julga.
Passo 4: Exija dois revisores nas áreas sensíveis
Pagamento, autenticação, dados de cliente e infraestrutura entram numa lista publicada de pastas protegidas.
Deu certo quando: A ferramenta de código bloqueia a entrada sem o segundo aceite.
Erro comum: Tratar uma linha alterada na autenticação como alteração pequena.
Passo 5: Meça horas de revisão por entrega aceita
É o imposto de verificação em número, coletado toda semana pelo registro da ferramenta.
Deu certo quando: Tendência visível em quatro semanas, para cima ou para baixo.
Erro comum: Medir só o volume entregue.
No fim você tem: Uma rotina de revisão que gasta menos hora sênior por entrega e deixa rastro que a auditoria consegue ler.
Três perguntas para testar a decisão antes da próxima reunião: (1) Um agente do seu time apagou dado de cliente num sábado. Qual é a primeira pergunta que você faz na segunda, e qual é a pergunta que você não faz primeiro de propósito? (2) O fornecedor responde que a interface dele funcionou conforme projetada e que a credencial era sua. Você aceita a resposta, escala ou renegocia, e com base em quê? (3) O diretor comercial quer cancelar o contrato hoje e você discorda. Qual evidência você coloca na mesa em cinco minutos para adiar a decisão sem parecer que está protegendo a ferramenta?
Uma entrega feita com IA exige geração e conferência. O peso de cada etapa varia por tarefa. Ao concluir esta parte, você deve conseguir pedir uma medida do trabalho completo e localizar o responsável por revisar os resultados.
Aplique as três perguntas ao último incidente registrado com código de IA, ainda nesta semana, e escreva a classificação numa linha. Adote o guia de revisão acima como regra do time por trinta dias. No fim do prazo, confira se as horas de revisão por entrega aceita caíram ou ficaram estáveis.
Seu caderno neste capítulo
Abrir o caderno completoSelecione um trecho do capítulo para destacar ou anotar. Nos vídeos e áudios, use Anotar este momento. No teclado, selecione com Shift e as setas e use Alt+Shift+D para destacar ou Alt+Shift+N para anotar.
Salvo neste navegador. Entre na sua conta para levar o caderno a outros aparelhos.
Entre na sua conta para compartilhar o que aprendeu e convidar alguém para estudar com você.
Veja o que estudar antes e para onde seguir depois, explore os conceitos e compare abordagens em outros cursos. Sugestões marcadas como “sugerido pelo grafo” vêm dos assuntos em comum, não do índice do curso.
- CursoSetup Completo: do zero ao Claude Code (Windows)sugerido pelo grafoO Setup ensina permissões, contexto do projeto e escolha de modelo por custo. Essa preparação sustenta os exercícios de comparação de assistentes, criação do gerador de UTM e regras de projeto no curso de aprendizado por reforço e vibecoding.
- CursoAstra profundosugerido pelo grafo4 capítulos de “Avaliar e melhorar agentes” usam conceitos apresentados em “Astra profundo”.
- CursoLetramento em IA para Executivossugerido pelo grafo5 capítulos de “Avaliar e melhorar agentes” usam conceitos apresentados em “Letramento em IA para Executivos”.
- CursoVídeo com IA: do roteiro à publicaçãosugerido pelo grafo2 capítulos de “Avaliar e melhorar agentes” usam conceitos apresentados em “Vídeo com IA: do roteiro à publicação”.
- Modelo de trabalho com agentes de IAQue evidência mostra se a entrega funcionou?Examinar conexões de Que evidência mostra se a entrega funcionou?
- Engenharia de Software para ExecutivosPlanejar uma entrega e acompanhar o prazoExaminar conexões de Planejar uma entrega e acompanhar o prazo
- Letramento em IA para ExecutivosCalcule quanto a IA custa por entrega aprovadaExaminar conexões de Calcule quanto a IA custa por entrega aprovada
- Sistemas e dados para IAPor que os sistemas não mostram a mesma empresa?Examinar conexões de Por que os sistemas não mostram a mesma empresa?
Terminou a leitura?
Você está aqui: capítulo 3 de 27
0 de 27 concluídos
- Próximo · Capítulo 4 de 27 · 15 minSaber quando melhorar a instruçãoLer o capítulo 4 sem concluir
Marque como concluído para o capítulo contar no seu painel e no certificado.
- Anterior · Capítulo 2 de 27 · 15 minEncontrar o custo que a primeira resposta escondeVoltar para o capítulo 2
Leve uma ideia para a prática
Escolha uma atividade no painel e volte a este curso quando quiser.
Atividades e evolução ficam reunidas no painel da sua conta.
- 01Avaliar o trabalho entregue pela IA
- 02Encontrar o custo que a primeira resposta esconde
- 03Descobrir por que o agente errou
- 04Saber quando melhorar a instrução
- 05Medir como o agente trabalha hoje


