Salt la conținutul principal
Română— Alege o limbă
Meniu

Evaluarea agenților dumneavoastră: Metrici și repere

Lecția 22 din 25 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Evaluarea agenților dumneavoastră: Metrici și repere
  2. De ce să evaluați?
  3. Metrici de bază
  4. Evaluarea prin LLM (LLM-as-Judge)
  5. Suite de testare structurate
  6. Puncte cheie

Evaluarea agenților dumneavoastră: Metrici și repere

Un agent care funcționează în dezvoltare poate eșua în producție. Evaluarea sistematică este singura modalitate de a garanta calitatea înainte și după implementare. În această lecție, veți învăța cum să definiți metrici, să creați suite de testare și să automatizați evaluarea.

De ce să evaluați?

Fără o evaluare formală, zburați la întâmplare. Reformulați o instrucțiune deoarece un utilizator s-a plâns, dar nimic nu vă spune dacă agentul s-a îmbunătățit sau dacă tocmai ați stricat alte trei scenarii. Ezitați între Terra și Luna pentru cazul dumneavoastră de utilizare—sau între două niveluri de raționament pe același model—și fără măsurători, decizia se bazează pe o intuiție după cinci încercări manuale. Modificați o schemă de instrument, agentul încetează să îl mai apeleze într-un caz specific, iar nimeni nu observă până când volumul de tichete nu explodează. O suită de evaluare transformă fiecare dintre aceste situații într-un număr comparabil de la o versiune la alta.

Metrici de bază

Acuratețe

Prima întrebare este cea mai directă: oferă agentul răspunsul corect? Redați un set de întrebări pentru care cunoașteți răspunsul și verificați prezența acestuia în ieșire. Potrivirea șirurilor de caractere insensibilă la majuscule/minuscule este intenționat grosieră—tolerează „Laptopul Pro costă 1.299 € cu TVA inclus“ acolo unde egalitatea strictă ar eșua—dar este suficientă pentru fapte verificabile și se calculează într-o secundă.

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"])
        # Automatic or LLM-based verification
        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

# Test suite
test_cases = [
    {"question": "What is the price of the Pro laptop?", "expected_answer": "1299"},
    {"question": "How many laptops are in stock?", "expected_answer": "45"},
    {"question": "What is the cheapest product?", "expected_answer": "tablet"},
]

Utilizarea corectă a instrumentelor

Un răspuns corect obținut din întâmplare rămâne o problemă. Un agent care recită un preț memorat în loc să interogheze catalogul va trece testul de acuratețe astăzi și va oferi o rată învechită mâine. A doua metrică privește therefore calea, nu rezultatul: apelează agentul instrumentele potrivite cu argumentele corecte? Citiți apelurile în raw_responses, filtrând ieșirile function_call, iar comparația utilizează seturi pentru a rămâne indiferentă la ordine.

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

        # Extract called tools from raw responses
        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": "What is the price of the laptop?",
        "expected_tools": ["search_product"],
    },
    {
        "question": "Price of the laptop with 10% discount",
        "expected_tools": ["search_product", "calculate_discount"],
    },
]

Al doilea caz de test este cel mai instructiv: întrebarea necesită înlănțuirea a două instrumente, iar aceasta este exact genul de compoziție pe care o modificare a descrierii o poate strica în tăcere.

Latență și cost

În final, există dimensiunea operațională. O medie nu spune nimic despre experiența reală: coada distribuției este cea care îndepărtează utilizatorii, atunci când una din o sută de cereri durează douăzeci de secunde. Repetând fiecare mesaj de mai multe ori, obțineți o distribuție utilizabilă și citiți mediana ca comportament tipic, iar P99 ca scenariu obișnuit de caz cel mai defavorabil.

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")

Evaluarea prin LLM (LLM-as-Judge)

Aceste trei metrici lasă deoparte orice nu are un singur răspuns corect: o explicație a politicii de retur, o reformulare de vânzări, un mesaj de scuze. Pentru aceste răspunsuri deschise, utilizați un model pentru a evalua calitatea. Judecătorul primește întrebarea și răspunsul, aplică criterii pe care le-ați scris—acuratețe, relevanță, profesionalism—și returnează un scor structurat datorită unui output_type Pydantic. Constrângerea de format este ceea ce face procesul utilizabil: obțineți un întreg agregabil, nu un comentariu de recitit.

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

Câmpul reason merită atenția dumneavoastră în timpul revizuirilor: aici judecătorul explică de ce a acordat 3 din 5, iar aceasta este adesea formularea unui defect pe care nu ați reușit să îl numiți.

Suite de testare structurate

O evaluare care nu este reproductibilă este inutilă. Organizați cazurile de test într-un format stabil unde fiecare intrare conține un ID, o categorie, întrebarea, răspunsul așteptat, instrumentele așteptate și criteriile calitative. Categoria face toată munca aici: un scor global de 4,2 din 5 este înșelător de reconfortant, în timp ce un scor detaliat relevă faptul că categoria „stoc“ se prăbușește la 2,8, în timp ce „preț“ trage media în sus.

import json

# evaluation_dataset.json
DATASET = [
    {
        "id": "test_001",
        "category": "price",
        "question": "What is the price of the Pro laptop?",
        "expected_answer": "€1,299",
        "expected_tools": ["search_product"],
        "criteria": ["contains_price", "professional_tone"],
    },
    {
        "id": "test_002",
        "category": "stock",
        "question": "Is the Tablet Air in stock?",
        "expected_answer": "yes",
        "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,
        })

    # Report
    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

Rulați această evaluare în pipeline-ul dumneavoastră de integrare continuă, la fel ca testele unitare, și stabiliți un prag sub care livrarea este blocată. De atunci, fiecare modificare—model nou, instrucțiuni ajustate, instrument adăugat—se compară cu cea anterioară pe aceleași cazuri, iar discuția încetează să se învârtă în jurul impresiilor.

Puncte cheie

  • Evaluați acuratețea, utilizarea instrumentelor, latența și costul
  • Evaluarea prin LLM (LLM-as-Judge) gestionează răspunsurile deschise
  • Creați suite de testare structurate și reproductibile
  • Automatizați evaluarea în CI/CD pentru a detecta regresii
  • Comparați sistematic modificările (model, instrucțiuni, instrumente)