Run · Chapter 08

Agent evaluation and reliability

Testing agents before you trust them with a transition.

A convincing demonstration shows that a system can succeed in particular circumstances. Before giving it more responsibility, ask which circumstances the business will actually encounter and what a costly mistake would look like. Those cases belong in its evaluation.

Collect representative examples with permitted data. Include ordinary work, missing inputs, stale claims and failures that would affect a customer. Agree what counts as an acceptable result before comparing models or instructions. A fluent answer is not automatically a correct or usable one.

Keep a record the next change must answer to

Give the cases explicit scoring criteria and keep them with the relevant model, prompt, skill and tool versions. A tool such as Promptfoo can run comparisons; the business still has to choose the cases and judge whether their scoring reflects the work.

Check quality alongside cost, latency and human correction. Where permission or recovery matters, test that behavior too: an approval for the wrong version should not authorize the current action, and retrying an interrupted run should not duplicate its effects. Mark paths you have not exercised as untested.

Let the evidence set the boundary

Run the cases again when a model, skill or connection changes. A regression gate should make a decline visible before the new version takes over. Investigate disagreements between the scores and the reviewer’s judgment instead of hiding them in an average.

Expand autonomy when the results support it and an accountable owner accepts the remaining limits. The evaluation earns its place when it changes a deployment decision, catches a regression or identifies work that should still return to a person.

Tools and setup

Existing implementation: Promptfoo's official quickstart provides a local evaluation configuration and comparison interface. Real cases and judgments still come from the workflow owner.

  1. Choose permitted examples and a rubric; include stale facts, missing input, untrusted instructions, duplicate effects and approval mismatches where relevant. Start small, expand from incidents and preserve a holdout where practical.
  2. In a separate test folder with a supported Node runtime, run npx promptfoo@latest init. Inspect generated files; configure chosen providers, prompts, cases and assertions. Put credentials in the local environment/secret manager, not the case file or chat. Pin the reviewed package version for repeatable team/CI use.
  3. After test-spend approval, run npx promptfoo@latest eval and npx promptfoo@latest view. Compare results and manually adjudicate critical cases. Version config, skill/prompt revision, provider/model and result report. No real customer side effects should be enabled in tests.

Setup paths checked against linked documentation on 15 November 2026. Verify current account support during setup; reader integrations have not been tested here.

Work through this with your agent

Paste the request into your assistant. It will interview you and help produce the working artifact.

Interview me to create an evaluation set for one workflow. Ask at most three questions per turn and wait. Ask what acceptable output means, which failures matter and which real cases we may use. Start with a small representative set; cover common, ambiguous, missing-data, stale-fact, unauthorized-action and untrusted-input cases as relevant. Remove or protect sensitive data. Record inputs, expected outcomes, scoring rubric, severity and source permission; reserve holdout cases when practical. Version cases with the prompt, skill, model and tool setup. Run an authorized baseline and compare proposed changes on the same cases, including cost and human review. Save EVAL-CASES.md and EVAL-REPORT.md with actual results, known gaps and a release gate. Expand coverage from observed failures. Never fabricate passing results, treat model grading as sufficient for critical claims, or switch models solely because a new release exists.

Use these documented setup paths as references; check current account support before acting:
https://www.promptfoo.dev/docs/getting-started/

The Hypothesis Diff · weekly

Know when a hypothesis is stressed or changes.

One email a week: which hypotheses hold, which are stressed, which changed, and the tools worth trying. Nobody else publishes what stopped being true.