Wskazówki praktyczne: Oceny – szybki przewodnik dla agentów i umiejętności
Praktyczne wskazówki: Oceny – szybki kurs dla agentów oraz Umiejętności: kontrakty, weryfikacje i miejsca na kod dla zespołów implementujących ten wzorzec.
Poniższe notatki przedstawiają praktyczny plan działania w ramach materiału „Evals: A Crash Course for Agents and Skills”. Nacisk kładziony jest na umowy, sprawdzania oraz miejsca zastępcze dla kodu, a nie na aspekty motywacyjne. Podczas przechodzenia przez etap przeglądu najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury.
Model mentalny
Etap modelowania mentalnego działa najlepiej, gdy traktuje się go jako mierzalną powierzchnię. Zapisz jeden idealny przypadek, jeden przypadek niepowodzenia oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Zdokumentuj zarówno ścieżkę pomyślnego przebiegu, jak i ścieżkę naprawczą. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości nieodebranych stanowią część produktu, a nie elementy dodawane później. Przydziel budżet tokenów na każdy ruch i sesję. Narzędzia typu agentic intensywnie rozszerzają kontekst; sztywne limity zapobiegają temu, by demonstracje przerodziły się w niespodziewane rachunki.
Szarytety oceny
Faza warstw oceny funkcjonuje najlepiej, gdy traktowana jest jako mierzalna powierzchnia. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Wolij małe, testowalne jednostki nad rozbudowane skrypty. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Utrzymuj stan grafu w prostej formie i z określonym typem danych. Wkładane elementy ukrywają informację o tym, który węzeł zapisał dane do którego pola, i powodują przerwanie kontynuacji po przerwach.
Umiejętności wymagają dwóch zestawów oceny
Najlepiej sprawdza się model dwóch etapów oceny w The Skills, gdy traktuje się go jako mierzalną powierzchnię do analizy. Zanim rozszerzy się zakres, należy zarejestrować jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij poszczególne elementy, zdefiniuj kryteria sukcesu i odrzuć przypadki częściowego ukończenia bez żadnych informacji. Utrzymuj stan grafu w prostej formie i z określonym typem danych. Wложone struktury ukrywają informacje o tym, który węzeł zapisał dane w danym polu, co powoduje przerwanie kontynuacji po przerwach. Najlepiej sprawdza się model dwóch etapów oceny w The Skills, gdy traktuje się go jako mierzalną powierzchnię do analizy. Zanim rozszerzy się zakres, należy zarejestrować jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian. Utrzymuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą audytować bez konieczności czytania całego grafu.
- prompt: "Patch the vulnerable npm dependencies"
expected_skill: cve-remediation
- prompt: "Review authentication input validation"
forbidden_skill: cve-remediation
Jak wygląda dobry przypadek oceny
Dla etapu oceny „Co za doskonały etap”, zdefiniuj dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Zdokumentuj zarówno standardową ścieżkę działania, jak i ścieżkę naprawczą. Próby ponownych działań, kontrola przez ludzi oraz obsługa nieudanych transakcji stanowią część produktu, a nie elementy dodawane później. Wymagaj zatwierdzenia przez człowieka w przypadkach, gdy dochodzi do wydawania pieniędzy lub zmiany danych produkcyjnych. Połączenia realizowane w czasie kompilacji nie równają się kompletności rozwiązania biznesowego.
{
"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"
]
}
Oceny: używaj najskuteczniejszego dostępnego narzędzia
Dla osoby oceniającej należy użyć najtrudniejszego poziomu, określić dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy dany krok zawiedzie, powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Konieczna jest ludzka akceptacja w przypadkach, gdy dochodzi do wydawania pieniędzy lub modyfikacji danych produkcyjnych. Połączenia realizowane w czasie kompilacji nie równają się kompletności biznesowej.
Metryki, które mają znaczenie
W fazie „Metryki, które mają znaczenie” należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij poszczególne elementy, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadań. Zapewnij ludzką aprobatę w przypadkach, gdy dochodzi do wydawania pieniędzy lub zmiany danych produkcyjnych. Połączenia realizowane w czasie kompilacji nie równają się pełnej kompletności procesu biznesowego. W fazie „Metryki, które mają znaczenie” należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury.
Budowanie dobrego zestawu danych
Gdy przechodzisz przez etap budowania dobrego zestawu danych, najpierw zapisz specyfikację: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zdokumentuj zarówno prawidłowy przebieg operacji, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez człowieka oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później. Ustaw punkty kontrolne po kosztownych krokach. Narzędzie do kontynuacji pracy nie powinno ponownie naliczać opłat za tę samą wywołanie LLM, gdy operator próbuje ponownie uruchomić późniejszy węzeł.
Praktyczny cykl
Gdy przechodzisz przez etap „Praktyczny pętla”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolij małe, testowalne jednostki nad rozbudowane skrypty. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Ustalaj punkty kontrolne po kosztownych krokach. System powinien unikać ponownego pobierania opłat za tę samą funkcję LLM, gdy operator próbuje ponownie wykonać późniejszy element.
Częste błędy
Gdy przechodzisz przez etap „Powszechne błędy”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć możliwość cichego, częściowego ukończenia zadania. Ustaw punkty kontrolne po kosztownych krokach. System powinien unikać ponownego pobierania opłat za tę samą operację LLM, gdy operator próbuje ponownie wykonać późniejszy element procesu. Gdy przechodzisz przez etap „Powszechne błędy”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury.
Metryki routingu w praktyce
Metryki routingu działają najlepiej, gdy traktuje się je jako mierzalną powierzchnię. Zanim rozszerzysz zakres, zapisz jeden idealny przypadek działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian. Zdokumentuj zarówno ścieżkę pomyślnego działania, jak i ścieżkę przywracania. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości nieodebranych stanowią część produktu, a nie elementy dodawane później. Utrzymuj stan grafu w prostej formie i z określonym typem danych. Wplecione struktury ukrywają informację o tym, który węzeł zapisał dane w danym polu, i powodują przerwanie kontynuacji po przerwach.
Najlepsze miejsce na rozpoczęcie
Najlepsze miejsce na realizację zadań działa najskuteczniej, gdy traktuje się je jako mierzalną powierzchnię. Zapisz jeden udany przykład działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Utrzymuj stan grafu w prostej formie i z określonym typem danych. Wtórne struktury ukrywają informację o tym, który węzeł zapisał dane do którego pola, i powodują przerwanie kontynuacji po przerwach.
Prawdziwa, minimalna ramka oceny, którą możesz skopiować
Rzeczywiście minimalna faza oceny funkcjonuje najlepiej, gdy jest traktowana jako mierzalna powierzchnia. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadania. Utrzymuj stan grafu w prostej formie i z określonym typem danych. Wkładki nawiasowe ukrywają informację o tym, który węzeł zapisał dane do którego pola, co powoduje przerwanie kontynuacji po przerwach. Rzeczywiście minimalna faza oceny funkcjonuje najlepiej, gdy jest traktowana jako mierzalna powierzchnia. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Utrzymuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całego grafu.
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.
// 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"
]
}
// 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" }
]
}
# 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.
# 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.
# 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.
$ 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)
Nie buduj od zera, jeśli nie jest to konieczne
Aby uniknąć budowania od nowa, zdefiniuj wejścia, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Zdokumentuj zarówno standardową ścieżkę działania, jak i ścieżkę naprawczą. Próby ponownych działań, kontrola przez ludzi oraz obsługa błędów stanowią część produktu, a nie elementy dodawane później. Wymagaj zatwierdzenia przez człowieka w przypadkach, gdy dochodzi do wydawania pieniędzy lub zmiany danych produkcyjnych. Połączenia realizowane w czasie kompilacji nie równają się kompletności rozwiązania biznesowego.
Ogólne oceny LLM i promptów
W fazie oceny promptów ogólnych dla modeli LLM należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy preferować małe, łatwe do przetestowania jednostki zamiast rozbudowanych skryptów. Gdy dany krok zawiedzie, powinno to wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. W przypadku, gdy następnym krokiem jest kod lub wywołanie narzędzia, lepsze są ustrukturyzowane wyniki z walidacją schematu niż tekst w formie swobodnej.
Śledzenie, zbiory danych i platformy z modelem LLM jako sędzią
W fazie platform LLM-as-judge dla zestawów danych Tracing należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij pliki generowane w trakcie pracy, zdefiniuj kryteria sukcesu i odrzucaj ciche, częściowe ukończenie zadań. Przy następnym kroku, który polega na pisaniu kodu lub wywoływaniu narzędzi, preferuj strukturyzowane wyniki z walidacją schematu zamiast tekstów w formie swobodnej. W fazie platform LLM-as-judge dla zestawów danych Tracing należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całego kodu.
cały wykres.Specjalne narzędzia i testy dla agentów
Gdy przechodzisz przez etap testowania specjalnych narzędzi dla agentów, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zdokumentuj zarówno prawidłowy przebieg, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez ludzi oraz obsługa wiadomości błędnych są częścią produktu, a nie elementem późniejszej dopracowywania. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdej wywołania. Bez takich informacji debugowanie pętli agenta marnuje godziny.
Jak wybrać
Gdy przechodzisz przez etap „Jak wybrać”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolij małe, testowalne jednostki nad rozbudowane skrypty. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Ustalaj punkty kontrolne po kosztownych krokach. System powinien unikać ponownego pobierania opłat za tę samą funkcję LLM, gdy operator próbuje ponownie wykonać późniejszy element.
Lista kontrolna operacyjna
W etapie listy kontrolnej operacyjnej zdefiniuj dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed wprowadzaniem zmian w kodzie. Operatorzy powinni móc ponownie wykonać dany krok na podstawie znanej punktu kontrolnego, bez konieczności zgadywania ukrytego stanu systemu.
Zapisuj czas wykonywania oraz koszt tokena lub zapytania obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z środowiska demonstracyjnego do udostępnionych środowisk.
Zastosuj ludzką aprobatę w przypadku operacji, które generują wydatki lub zmieniają dane produkcyjne. Połączenia skompilowane w czasie kompilacji nie gwarantują kompletności rozwiązania biznesowego.
Ewentualnie gorsza odpowiedź, która kosztuje 10 razy mniej, może być lepszym wyborem do użycia w środowisku produkcyjnym.
Zapisz wersje zależności oraz digest obrazu, który uruchomił demonstrację. Reprodukowalność jest ważniejsza od lokalnej wiedzy specjalistów.
Niechaj przeważać będą małe, testowalne jednostki nad rozbudowanymi skryptami. Gdy jakiś krok zawiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji.
Zanim zaczniesz promować tę architekturę, zamroź wersje, utwórz dokładny zapis dla kluczowych etapów realizacji oraz potwierdź kroki odwracania zmian. Środowiska współdzielone wymagają ograniczeń szybkości, weryfikacji przynależności użytkowników oraz wyraźnego właściciela odpowiedzialnego za rotację haseł. Wolimy nudną niezawodność od pomysłowych, jednorazowych demonstracji.
Uwaga dotycząca ce69f1512f25: unikaj przechowywania kluczy dostawcy w repozytorium, ustaw ograniczenie liczby tokenów na sesję oraz przechowuj zapisy obok plików przygotowawczych do testowania, aby późniejsze zmiany modeli pozostawały porównywalne.