agent-eval
Bewijs wat je AI-agent echt deed. Controleer een opgenomen run in je tests/CI: gebruikte hij de juiste tools, bleef hij binnen budget, was hij klaar, en produceerde hij een output waarop je kunt asserteren? Scoor daarna de consistentie over veel runs om wisselvalligheid te betrappen.
@paulodevries/agent-evalWaarom
Agents zijn niet-deterministisch, dus "het werkte toen ik het probeerde" is geen test. Je moet asserteren op gedrag — welke tools werden aangeroepen, of de scope standhield, wat het kostte, of hij daadwerkelijk klaar was — en of hij dat allemaal consistent doet, niet één run op de drie. agent-eval zet een opgenomen run om in een geslaagd/gefaald-rapport dat je in CI kunt zetten.
Snelstart
import { evaluate, assertPass, usedOnlyTools, outputContains, withinBudget, finished }
from '@paulodevries/agent-eval';
// A "run" is what your agent loop already produces:
const run = {
actions: [
{ tool: 'search', input: 'opening hours', cost: 0.002 },
{ tool: 'read_file', input: 'hours.md', cost: 0.001 },
],
output: 'Open 08:00–18:00, Mon–Fri. Source: hours.md',
};
const report = await evaluate(run, [
usedOnlyTools(['search', 'read_file']), // stayed in scope
outputContains('08:00'), // got the real answer
withinBudget({ cost: 0.5, calls: 10 }), // affordable
finished(), // actually answered
]);
assertPass(report); // throws in CI if it didn't passIngebouwde checks
| usedTools(list) | elke vermelde tool werd minstens één keer gebruikt |
| usedOnlyTools(list) | de agent bleef binnen een allowlist (geen aanroepen buiten scope) |
| didNotUseTools(list) | geen van deze tools werd aangeraakt |
| outputContains / Omits / Matches | asserteer op de uiteindelijke output (substrings, verboden strings, RegExp) |
| withinBudget({cost,calls}) | kosten & aantal aanroepen bleven binnen de grenzen |
| maxSteps(n) | de agent voerde niet meer dan n acties uit |
| finished(predicate?) | hij produceerde daadwerkelijk een output |
| custom(name, fn) | je eigen predicaat over (output, run) |
| judge(name, fn) | LLM-als-jury — jij levert de model-aanroep, zodat het zero-dependency blijft |
Betrap wisselvallige agents met scoreRuns(runs, checks) → slaagpercentage + gemiddelde score over veel runs. Een check die een fout gooit faalt gesloten, nooit stilzwijgend.
Onderdeel van een tweedelige betrouwbaarheids-toolkit
agent-guardrails →
Weigert onveilige acties voordat ze draaien — begrensde scope, kostenplafonds, deny-lists, secret-blokkering.
agent-eval
Verifieert een run achteraf — de asserties die een agent veilig maken om in CI te shippen.
Dezelfde actievorm, hetzelfde mentale model. Het denkwerk achter beide: Betrouwbaarheid van agents is een guardrails-probleem, geen modelprobleem →. Feedback + PR's welkom.
Vragen
- Wat is agent-eval?
- Een zero-dependency JavaScript-library die een opgenomen AI-agent-run omzet in een geslaagd/gefaald-rapport dat je in CI kunt zetten. Het bewijst welke tools zijn gebruikt, of scope en budget standhielden, of de agent klaar was, en wat zijn output bevatte — en scoort vervolgens de consistentie over veel runs om wisselvalligheid te betrappen. Ongeveer 4 KB, Node 18+, MIT-gelicentieerd, werkt in elke test runner.
- Hoe test je een niet-deterministische AI-agent?
- Je bewijst niet de exacte outputtekst — je bewijst gedrag. Neem op wat de agent deed en controleer invarianten: dat hij alleen de tools gebruikte die je toestond, binnen een kosten- en aanroepbudget bleef, daadwerkelijk klaar was, en dat zijn output het echte antwoord bevatte. Draai hem daarna veel keer en scoor het slaagpercentage — één groene run is geen test; een stabiel slaagpercentage wel. Een check die een fout gooit faalt gesloten, nooit stilzwijgend.
- Hoe verschilt agent-eval van agent-guardrails?
- agent-guardrails is de runtime-helft — het weigert onveilige acties voordat ze draaien. agent-eval is de test-tijd-helft — het verifieert een opgenomen run achteraf, in CI. Dezelfde actievorm, hetzelfde mentale model: guardrails stoppen de agent live; eval bewijst in je test suite dat hij zich gedroeg.