Ocena agentów i umiejętności w praktyce: trajektorie, oceniacze, kryteria zdania i narzędzia

Prędzej czy później każdy zespół zajmujący się agentami i ich umiejętnościami napotyka jeden problem: demo robi wrażenie, ale rzeczywisty ruch odkrywa błędy, których nikt wcześniej nie zauważył. Oceny zastępują domysły pomiarami. Poniżej znajduje się praktyczny przewodnik dotyczący tego, co należy mierzyć, jak tworzyć przypadki testowe i narzędzia oceny oraz jak uruchomić cykl doskonalenia, który naprawdę poprawi umiejętności agenta.

Model mentalny

Ocena to eksperyment powtarzalny. Podaj agentowi dane wejściowe i środowisko, a następnie obserwuj dwie rzeczy: trajektorię, czyli to, co agent robił w trakcie, oraz wynik, czyli ostateczny produkt, który stworzył.

Oceniaj oba aspekty:

• Wynik: czy ukończony produkt spełnia zadanie?
• Trajektoria: czy agent wybrał odpowiednie umiejętności i narzędzia, unikał niebezpiecznych działań i pracował efektywnie?

Wyrafinowana ostateczna odpowiedź może ukrywać słabą ścieżkę działania, a niezdarna ścieżka nadal może przynieść przypadkowy wynik. Patrzenie tylko na jeden z tych aspektów pokazuje tylko połowę historii.

Warstwy oceny

Żadna pojedyncza liczba nie wskazuje, czy agent jest dobry. Podziel pytanie na warstwy, z których każda wymaga osobnej weryfikacji:

• Doboru umiejętności. Czy wybrano odpowiednią umiejętność? Sprawdź dokładność, trafność oraz fałszywe wyzwalacze.
• Przestrzegania zasad umiejętności. Czy rzeczywiście postępowano zgodnie z instrukcjami umiejętności, włączając wymagane kroki i zabronione działania?
• Używania narzędzi. Czy narzędzia zostały wywołane prawidłowo, z odpowiednimi argumentami, w rozsądnej kolejności i bez niepotrzebnych wywołań?
• Wyniku zadania. Czy wynik jest funkcjonalny? Testy, sprawdzenia schematu oraz twierdzenia behawioralne odpowiadają na to pytanie.

Jakość. Czy wynik jest utrzymywalny i odpowiedni? Decyduje o tym rubrykator lub recenzent.

Bезpieczeństwo. Czy przestrzegano granic dotyczących tajemnic, destruktywnych operacji oraz iniekcji zapytań?

Wydajność. Ile kosztował sukces w postaci tokenów, opóźnień, wywołań i prób ponownych?

Umiejętność wymaga dwóch zestawów ocen

Umiejętność to coś więcej niż zbiór instrukcji. Obejmuje decyzję o tym, kiedy ją aktywować, oraz plan działań po tym, jak zostanie uruchomiona, dlatego wymaga dwóch oddzielnych zestawów ocen.

Trigger evals sprawdzają, czy umiejętność zostaje uruchomiona przy odpowiednich zapytaniach. W każdym przypadku zapytanie jest sparowane z oczekiwaną umiejętnością lub z umiejętnością, która nie powinna zostać uruchomiona:

- prompt: "Patch the vulnerable npm dependencies"
  expected_skill: cve-remediation
- prompt: "Review authentication input validation"
  forbidden_skill: cve-remediation

Ukrywaj oczywiste pozytywy, przefrasowuj pozytywne oceny, negatywy, które ledwo uniknęły błędu, niejednoznaczne polecenia oraz konflikty pomiędzy dwiema prawdopodobnymi umiejętnościami. Raportuj macierz pomieszania zamiast zwykłej dokładności, ponieważ fałszywy pozytyw może zaszkodzić tak samo mocno jak pominięty sygnał.

Oceny wykonywania sprawdzają, czy użycie danej umiejętności poprawia jakość pracy. Porównuj agenta, który jej nie posiada, z tym samym agentem wyposażonym w tę umiejętność, używając identycznych przypadków, środowiska, modelu i narzędzi, oraz powtarzaj te testy, ponieważ agenci są niedeterministyczni. Umiejętność zasługuje na swoje miejsce tylko wtedy, gdy uzyskana poprawa usprawiedliwia jej dodatkową złożoność i koszt tokenów.

Jak wygląda dobry przypadek

Wolą realistyczne zrzuty stanu repozytorium nad izolowane, błahe informacje. Dobry przypadek jest samodzielny i może zostać sprawdzony przez maszynę:

{
  "id": "fix-null-condition",
  "prompt": "Fix saving rules with a null condition",
  "fixture": "repos/null-condition",
  "setup": ["npm install"],
  "checks": [
    "npm test -- null-condition.test.js",
    "git diff --check"
  ],
  "rubric": [
    "Fixes the root cause",
    "Preserves existing behavior",
    "Adds a regression test",
    "Avoids unrelated changes"
  ],
  "forbidden": [
    "deleting existing tests",
    "hard-coded fixture-specific output"
  ]
}

Narzędzia oceny: użyj najskuteczniejszego, jaki masz

Najlepiej wybrać najbardziej pewne narzędzie oceny, a do oceny subiektywnej uciekać się tylko w razie konieczności. Mniej więcej od najskuteczniejszego do najmniej skutecznego:

1. precyzyjne stwierdzenia
2. skompilowanie oraz testy jednostkowe lub integracyjne
3. weryfikacja schematu lub drzewa składni
4. sprawdzanie zachowania za pomocą przeglądarki lub API
5. statyczna analiza ścieżki wykonywania
6. LLM oceniające na podstawie kryteriów
7. przegląd przez człowieka

LLM oceniające sprawdzają takie cechy jak jasność i dopasowanie architektoniczne, jednak nie powinny zastępować testów wykonywalnych. Ukryj przed nimi, która wersja dała wynik, oraz zmień kolejność porównań.

Wskaźniki wartych śledzenia

• Wskaźnik sukcesu to udział przypadków, które przeszły wszystkie kluczowe testy.
• Pass@k to prawdopodobieństwo, że przynajmniej jedna z k prób się powiedzie.
• Pass^k to prawdopodobieństwo, że wszystkie k prób się powiedzie, co stanowi najwierniejszy wskaźnik niezawodności.
• Dokładność i trafność routingu opisują jakość selekcji umiejętności.
• Stopa regresji liczy przypadki, w których wcześniej działanie się udawało, a teraz zawodzi.
• Koszt za udaną zadanie, mediana i opóźnienie na końcu rozkładu, liczba wywołań narzędzi, stopy ponawiania prób oraz częstotliwość interwencji człowieka – to wszystko również powinno znaleźć się na panelu kontrolnym.

Dla agentów produkcyjnych stała niezawodność zazwyczaj przewyższa imponujące wyniki w najlepszych warunkach.

Budowanie zestawu danych

Zacznij od 20 do 50 przypadków zaczerpniętych z rzeczywistej pracy: wcześniejszych niepowodzeń i incydentów wsparcia, codziennych zadań, przypadków krawędziowych, mylących lub wrogich zapytań, niejasno sformułowanych instrukcji, zadań, które należy odrzucić lub doprecyzować, oraz sytuacji, w których żadna umiejętność nie powinna zostać aktywowana.

Następnie podziel je na trzy zbiory:

• zbiór rozwojowy, który możesz używać podczas doskonalenia umiejętności
• zbiór rezerwowy, który pozostaje nietknięty aż do weryfikacji
• zbiór regresji, do którego trafiają wszystkie odkryte przez ciebie niepowodzenia, na stałe

Unikaj optymalizacji wyłącznie na podstawie jednego ustalonego, publicznego zbioru, ponieważ agenci szybko nadadaptują się do jego sformułowań.

Proces pracy

Pomyśl o tym jako o rozwoju opartym na testach dla zachowania agenta:

1. Zarejestruj rzeczywiste niepowodzenie.
2. Zredukuj je do powtarzalnego przykładu do testowania.
3. Napisz instrukcje oceny przed dotknięciem umiejętności lub agenta.
4. Przeprowadź kilka prób bazowych.
5. Zrób jedną celowaną zmianę.
6. Ponownie uruchom przypadek docelowy wraz z całym zestawem testów regresji.
7. Porównaj jakość, niezawodność, opóźnienie i koszt.
8. Zachowaj zmianę tylko wtedy, gdy poprawi się ogólna równowaga.

Częste błędy

• ocenianie tylko końcowego tekstu
• używanie tylko promptów typu „happy path”
• sprawdzanie, czy instrukcje zostały powtórzone, a nie wykonane
• pytanie sędziego LLM o fakty, które można zweryfikować za pomocą testu
• przeprowadzenie jednego testu i traktowanie wyniku jako deterministycznego
• zmiana promptu, modelu, narzędzi i umiejętności jednocześnie
• uznawanie usuniętych testów lub modyfikacji narzędzia oceny za sukces
• używanie syntetycznych przypadków, które w ogóle nie przypominają rzeczywistej pracy użytkownika
• przeoczenie wstrzykiwania poleceń ukrytych w plikach lub wynikach narzędzi

Metryki routingu w praktyce

Załóżmy, że istnieje umiejętność przeglądu bezpieczeństwa, a oceniający decyduje dla każdego polecenia, czy powinno ono zostać uruchomione. Możliwe są cztery wyniki:

• Prawdziwy pozytyw (TP): powinno zostać uruchomione i tak się stało.
• Fałszywy pozytyw (FP): nie powinno zostać uruchomione, ale tak się stało – to fałszywe uruchomienie.
• Fałszywy negatyw (FN): powinno zostać uruchomione, ale tak się nie stało.
• Prawdziwy negatyw (TN): nie powinno zostać uruchomione i tak się nie stało.

Dokładność określa, jak często uruchomienie było poprawne: TP podzielone przez (TP + FP). Jeśli umiejętność została uruchomiona dziesięć razy, a osiem razy poprawnie, dokładność wynosi 80%. Wysoka dokładność oznacza niewiele fałszywych uruchomień.

Pamięć określa, ile z zapytań wymagających danej umiejętności zostało faktycznie rozpoznanych: TP podzielone przez (TP + FN). Jeśli dziesięć zapytań tego wymagało, a siedem zostało rozpoznanych, pamięć wynosi 70%.

Fałszywy wyzwalacz to po prostu fałszywy pozytyw. Przykładem jest zapytanie typu „Upgrade React dependencies”, które błędnie uruchamia proces sprawdzania bezpieczeństwa. Wiele fałszywych wyzwalaczy oznacza niską precyzję.

Matryca pomyłek uwzględnia wszystko. Przy TP = 8, FN = 2, FP = 3 i TN = 7 zapytania, które powinny zostać rozpoznane, to 8, a te, które nie powinny, to 2; z kolei zapytania, które powinny pozostać nierozpoznane, to 3, a te, które nie powinny, to 7. Precyzja wynosi 8 / 11, czyli około 72,7%, a pamięć 8 / 10, czyli 80%. Wysoka precyzja oznacza, że umiejętność rzadko aktywuje się błędnie. Wysoka pamięć oznacza, że rzadko pomija istotne zapytania. Szerokie sformułowania wyzwalaczy zazwyczaj zwiększają pamięć, ale obniżają precyzję.

Od czego zacząć

Jako kluczową umiejętność, kompaktowy zestaw może znacznie pomóc. Zbierz dziesięć promptów, które powinny ją aktywować, oraz dziesięć przypadków, w których to nie powinno się zdarzyć, plus pięć realistycznych zadań do wykonania. Dodaj sprawdzanie deterministycznych wyników, trzy do pięciu powtórzeń każdego zadania, jedno wykonywanie bez tej umiejętności jako punkt odniesienia oraz zestaw testów regresji, który zachowuje każdą wykrytą awarię.

Taka mała konfiguracja ujawnia większość problemów z routowaniem i pokazuje, czy umiejętność rzeczywiście pomaga, czy tylko sprawia wrażenie zaawansowanej.

Minimalna struktura, którą można skopiować

Dostatecznie dużo teorii. Mały skrypt napisany w zwykłym Pythonie, wykorzystujący jedynie standardową bibliotekę, może ocenić zarówno proces routowania umiejętności, jak i wynik wykonywania zadań przez agenta. Składający się z około 70 linii kodu, pokazuje wszystkie powyższe koncepcje: pliki przypadków, warstwowe narzędzia oceny, powtarzane wykonywania oraz metryki niezawodności.

Struktura folderów:

evals/
  cases/
    skills/security-review.trigger.json
    agents/fix-null-condition.json
  graders.py
  metrics.py
  runner.py
  run.py        # CLI entry1. Case files. A skill trigger case is just positives and negatives. An agent case is a prompt plus graders and a run count.

W pliku przypadku wyzwalacza wymieniono nazwę umiejętności wraz z wskazówkami, które powinny i nie powinny ją aktywować:

// cases/skills/security-review.trigger.json
{
  "skill": "security-review",
  "positives": [
    "Audit this endpoint for SQL injection",
    "Check the login flow for auth bypasses",
    "Is this file-upload handler safe?"
  ],
  "negatives": [
    "Upgrade React dependencies",
    "Rename this variable across the repo",
    "Add a loading spinner to the form"
  ]
}

Plik przypadku agenta zawiera identyfikator, instrukcję, elementy konfiguracyjne oraz listę do sprawdzenia:

// cases/agents/fix-null-condition.json
{
  "id": "fix-null-condition",
  "prompt": "Fix saving rules with a null condition",
  "fixture": "fixtures/null-condition",
  "setup": ["npm ci"],
  "runs": 5,
  "graders": [
    { "type": "shell", "cmd": "npm test -- null-condition", "critical": true },
    { "type": "shell", "cmd": "git diff --check" },
    { "type": "forbidden", "pattern": "it\\.skip|xit\\(", "message": "must not disable tests" }
  ]
}

Następne są systemy oceny. Jeden wykonywa komendy wiersza poleceń, takie jak zestawy testowe, inny skanuje trajektorię w poszukiwaniu zmian, które nie były dozwolone, a model sędziego, który nie wie, którą wersję ocenia, zajmuje się aspektami subiektywnymi.

# graders.py
import re, subprocess
def shell(step, ctx):
    r = subprocess.run(step["cmd"], cwd=ctx.workdir, shell=True,
                       capture_output=True, text=True)
    ok = r.returncode == 0
    return {"pass": ok, "score": 1 if ok else 0, "detail": r.stdout[-400:]}
def forbidden(step, ctx):
    bad = re.search(step["pattern"], ctx.diff) is not None
    return {"pass": not bad, "score": 0 if bad else 1,
            "detail": step["message"] if bad else ""}
def judge(step, ctx):
    v = ctx.llm.rate(step["rubric"], ctx.artifact)  # 0..1, blinded
    return {"pass": v >= step.get("threshold", 0.7), "score": v}
GRADERS = {"shell": shell, "forbidden": forbidden, "judge": judge}3. Metrics. Success rate, pass@k, pass^k, and the routing confusion matrix — exactly the numbers from earlier.

Moduł metryk przekształca listy wyników wykonywań w liczby:

# metrics.py
def success_rate(rs):
    return sum(1 for r in rs if r["pass"]) / len(rs)
def pass_at_k(rs):
    return 1 if any(r["pass"] for r in rs) else 0
def pass_hat_k(rs):
    return 1 if all(r["pass"] for r in rs) else 0
def routing(positives, negatives, fired):
    tp = sum(1 for p in positives if fired(p))
    fp = sum(1 for n in negatives if fired(n))
    fn = len(positives) - tp
    tn = len(negatives) - fp
    return {"tp": tp, "fp": fp, "fn": fn, "tn": tn,
            "precision": tp / (tp + fp or 1),
            "recall": tp / (tp + fn or 1)}4. The runner. One function per suite. The agent runner repeats each case so pass^k is meaningful; the skill runner just asks the router which skills fire.

Biegacz ładowa przypadki, wzywa osoby oceniające, powtarza każdy bieg i wyświetla metryki:

# runner.py
import json
from graders import GRADERS
from metrics import success_rate, pass_at_k, pass_hat_k, routing
def run_agent_case(agent, path):
    c = json.load(open(path))
    runs = []
    for _ in range(c.get("runs", 3)):
        ctx = agent.run(c["prompt"], fixture=c["fixture"], setup=c["setup"])
        ok = True
        for step in c["graders"]:
            g = GRADERS[step["type"]](step, ctx)
            if step.get("critical") and not g["pass"]:
                ok = False
        runs.append({"pass": ok})
    return {"id": c["id"], "success": success_rate(runs),
            "pass_at_k": pass_at_k(runs), "pass_hat_k": pass_hat_k(runs)}
def run_skill_trigger(router, path):
    c = json.load(open(path))
    fired = lambda prompt: c["skill"] in router.route(prompt)
    return {"skill": c["skill"], **routing(c["positives"], c["negatives"], fired)}5. Run it. The CLI just dispatches on the case type and prints the metrics.

Uruchomienie go daje wynik w tym rodzaju:

$ python run.py cases/agents/fix-null-condition.json
fix-null-condition   success=0.80   pass@5=1.00   pass^5=0.20
$ python run.py cases/skills/security-review.trigger.json
security-review      precision=0.86  recall=1.00   (tp=6 fp=1 fn=0 tn=5)

Czytaj te linijki w sposób zalecany przez całe to podejście. Agent przeprowadza cztery próby na pięć, więc pass@5 wydaje się idealne, jednak pass^5 o wartości 0,20 wskazuje, że jeszcze nie jest niezawodny. Umiejętność rozpoznaje każdą prawdziwą prośbę, osiągając wskaźnik recall na poziomie 1,0, ale została uruchomiona raz wtedy, gdy nie powinna była, przy precyzji 0,86, więc istnieje jeden fałszywy sygnał do wyeliminowania.

W tym właśnie polega cel ocen: przekształcanie stwierdzeń typu „wydawało się, że to działa” w liczby, które można udoskonalić. Zacznij od takiego narzędzia, dodawaj nowe przypadki w momencie, gdy coś się psuje, i pozwól, by zbiór danych regresji ewoluował wraz z twoją definicją tego, co jest dobre.

Korzystaj z istniejących frameworków, gdy to możliwe

Domowej roboty narzędzie jest przydatne do nauki zasad działania i zapewnienia pełnej kontroli, ale dojrzałe projekty otwarte już oferują narzędzia do przeprowadzania prób, oceniania, dostarczają zestawów danych oraz paneli kontrolnych. Przyjrzyj im się przed stworzeniem własnego rozwiązania.

Ogólne wskazówki dotyczące promptów i ocen LLM

OpenAI Evals to oryginalna platforma w stylu rejestru, która definiuje testy w formacie YAML przy użyciu narzędzi Python do oceny dowolnych modeli; nadaje się do sprawdzania wyników oraz klasyfikacji. promptfoo jest sterowany konfiguracją, pokazuje prompty w porównaniu z modelami w formie macierzy obok siebie, zawiera twierdzenia takie jak sprawdzanie obecności elementów, regular expressions, schematy JSON oraz kryteria oceny LLM, a także posiada tryb red-team, co czyni go doskonałym narzędziem do zarządzania umiejętnościami modeli i wykrywania regresji w promptach. DeepEval funkcjonuje jak pytest dla modeli LLM, oferując metryki wierności, trafności oraz pojawiania się halucynacji, a także dostosowane kryteria oceny G-Eval, i naturalnie integruje się z procesami CI. Ragas jest przeznaczony specjalnie do pipeline’ów RAG, oceniając dokładność i trafność kontekstu, wierność oraz istotność odpowiedzi. Funkcja oceny modeli LLM w MLflow umożliwia śledzenie i porównywanie wyników, jeśli MLflow jest już używany.

Śledzenie, zbiory danych i platformy oceny

LangSmith oferuje zestawy danych, narzędzia do śledzenia trajektorii oraz funkcje oceny, przydatne wtedy, gdy trzeba przeanalizować całą ścieżkę działania, a nie tylko wynik końcowy. Langfuse jest oprogramowaniem otwartym, można je uruchomić lokalnie i jest niezależne od konkretnego modelu; posiada funkcje śledzenia, oceny oraz zestawy danych do monitorowania w środowisku produkcyjnym. Braintrust traktuje procesy oceny jak element CI/CD, oferując funkcje oceny, zestawy danych w wersjach kontrolnych oraz widok różnic dla eksperymentów. Arize Phoenix opiera się na technologii OpenTelemetry do śledzenia i zawiera szablony oceny, które ułatwiają wykrywanie regresji w ruchu sieciowym w czasie rzeczywistym. Inspect, stworzony przez UK AI Safety Institute, to starannie zaprojektowana platforma do rozwiązywania zadań i oceny, która zdobywa coraz większe uznanie w zakresie poważnych ocen agentów i aspektów bezpieczeństwa.

Standardy oceny agentów

SWE-bench i SWE-bench Verified stanowią standard określający, czy agent potrafi naprawić rzeczywisty problem na GitHubie, przy czym jako narzędzie oceny wykorzystywane są własne testy repozytorium. AgentBench, WebArena, GAIA oraz τ-bench dostarczają zewnętrznych kryteriów oceny dotyczących używania narzędzi, zadań internetowych oraz agentów wieloetapowych. Frameworki takie jak AutoGen i LangGraph oferują mechanizmy testowe umożliwiające weryfikację wywołań narzędzi oraz poszczególnych kroków w procesie.

Wybór

• Jeśli chodzi wyłącznie o generowanie promptów i kierowanie umiejętnościami agenta, promptfoo to najszybszy sposób na konfigurację wraz z mechanizmami weryfikacji.
• Dla metryk opartych na kodzie i dostosowanych do środowisk CI, rozważ DeepEval lub Braintrust.
• Aby ocenić rozwój agentów wieloetapowych, sprawdź LangSmith, Langfuse lub Inspect.
• Dla zastosowań typu RAG dodaj Ragas.
• Dla rzeczywistego benchmarku agentów programistycznych użyj SWE-bench Verified.

To podejście jest stosowane wszędzie: w przypadkach różnych zadań, ocenie wyników, powtarzanych próbach oraz śledzeniu zmian w czasie. Frameworki pomagają załatwić te kwestie, więc zachowaj dyscyplinę i wybierz narzędzie pasujące do twojego zestawu. Specjalne rozwiązania należy zachować głównie na wypadek luk pozostawionych przez te narzędzia lub w projektach, które wymagają braku jakichkolwiek zależności w środowisku CI.