My field notes
"We buy cars knowing they've been crash tested. AI systems? Most get shipped on vibes."
Two failure patterns I kept coming back to: a chatbot that passed every test and failed in production because nobody put out-of-scope inputs in the test set — and a bias fix that broke a different slice because only the repaired cases were re-tested. The root cause was the same: gaps in what was tested, and testing after building instead of before. That's the shift I now apply to every agentic project — define what success looks like before writing a single line of agent code.
The Benchmark Problem
Every model launch comes with a slide full of benchmark scores. They're not lies — but they're not the full truth either. Benchmarks test the model in a controlled, standardised scenario. Your system is none of those things.
What benchmarks actually measure
General Knowledge
History, facts, relationships between concepts. MMLU is the canonical benchmark here.
Math & Reasoning
Equations, multi-step logic, word problems. GSM8K, MATH. Harder to game than trivia.
Coding
HumanEval, SWE-Bench. Most-cited because coding ROI is largest — Cursor, Copilot, Devin.
Retrieval / Context
Needle-in-haystack: hide a fact deep in a 100K-token document, ask the model to find it.
Tool Use / Agentic
Does the model select the right tool, at the right time, without being prompted? ToolBench, τ-bench.
Humanity's Last Exam
Expert-level questions across 100+ disciplines. Frontier models score ~8–30%. Designed to resist saturation.
When to use them, when to distrust them
Click each scenario to see the failure mode.
Healthcare, legal, financial domains are not in benchmark datasets. A model scoring 90% on MMLU could score 40% on your clinical note summarisation task. The benchmark never saw your domain.
The model has never seen your internal docs, product catalogues, or customer history. Benchmark tests what it was trained on. Your data is different.
Benchmarks test the model in isolation. Your agent wraps it in retrieval, memory, tool calls, and routing. The model's benchmark score says nothing about how those layers interact.
MMLU, GSM8K, HumanEval — all public. LLMs train on the internet. The model may have memorised questions and answers during pre-training, inflating its score without genuine reasoning.
Benchmarks give the model one question, one shot. Real agents make sequential decisions over many steps. Compound error rates mean even a "97%-accurate" model fails end-to-end. See the cascade calculator below.
Most frontier models now cluster near the ceiling on popular benchmarks. The gap between model versions (4.1 → 4.2 → 4.3) is marginal on MMLU. Benchmarks stop differentiating precisely when you need them to.
Two real-world failures that changed how I think about this
The Input Gap — Chipotle's Chatbot
Built to answer menu questions. Users asked Python coding questions — and it answered. Not because the model was broken. Because nobody put out-of-scope inputs in the test set. It passed every test. Failed in production.
The lesson: What you test defines what you know. Gaps in test coverage are invisible until production finds them.
The Fix Trap — Google's Image Model
Engineers fixed a racial bias problem. The fix made the model start generating people of color in historically wrong contexts. They tested only the repaired slice — never re-ran the full dataset. Fix one metric, break another.
The lesson: Every fix needs a full regression run. Patch testing is how you swap one problem for another.
RAGAS — What Practitioners Actually Use
ROUGE and BLEU measure word overlap between your answer and a reference string. Useful in 2015 for machine translation. For RAG systems in 2025, they miss the point: meaning matters, not word matching.
RAGAS (Retrieval-Augmented Generation Assessment) uses an LLM internally to judge semantic quality across four dimensions. You give it: the question, the generated answer, the retrieved chunks, and the ground truth. It returns four scores from 0 to 1.
Click each card to see a scored example.
Context says: "Returns accepted within 30 days of purchase."
Answer: "You can return your order within 30 days."
Every claim in the answer traces directly to context.
Context says: "Returns accepted within 30 days."
Answer: "You can return within 30 days and get a full refund including shipping."
"Full refund including shipping" was not in context — hallucinated.
Question: "Can I return my order after 30 days?"
Answer: "Our return policy allows returns within 30 days of delivery."
Directly answers what was asked.
Question: "Can I return my order after 30 days?"
Answer: "You can track your order using the tracking number in your confirmation email."
Accurate information — but about shipping, not returns.
Retrieved 10 chunks. 9 were about "maternity leave policy."
Question was about maternity leave. Retrieval was focused and relevant.
Retrieved 10 chunks: 2 about maternity leave, 8 about unrelated HR policies.
The retrieval pipeline is pulling noisy chunks. Chunk strategy needs work.
Question needed 4 clauses from a contract to answer fully.
Retrieval returned all 4 relevant clauses. Nothing important was missed.
Question needed 4 clauses. Retrieval returned 1 of them.
Model answered based on partial info — missed key limitations in clauses 2, 3, 4.
The Bias Lab
LLM-as-judge is powerful but not objective. Every judge model carries systematic biases that skew scores regardless of actual quality. Knowing the bias tells you how to counteract it.
When shown two answers (A and B), the judge tends to prefer whichever appears first — not because it's better, but because of how attention weights work in transformers.
Answer B: "You have 30 days after delivery to initiate a return."
Answer A: "The return window is 30 days from delivery."
Longer answers consistently score higher — regardless of whether the extra length adds value. The judge conflates thoroughness with quality.
A model used as judge subtly prefers outputs that resemble its own style and patterns — as if grading its own work. If you use Claude as both agent and judge, Claude-the-judge will favour Claude-style responses.
If you frame the evaluation prompt with a preference signal — even subtly — the judge agrees with it. The judge is optimised to please, and that optimisation contaminates evaluation.
Response: "Returns are accepted within 30 days."
Same response: "Returns are accepted within 30 days."
Calibrating your judge (the actual process)
- Take 100–200 examples from your golden dataset
- Have humans rate each response (1–5 or pass/fail)
- Run your LLM judge on the same examples
- Calculate Spearman rank correlation between human and judge scores
- Correlation > 0.80 — judge is calibrated, use at scale
- Correlation < 0.80 — adjust judge prompt, add scored examples to its system prompt, or try a different model
Eval Method Selector
Four methods exist. Each is right for a different situation. Answer three questions to find yours.
Human Eval
Highest fidelity. Experts review each response. Catches nuance, tone, subtle errors. Slow, expensive, doesn't scale. Must-have for any production system.
User Eval
Real users rating real outputs in production. Thumbs up/down, preference between two outputs. Scale advantage — millions of data points. But delayed signal.
Code-Based Eval
For deterministic outputs. Write a function to check: did it return valid JSON? Is the intent label correct? Binary, cheap, instant, runs in CI. No LLM call needed.
LLM-as-Judge
A larger model reviews your agent's outputs. Scalable, affordable, but carries biases (see the Bias Lab above). Must be calibrated against human labels before trusting.
The Coverage Matrix
Your golden dataset is only as good as its distribution. A dataset that's 90% happy-path cases will make your eval look great — while your production system fails constantly on the edge cases real users throw at it.
Set how many examples you plan for each category. Watch the warnings.
Minimum viable dataset sizes
| Stage | Min examples | What it's good for |
|---|---|---|
| Early prototype | 25–50 | Catching obvious failures, initial prompt tuning |
| Development | 100–200 | Meaningful signal, iteration between versions |
| Pre-production | 500+ | Statistical confidence (2% improvement is real, not noise) |
| Production-grade | 1,000+ | Reliable regression detection, fine-grained metric tracking |
The Cascade Calculator
Single-step accuracy is not end-to-end accuracy. If each step in your agent pipeline succeeds 95% of the time, a 10-step agent completes successfully less than 60% of the time. This is the most important number in multi-agent eval.
The Iron Triangle
Every production AI system is optimised across exactly three dimensions. Pull one vertex and the other two stretch. There is no free lunch — only the right tradeoff for your use case.
What adds to cost
| Source | What it is | Optimise by |
|---|---|---|
| Output tokens | 3–5× more expensive than input. Every intermediate step costs output tokens too. | Instruct model to be concise. Token budget in system prompt. |
| Repeated system prompts | Same prompt sent with every request burns tokens each time. | Prompt caching — 90% discount on cached prefix tokens (Anthropic, OpenAI both offer this). |
| External API calls | Search APIs (Exa, Tavily, Perplexity) charge per call. | Cache results. Don't call if context already has the answer. |
| Vector retrieval | Embedding, similarity search, re-ranking — none are free. | Right chunk size. Smaller top-K. Cache frequent queries. |
| Retries | Failed steps get rerun. Each retry compounds cost. | Cap max retries. Early stopping. Timeout budgets. |
| LLM-as-judge calls | Running eval is itself an LLM call — often overlooked. | Use smaller distilled judge models. Batch non-realtime evals. |
What adds to latency
TTFT — Time to First Token
How long before the model starts generating. Includes retrieval, context assembly, and model thinking time. Users feel this as the "loading" gap.
TPS — Tokens per Second
Generation speed. Smaller models are faster. Streaming output hides latency by showing tokens as they generate rather than waiting for completion.
Sequential vs Parallel
Not every tool call needs to be sequential. Parallelise independent calls. A 3-second operation run in parallel with two others costs 3 seconds total, not 9.
Guardrailing overhead
Safety checks mid-processing add latency. The check itself may require an LLM call. Design guardrails as lightweight classifiers, not full inference calls.
Eval vs Monitoring vs Observability
These three terms get used interchangeably. They're not the same. They live under the same umbrella but serve different purposes at different times.
Eval
Asking: "Is the system producing correct, useful, safe outputs?" You're running a test suite against your golden dataset. You get a score. You make a decision (ship / don't ship / fix).
- Runs before deployment (offline)
- Runs after deployment (online)
- Driven by you, not by live traffic
Monitoring
Asking: "Is the system healthy right now?" A dashboard showing latency, cost, error rates, quality scores — all moving in real time. You're watching, not testing.
- Continuous, always-on
- Alerts when metrics cross thresholds
- Monitoring without alerts is useless — it's just a recording
Observability
Asking: "What exactly went wrong and why?" Triggered when monitoring shows something off. Deep traces of every micro-step — input, output, tokens, tool calls, timing.
- Logs: "what happened" (tool failed, output sent)
- Traces: "why it happened" (input → model → tool → output with timing)
- You need enough logged to debug — design for observability from day one
Alerts — monitoring isn't enough without them
A security camera that records but never sends an alert is near-useless. You only find out something went wrong after the damage is done. Same principle applies to AI monitoring.
Set thresholds for:
- End-to-end latency > X ms
- Quality score drops below X%
- Tool failure rate exceeds X%
- Cost per query exceeds $X
- Hallucination rate spikes above X%
Where to look:
- LangSmith — best for LangChain ecosystem
- Arize / Phoenix — strong for model performance
- Langfuse — open source, self-hostable
- Braintrust — eval-first workflow
Your Eval Maturity Level
Check every practice you currently have in place. Your level updates automatically.
Check
Dataset
Scoring
Monitoring
Eval Loop
Abbreviations
Every term used on this page, in one place.
Public Sources & Further Reading
DeepEval (Confident AI)
Open-source LLM eval framework — LLM judge, RAGAS, red-teaming
RAGAS Documentation
docs.ragas.io — RAG evaluation metrics and methodology
PromptFoo Documentation
promptfoo.dev — prompt regression testing and red-teaming
SWE-Bench
swebench.com — real GitHub issue benchmark for coding agents
My workflow: A GenAcademy session introduced me to the eval-driven development mindset — using evals as guardrails from day one, not an afterthought. From there I explored DeepEval, RAGAS, PromptFoo, and public benchmark research, then built this guide to make the decision tree concrete. This is my personal learning synthesis. A live session has far more depth and takeaways than any set of notes captures — for the full curriculum, reach out to GenAcademy directly.