Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Avaliar os Seus Agentes: Métricas e Benchmarks

Aula 22 de 25 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Avaliar os Seus Agentes: Métricas e Benchmarks
  2. Por Que Avaliar?
  3. Métricas Principais
  4. Avaliação por LLM (LLM-as-Judge)
  5. Conjuntos de Testes Estruturados
  6. Pontos-chave

Avaliar os Seus Agentes: Métricas e Benchmarks

Um agente que funciona em desenvolvimento pode falhar em produção. A avaliação sistemática é a única forma de garantir a qualidade antes e depois da implementação. Nesta lição, irá aprender a definir métricas, criar conjuntos de testes e automatizar a avaliação.

Por Que Avaliar?

Sem uma avaliação formal, está a voar às cegas. Reformula uma instrução porque um utilizador se queixou, mas nada lhe diz se o agente melhorou ou se acabou de quebrar três outros cenários. Hesita entre o Terra e o Luna para o seu caso de uso — ou entre dois níveis de raciocínio no mesmo modelo — e, sem medição, a decisão baseia-se num palpite após cinco testes manuais. Altera o esquema de uma ferramenta, o agente deixa de a chamar num caso específico e ninguém nota até o volume de tickets disparar. Um conjunto de avaliação transforma cada uma destas situações num número comparável de uma versão para a outra.

Métricas Principais

Precisão

A primeira pergunta é a mais direta: o agente dá a resposta certa? Reproduz um conjunto de perguntas onde conhece a resposta e verifica a sua presença na saída. A correspondência de substrings insensível a maiúsculas/minúsculas é intencionalmente grosseira — tolera “O portátil Pro custa 1.299 € com IVA” onde a igualdade estrita falharia — mas é suficiente para factos verificáveis e calcula-se num segundo.

from agents import Agent, Runner

async def evaluate_accuracy(agent, test_cases):
    results = []
    for case in test_cases:
        result = await Runner.run(agent, case["question"])
        # Verificação automática ou baseada em LLM
        is_correct = case["expected_answer"].lower() in result.final_output.lower()
        results.append({
            "question": case["question"],
            "answer": result.final_output,
            "expected": case["expected_answer"],
            "correct": is_correct,
        })

    rate = sum(1 for r in results if r["correct"]) / len(results)
    print(f"Accuracy: {rate:.1%} ({sum(1 for r in results if r['correct'])}/{len(results)})")
    return results

# Conjunto de testes
test_cases = [
    {"question": "Qual é o preço do portátil Pro?", "expected_answer": "1299"},
    {"question": "Quantos portáteis estão em stock?", "expected_answer": "45"},
    {"question": "Qual é o produto mais barato?", "expected_answer": "tablet"},
]

Utilização Correta de Ferramentas

Uma resposta correta obtida por acaso continua a ser um problema. Um agente que recita um preço memorizado em vez de consultar o catálogo passará no teste de precisão hoje e dará uma taxa desatualizada amanhã. A segunda métrica olha, portanto, para o caminho, não para o resultado: o agente chama as ferramentas certas com os argumentos certos? Lê as chamadas em raw_responses, filtrando as saídas function_call, e a comparação utiliza conjuntos para permanecer indiferente à ordem.

async def evaluate_tools(agent, test_cases):
    results = []
    for case in test_cases:
        result = await Runner.run(agent, case["question"])

        # Extrair ferramentas chamadas das respostas brutas
        called_tools = []
        for response in result.raw_responses:
            for output in getattr(response, "output", []):
                if hasattr(output, "type") and output.type == "function_call":
                    called_tools.append(output.name)

        tools_correct = set(case["expected_tools"]) == set(called_tools)
        results.append({
            "question": case["question"],
            "called_tools": called_tools,
            "expected_tools": case["expected_tools"],
            "correct": tools_correct,
        })

    rate = sum(1 for r in results if r["correct"]) / len(results)
    print(f"Correct tools: {rate:.1%}")
    return results

tool_cases = [
    {
        "question": "Qual é o preço do portátil?",
        "expected_tools": ["search_product"],
    },
    {
        "question": "Preço do portátil com 10% de desconto",
        "expected_tools": ["search_product", "calculate_discount"],
    },
]

O segundo caso de teste é o mais instrutivo: a pergunta exige encadear duas ferramentas, e este é exatamente o tipo de composição que uma alteração na descrição pode quebrar silenciosamente.

Latência e Custo

Finalmente, existe a dimensão operacional. Uma média não diz nada sobre a experiência real: é a cauda da distribuição que afasta os utilizadores, quando um pedido em cada cem demora vinte segundos. Ao repetir cada mensagem várias vezes, obtém uma distribuição utilizável e lê a mediana como o comportamento típico, e o P99 como o seu pior cenário comum.

import time

async def evaluate_performance(agent, messages, iterations=10):
    latencies = []
    for message in messages:
        for _ in range(iterations):
            start = time.perf_counter()
            result = await Runner.run(agent, message)
            duration = time.perf_counter() - start
            latencies.append(duration)

    import statistics
    print(f"Average latency: {statistics.mean(latencies):.2f}s")
    print(f"P50 latency: {statistics.median(latencies):.2f}s")
    print(f"P99 latency: {sorted(latencies)[int(len(latencies) * 0.99)]:.2f}s")

Avaliação por LLM (LLM-as-Judge)

Estas três métricas deixam de fora tudo o que não tem uma única resposta correta: uma explicação de uma política de devolução, uma reformulação de vendas, uma mensagem de desculpa. Para estas respostas abertas, utilize um modelo para avaliar a qualidade. O juiz recebe a pergunta e a resposta, aplica critérios que escreveu — precisão, relevância, profissionalismo — e devolve uma pontuação estruturada graças a um output_type Pydantic. A restrição de formato é o que torna o processo utilizável: obtém um inteiro agregável, não um comentário para reler.

from pydantic import BaseModel

class Evaluation(BaseModel):
    score: int  # 1-5
    reason: str
    is_correct: bool
    is_relevant: bool
    is_professional: bool

evaluator_agent = Agent(
    name="Evaluator",
    instructions="""Evaluate the quality of the agent's response.
    Criteria:
    - Accuracy: Is the response factual and correct?
    - Relevance: Does the response answer the question asked?
    - Professionalism: Is the tone appropriate?
    Score from 1 (very poor) to 5 (excellent).""",
    model="gpt-5.6-sol",
    output_type=Evaluation,
)

async def evaluate_quality(question, agent_response):
    prompt = f"""Question asked: {question}
    Agent response: {agent_response}
    Evaluate this response."""

    result = await Runner.run(evaluator_agent, prompt)
    return result.final_output

O campo reason merece a sua atenção durante as revisões: é aqui que o juiz explica por que razão atribuiu 3 em 5, e é frequentemente a formulação de uma falha que não tinha conseguido nomear.

Conjuntos de Testes Estruturados

Uma avaliação que não é reproduzível é inútil. Organize os seus casos de teste num formato estável onde cada entrada carrega um ID, uma categoria, a pergunta, a resposta esperada, as ferramentas esperadas e critérios qualitativos. A categoria faz todo o trabalho aqui: uma pontuação global de 4,2 em 5 é enganadoramente tranquilizadora, enquanto uma pontuação detalhada revela que a categoria “stock” colapsa para 2,8 enquanto “preço” puxa a média para cima.

import json

# evaluation_dataset.json
DATASET = [
    {
        "id": "test_001",
        "category": "price",
        "question": "Qual é o preço do portátil Pro?",
        "expected_answer": "1.299 €",
        "expected_tools": ["search_product"],
        "criteria": ["contains_price", "professional_tone"],
    },
    {
        "id": "test_002",
        "category": "stock",
        "question": "O Tablet Air está em stock?",
        "expected_answer": "sim",
        "expected_tools": ["search_product"],
        "criteria": ["clear_answer", "stock_information"],
    },
]

async def run_complete_evaluation(agent):
    results = []
    for case in DATASET:
        result = await Runner.run(agent, case["question"])
        eval_result = await evaluate_quality(case["question"], result.final_output)
        results.append({
            **case,
            "agent_response": result.final_output,
            "score": eval_result.score,
            "evaluation": eval_result.reason,
        })

    # Relatório
    average_score = sum(r["score"] for r in results) / len(results)
    print(f"\nAverage score: {average_score:.1f}/5")
    for cat in set(r["category"] for r in results):
        cat_scores = [r["score"] for r in results if r["category"] == cat]
        print(f"  {cat}: {sum(cat_scores)/len(cat_scores):.1f}/5")

    return results

Execute esta avaliação no seu pipeline de integração contínua, tal como os seus testes unitários, e defina um limiar abaixo do qual a entrega é bloqueada. A partir desse momento, cada alteração — novo modelo, instruções ajustadas, ferramenta adicionada — compara-se com a anterior nos mesmos casos, e a discussão deixa de girar em torno de impressões.

Pontos-chave

  • Avalie a precisão, a utilização de ferramentas, a latência e o custo
  • A avaliação por LLM (LLM-as-Judge) lida com respostas abertas
  • Crie conjuntos de testes estruturados e reproduzíveis
  • Automatize a avaliação no seu CI/CD para detetar regressões
  • Compare sistematicamente as alterações (modelo, instruções, ferramentas)