Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Evalwa l-Aġenti Tiegħek: Metriċi u Punti ta' Referenza

Lezzjoni 22 / 25 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Evalwa l-Aġenti Tiegħek: Metriċi u Punti ta’ Referenza
  2. Għaliex Tevalwa?
  3. Metriċi Ewlenin
  4. Evalwazzjoni permezz ta’ LLM (LLM-as-Judge)
  5. Settijiet ta’ Testijiet Strutturati
  6. Punti Ewlenin

Evalwa l-Aġenti Tiegħek: Metriċi u Punti ta’ Referenza

Aġent li jaħdem fl-iżvilupp jista’ jfalli fil-produzzjoni. L-evalwazzjoni sistematika hija l-uniku mod biex tiggarantixxi l-kwalità qabel u wara l-implimentazzjoni. F’din il-lezzjoni, se titgħallem kif tiddefinixxi l-metriċi, toħloq settijiet ta’ testijiet, u tawtomatizza l-evalwazzjoni.

Għaliex Tevalwa?

Mingħajr evalwazzjoni formali, qed itir bl-individwu. Terġa’ tifformula istruzzjoni għax utent ilmenta, iżda xejn ma jgħidlek jekk l-aġent titjibx jew jekk sempliċiment kisserx tliet xenarji oħra. Tittardja bejn Terra u Luna għall-każ ta’ użu tiegħek—jew bejn żewġ livelli ta’ raġunar fuq l-istess mudell—u mingħajr kejl, id-deċiżjoni tibqa’ fuq is-sensazzjoni wara ħames provi manwali. Tibdel skema ta’ għodda, l-aġent jieqaf isejjaħha f’każ speċifiku, u ħadd ma jinnota sakemm il-volum tat-tikketti jiżdied b’mod qawwi. Sett ta’ evalwazzjoni jħawwal kull waħda minn dawn is-sitwazzjonijiet f’numru li tista’ tqabbel minn verżjoni għall-oħra.

Metriċi Ewlenin

Preċiżjoni

L-ewwel mistoqsija hija l-aktar diretta: l-aġent jagħti t-tweġiba t-tajba? Doħħol mill-ġdid sett ta’ mistoqsijiet fejn taf it-tweġiba u vverifika l-preżenza tagħha fl-output. It-tqabbil ta’ sottostringa insensittiv għall-każ huwa intenzjonalment grossolan—jittollera “Il-laptop Pro jiswa €1,299 inkluż it-taxxa” fejn l-ugwaljanza stretta tkun tfalli—iżda biżżejjed għal fatti verifikabbli u jikkalkula f’sekonda.

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"])
        # Verifika awtomatika jew ibbażata fuq 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

# Sett ta' testijiet
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"},
]

Użu Korrett tal-Għodod

Tweġiba korretta miksuba b’kumbinazzjoni tibqa’ problema. Aġent li jirreċita prezz memorizzat minflok ma jikkonsulta l-katalogu jgħaddi mit-test tal-preċiżjoni llum u jagħti rata antiquata għada. Għalhekk, it-tieni metrika tħares lejn il-mogħdija, mhux lejn ir-riżultat: l-aġent isejjaħ l-għodod it-tajbin bl-argumenti t-tajbin? Taqra s-sejħiet f’raw_responses, tiffiltra għal outputs function_call, u t-tqabbil juża settijiet biex jibqa’ indifferenti għall-ordni.

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

        # Estrazzjoni tal-għodod imsejħa mir-risposti mhux ipproċessati
        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"],
    },
]

It-tieni każ ta’ test huwa l-aktar istruttiv: il-mistoqsija teħtieġ katina ta’ żewġ għodod, u dan huwa eżattament it-tip ta’ kompożizzjoni li bidla fid-deskrizzjoni tista’ tkisser b’mod silenzjuż.

Latenza u Spiża

Fl-aħħar nett, hemm id-dimensjoni operattiva. Medja ma tgħid xejn dwar l-esperjenza reali: hija d-denb tad-distribuzzjoni li tbiegħed lill-utenti, meta talba waħda minn mitt tieħu għoxrin sekonda. Billi tirrepeti kull messaġġ diversi drabi, tikseb distribuzzjoni użabbli u taqra l-medjan bħala l-imġiba tipika, u l-P99 bħala l-agħar xenarju komuni tiegħek.

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

Evalwazzjoni permezz ta’ LLM (LLM-as-Judge)

Dawn it-tliet metriċi iħallu barra kull ħaġa mingħajr tweġiba waħda korretta: spjegazzjoni ta’ politika ta’ ritorn, riformulazzjoni tal-bejgħ, messaġġ ta’ apoloġija. Għal dawn ir-risposti miftuħa, uża mudell biex tevalwa l-kwalità. L-imħallef jirċievi l-mistoqsija u t-tweġiba, japplika kriterji li ktibt int—preċiżjoni, rilevanza, professjonaliżma—u jirritorna punteġġ strutturat grazzi għal output_type ta’ Pydantic. Il-vincolu tal-format huwa dak li jagħmel il-proċess użabbli: tikseb numru sħiħ li tista’ taggrega, mhux kumment li trid terġa’ taqra.

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

Il-qasam reason jistħoqqilu attenzjoni waqt ir-reviżjonijiet: hawnhekk l-imħallef jispjega għaliex ta 3 minn 5, u spiss din hija l-formulazzjoni ta’ difett li ma rnexxielekx isemmi.

Settijiet ta’ Testijiet Strutturati

Evalwazzjoni li mhix riproduċibbli hija inutili. Organizza l-każijiet tat-test tiegħek f’format stabbli fejn kull entrata ġġorr ID, kategorija, il-mistoqsija, it-tweġiba mistennija, l-għodod mistennija, u kriterji kwalitattivi. Il-kategorija tagħmel ix-xogħol kollu hawn: punteġġ ġenerali ta’ 4.2 minn 5 huwa qarrieqi u jisseddaq, filwaqt li punteġġ dettaljat jiżvela li l-kategorija “stock” tinżel għal 2.8 filwaqt li “price” tiġbed il-medja ‘l fuq.

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,
        })

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

Ħaddem din l-evalwazzjoni fil-pipeline tal-integrazzjoni kontinwa tiegħek, eżattament bħat-testijiet tal-unità tiegħek, u stabbilixxi limitu li taħtu l-konsenja tiġi mblukkata. Minn dak il-mument ‘il quddiem, kull bidla—mudell ġdid, istruzzjonijiet aġġustati, għodda miżjuda—titqabbel ma’ dik ta’ qabilha fuq l-istess każijiet, u d-diskussjoni tieqaf iddur madwar l-impressjonijiet.

Punti Ewlenin

  • Evalwa l-preċiżjoni, l-użu tal-għodod, il-latenza u l-ispiża
  • L-evalwazzjoni permezz ta’ LLM (LLM-as-Judge) tittratta risposti miftuħa
  • Oħloq settijiet ta’ testijiet strutturati u riproduċibbli
  • Awtomatizza l-evalwazzjoni fil-CI/CD tiegħek biex tiskopri regrezzjonijiet
  • Qabbel sistematikament il-bidliet (mudell, istruzzjonijiet, għodod)