Avaliação de Agents (Eval)

Pensa em um professor corrigindo provas: ele já tem as respostas dos alunos (as conversas que o seu Agent já teve) e um gabarito (o que era esperado). O Eval funciona assim — ele pega conversas que o Agent já teve e pontua o quão perto elas ficaram do esperado, segundo critérios que você define.

Dica

Quer disparar o Agent ao vivo (sem depender de uma conversa já registrada), acompanhar o que ele faz em tempo real e salvar o resultado como caso de teste? Veja o Playground ao vivo.

Conceitos

Conceito	O que é
Conjunto de testes (Eval Set)	Uma coleção de casos de teste para um Agent, com os critérios e as notas mínimas que serão usados para aprovar/reprovar cada caso.
Caso de teste (Eval Case)	Um caso de teste individual: uma entrada, opcionalmente a sequência de ações esperada, a resposta final esperada e/ou uma lista de rubricas (afirmações em texto livre, usadas no critério de julgamento por rubrica).
Rodada de avaliação (Eval Run)	Uma execução do conjunto de testes inteiro: pontua uma conversa registrada para cada caso e reúne os resultados num resumo (taxa de aprovação e nota média por critério).
Resultado do caso	O resultado de um caso dentro de uma rodada — aprovado ou reprovado, com as notas de cada critério aplicado.

Um caso de teste pode ser criado de duas formas: promovendo uma conversa real do seu Agent a caso de teste (transformando uma conversa que já aconteceu — boa ou ruim — em um exemplo que passa a ser verificado toda vez que você rodar o conjunto de testes) ou montando o caso na mão, digitando a entrada, a sequência esperada, a resposta esperada e/ou as rubricas diretamente. Veja as duas formas abaixo.

Critérios disponíveis

Critério	O que avalia	Nota mínima padrão
Trajetória de ferramentas	Se as ferramentas chamadas pelo Agent (nome + argumentos) batem com a sequência de ações esperada do caso.	1.0 (todas as chamadas esperadas precisam bater)
Resposta final	Se a resposta final do Agent é equivalente, em significado, à resposta esperada — julgada por um modelo de IA (um "juiz automático").	0.8
Rubrica	Julgamento por IA sem resposta de referência: avalia a resposta final contra as rubricas (afirmações em texto livre) do caso, uma a uma. Nota = fração de rubricas aprovadas.	0.7
Segurança	Binário e sem uso de IA: falha se algum guardrail disparou durante a conversa.	— (0.0/1.0)

Dica

Se um caso não define a resposta final esperada, o critério de resposta final é automaticamente marcado como aprovado (nota 1.0, sinalizado como "não aplicável") — ele simplesmente não se aplica àquele caso. O mesmo vale para o critério de rubrica quando o caso não define rubricas.

O critério de rubrica não compara com uma resposta pronta — ele pede pro juiz automático dizer "SIM"/"NÃO" para cada rubrica (ex.: "a resposta deve citar o prazo em dias úteis") e devolve quais rubricas foram aprovadas e quais foram rejeitadas, cada uma com a justificativa do juiz.

O critério de segurança não usa IA: ele lê os eventos de guardrail acionado da conversa registrada e, se houver qualquer um, marca o caso como reprovado (nota 0.0) com o detalhe de quais guardrails dispararam.

As notas mínimas de cada critério ficam configuradas no conjunto de testes. A coluna da direita do caso (Como este caso é avaliado) mostra os critérios ativos e a nota mínima de cada um.

Dica

O critério de segurança não tem nota mínima configurável — ou nenhum guardrail disparou (passa) ou algum disparou (falha).

A tela de avaliações

Agentes → (seu Agent) → Avaliações é a bancada de qualidade do Agent. O cabeçalho identifica de qual Agent se trata (ícone, nome e situação), e a tela se organiza em torno de um objeto só: o conjunto de testes.

Tela de Avaliações do Agent, com os conjuntos de testes à esquerda e, à direita, o resultado da última avaliação e os casos.

• À esquerda, os conjuntos. A lista fica sempre visível e a seleção é única — o conjunto escolhido vale tanto para avaliar quanto para otimizar. O primeiro conjunto abre sozinho ao entrar na tela.
• À direita, o que fazer com ele. Avaliar roda os casos e mostra o resultado; Otimizar gera versões da instrução do Agent e testa cada uma contra esse mesmo conjunto (requer permissão de gerenciar avaliações).
• No topo, "Conversas do agente". Um painel lateral com as conversas que o Agent já teve, de onde saem casos novos. Cada linha começa pelo que o Agent respondeu e por qual persona (sub-agente) respondeu, agrupada por dia ("Hoje", "Ontem", a data). Conversas que não chegaram ao fim aparecem com a explicação em português e o erro técnico atrás de Detalhe técnico — nunca cru na lista. Só conversas concluídas oferecem Transformar em caso.

Promovendo uma run a caso de teste

Encontrou uma conversa real do Agent — boa ou ruim — que você quer garantir que não regrida (ou que quer corrigir e travar como exemplo)? Promova essa conversa a um caso de teste.

Isso é feito na tela de Avaliações (passos abaixo). Se a conversa nasceu no Playground ao vivo, o botão Salvar caso de lá faz o mesmo. O diálogo Transformar em caso de teste mostra a resposta que será gravada, sugere um nome a partir dela e pede o conjunto de destino (Escolha um conjunto).

1. ·

   Em Agentes → (seu Agent) → Avaliações, clique em Conversas do agente (canto superior direito).

2. ·

   Localize a conversa concluída que você quer travar como exemplo e clique em Transformar em caso.

3. ·

   Escolha o conjunto de destino, ajuste o nome se quiser e clique em Transformar em caso.

Isso gera um retrato das ferramentas chamadas e da resposta final daquela conversa, criando um caso de teste no conjunto de testes indicado, referenciando a conversa original.

Permissão requerida: criar caso de teste.

Criando um caso manualmente

Nem todo caso precisa vir de uma conversa registrada — você pode montar um caso de teste do zero, útil para cobrir um cenário que ainda não aconteceu na prática (ou que você quer garantir que nunca aconteça).

No Agent Builder, o botão Novo caso na tela do conjunto de testes abre a conversa-modelo: você escreve o caso como um diálogo, de cima para baixo.

• Cliente escreve — a mensagem que chega, em texto comum. O nome do caso é sugerido a partir dela e pode ser editado. Para uma entrada fora do padrão (mais do que uma mensagem de texto), use Editar como JSON, que abre a entrada completa sem perder as demais chaves.
• Antes de responder — as ferramentas que o Agent deve acionar, na ordem. A lista traz o catálogo do Agent agrupado por origem: as ferramentas internas do Agent (transfer_to_agent para delegar a um sub-agente, load_skill, kb_retrieve, memory_search — injetadas pelo runtime, não pertencem a nenhum servidor MCP), o MCP do Atende Direito, os servidores MCP vinculados e as ferramentas próprias. As liberadas aparecem primeiro; as que nenhuma allowlist da árvore libera vêm depois, sob não liberadas para este agente — continuam selecionáveis, o que permite escrever um caso que prova que o Agent não deveria acioná-las. A varredura considera o Agent raiz e os sub-agentes, já que numa orquestração quem aciona a ferramenta costuma ser o sub-agente. Um nome fora do catálogo ainda pode ser digitado. Cada etapa tem um painel Argumentos opcional, que mostra os parâmetros aceitos pela ferramenta escolhida.
• Agente deveria responder — a resposta final esperada, referência do critério de resposta final.
• Critérios de qualidade — as rubricas, na coluna da direita, uma frase por critério.

A coluna da direita também mostra como este caso é avaliado: os critérios ativos do conjunto de testes e a nota mínima de cada um. Quando um critério está desligado, a seção correspondente avisa que o preenchimento fica guardado mas não entra na nota.

Para criar: abra o conjunto de testes, clique em Novo caso, preencha a conversa-modelo e salve. Todos os campos além do nome e da entrada são opcionais — defina só o que fizer sentido para o critério que você quer testar (trajetória para o critério de trajetória de ferramentas, resposta esperada para o critério de resposta final, rubricas para o critério de rubrica; o critério de segurança não depende de nenhum desses campos, só da conversa pontuada).

Permissão requerida: gerenciar avaliações do Agent.

Disparando uma avaliação

Pela tela do Agent Builder

1. ·

   Em Agentes → (seu Agent) → Avaliações, selecione o conjunto de testes na lista à esquerda.

2. ·

   No seletor Avaliar contra, escolha Conversas gravadas ou Conversas novas. Para rodar cada caso mais de uma vez, ajuste Amostras por caso (de 1 a 10; custo e tempo multiplicam pelo número de amostras).

3. ·

   Clique em Avaliar agora. A avaliação roda em segundo plano e o resultado aparece na própria tela, com o andamento em tempo real.

O modo escolhido define como as conversas pontuadas são obtidas:

Modo	Comportamento
Conversas gravadas (padrão)	Pontua conversas já existentes — não dispara o Agent de novo.
Conversas novas	Dispara o Agent de verdade (em sandbox, sem efeitos reais de CRM) para cada caso do conjunto de testes, espera a execução terminar e pontua o resultado. Veja a seção Modo ao vivo abaixo.

Em Conversas gravadas, cada caso é pontuado contra a conversa original que deu origem a ele.

Permissão requerida para disparar: gerenciar avaliações do Agent. Para ver resultados: visualizar avaliações do Agent.

Lendo o resultado no Agent Builder

O topo da tela traz o retrato da rodada: uma barra com um segmento por caso, na ordem do conjunto de testes. Cada segmento é colorido pelo veredito do caso e clicável — leva direto ao caso correspondente. Abaixo dela vem a frase que resume o resultado ("3 de 4 casos passaram"), a taxa de aprovação, quando a rodada correu e contra o quê (conversas gravadas ou novas). Uma legenda aparece só com os estados que existem naquela rodada.

Os vereditos possíveis:

Veredito	Significa
Passou	Todas as amostras pontuadas do caso passaram.
Falhou	Nenhuma amostra pontuada passou.
Instável	Parte das amostras passou e parte falhou (só com samples > 1).
Não medido	Não havia execução do Agent para pontuar. Não é reprovação.
Na fila	O caso ainda não foi pontuado nesta rodada.

Não medido é o estado que separa "o Agent errou" de "não deu pra saber". Ele aparece quando a rodada correu em conversas gravadas e o caso não tem nenhuma execução associada. Nesse cenário a tela não mostra 0% de aprovação — ela diz que nada pôde ser medido e oferece o botão para reavaliar em conversas novas, que é a correção. Os segmentos desses casos aparecem hachurados, nunca vermelhos.

Cada caso é uma linha fechada com veredito, nome e o começo da mensagem do cliente; o primeiro caso problemático abre sozinho. Aberto, o caso é lido como a conversa que ele descreve, no mesmo formato da tela de autoria:

• Notas por critério — nota obtida, nota mínima e a barra com a marca da meta.
• Cliente escreveu — a mensagem, em texto. O JSON completo da entrada fica atrás de Ver dados completos.
• Antes de responder — ferramentas esperadas × obtidas, com as que faltaram riscadas e as que sobraram marcadas como "a mais".
• Agente respondeu — resposta esperada e obtida lado a lado, com a obtida destacada quando o critério de resposta final reprovou.
• Critérios de qualidade — as rubricas definidas no caso.

Enquanto a avaliação corre, a barra de progresso mostra o andamento e os casos viram do estado Na fila para o veredito final sem precisar dar refresh.

Escolhendo contra o que pontuar

O disparo tem dois modos, escolhidos no seletor acima dos casos:

• Conversas gravadas — pontua execuções do Agent que já aconteceram. Se não houver nenhuma, os casos ficam Não medido.
• Conversas novas — o Agent responde na hora, em sandbox, e a resposta dele é pontuada.

Modo ao vivo (live)

Para usar, selecione Conversas novas em Avaliar contra e clique em Avaliar agora.

Diferente de Conversas gravadas (que reaproveita conversas já registradas), o modo Conversas novas gera conversas novas para cada caso do conjunto de testes: a plataforma dispara o Agent em sandbox — sem efeitos reais em CRM, WhatsApp, etc. —, aguarda a execução terminar e só então pontua o resultado com os mesmos critérios de Conversas gravadas.

Como o disparo do Agent roda em segundo plano, fora do processamento normal de uma requisição web, o modo ao vivo não tem um limite curto de tempo de execução — mesmo um conjunto de testes com muitos casos e Agents lentos pode rodar até o fim.

Dica

As chamadas de IA usam a credencial do próprio workspace, e o modelo é determinado pelo sistema. Tanto o Agent (ao gerar as conversas) quanto o juiz automático dos critérios de resposta final e de rubrica autenticam com a chave do cliente — a integração conectada do workspace —, nunca com uma chave global. O juiz herda o mesmo provedor/credencial que roda o Agent: o provedor é derivado do modelo do Agent (gpt-4o → OpenAI, claude-sonnet-4 → Anthropic, gemini-2.5-flash → Gemini, qualquer modelo com / no identificador → OpenRouter; identificador começando em groq- → Groq), então não é preciso conectar o OpenRouter separadamente — se o Agent roda em OpenAI/Anthropic/Gemini/etc., o juiz usa essa mesma integração. O Agent roda no seu próprio modelo (o publicado na versão), e o juiz roda num modelo mais barato, determinado pelo sistema por provedor (ex.: um Nano na OpenAI, um Haiku na Anthropic, um Flash Lite no Gemini). Opcionalmente, o workspace pode fixar um modelo único de juiz para todas as avaliações — veja Modelo do juiz do workspace; nesse caso provedor e credencial vêm do modelo escolhido. Se a integração do provedor (do Agent, ou do modelo do juiz quando há essa opção fixada) não estiver conectada no workspace, a pontuação falha com um erro claro citando o provedor correto a configurar.

Modo	Quando usar
Conversas gravadas	Verificar regressão contra o histórico real do Agent (promovido do playground) — rápido, sem custo extra de IA além dos juízes. Bom para rodar com frequência.
Conversas novas	Validar mudanças de instrução/configuração antes de existir uma conversa registrada para o cenário, ou quando você quer garantir que o comportamento atual do Agent (não uma gravação antiga) passa no conjunto de testes. Custa tokens (o "combustível" cobrado por uso de IA) — roda o Agent de verdade a cada caso, além dos juízes de IA.

O progresso é publicado ao vivo (contagem de casos já pontuados sobre o total) pelo mesmo canal de atualizações em tempo real do progresso de Conversas gravadas descrito acima.

Permissão requerida: gerenciar avaliações do Agent.

Importando casos em lote e rodando pela linha de comando

Para conjuntos grandes (ex.: um conjunto de referência montado fora da plataforma) e para CI, use os comandos Artisan do backend.

Importar casos: agent:eval-import

php artisan agent:eval-import {evalSet} {arquivo.jsonl} [--dry-run] [--replace]

evalSet é o ID ou o nome do conjunto de testes. O arquivo é JSONL: uma linha = um caso, no formato nativo do caso de teste:

{"name": "reconexao-whatsapp", "session_input": {"input": "a conexao caiu novamente"}, "expected_final_response": "Passo a passo de reconexao...", "expected_trajectory": [{"tool_name": "transferConversationToDepartment", "tool_args": null}], "rubrics": ["Explica como reconectar o numero", "Nao promete prazo"]}

• session_input é obrigatório e deve ser um objeto: {"input": "texto"} para um turno, ou com messages/_context_turns para conversas com histórico. Os demais campos são opcionais.
• Cada linha passa pelas mesmas regras de validação do cadastro manual de caso. Linhas inválidas são reportadas com o número da linha e as demais seguem; o comando termina com código de saída diferente de zero se houve linha inválida.
• É idempotente por name dentro do conjunto: reimportar atualiza o caso existente em vez de duplicar.
• --dry-run só valida e relata, sem gravar nada.
• --replace apaga os casos do conjunto antes de importar (pede confirmação no modo interativo; com --no-interaction não pergunta). Apagar um caso apaga também os resultados históricos dele.
• A gravação é feita em uma única transação por execução.

Rodar pela linha de comando: agent:eval

php artisan agent:eval {agent} {evalSet} [--mode=offline|live] [--samples=1] [--timeout=1800] [--min-pass-rate=1.0] [--detailed]

• --mode=offline (padrão): pontua as conversas registradas associadas aos casos, de forma síncrona.
• --mode=live: pede ao Agent para gerar conversas novas em sandbox (mesmo caminho do modo ao vivo da tela). Como a pontuação chega em segundo plano, o comando aguarda consultando o andamento até a rodada concluir ou até --timeout segundos (padrão 1800); estourar o tempo ou a rodada falhar resulta em código de saída diferente de zero.
• --samples (1 a 10) repete cada caso para reduzir o efeito da variação do Agent e do juiz.
• O código de saída é 0 quando a taxa de aprovação atinge --min-pass-rate, e diferente de zero caso contrário (uso em CI).

Modelo do juiz do workspace

Por padrão o modelo do juiz é determinado pelo sistema, por provedor — um modelo barato/leve por provedor do Agent avaliado, com provedor e credencial herdados do Agent. Se preferir, o workspace pode definir um modelo único de juiz que passa a valer para todas as avaliações. Nesse caso, provedor e credencial vêm do modelo escolhido, e o workspace precisa ter a integração desse provedor conectada.

1. ·

   Acesse as configurações do workspace e localize o card Modelos de IA.

2. ·

   No campo Modelo do juiz de avaliação, selecione o modelo desejado. Deixe vazio para usar o padrão do sistema por provedor do Agent.

3. ·

   Salve as configurações do workspace.

Só aparecem modelos que as integrações de IA conectadas no workspace conseguem pagar.

Permissão requerida: gerenciar avaliações do Agent para alterar; visualizar avaliações do Agent para consultar.

Limitações e próximas fases

Além do modo ao vivo (que dispara o Agent em sandbox por caso), para gerar conversas novas de teste sem sair da tela de eval você também pode usar o Playground ao vivo: ele dispara o Agent de verdade e permite salvar o resultado direto como caso de teste, para depois pontuar em Conversas gravadas.

Ainda não disponível:

• Modo repetição (replay) — comparar uma execução ao vivo contra uma gravação determinística, reproduzindo exatamente as mesmas respostas de ferramentas/IA de uma conversa anterior.

Saiba mais

• Playground ao vivo — dispare o Agent ao vivo e salve o resultado como caso de teste
• Otimização de instruções (Optimizer) — melhore a instrução automaticamente usando o Eval como régua
• Instruções e modelo — como a instrução avaliada é escrita e configurada