Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Agenttiesi arviointi: mittarit ja vertailuarvot

Oppitunti 22 / 25 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Agenttiesi arviointi: mittarit ja vertailuarvot
  2. Miksi arvioida?
  3. Keskeiset mittarit
  4. LLM-arviointi (LLM-as-Judge)
  5. Jäsennellyt testisarjat
  6. Keskeiset asiat

Agenttiesi arviointi: mittarit ja vertailuarvot

Kehitysympäristössä toimiva agentti voi epäonnistua tuotannossa. Systemaattinen arviointi on ainoa tapa varmistaa laatu ennen käyttöönottoa ja sen jälkeen. Tässä oppitunnissa opit määrittelemään mittareita, luomaan testisarjoja ja automatisoimaan arvioinnin.

Miksi arvioida?

Ilman muodollista arviointia lennät sokkona. Muotoilet ohjeen uudelleen käyttäjän valituksen jälkeen, mutta mikään ei kerro, parantuiko agentti vai rikkoitko samalla kolme muuta skenaariota. Epäröit Terran ja Lunan välillä käyttötapaustasi varten – tai kahden eri päättelytason välillä samassa mallissa – ja ilman mittauksia päätös perustuu mututuntumaan viiden manuaalisen kokeilun jälkeen. Muutat työkalun skeemaa, agentti lakkaa kutsumasta sitä tietyssä tilanteessa, eikä kukaan huomaa sitä ennen kuin tukipyyntöjen määrä räjähtää. Arviointisarja muuttaa jokaisen näistä tilanteista vertailukelpoiseksi luvuksi versiosta toiseen.

Keskeiset mittarit

Tarkkuus

Ensimmäinen kysymys on suoraviivaisin: antaako agentti oikean vastauksen? Toistat kysymyssarjan, johon tiedät vastauksen, ja tarkistat sen esiintymisen tulosteessa. Kirjainkoosta riippumaton osamerkkijonotäsmäys on tarkoituksellisen karkea – se hyväksyy lauseen “Pro-kannettavan hinta on 1 299 € (sis. alv)”, jossa tiukka yhtäsuuruus epäonnistuisi – mutta se riittää varmennettaviin faktoihin ja laskee tuloksen sekunnissa.

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"])
        # Automaattinen tai LLM-pohjainen varmennus
        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

# Testisarja
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"},
]

Oikea työkalujen käyttö

Oikea vastaus, joka on saatu sattumalta, on edelleen ongelma. Agentti, joka luettelee ulkoa opetellun hinnan kyselyn sijaan tuoteluettelosta, läpäisee tarkkuustestin tänään, mutta antaa vanhentuneen hinnan huomenna. Toinen mittari tarkastelee siksi polkua, ei tulosta: kutsuuko agentti oikeita työkaluja oikeilla argumenteilla? Luet kutsut kohdasta raw_responses, suodattaen function_call-tulosteet, ja vertailussa käytetään joukkoja, jotta järjestys ei vaikuta tulokseen.

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

        # Pura kutsutut työkalut raaoista vastauksista
        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"],
    },
]

Toinen testitapaus on opettavaisin: kysymys vaatii kahden työkalun ketjutusta, ja juuri tämäntyyppinen yhdistelmä on se, jonka kuvauksen muutos voi hiljaisesti rikkoa.

Viive ja kustannukset

Lopuksi on operatiivinen ulottuvuus. Keskiarvo ei kerro mitään todellisesta kokemuksesta: käyttäjät karkaa jakauman häntäpään vuoksi, kun yksi pyyntö sadasta kestää kaksikymmentä sekuntia. Toistamalla jokaisen viestin useita kertoja saat käyttökelpoisen jakauman ja voit lukea mediaanin tyypillisenä käyttäytymisenä sekä P99-arvon yleisenä pahimpana tapauksenasi.

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

LLM-arviointi (LLM-as-Judge)

Nämä kolme mittaria jättävät huomiotta kaiken, jossa ei ole yhtä oikeaa vastausta: palautuskäytännön selityksen, myyntipuheen uudelleenmuotoilun tai pahoitteluviestin. Näitä avoimia vastauksia varten käytä mallia laadun arviointiin. Tuomari saa kysymyksen ja vastauksen, soveltaa kirjoittamiasi kriteerejä – tarkkuus, relevanssi, ammattimaisuus – ja palauttaa jäsennellyn pistemäärän Pydanticin output_type-määrittelyn ansiosta. Muotorajoitus on se, mikä tekee prosessista käyttökelpoisen: saat yhteenlaskettavan kokonaisluvun etkä uudelleenluettavaa kommenttia.

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

Kenttä reason ansaitsee huomiosi katselmusten aikana: tässä tuomari selittää, miksi se antoi 3/5, ja usein juuri tästä löydät vian muotoilun, jota et ole osannut nimetä.

Jäsennellyt testisarjat

Arviointi, jota ei voi toistaa, on hyödytön. Järjestä testitapauksesi vakaaseen muotoon, jossa jokainen merkintä sisältää tunnisteen, luokan, kysymyksen, odotetun vastauksen, odotetut työkalut ja laadulliset kriteerit. Luokka tekee tässä kaiken työn: yleinen pistemäärä 4,2/5 on harhaanjohtavan lohduttava, kun taas yksityiskohtainen pistemäärä paljastaa, että “varasto”-luokka romahtaa lukemaan 2,8, kun taas “hinta” vetää keskiarvoa ylöspäin.

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

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

Suorita tämä arviointi jatkuvan integraation putkessasi aivan kuten yksikkötestisi, ja aseta kynnysarvo, jonka alittaminen estää toimituksen. Tästä eteenpäin jokainen muutos – uusi malli, hienosäädetty ohjeistus, lisätty työkalu – vertautuu edelliseen samojen tapausten pohjalta, eikä keskustelu enää pyöri vaikutelmien ympärillä.

Keskeiset asiat

  • Arvioi tarkkuus, työkalujen käyttö, viive ja kustannukset
  • LLM-arviointi (LLM-as-Judge) käsittelee avoimet vastaukset
  • Luo jäsenneltyjä ja toistettavia testisarjoja
  • Automatisoi arviointi CI/CD-prosessissasi regressioiden havaitsemiseksi
  • Vertaile muutoksia (malli, ohjeistus, työkalut) systemaattisesti