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 (valor padrão) e, opcionalmente, podem ser ajustadas pontualmente no disparo de uma rodada:

{
  "tool_trajectory_avg_score": 1.0,
  "final_response_match": 0.8,
  "rubric_based": 0.7
}

Dica

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

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.

No Agent Builder, isso é feito diretamente na tela da conversa, com o botão de promover a caso de teste. Para times técnicos, também é possível via API:

curl -X POST https://sua-instancia/api/ai-agents/{agent}/runs/{run}/promote-to-case \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
        "eval_set_id": "01J0000000000000000000000B",
        "name": "Caso promovido — prazo recursal"
      }'

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 um formulário: entrada, etapas da trajetória esperada, resposta final esperada e uma lista de rubricas — tudo direto na tela.

Para times técnicos, o mesmo pode ser feito via API:

curl -X POST https://sua-instancia/api/ai-agents/{agent}/eval-sets/{set}/cases \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Pergunta sobre prazo de contestação",
        "session_input": { "message": "Qual o prazo pra contestar?" },
        "expected_trajectory": [
          { "tool_name": "buscar_prazo_processual", "tool_args": { "tipo": "contestacao" } }
        ],
        "expected_final_response": "O prazo é de 15 dias úteis.",
        "rubrics": [
          "A resposta deve citar o prazo em dias úteis",
          "A resposta não deve prometer resultado do processo"
        ]
      }'

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 ou via API

curl -X POST https://sua-instancia/api/ai-agents/{agent}/eval-sets/{set}/run \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "run_selection": "source" }'

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

Modo	Comportamento
Offline (padrão)	Pontua conversas já existentes — não dispara o Agent de novo.
Ao vivo	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.

No modo offline, é possível escolher, por caso, qual conversa registrada será pontuada: a conversa original que deu origem ao caso (padrão), ou uma conversa específica indicada explicitamente — útil para reavaliar um caso contra uma execução diferente da original.

A resposta devolve a rodada de avaliação recém-criada, com status "na fila". A avaliação roda em segundo plano (o critério de resposta final usa um juiz automático, que é mais lento) — consulte o resultado depois:

curl https://sua-instancia/api/ai-agents/{agent}/eval-runs/{evalRun} \
  -H "Authorization: Bearer {token}"

{
  "data": {
    "id": "01J0000000000000000000000C",
    "status": "completed",
    "summary": {
      "pass_rate": 0.83,
      "avg_score": {
        "tool_trajectory_avg_score": 0.91,
        "final_response_match": 0.78
      }
    }
  }
}

Para ver o detalhe de cada caso (o que passou, o que falhou e por quê):

curl https://sua-instancia/api/ai-agents/{agent}/eval-runs/{evalRun}/results \
  -H "Authorization: Bearer {token}"

Cada item da lista traz se o caso passou ou falhou e as notas por critério, com nota obtida, nota mínima, se passou e o detalhe (por exemplo, ferramentas que faltaram ou sobraram na trajetória).

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

Progresso ao vivo

No Agent Builder, ao disparar uma avaliação você não fica olhando pra uma tela em branco esperando o resultado: a tela mostra os casos sendo pontuados em tempo real, um a um, com uma barra de progresso ("Avaliando caso 2 de 5…"). Para cada caso, à medida que o resultado chega, dá pra abrir e ver:

• Entrada testada — a entrada do caso.
• Trajetória — esperada vs. real — cada etapa esperada (ferramenta + argumentos), marcada como batida (✓) ou faltando (✗); chamadas extras que o Agent fez e não eram esperadas aparecem destacadas à parte.
• Resposta final — esperada vs. real — lado a lado, com a resposta real destacada quando o critério de resposta final reprovou.
• Notas por critério — uma por critério aplicado (trajetória de ferramentas, resposta final, rubrica, segurança), com a nota obtida, a nota mínima e se passou ou não.

Casos ainda não pontuados aparecem com o badge Aguardando, e viram Passou/Falhou assim que o resultado chega — sem precisar dar refresh na página.

Modo ao vivo (live)

curl -X POST https://sua-instancia/api/ai-agents/{agent}/eval-sets/{set}/run \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "live" }'

Diferente do modo offline (que reaproveita conversas já registradas), o modo ao vivo 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 do modo offline.

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), 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.: gpt-4o-mini na OpenAI, um Haiku na Anthropic, um Flash no Gemini). Opcionalmente, o workspace pode fixar um modelo único de juiz para todas as avaliações — veja Modelo do juiz por 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
Offline	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.
Ao vivo	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 do modo offline descrito acima.

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

Modelo do juiz por workspace (override)

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. Cada workspace pode definir um modelo ÚNICO de juiz (ex.: openai/gpt-4.1-nano ou gemini-2.5-flash-lite) que passa a valer para todas as avaliações.

Quando essa opção está ativa, o juiz usa esse modelo para qualquer Agent — e, diferente do comportamento padrão, provedor e credencial passam a vir do modelo escolhido. Ou seja, o provedor do Agent é ignorado nesse caso; o workspace precisa ter a integração conectada do provedor do modelo escolhido.

Quando vazio, vale o comportamento padrão do sistema por provedor do Agent.

Lendo o modelo do juiz configurado

curl https://sua-instancia/api/workspaces/current/eval-judge-model \
  -H "Authorization: Bearer {token}" \
  -H "X-Workspace-Id: {workspace}"

{
  "data": {
    "judge_model": "openai/gpt-4.1-nano"
  }
}

Quando judge_model vem vazio, não há opção fixada — usa o padrão do sistema por provedor do Agent.

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

Gravando o modelo do juiz

curl -X PUT https://sua-instancia/api/workspaces/current/eval-judge-model \
  -H "Authorization: Bearer {token}" \
  -H "X-Workspace-Id: {workspace}" \
  -H "Content-Type: application/json" \
  -d '{ "judge_model": "gemini-2.5-flash-lite" }'

Essa chamada grava o modelo único do juiz do workspace. Enviar um valor vazio remove a opção fixada (volta ao padrão do sistema por provedor do Agent).

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

Via linha de comando (para pipelines automatizados)

Para rodar um conjunto de testes de forma automatizada — por exemplo, como uma trava de qualidade num pipeline de integração contínua — os times técnicos podem usar o comando:

php artisan agent:eval {agent} {evalSet} --min-pass-rate=0.9 --detailed

Argumento/opção	Descrição
{agent}	ID ou nome do Agent
{evalSet}	ID ou nome do conjunto de testes
--min-pass-rate=1.0	Taxa de aprovação mínima exigida para o comando terminar com sucesso (padrão: 1.0, ou seja, 100%)
--detailed	Além da tabela resumo, imprime o detalhe de cada critério que falhou

O comando roda o conjunto de testes de ponta a ponta, imprime uma tabela com caso / status / notas, e termina com sucesso se a taxa de aprovação final for maior ou igual à taxa mínima definida, ou com erro caso contrário — pronto para travar um pipeline automatizado quando a qualidade do Agent regredir.

Dica

Esse comando de linha de comando é sempre offline (pontua conversas já existentes), sem amostragem. Para disparar o modo ao vivo (gerar conversas novas via Agent em sandbox), use a API — veja Modo ao vivo acima.

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 modo offline.

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