Como criar um dataset de avaliação de agentes: tarefas reais, trajetórias e testes de regressão

Na semana passada, o agente de relatórios diários ainda gerava relatórios normalmente. Depois de um upgrade de modelo, ele continua retornando um resumo final que parece correto, mas a trajetória pulou a verificação de permissão e a ferramenta de atualização de dados. Um agente de suporte dá a resposta final certa, mas chama a ferramenta de reembolso com argumentos errados; um benchmark público não enxerga esse risco. Em uma retrospectiva de incidente já existem traceId, tool call, approvalId, state event e julgamento humano, mas nada virou teste obrigatório antes do próximo release.

Esse tipo de regressão não se resolve trocando de modelo nem rodando mais uma demo. Um dataset de avaliação de agentes precisa vir da distribuição real de tarefas e das trajetórias de falha em produção: tool calls, formatos de argumento, transições de estado, approval records e human labels. Depois, ele deve entrar no CI como gate de regressão. O foco aqui são casos de falha e cenários reais: como construir um eval dataset sustentável que proteja o limite de qualidade de cada release.

1. Por que benchmarks públicos não bastam

1.1 Limites dos benchmarks públicos

Benchmarks públicos medem capacidade do modelo, não a qualidade das suas tarefas de negócio. Conjuntos como AgentBench e WebArena fornecem tarefas padronizadas, mas não cobrem a toolchain, o modelo de permissões nem a state machine do seu time.

Por exemplo, seu agente de relatórios pode precisar chamar check_permission, refresh_data e generate_report na ordem “verificar → atualizar → gerar”. Um benchmark público não testa esse fluxo, porque não conhece seus tool schemas nem seus limites de permissão.

Um bom score em benchmark público não significa que sua tarefa de negócio não vai regredir. Um dataset de avaliação de agentes deve testar a sua distribuição real de tarefas, não uma capacidade geral de raciocínio.

1.2 Valor principal de um dataset próprio

Um eval dataset próprio captura riscos que benchmarks públicos não enxergam. Veja a comparação:

Use benchmarks públicos para escolher modelos; use seu dataset próprio para proteger release gates. Eles se complementam, mas não se substituem. Se você já leu Comparativo de benchmarks de avaliação de agentes, sabe quais conjuntos públicos ajudam na escolha. Aqui o foco é construir dados de avaliação a partir do seu próprio ambiente de produção.

2. Campos centrais de um agent eval dataset

2.1 Campos obrigatórios

Um agent eval dataset não é só salvar entrada do usuário e resposta esperada. Ele precisa registrar trajetória de tool calls, transições de estado e julgamento humano. Estes são os campos obrigatórios:

LangSmith, em Evaluation concepts, recomenda que a avaliação de agentes cubra seleção de ferramentas, formato de argumentos e trajetória de execução, não apenas a resposta final. OpenAI Agents SDK Tracing fornece campos como trace_id, workflow_name e span para registrar tool calls e eventos de estado, mas esses campos brutos precisam ser anonimizados e extraídos antes de entrar em um dataset.

2.2 Campos opcionais

Adicione estes campos conforme a necessidade do negócio:

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Se você leu o modelo de permissões de agentes (N157) e o design de aprovação humana (N155), sabe que approval records deve registrar etapa de aprovação, aprovador e resultado, para verificar se uma operação de alto risco passou por aprovação.

2.3 Anonimização e privacidade

Production trace não pode entrar cru no conjunto de avaliação. A documentação de OpenAI Agents SDK Tracing lembra que alguns spans podem capturar entradas/saídas do modelo ou entradas/saídas de function tools; por isso é preciso configurar se dados sensíveis serão incluídos.

Campos que devem ser anonimizados: PII (nome, email, telefone), secrets (API key, senha de banco de dados), dados de cliente (número de pedido, valor de transação).

Campos a manter: traceId, span_id para diagnóstico, workflow_name para classificação, nome da ferramenta e nome do estado para assertions.

Métodos de anonimização incluem substituir por placeholders como <user_id>, aplicar hash ou remover diretamente. A documentação Phoenix Running Evals on Traces mostra que traces podem virar entradas de avaliação, mas ainda precisam de label, score e rubric. Não coloque traces brutos completos diretamente no eval dataset.

3. Do production trace ao eval example

3.1 Fluxo de coleta de dados

Para transformar um production trace em eval example, você precisa de quatro etapas: anonimização, rotulagem, estratificação e armazenamento. Isso não é um projeto único de engenharia, é operação contínua.

Checklist:

1. Exportar traces com falha da plataforma de monitoramento (veja Monitoramento de agentes e recuperação de falhas).
2. Classificar por tipo de falha: erro de tool call, erro de formato de argumento, erro de transição de estado, erro de resposta final.
3. Anonimizar: remover PII/secret/dados de cliente e manter traceId, span_id, workflow_name.
4. Adicionar rótulo humano: correto/errado/parcialmente correto + motivo da falha.
5. Armazenar por camada: golden set / negative cases / edge cases.

A documentação de Phoenix datasets diz que examples podem ser coletados de production, staging, evaluations ou manual. Produção traz a distribuição real de tarefas; staging ajuda a complementar cenários de borda.

3.2 Critérios de estratificação

Dimensões de rotulagem, alinhadas a uma rubric LLM-as-judge: correção da seleção de ferramentas, correção do formato de argumentos, correção da ordem de execução, qualidade da resposta final e alinhamento com rótulos humanos.

OpenAI Evaluation best practices recomenda dados de teste com typical, edge e adversarial cases, usando human expert labellers. A estratificação acima segue essa lógica, mas enfatiza tarefas frequentes e modos típicos de falha, porque o objetivo é proteger o release gate, não cobrir todos os cenários.

4. Como escrever trajectory assertions

4.1 Tipos de restrições de trajetória

Trajectory assertions definem as regras de tool calls, formato de argumentos, transições de estado e aprovação que o agente deve cumprir. Estes são cinco tipos comuns:

LangSmith Evaluation concepts menciona trajectory, tool selection e argument formatting como partes da avaliação de agentes. Phoenix Running Evals on Traces usa span_id para associar resultados de avaliação a um segmento específico de execução, mostrando que assertions de trajetória podem apontar para o span com falha.

Se você leu avaliação de capacidade de planejamento de agentes (N158) e limites entre state machine e prompt, sabe que campos de trajetória de estado vêm de state/event/checkpoint. Eles verificam se a transição de estado segue a ordem esperada.

4.2 Exemplo de código

Aqui está um pseudocódigo de trajectory assertions para uma avaliação genérica de agentes:

# Exemplo de trajectory assertions
def assert_trajectory_correct(result):
    # Extrair a lista de tool calls
    tools_called = [call.tool for call in result.tool_calls]

    # Ferramentas obrigatórias
    required_tools = ["check_permission", "refresh_data"]
    for tool in required_tools:
        assert tool in tools_called, f"Missing required tool: {tool}"

    # Ferramentas proibidas
    forbidden_tools = ["delete_user"]
    for tool in forbidden_tools:
        assert tool not in tools_called, f"Called forbidden tool: {tool}"

    # Restrições de formato de argumento
    for call in result.tool_calls:
        if call.tool == "refund":
            assert isinstance(call.args["refund_amount"], (int, float)), "refund_amount must be number"
            assert len(call.args["user_id"]) == 36, "user_id must be uuid format"

    # Ordem de transição de estado
    expected_states = ["init", "check", "approve", "execute"]
    actual_states = [event.state for event in result.state_events]
    assert actual_states == expected_states, "State transition order mismatch"

    # Existência da etapa de aprovação
    approval_events = [e for e in result.state_events if e.type == "approval"]
    assert len(approval_events) >= 1, "Missing approval step"

Esse código mostra como verificar ferramentas obrigatórias, ferramentas proibidas, formatos de argumentos, ordem de transições de estado e etapas de aprovação. Na prática, você pode usar trajectory assertions do LangSmith ou trace eval do Phoenix, mas a lógica central é a mesma.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Se você leu Avaliação de planejamento de agentes, sabe que trajetórias de planejamento também podem virar amostras de regressão para verificar decomposição de tarefas e autocorreção.

5. Rubric em camadas para LLM-as-judge

5.1 Por que o score total não basta

Se LLM-as-judge retorna apenas um score total, o resultado oscila e é difícil de diagnosticar. Um 80 pode significar que a seleção de ferramentas foi errada, mas a resposta saiu certa por acaso; ou que a resposta foi errada, mas o formato parecia bom. Não dá para saber se o problema está no prompt, no tool schema, no retrieval ou na state machine.

LangSmith Evaluation concepts recomenda definir padrões de qualidade para componentes-chave do agente: correct tool selection, proper argument formatting e trajectory. Ao pontuar cada componente separadamente, fica muito mais rápido localizar regressões depois de mudança de modelo ou prompt.

Se você leu Práticas avançadas de prompt engineering, sabe que DeepEval também enfatiza métricas em camadas como TaskCompletenessMetric, e não só a saída final.

5.2 Tabela de pontuação em camadas

A rubric abaixo divide a avaliação de agentes em cinco dimensões, cada uma com 0-2 pontos:

Exemplo de configuração de rubric para LangSmith ou Phoenix:

rubric:
  dimensions:
    - name: tool_selection
      weight: 0.3
      criteria:
        0: "Chamou a ferramenta errada"
        1: "Chamou algumas ferramentas corretas"
        2: "Seleção de ferramentas totalmente correta"

    - name: argument_formatting
      weight: 0.2
      criteria:
        0: "Tipo de argumento incorreto"
        1: "Alguns campos têm erro de formato"
        2: "Formato de argumentos totalmente correto"

    - name: execution_order
      weight: 0.2
      criteria:
        0: "Transição de estado salta ou se repete"
        1: "Ordem de execução com desvios"
        2: "Ordem de execução totalmente correta"

    - name: final_answer_quality
      weight: 0.2
      criteria:
        0: "Não atende à solicitação do usuário"
        1: "Atende parcialmente à solicitação"
        2: "Atende completamente à solicitação"

    - name: human_alignment
      weight: 0.1
      criteria:
        0: "Contradiz julgamento especialista"
        1: "Parcialmente alinhado"
        2: "Muito alinhado"

Seleção de ferramentas tem o maior peso (0.3), porque o núcleo de um agente é chamar a ferramenta correta. Alinhamento humano tem o menor peso (0.1), pois serve principalmente para calibrar se LLM-as-judge concorda com o julgamento especialista.

6. Release gates e testes de regressão

6.1 Etapas de integração com CI

O valor de um agent eval dataset aparece quando ele entra no CI como release gate. Use este fluxo:

Checklist:

1. Adicionar uma etapa de eval na CI pipeline, como pytest, LangSmith offline eval ou Phoenix experiments.
2. Configurar um limiar de pass rate, por exemplo 90%.
3. Exigir que o golden set passe completo (100%).
4. Configurar regras de alerta para negative cases. Elas podem notificar o time sem bloquear.
5. Configurar comparação de versões (improvement/regression) entre baseline e versão atual.
6. Definir quando o gate roda: PR / merge / canary.

LangSmith Evaluation concepts menciona que offline evaluations podem ser usadas para regression testing, unit testing e backtesting sobre examples de datasets. A documentação Phoenix experiments explica que é possível comparar mudanças de prompt, LLM ou lógica da aplicação para julgar improvement/regression. DeepEval descreve evals pytest-native que podem rodar em CI/CD ou Python scripts, usando LLMTestCase e TaskCompletenessMetric para pontuar agent traces em camadas.

6.2 Tabela de limiares

Exemplo de configuração de CI:

evaluation:
  triggers:
    - pull_request
    - merge_to_main
    - canary_deployment

  conditions:
    pass_rate: 0.9
    golden_set: 1.0
    no_regression: true

  notifications:
    on_failure: ["team-lead", "on-call"]
    on_negative_alert: ["team-lead"]

Os gatilhos incluem PR, para impedir código problemático de entrar na main; merge, para garantir que o estado mesclado ainda cumpre as condições; e canary, para validar antes do tráfego de produção. Se você leu controle de custo e roteamento de modelos (N156), sabe que limiares de custo também podem virar condições de gate. Aqui ficamos nos limiares de avaliação.

7. Retrospectiva de um caso real

7.1 Descrição do cenário

O agente de relatório diário funcionava bem na semana passada: chamava check_permission para verificar permissões, refresh_data para atualizar dados e depois generate_report para gerar o relatório. Após o upgrade de modelo, o agente ainda retorna um resumo final que parece correto, mas a trajetória omite check_permission e refresh_data.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

O usuário recebe um relatório sem verificação de permissão e com dados desatualizados, mas isso não aparece na superfície. Um benchmark público não detecta esse risco, porque não tem seu tool schema nem sua state machine.

7.2 Localização do problema

Exporte o trace com falha da plataforma de monitoramento (veja Monitoramento de agentes e recuperação de falhas). A análise de trajetória mostra que a lista de tool calls não contém check_permission nem refresh_data, a transição de estado pula de init direto para execute, faltam check e approve, e a resposta final parece correta embora a fonte de dados não tenha sido atualizada.

Rótulo: erro de seleção de ferramentas + salto de transição de estado.

7.3 Atualização do dataset

Adicione o caso de falha a negative cases. Ao mesmo tempo, reforce o golden set: encontre a tarefa de relatório diário bem-sucedida da semana anterior, inclua a sequência completa de tool calls e rotule como caso correto.

Atualize as trajectory assertions: adicione check_permission e refresh_data à required tool list, e defina a assertion de ordem de estados como ["init", "check", "approve", "execute"].

7.4 Interceptação pelo gate de CI

A próxima PR dispara a execução de eval. O negative case gera alerta: falta o tool call check_permission. O golden set passa completo, então o caso de sucesso de referência continua intacto.

A causa está no prompt. Depois do upgrade, o modelo interpreta “gerar relatório” como execução direta e ignora a verificação e a atualização anteriores.

7.5 Correção e regressão

Corrija o prompt, deixando explícito que o agente deve verificar permissões e atualizar dados antes de gerar o relatório. Rode eval novamente: o pass rate sobe de 85% para 95%, o negative case passa sem alerta, o golden set passa completo e a comparação de versões mostra improvement sem regression.

Faça merge e release. O gate de CI segurou essa regressão antes da produção.

7.6 Tabela de mapeamento de campos

Esse ciclo mostra o caminho completo da falha em produção ao teste de regressão. Depois de cada retrospectiva de incidente, transforme traceId, tool call, approvalId, state event e julgamento humano em eval example. Assim o próximo release não tropeça no mesmo erro.

8. O que ler a seguir

• State machines de agentes e limites do prompt: entender de onde vêm as restrições de transição de estado e os campos de trajectory assertion
• Modelo de permissões de agentes: entender approval records e regras para tool calls de alto risco
• Design de aprovação humana: transformar approval records e fluxos de aprovação em testes duráveis
• Controle de custos e roteamento de modelos: entender como limiares de custo viram condições de gate
• Monitoramento de agentes e recuperação de falhas: exportar failed traces e construir uma retrospectiva de incidentes