Avaliação de AI Agents em Produção: de Traces a Test Suites

Viacheslav Dubrov

2026-06-10 · Atualizado 2026-08-16 · 25 min · Agentes de IA

Tradução automática Este artigo foi traduzido automaticamente a partir da versão original em inglês.

Uma resposta final pode afirmar que um reembolso está concluído, enquanto o trace mostra que verify_identity nunca foi executado, que issue_refund foi repetido 17 vezes ou que o agent declarou sucesso antes de a base de dados ser alterada. A avaliação apenas da resposta esconde estas falhas.

Para os engenheiros que operam agents com tool use em produção, a solução consiste em transformar traces repetíveis em casos de regressão delimitados: verificações determinísticas impõem a ordem das tools, os argumentos, os loops e os invariantes; judges calibrados tratam das decisões que exigem interpretação. O resultado é uma suite versionada que deteta a mesma falha antes da próxima release.

Para uma comparação breve das tools, consulte Best AI Agent Evaluation Tools.

Porque é que os evals de agents são diferentes

Os evals tradicionais de LLM costumam avaliar um par input-output: relevância, faithfulness, correção, segurança e, talvez, estilo. Os agents acrescentam planeamento, tool calls, retries e verificações de terminação, e cada passo é um novo ponto de falha.

Considere um refund agent. O transcript pode terminar bem, enquanto o trace está errado:

lookup_order -> issue_refund -> final_answer

O eval da resposta passa. Um eval de trajectória deve falhar porque verify_identity nunca foi executado antes de issue_refund. Para agents com tool use, os evals apenas da resposta são smoke tests: detetam uma falha total e deixam passar quase tudo o resto.

Há um segundo problema: os erros acumulam-se. Se um workflow tiver 20 passos obrigatórios, cada um tiver sucesso de forma independente e todos tiverem a mesma fiabilidade de 95%, a taxa de sucesso end-to-end será de cerca de 36%:

Assim, o agent pode parecer sólido em verificações isoladas e continuar a falhar na maioria das execuções completas. A falha costuma estar algures no meio, e encontrá-la exige visibilidade ao nível dos componentes, não outra análise da resposta.

Duas equipas de investigação quantificaram este problema.

tau-bench dá a um agent tarefas de atendimento ao cliente de companhias aéreas e retalho. O agent conversa com um utilizador simulado, chama APIs e tem de seguir a política do domínio. No fim da conversa, o grader verifica se a base de dados atingiu o estado objetivo anotado. Um transcript plausível com os registos errados continua a falhar.

Com esse método de avaliação, o GPT-4o resolveu apenas 35,2% das tarefas de aviação e pouco mais de 60% das tarefas de retalho. O artigo introduziu também pass^k: executar a mesma tarefa k vezes e contar como aprovação apenas se o agent tiver sucesso nas k execuções.

O retalho, a divisão mais fácil, caiu abaixo de 25% com k = 8. Em mais de três quartos dessas tarefas, o mesmo agent, perante a mesma tarefa oito vezes, falhou pelo menos uma vez. Um eval de uma única execução não consegue expor esta inconsistência.

MAST estuda as razões pelas quais os agents falham. Os autores criaram uma taxonomia de 14 modos a partir de 150 traces anotados manualmente e aplicaram-na a mais de 1.600 traces provenientes de 7 frameworks multi-agent populares. A taxonomia inclui definições vagas de papéis (system design), um agent ignorar aquilo que outro agent reportou (inter-agent misalignment) e declarar sucesso sem verificar o resultado (no verification). Estas falhas envolvem prompts, lógica de orquestração e verificações em falta no harness. Um modelo base mais forte não consegue executar um passo de verificação que nunca foi implementado; por isso, o alvo da avaliação tem de incluir o harness à volta do modelo.

A lacuna de adoção

O inquérito State of Agent Engineering da LangChain (1.340 respondentes, realizado no final de 2025) sugere que muitas equipas já dispõem da matéria-prima para evals melhores. O relatório indica que 89% tinham alguma forma de observabilidade, 52,4% executavam evals offline e 37,3% executavam evals online.

O inquérito indica também que 57,3% dos respondentes já tinham agents em produção. Quando questionados sobre os obstáculos à produção, 32% apontaram a qualidade e 20% a latência. Trata-se de um inquérito aos seus respondentes, não de um recenseamento das equipas de agents, mas revela uma lacuna útil entre a recolha de traces e a avaliação sistemática.

Isto deixa as equipas num estado intermédio incómodo: conseguem inspecionar uma execução problemática depois de esta acontecer, mas continuam a lançar duas vezes a mesma falha.

Cada falha de produção diagnosticada deve deixar um trace, um label, uma linha no dataset e um scorer. Uma falha repetível pertence à suite de regressão.

Escolha as métricas de acordo com o modo de falha

A métrica certa depende do modo de falha, não do framework. A divisão útil tem três níveis:

1. Evals de resultado respondem a se a tarefa foi concluída com sucesso.
2. Evals de trajectória respondem a se o percurso foi válido, eficiente e conforme à política.
3. Evals de componentes respondem a qual tool, retriever, sub-agent ou passo de decisão falhou.

Cada nível pode ser executado offline, sobre casos fixos e reproduzíveis antes da release, ou online, sobre traces de produção amostrados depois da resposta. A secção sobre guardrails abaixo detalha esta divisão. Os evals offline podem exigir goldens: casos armazenados que associam um input ao resultado, aos invariantes das tools e aos argumentos que uma execução correta deve produzir. Os evals online devem privilegiar invariantes, distribuições e verificações assíncronas que fiquem fora do caminho do pedido.

Comece pelas métricas determinísticas. São baratas, rápidas e não sofrem de drift.

Correção de tool calls

A correção das tools compara as tools chamadas com as tools esperadas. Escolha deliberadamente o grau de rigor:

• Correspondência exacta: a sequência tem de coincidir exactamente. Use-a quando a ordem for uma exigência da política, por exemplo lookup_order -> verify_identity -> issue_refund.
• Correspondência por ordem: as tools obrigatórias têm de aparecer na ordem relativa correcta, mas são permitidas chamadas adicionais inofensivas.
• Correspondência em qualquer ordem: as tools obrigatórias têm de aparecer, mas a ordem pode variar.

Um scorer local pequeno é suficiente para começar:

from collections import Counter

def tool_correctness(called: list[str], expected: list[str], mode: str = "in_order") -> float:
    if not expected:
        return 1.0
    if mode == "exact":
        return float(called == expected)
    if mode == "any_order":
        matched = sum((Counter(called) & Counter(expected)).values())
        return matched / len(expected)

    rows = [[0] * (len(expected) + 1) for _ in range(len(called) + 1)]
    for i, tool in enumerate(called):
        for j, wanted in enumerate(expected):
            if tool == wanted:
                rows[i + 1][j + 1] = rows[i][j] + 1
            else:
                rows[i + 1][j + 1] = max(rows[i][j + 1], rows[i + 1][j])
    return rows[-1][-1] / len(expected)

called = ["lookup_order", "check_refund_policy", "issue_refund"]
expected = ["lookup_order", "verify_identity", "issue_refund"]

print(round(tool_correctness(called, expected, "exact"), 3))     # 0.0
print(round(tool_correctness(called, expected, "in_order"), 3))  # 0.667

A métrica in_order é o recall da longest-common-subsequence: a fracção da sequência obrigatória que sobreviveu, pela ordem certa. Repare no que ignora. As chamadas desnecessárias não a reduzem, pelo que um agent pode obter 1,0 aqui fazendo o dobro das chamadas necessárias. Quando as chamadas adicionais têm custos ou alteram o estado, acompanhe também a precision (chamadas obrigatórias correspondidas sobre o total de chamadas) e leia ambas em conjunto. O recall deteta o passo em falta; a precision deteta a divagação.

A métrica Tool Correctness da DeepEval disponibiliza os mesmos controlos através de should_consider_ordering e should_exact_match.

Correção dos argumentos

Chamar a tool certa com os argumentos errados é muitas vezes pior do que chamar a tool errada, porque o trace parece normal.

Nos casos simples, valide o JSON Schema e os valores exactos. Nos casos semânticos, armazene os argumentos esperados e avalie as diferenças:

{
    "trace_id": "tr_2417",
    "input": "Reschedule order A-100 for next Friday.",
    "expected_tools": ["lookup_order", "reschedule_delivery"],
    "expected_arguments": {
        "reschedule_delivery": {
            "order_id": "A-100",
            "date": "2026-06-19"
        }
    }
}

Uma métrica baseada apenas no nome da tool não deteta 2026-06-17 quando a política exige 2026-06-19. O dataset também tem de armazenar os argumentos.

A métrica associada a esse dataset é a correspondência de parâmetros: a fracção dos triplos (tool, key, value) esperados que o agent acertou.

def argument_correctness(called_args: dict, expected_args: dict) -> float:
    total = matched = 0
    for tool, params in expected_args.items():
        for key, want in params.items():
            total += 1
            if called_args.get(tool, {}).get(key) == want:
                matched += 1
    return matched / total if total else 1.0

A igualdade exacta é adequada para IDs, enums e datas já normalizadas para um único formato. É inadequada para texto livre, floats e datas no formato produzido pelo modelo, em que == assinala como errada uma resposta correcta. Avalie esses campos de acordo com a sua natureza: correspondência de strings normalizadas, parsing de datas ou tolerância numérica. A métrica mantém-se; muda o comparador por campo.

Eficiência, loops e becos sem saída

Um agent que conclui a tarefa depois de cinco tool calls redundantes continua a revelar um problema de planeamento e custa mais a executar.

Sinais baratos pelos quais deve começar:

• Taxa de chamadas redundantes: tool calls idênticos, com argumentos idênticos, repetidos mais de duas vezes.
• Anomalias na forma do trace: aumentos súbitos na profundidade, no número de tool calls, no número de tokens, na latência ou no custo.
• Convergência do percurso: quão próxima está a execução do percurso válido mais curto conhecido para a tarefa.
• Correção da terminação: se o agent parou cedo, continuou a trabalhar depois do sucesso ou declarou sucesso sem a alteração de estado obrigatória.
• Adesão ao plano: se o agent escrever um plano antes de agir, verifique se o trace o seguiu. Um bom plano ignorado e um mau plano seguido na perfeição falham por razões opostas, e a diferença entre o plano e o trace indica qual delas ocorreu.

Execute estas verificações antes de um judge sempre que possível. Um detetor de loops requer apenas algumas linhas sobre o trace. Não precisa de um modelo.

Conclusão da tarefa e avaliação do resultado

Quando a avaliação se centra no resultado, a pergunta é: “o utilizador obteve aquilo que pediu?”

Dois padrões funcionam melhor:

• Avaliação referenceless da conclusão da tarefa: extraia o objetivo do input e avalie se o trace e a resposta final o atingiram. Funciona online porque o tráfego de produção raramente tem outputs golden.
• Avaliação do estado do ambiente: compare as linhas finais da base de dados, ficheiros, tickets, reservas ou registos com um estado objetivo anotado. É mais robusta do que comparar transcripts, porque os agents podem encontrar percursos válidos que não foram previamente especificados.

A segunda opção é melhor quando pode implementá-la. O estado final é o contrato. O transcript é apenas evidência.

Duas ressalvas ajudam a manter esta avaliação honesta. Uma auditoria de 2025 a benchmarks agentic concluiu que o tau-bench avalia algumas tarefas apenas pelo estado da base de dados. Em algumas tarefas, o resultado anotado não exige qualquer alteração de estado nem texto específico. Um agent que não faça nada pode então obter aprovação: 38% na divisão de aviação e 6,0% no retalho, com qualquer k. A Anthropic reportou uma execução do Opus 4.5 que “falhou” uma tarefa de reserva no tau2-bench, o benchmark sucessor. O agent encontrou uma lacuna na política que era, na realidade, o melhor resultado para o utilizador. A avaliação do estado é melhor do que a comparação de transcripts, mas o estado objetivo continua a ser uma anotação, e as anotações têm erros. Audite também os casos aprovados com demasiada facilidade, não apenas os que falham.

Evals de componentes

As métricas de resultado e de trajectória dizem-lhe que a execução falhou e, aproximadamente, onde. Os evals de componentes avaliam um span: o chunk recuperado era relevante, o sub-agent devolveu o schema esperado pelo chamador, a resposta da tool foi analisada correctamente? Associe o score ao span, não à execução, para que “qual foi a tool que piorou esta semana?” seja uma consulta, não uma nova execução.

Três verificações cobrem a maior parte do problema:

• Avaliação por span: execute a métrica adequada ao tipo de span. Os spans de retrieval obtêm recall e precision contra o chunk anotado; os spans de sub-agents obtêm validação do schema e o seu próprio score de correção das tools; os spans de tools obtêm taxa de erros e latência.
• Interpretação dos resultados das tools: forneça ao agent um output de tool correcto mas incómodo (uma lista vazia, uma correspondência parcial, um timestamp desactualizado) e verifique o que faz a seguir. Uma tool pode estar correcta enquanto o agent a interpreta mal, e essa falha só se torna visível dois passos mais tarde.
• Atribuição da falha: a falha visível costuma estar a jusante da falha real. Atribua-a ao primeiro span cujo output já estava errado, não ao passo que lançou o erro.

É também aqui que a matemática acumulada da introdução se torna útil. Se 20 passos parecerem correctos isoladamente, a execução pode continuar a falhar na maioria das vezes. As taxas de aprovação por span mostram qual é o passo que funciona a 95% e qual funciona a 70%.

O flywheel de trace para eval

Extraia falhas de produção antes de idealizar casos de eval adicionais.

O loop:

1. Capture o trace completo.
2. Identifique o que falhou.
3. Agrupe falhas semelhantes.
4. Mantenha um golden representativo por cluster.
5. Versione o dataset.
6. Execute-o no CI.
7. Continue a avaliar online traces de produção amostrados.

O repositório complementar trace2evals implementa o loop completo para um support agent com falhas. Captura spans GenAI de OpenTelemetry, deteta falhas com regras determinísticas, elimina duplicados e organiza os casos num dataset golden versionado, e volta a executar cada golden no CI. O backend predefinido substitui o modelo por regras determinísticas que reproduzem as decisões do agent com bugs, pelo que make demo reproduz todo o loop offline sem API key. Execute uv sync --extra live e defina uma API key; os mesmos comandos passam então a conduzir um modelo real.

Extraia falhas com error analysis

Hamel Husain e Shreya Shankar ensinam um workflow de error analysis precisamente para este passo; o field guide de Hamel descreve-o. Os dois primeiros passos usam nomes da investigação qualitativa, mas o método é simples: leia traces, tome notas e dê nome aos padrões.

1. Open coding: leia 30 a 50 traces reais e escreva notas livres sobre o que correu mal.
2. Axial coding: agrupe essas notas em 5 ou 6 categorias de falha com nome.
3. Atribua labels a tudo de acordo com a taxonomia.
4. Crie métricas para os grupos maiores.

Não comece com labels como reasoning_issue ou tool_problem. São demasiado vagos para serem testáveis. Use labels como missing_identity_verification, date_argument_mismatch, retried_same_tool_after_429 ou stopped_before_database_update. Um label tão específico diz-lhe exactamente o que o teste de regressão deve verificar.

Elimine duplicados antes de promover casos

O loop de trace mining tem uma armadilha: acrescentar eternamente todos os traces problemáticos. Isso cria um dataset grande, caro e estreito. Passa com quase-duplicados de março, mas não deteta a nova forma do mesmo bug em junho.

Agrupe primeiro. Promova um golden representativo por cluster. Armazene os IDs dos traces relacionados nos metadados para que um reviewer possa inspeccionar mais tarde a evidência de produção.

Se um cluster de falhas voltar a ocorrer depois de uma correção, o caso de regressão não generalizou. Volte a agrupar e alargue o golden em vez de adicionar 15 exemplos pontuais.

Versione o dataset

Versione os datasets da mesma forma que versiona prompts e código. Sempre que algo significativo mudar (modelo, prompt, tool schema, judge prompt ou comportamento da aplicação), deve executar a mesma versão do dataset antes e depois.

O gate de CI deve fixar:

• versão do dataset
• versão da aplicação
• versão do prompt
• judge model
• judge prompt
• versão do código do evaluator

Se algum destes elementos mudar, a comparação antes/depois fica pouco clara. Um ficheiro goldens-v3.json no git é suficiente em pequena escala. Snapshots nativos de tools no Langfuse, Phoenix, Braintrust ou LangSmith ajudam quando o dataset se torna colaborativo.

Crie um gate no CI

Uma métrica que falha tem de gerar uma build falhada; caso contrário, a suite de eval é apenas um dashboard que ninguém lê.

O teste deve voltar a executar o agent actual com o input golden. Não deve simplesmente reproduzir o trace antigo que falhou (esboço; a versão executável está no repositório complementar):

@pytest.mark.parametrize("golden", GOLDENS, ids=[item["id"] for item in GOLDENS])
def test_agent_regression(golden: dict) -> None:
    answer, fresh_trace = run_agent_and_capture_trace(golden["input"])

    refired = set(flag_failures(fresh_trace)) & set(golden["failure_modes"])
    assert not refired, f"failure mode regressed: {sorted(refired)}"

    assert tool_correctness(
        called=[call["name"] for call in fresh_trace["tool_calls"]],
        expected=golden["expected_tools"],
        mode=golden.get("tool_match", "in_order"),
    ) >= golden.get("tool_threshold", 1.0)

É fácil confundir esta distinção. A função do dataset é detetar a próxima versão do agent a repetir uma falha antiga, não arquivar a própria falha.

Calibre o judge antes de confiar nele

LLM-as-judge é útil. Também é fácil enganar-se com ele.

G-Eval avalia três benchmarks de meta-avaliação. São o SummEval, criado a partir de sumarização de notícias da CNN/DailyMail; o Topical-Chat, um benchmark de diálogo baseado em conhecimento; e o QAGS, que testa consistência factual em resumos da CNN/DailyMail e do XSum. Usando o GPT-4 como backbone, o G-Eval-4 atingiu uma correlação de Spearman de 0,514 com avaliações humanas no SummEval. A sua função de scoring pondera os níveis de avaliação pela probabilidade dos tokens ($\text{score} = \sum_i p(s_i)\,s_i$).

O artigo estimou as probabilidades dos tokens do GPT-4 através de 20 amostragens, porque esse modelo não as expunha na experiência. Um modelo alojado pode não disponibilizar logprobs utilizáveis; por isso, mantenha a rubric, mas não sugira que reproduziu a ponderação probabilística do artigo. Estes resultados comparam o protocolo do artigo com os seus baselines de NLG nesses benchmarks. Sustentam o teste de um judge com rubric explícita, não a sua substituição geral por métricas automáticas nem um benchmark de trajectórias de agents em produção.

O MT-Bench mostrou que o GPT-4 concordava com as preferências humanas com uma frequência semelhante à concordância entre humanos. Esse resultado ajudou a tornar os LLM judges mainstream. Trabalhos posteriores expuseram enviesamentos de posição, comprimento e self-preference. Os scores do judge também podem mudar quando o prompt ou a versão do modelo muda.

O JudgeBench criou pares de respostas em que uma das respostas está objectivamente errada em conhecimento verificável, raciocínio, matemática e código. Com um prompt de judge simples, o GPT-4o obteve 50,9%, pouco acima do acaso; o prompt Arena-Hard mais forte do artigo elevou o mesmo modelo apenas para 56,6%. Trocar o modelo mantendo esse prompt mais forte tem maior impacto: o Claude 3.5 Sonnet, o melhor judge general-purpose testado, atingiu 64,3%, e o o3-mini com high reasoning effort chegou aos 80,9%. Respostas confiantes mas erradas continuam a ser difíceis de avaliar por um judge que não raciocina antes de avaliar.

Trate o judge como um instrumento de medição: calibre-o com labels humanos antes de o usar para avaliar seja o que for e volte a verificá-lo sempre que mudar o modelo ou o prompt do judge.

Quando for necessário um judge, torne o veredicto estruturado. O Schema-Guided Reasoning (SGR) dá ao veredicto um schema para a forma do output e para a sua inspeccionabilidade. Structured Outputs ou constrained decoding podem impor a forma do objecto, campos obrigatórios e restrições de valores para campos como evidence, passed_criteria, failed_criteria, failure_mode e score.

Coloque os campos de evidência antes do score se isso tornar o registo mais fácil de inspeccionar. A ordem dos campos é uma questão de apresentação, não uma garantia de raciocínio. Um veredicto válido segundo o schema pode, ainda assim, conter evidência sem suporte ou um score pouco fiável. Use a calibração com labels humanos, validadores determinísticos e revisão do transcript para testar a fiabilidade do judge. O CI pode comparar um objecto JSON estável, mas isso verifica a inspeccionabilidade e a forma, não prova que as etapas da rubric foram seguidas.

Um veredicto estruturado também pode alterar a curva de custos. Trate um modelo mais barato como candidato, não como substituto automático. Execute-o sobre o mesmo conjunto de calibração com labels humanos. Compare a concordância, a taxa de falsos positivos de aprovação e a taxa de falsos positivos de reprovação com o judge maior. Use-o para casos rotineiros apenas se ultrapassar os limiares definidos pela sua aplicação. Mantenha o judge maior para discordâncias, casos de alto risco ou execuções de calibração.

Checklist predefinida de higiene do judge:

1. Prefira pass/fail binário sempre que possível. Escalas de cinco pontos convidam a uma precisão falsa.
2. Faça a anotação manual de 30 a 50 trajectórias antes de escrever a rubric final.
3. Meça a concordância entre o judge e os humanos com o kappa de Cohen, uma matriz de confusão e recall positivo/negativo. Um judge que responde sempre “pass” não tem capacidade de discriminação útil; o kappa pode ser zero ou indefinido quando o denominador da concordância esperada é zero. Defina explicitamente uma política para kappa indefinido antes de usar a métrica como gate de deployment.
4. Decomponha critérios amplos. “O agent verificou a identidade antes da tool call de reembolso?” é melhor do que “A trajectória foi boa?”
5. Emita o veredicto através de um schema SGR com evidência, critérios falhados, modo de falha e score.
6. Use, quando possível, um judge de uma família de modelos diferente da do generator.
7. Randomize a ordem dos pares e calcule a média nas duas direcções.
8. Penalize no rubric o comprimento sem suporte. Uma resposta mais longa não é necessariamente melhor.
9. Fixe o modelo do judge, o prompt, o dataset, o schema e a versão da aplicação.
10. Volte a calibrar depois de alterações ao modelo, prompt, tool, política ou schema.

Para scores de alto risco, use um pequeno júri em vez de um único judge grande. O PoLL testou um painel de judges mais pequenos, provenientes de famílias de modelos disjuntas, e agregou os seus veredictos. Em seis datasets, o painel acompanhou melhor as avaliações humanas do que um único judge GPT-4. Evitou também o enviesamento de self-preference do judge único e custou mais de sete vezes menos. Mantenha a revisão humana para decisões que afectem dinheiro, acesso, segurança ou conformidade.

Se um judge concordar com os humanos com um kappa de 0,55 na sua tarefa, não o use para bloquear deployments. Use-o para ordenar filas de revisão. Se estiver perto de 0,75 e o custo da falha for moderado, um gate de CI é muito mais fácil de justificar.

Os guardrails bloqueiam inline; os evals online observam depois

As pessoas confundem estes mecanismos porque ambos produzem scores. A diferença está na colocação: inline no caminho do pedido, antes da release ou depois da resposta.

Guardrails executam-se inline. São rápidos e visíveis para o utilizador. Um guardrail pode bloquear uma tool call, redigir PII, rejeitar prompt injection ou forçar um retry antes de a resposta sair do sistema. Um falso positivo é um bug de produção. Um falso negativo é mais silencioso e pior, porque nada no caminho do pedido o comunica. As verificações de schema, intervalo e política são determinísticas. A deteção de injection e PII são classificadores; por isso, trate as falhas como esperadas e mantenha um eval assíncrono a observar o que deixaram passar.

Evals offline executam-se antes da release. São reproduzíveis. Fazem o gate de prompts, modelos, tools, retrievers e políticas contra um dataset fixo.

Evals online executam-se depois da resposta, normalmente sobre tráfego amostrado. Podem usar LLM judges mais lentos porque não estão no caminho da latência. A sua função é detetar drift, encontrar novos clusters de falhas e alimentar o dataset offline seguinte.

Colocar o mecanismo no sítio errado prejudica o sistema de qualquer forma:

• Um judge no caminho do pedido acrescenta latência e uma nova fonte de instabilidade.
• Um guardrail relegado para scoring assíncrono permite que violações de política cheguem aos utilizadores.

Em sistemas de grande volume, avalie uma amostra pequena com um judge mais forte e uma amostra maior com classificadores mais baratos. Emita alertas para clusters e intervalos de confiança, não para uma única estimativa pontual ruidosa.

Escolha de ferramentas

Nenhuma tool é responsável por todo o loop. Compare separadamente um trace/dataset store e um CI/eval runner; um produto pode cobrir ambos, mas não precisa de comprar os dois ao mesmo vendor.

Este é um snapshot do autor verificado em 2026-08-16. Cada link corresponde à documentação actual que usei para a afirmação sobre a capacidade. Continuam a aplicar-se os planos, licenças, API keys, acesso a providers e requisitos de infraestrutura.

As notas sobre trade-offs descrevem a origem do custo, não o seu valor. As páginas de preços mudam, e os vendors contam coisas diferentes: traces, observations, spans, scores, utilizadores, retenção ou dados processados. Volte a verificar os preços actuais antes de se comprometer.

Recomendações por restrição:

• Escolha Phoenix quando self-hosting, privacidade e tracing compatível com OTel forem requisitos obrigatórios e a sua equipa conseguir operar o deployment.
• Escolha Langfuse quando também precisar de versionamento de datasets e experiências, e puder operar a sua stack de armazenamento ou comprar os add-ons necessários.
• Escolha DeepEval quando o contrato principal for pass/fail em CI com Python/pytest.
• Escolha Inspect AI quando o trabalho principal for a avaliação de segurança ou de frontier agents em sandboxes configuráveis.
• Escolha LangSmith quando a integração com LangChain/LangGraph compensar o requisito Enterprise para deployment hybrid ou self-hosted.
• Escolha Braintrust quando o feedback gerido em pull requests e a comparação de experiências justificarem um serviço suportado por API key.
• Escolha Promptfoo quando os checks de prompts ou red-team forem a principal superfície de regressão e um trace store estiver fora do âmbito.

A escolha da tool é secundária. Se as falhas de produção não se transformarem em casos de teste, está sobretudo a pagar por armazenamento de traces.

Checklist prática de rollout

Construa o pipeline de evidência antes de expandir a stack de métricas. Comece por decidir de onde virão os exemplos.

1. Recolha primeiro as execuções históricas. Se o agent já existir, recolha traces, tickets de suporte, relatórios de bugs, sessões com thumbs-down, transcripts de QA manual e notas de dogfooding antes de alterar a implementação. Se o agent ainda não existir, registe todas as execuções de protótipos e testes manuais desde o primeiro dia.

2. Instrumente a forma do trace. Capture mensagens, tool calls, argumentos, outputs das tools, erros, contagens de tokens, latência, custo, feedback do utilizador, versão da aplicação, versão do prompt, versão do modelo, versão do tool schema e estado final do ambiente. Use as convenções OpenTelemetry GenAI ou spans ao estilo OpenInference se quiser portabilidade. Use Langfuse, LangSmith, Phoenix ou Braintrust se quiser imediatamente uma UI de traces e um workflow de datasets.

3. Transforme falhas reais em casos seed. Leia os traces antes de os resumir com um modelo. Para cada falha útil, armazene o input, o ID do trace de origem, o estado esperado, os invariantes esperados das tools, o modo de falha, a severidade e a nota do reviewer. O Langfuse pode associar itens do dataset aos traces de produção; o LangSmith pode criar datasets a partir de execuções com traces. Mantenha o link de origem para que o caso permaneça auditável.

4. Se não houver histórico, gere casos de cold start. Peça a um LLM para criar tarefas a partir de requisitos do produto, políticas, tool schemas, máquinas de estados e macros de suporte. Cubra percursos felizes e falhas como permissões incorrectas, verificações de identidade em falta, resultados de tools desactualizados, datas ambíguas, retries depois de rate limits e outputs contraditórios das tools.

5. Não confie em casos sintéticos sem revisão humana. Exemplos sintéticos são úteis para cobertura, não para determinar a verdade. Marque-os com source: synthetic e exija que um reviewer aprove o resultado esperado. Execute um percurso de referência conhecido como correcto quando possível e use famílias de modelos diferentes para gerar o caso e avaliar o resultado.

6. Construa um dataset pequeno e equilibrado. Inclua sucessos, falhas, recusas, casos-limite, casos com muitos turnos, casos sensíveis à política e percursos alternativos válidos. Não transforme o golden no “transcript antigo exacto”. Armazene tudo o que um golden deve armazenar, além do modo de falha que colocou o caso na suite.

7. Adicione primeiro verificações determinísticas. A ordem obrigatória das tools quando a ordem for política, os argumentos obrigatórios, a validação do schema, as diferenças do estado final, os limites de loops e os limites de tokens e latência, bem como os invariantes específicos da tarefa, devem ser executados antes de qualquer judge.

8. Adicione um judge com estrutura SGR. Use-o apenas para a parte que exige interpretação. Calibre-o com labels humanos. Se não conseguir separar exemplos bons e maus no conjunto de calibração, corrija a rubric antes de o ligar ao CI.

9. Ligue o loop. Execute a suite offline pequena no CI, a suite maior antes da release, avalie online tráfego de produção amostrado e promova os clusters recorrentes de falhas online de volta ao dataset offline.

A sua primeira suite de eval terá erros aborrecidos. Publique-a na mesma. Uma suite que é executada todos os dias é mais fácil de corrigir do que um design doc perfeito que nunca bloqueia uma PR problemática.

Referências

• Repositório de demonstração complementar trace2evals
• LangChain - State of Agent Engineering
• Anthropic - Demystifying Evals for AI Agents
• Hamel Husain - A Field Guide to Rapidly Improving AI Products
• OpenTelemetry semantic conventions for generative AI systems
• DeepEval Tool Correctness
• DeepEval Task Completion
• DeepEval unit testing in CI/CD
• Inspect running evals
• OpenAI Structured model outputs
• Schema-Guided Reasoning: vLLM, xgrammar, and Pydantic
• Phoenix self-hosting
• Langfuse datasets and versioning
• Langfuse experiments in CI/CD
• LangSmith platform setup
• LangSmith - Create and manage datasets programmatically
• Braintrust - Create experiments
• Phoenix LLM evals
• Promptfoo GitHub Action integration
• tau-bench: A Benchmark for Tool-Agent-User Interaction in Real-World Domains
• Why Do Multi-Agent LLM Systems Fail?
• Establishing Best Practices for Building Rigorous Agentic Benchmarks
• G-Eval: NLG Evaluation using GPT-4 with Better Human Alignment
• Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena
• Replacing Judges with Juries: Evaluating LLM Generations with a Panel of Diverse Models
• JudgeBench: A Benchmark for Evaluating LLM-based Judges
• Self-Preference Bias in LLM-as-a-Judge