AI Agent Evals: How to Prove Your Agent Actually Works

You shipped an AI agent last week. It works. You know it works because you ran it four times and the output looked right.

That is not proof. That is a vibe.

AI agent evals are the fix. An AI agent eval is a repeatable test that runs a fixed set of inputs through your agent and scores the outputs against a known correct answer, so you end up with a number instead of a feeling.

Today we build that scoring system. You will finish this post with a five step method, the real tools that run it, and a pass threshold you can put in front of a client without flinching.

Key takeaways

• An AI agent eval is a repeatable test that runs fixed inputs through an agent and scores the outputs against reference answers.
• Manual spot checking does not scale, because agents fail on the inputs you never thought to try.
• n8n ships an Evaluation node with a Set Metrics operation that supports Correctness, Helpfulness, String Similarity, Categorization, and Tools Used as built in metrics.
• The OpenAI Evals API scores outputs with graders including String Check, Text Similarity, Label Model, Score Model, and Python graders.
• LangSmith supports offline evaluation on curated datasets and online evaluation that scores live production traffic, plus human annotation queues to calibrate automated judges.
• Twenty to thirty scored test cases with a written pass threshold beats a hundred casual manual runs.

Why “it looked right” fails in production

I spent sixteen years building enterprise automation before I built a single AI agent. Classic robotic process automation, meaning software bots that click through applications the same way a person would, taught me one lesson that transfers directly: the bot never breaks on the case you tested. It breaks on case 47, the one with the weird address format, at 2 a.m., on a Saturday.

AI agents are worse, not better, on this point. A traditional bot fails loudly. It throws an error and stops. An AI agent fails quietly. It produces a fluent, confident, well formatted answer that happens to be wrong, and it hands that answer to your client with the same tone it uses when it is right.

You cannot eyeball your way out of a failure mode that looks identical to success.

What AI agent evals actually measure

Most operators assume an eval measures one thing: did the agent get the right answer. A useful eval scores three.

The first is output quality. Is the final answer correct, complete, and in the right format. This is what most people mean when they say testing.

The second is trajectory, meaning the path the agent took to get there. An agent can reach the right answer by calling the wrong tool, calling five tools when one would do, or skipping a lookup it was supposed to run. n8n’s Evaluation node exposes this directly through a Tools Used metric that scores whether the execution actually called tools. A right answer through a wrong path is a bug waiting to surface.

The third is cost and latency. An agent that is correct and slow is still a problem when you have promised a client a response window. If you have not priced the run yet, do that before you sell it.

The RANGE Check: five steps to test an AI agent

Every rifle gets zeroed on a range before anyone trusts it downrange. Same idea here. The RANGE Check is the sequence I run before an agent touches a client account.

R: Reference set

Collect twenty to thirty real inputs and write the correct output for each one by hand. This is your reference set, sometimes called a golden set. Pull from actual traffic if you have it. Include the ugly ones: the blank fields, the misspellings, the customer who wrote three paragraphs when the form asked for one line.

Action step: open a spreadsheet with two columns, input and expected output. Fill thirty rows. That spreadsheet is your test suite.

A: Assertions

Write down what “correct” means in plain language before you score anything. Vague standards produce vague scores.

Bad assertion: the summary should be good. Good assertion: the summary is under 80 words, names the company, states the budget range if one was given, and never invents a number that was not in the source. Each of those is checkable.

N: Numbers

Pick the metric that fits each assertion. Deterministic checks come first because they are free and they never drift.

• Exact match on a fixed label such as hot, warm, or cold. n8n calls this Categorization, OpenAI calls it a String Check grader.
• Character level closeness for near matches. n8n calls this String Similarity, OpenAI calls it Text Similarity.
• A model grading a model for anything judgment based. n8n ships Correctness and Helpfulness as AI based metrics on a one to five scale. OpenAI offers Label Model and Score Model graders for the same job.
• Tool path checks, so you catch the agent that got lucky.

Use the model grader last and least. Every judgment call you hand to another model is a call you can no longer fully explain to a client.

G: Gate

Set the number that blocks deployment, and write it down before you see your first score. Otherwise you will move the line to wherever your agent happens to land.

Mine is simple. Categorization accuracy at or above 90 percent, zero fabricated facts across the whole reference set, and no single case scoring below a 3 on Correctness. The fabrication count is the one I will not negotiate. One invented number in a client deliverable costs more than the entire engagement is worth.

E: Every change

Re-run the full reference set on every prompt edit, every model swap, and every tool change. No exceptions. This is where evals earn their keep, because the failure you are guarding against is the silent regression: you tighten a prompt to fix one case and quietly break six others.

Model swaps are the most dangerous. A newer model is not automatically better on your task, and only a before and after score on the same inputs will tell you.

Worked example: evals for a lead qualification agent

Example scenario. You built an agent that reads inbound contact form submissions and tags each one hot, warm, or cold, then writes a two sentence summary for the owner. If you have not built one yet, start with the AI lead qualification agent build first, then come back and score it.

1. Reference set: thirty real form submissions from the last quarter, each tagged by hand by the person who actually worked those leads.
2. Assertions: the tag matches the human tag, the summary is under 40 words, the summary names the service requested, and the summary contains no budget figure that was not in the submission.
3. Numbers: Categorization for the tag, a custom word count metric for length, and a Correctness score against the hand written summary.
4. Gate: 90 percent tag accuracy, zero invented budget figures, no summary over 40 words.
5. Every change: the suite re-runs whenever the classification prompt is edited.

The first run is usually humbling. That is the point. You would rather find the gap on thirty archived leads than on a live one.

The tools that score for you

You do not need a custom harness. Three options cover almost every solo operator setup.

n8n Evaluations. If your agent already runs in n8n, this is the shortest path. n8n added Evaluations in June 2025, requiring version 1.95.1 or higher. It runs your reference set as a separate path inside the same workflow, and the Evaluation node’s Set Metrics operation gives you Correctness and Helpfulness on a one to five scale, String Similarity from 0 to 1, Categorization as an exact match, Tools Used, and custom metrics you calculate yourself. If you are still standing the agent up, the n8n AI agent build walkthrough comes first.

OpenAI Evals API. Define an eval with a data source config, attach testing criteria, and run. Graders include String Check with operations like equality and contains, Text Similarity, Label Model for classification, Score Model for numeric quality ratings, and Python graders for custom logic.

LangSmith. The heavier option, and the right one when you are running agents for paying clients. It separates offline evaluation on curated datasets from online evaluation that scores real user interactions as they happen, and it includes human annotation queues so a subject matter expert can review flagged runs and calibrate the automated judge. It also plugs into pytest and GitHub workflows, which turns your gate into an actual deploy blocker.

Your first eval this week

1. Pick one agent you already run. Only one.
2. Pull twenty real inputs from its execution history and write the correct output for each by hand. Budget ninety minutes.
3. Write three assertions in plain language. Make each one checkable.
4. Score the twenty runs against those assertions. Spreadsheet is fine on day one.
5. Write your gate number down and date it.
6. Move the suite into the Evaluation node or the Evals API once the scoring logic stops changing.

Pair the scores with an AI agent audit trail so that when a client asks why the agent made a call, you have both the score and the receipt.

Frequently asked questions

What are AI agent evals?

AI agent evals are repeatable tests that run a fixed set of inputs through an AI agent and score the outputs against known correct answers. They convert “it seemed fine” into a number you can track across prompt edits, model swaps, and tool changes.

How many test cases do I need to start?

Twenty to thirty is enough to start, provided they are real inputs rather than invented ones. The value comes from covering the edge cases you have actually seen, not from volume.

Can one AI fairly grade another AI?

It can, within limits, and it needs calibration against human judgment to stay honest. That is exactly why LangSmith pairs LLM as judge evaluators with human annotation queues, so people review flagged runs and correct the judge when it drifts. Use deterministic checks wherever a deterministic check will do the job.

How are evals different from shadow mode?

Evals score a fixed set of known inputs offline, while shadow mode runs the agent alongside live traffic without letting it act. They solve different problems and you want both: run AI agent shadow mode to see how the agent behaves on real volume, and run evals to catch regressions before that volume ever reaches it.

Do I need a paid tool to run AI agent evals?

No. A spreadsheet of inputs and expected outputs plus a scoring column is a valid eval suite. Move to tooling when re-running the suite by hand starts costing you more time than the agent saves.

What should I do when the score drops?

Roll back to the last version that passed the gate, then change one variable at a time. Sometimes the fix is not a better prompt but better AI agent error handling around the failure.

Recap

To recap: an agent that looks right is not an agent that is right, and the gap between those two is where client trust goes to die. AI agent evals close it by turning output quality into a score.

Run the RANGE Check. Build a Reference set of real inputs. Write Assertions in plain language. Attach Numbers you can actually compute. Set a Gate before you see your first score. Re-run on Every change.

The tooling already exists. None of it helps until you write down thirty correct answers by hand, which is the unglamorous hour that separates an operator from a hobbyist.

You zero the weapon before the mission. Zero the agent too.

Subscribe to the blog to get the next build in this series delivered as it publishes.

References

LangChain. (n.d.). LangSmith: AI agent and LLM model evaluation platform. Retrieved September 15, 2026, from https://www.langchain.com/langsmith/evaluation

n8n. (2025, June 6). Introducing evaluations for AI workflows. n8n Blog. Retrieved September 15, 2026, from https://blog.n8n.io/introducing-evaluations-for-ai-workflows/

n8n. (n.d.). Use metrics to measure quality. n8n Docs. Retrieved September 15, 2026, from https://docs.n8n.io/build/integrate-ai/test-and-improve-ai-workflows/use-metrics-to-measure-quality

OpenAI. (n.d.). Evaluating model performance. OpenAI Developer Documentation. Retrieved September 15, 2026, from https://developers.openai.com/api/docs/guides/evals