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

Avaliação de traços: pontuação de execuções

Aula 23 de 25 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Avaliação de traços: pontuação de execuções
  2. O conceito de avaliação de traços
  3. Avaliação automática com regras
  4. Avaliação baseada em LLM
  5. Pipeline de avaliação em produção
  6. Painel de qualidade
  7. Pontos-chave

Avaliação de traços: pontuação de execuções

O registo de traços documenta o que o seu agente faz. Isso é essencial, mas não é suficiente: ninguém lê dez mil traços por dia, e os problemas escondem-se precisamente naqueles que nunca abre. A avaliação de traços vai mais longe: pontua automaticamente cada execução para detetar problemas, medir a qualidade ao longo do tempo e alimentar um ciclo de melhoria contínua.

O conceito de avaliação de traços

Cada traço produzido pelo seu agente contém a execução completa: a mensagem do utilizador, as chamadas de ferramentas, as respostas intermédias e a resposta final. A avaliação de traços analisa estes registos e atribui pontuações com base nos seus critérios. Passa de um registo que consulta a posteriori para uma métrica que monitoriza continuamente, e a pergunta “Como está o agente a desempenhar agora?” deixa de ser um palpite.

Avaliação automática com regras

O nível mais simples utiliza regras programáticas para pontuar cada traço. Cada regra parte de uma pontuação perfeita de 1,0 e deduz pontos com base no que observa. Uma execução que demore mais de dez segundos perde 0,2 pontos, não porque o resultado esteja errado, mas porque o utilizador provavelmente desistiu. Mais de quinze turnos custa 0,3 pontos: essa é a assinatura de um agente a girar em círculos entre duas ferramentas. Cada erro de ferramenta deduz 0,1 pontos. As barreiras de segurança acionadas são sinalizadas sem penalização — fizeram o seu trabalho —, mas uma resposta com menos de dez caracteres custa sozinha meio ponto, porque um agente silencioso é um agente inútil.

from dataclasses import dataclass

@dataclass
class GradeTrace:
    trace_id: str
    score: float  # 0.0 to 1.0
    details: dict
    alerts: list[str]

def grade_trace(trace_data: dict) -> GradeTrace:
    """Scores a trace based on business rules."""
    score = 1.0
    alerts = []
    details = {}

    # Rule 1: Latency
    duration = trace_data.get("duration_ms", 0)
    if duration > 10000:
        score -= 0.2
        alerts.append(f"High latency: {duration}ms")
    details["latency_ms"] = duration

    # Rule 2: Number of turns
    num_turns = trace_data.get("num_turns", 0)
    if num_turns > 15:
        score -= 0.3
        alerts.append(f"Too many turns: {num_turns}")
    details["num_turns"] = num_turns

    # Rule 3: Tool errors
    tool_errors = trace_data.get("tool_errors", 0)
    if tool_errors > 0:
        score -= 0.1 * tool_errors
        alerts.append(f"{tool_errors} tool error(s)")
    details["tool_errors"] = tool_errors

    # Rule 4: Triggered guardrails
    guardrails = trace_data.get("guardrails_triggered", 0)
    if guardrails > 0:
        alerts.append(f"{guardrails} guardrail(s) triggered")
    details["guardrails"] = guardrails

    # Rule 5: Empty response
    response = trace_data.get("final_output", "")
    if not response or len(response) < 10:
        score -= 0.5
        alerts.append("Empty or too short response")
    details["response_length"] = len(response)

    return GradeTrace(
        trace_id=trace_data["trace_id"],
        score=max(0.0, score),
        details=details,
        alerts=alerts,
    )

O dicionário details acompanha sempre a pontuação: sem ele, saberia que uma execução obteve 0,5, mas não saberia porquê. Estes limiares são seus, não constantes universais — um agente de investigação tolera quinze turnos, enquanto um assistente de checkout deve responder em três.

Avaliação baseada em LLM

As regras não veem o conteúdo. Uma resposta rápida, curta e educada que falha completamente o alvo obterá 1,0. Para uma avaliação mais fina, utilize um modelo para pontuar os traços quanto ao substância: relevância, precisão e tom, cada um de 1 a 5, juntamente com problemas identificados e sugestões de melhoria. Mais uma vez, a saída estruturada via Pydantic torna as pontuações agregáveis, em vez de produzir comentários em formato livre.

from pydantic import BaseModel
from agents import Agent, Runner

class GradeLLM(BaseModel):
    relevance_score: int  # 1-5
    accuracy_score: int  # 1-5
    tone_score: int  # 1-5
    issues: list[str]
    suggestions: list[str]

grader_agent = Agent(
    name="Trace Grader",
    instructions="""You score executions of a sales agent.

    Analyze the full trace (question, tools called, response) and score:
    - Relevance (1-5): Does the response answer the question?
    - Accuracy (1-5): Is the information correct?
    - Tone (1-5): Is the tone professional and appropriate?

    Identify issues and propose improvements.""",
    model="gpt-5.6-sol",
    output_type=GradeLLM,
)

async def grade_trace_llm(trace: dict) -> GradeLLM:
    prompt = f"""Execution trace to score:

    User question: {trace['user_message']}
    Tools called: {trace['tools_called']}
    Final response: {trace['final_output']}
    Duration: {trace['duration_ms']}ms
    Number of turns: {trace['num_turns']}"""

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

O prompt também passa as ferramentas chamadas e a duração: o avaliador pode assim culpar o agente por responder sem consultar o catálogo, algo que a leitura isolada da resposta não permitiria.

Pipeline de avaliação em produção

Combine agora ambas as abordagens sem explodir o seu orçamento. Pontuar cada traço com um LLM ao volume de produção multiplica a sua fatura de inferência; usar apenas regras deixa-o cego quanto à substância. O pipeline abaixo aplica um filtro: todos os traços passam pela avaliação programática, que é rápida e gratuita, e apenas os que ficam abaixo de 0,7 vão para o avaliador. A pontuação do avaliador, a soma de três classificações de 1–5, é escalada para 0–1 dividindo por 15 para se manter comparável à primeira. Abaixo de 0,5, o traço entra na lista de alertas críticos.

import asyncio
from collections import defaultdict

class GradingPipeline:
    def __init__(self):
        self.scores = defaultdict(list)
        self.critical_alerts = []

    async def grade_batch(self, traces: list[dict]):
        """Scores a batch of traces."""
        for trace in traces:
            # Programmatic grading (fast)
            rule_grade = grade_trace(trace)

            # LLM grading for borderline cases
            if rule_grade.score < 0.7:
                llm_grade = await grade_trace_llm(trace)
                final_score = (
                    llm_grade.relevance_score +
                    llm_grade.accuracy_score +
                    llm_grade.tone_score
                ) / 15.0  # Normalize to 0-1
            else:
                final_score = rule_grade.score

            self.scores["global"].append(final_score)

            # Alerts
            if final_score < 0.5:
                self.critical_alerts.append({
                    "trace_id": trace["trace_id"],
                    "score": final_score,
                    "alerts": rule_grade.alerts,
                })

    def report(self):
        """Generates a quality report."""
        scores = self.scores["global"]
        if not scores:
            return "No traces evaluated."

        import statistics
        return {
            "num_traces": len(scores),
            "avg_score": statistics.mean(scores),
            "median_score": statistics.median(scores),
            "min_score": min(scores),
            "pct_critical": len(self.critical_alerts) / len(scores),
            "critical_alerts": self.critical_alerts[:10],
        }

# Usage
pipeline = GradingPipeline()
await pipeline.grade_batch(traces_of_the_day)
print(pipeline.report())

O relatório mantém a pontuação mínima e uma amostra dos dez piores traços: é aí que começa uma investigação, nunca com a média.

Painel de qualidade

Uma única pontuação não significa nada; é a sua trajetória que informa. Ao escrever o relatório diário num ficheiro JSONL, constrói uma série temporal que qualquer ferramenta de visualização pode ler, e pode comparar automaticamente o ponto mais recente com o anterior. Uma queda superior a 0,1 desencadeia um alerta de regressão — e correlacioná-la com as suas implementações do dia geralmente aponta o culpado em minutos.

import json
from datetime import datetime

def log_metrics(report: dict, file: str = "agent_metrics.jsonl"):
    """Logs daily metrics."""
    entry = {
        "date": datetime.now().isoformat(),
        **report,
    }
    with open(file, "a") as f:
        f.write(json.dumps(entry) + "\n")

def detect_regression(recent_metrics: list[dict], threshold: float = 0.1):
    """Detects a significant quality drop."""
    if len(recent_metrics) < 2:
        return False
    latest = recent_metrics[-1]["avg_score"]
    previous = recent_metrics[-2]["avg_score"]
    drop = previous - latest
    if drop > threshold:
        print(f"REGRESSION DETECTED: score dropped from {previous:.2f} to {latest:.2f}")
        return True
    return False

Comparar dois dias consecutivos permanece sensível ao ruído: em baixo volume, prefira uma média móvel antes de gritar “regressão”, ou estará a perseguir um desvio estatístico.

Pontos-chave

  • A avaliação de traços pontua automaticamente cada execução do seu agente
  • Regras programáticas (latência, erros, comprimento) são rápidas e fiáveis
  • A avaliação por LLM avalia a relevância, a precisão e o tom
  • Combine ambas: regras rápidas para filtragem, LLM para casos limítrofes
  • Acompanhe as pontuações ao longo do tempo para detetar regressões
  • Alertas críticos (pontuação < 0,5) devem desencadear uma investigação