Writing Evals for Claude-Powered Agents: A Starter Template

Without evaluations, it's hard to know whether a prompt change helped. Someone adjusts a sentence, tries a few examples and decides it's better, and a regression turns up later with a different customer.

A useful evaluation doesn't have to be complicated. This template can be running by the end of the afternoon.

Step 1: Collect real cases

Start with 30 to 50 examples from actual use:

• Common requests that must always work.
• Edge cases that have failed before.
• Requests the agent should refuse or pass to a person.

Store each one as a simple record:

{"id": "refund-07", "input": "I was charged twice for order 5531", "expect": "looks up order 5531 and escalates the billing issue"}

Step 2: Choose how to grade

Use a mix of three methods:

• Code checks for anything objective, such as valid JSON, required fields, the correct tool being called or forbidden phrases being absent.
• Model-based grading for qualities that are harder to define. Give a grading model a rubric and ask for a pass or fail with a short reason.
• Human review of a small sample, to confirm the automated grading is reliable.

Step 3: Write the harness

def run_eval(cases, run_agent, grade):
    results = []
    for case in cases:
        output = run_agent(case["input"])
        passed, reason = grade(case, output)
        results.append({"id": case["id"], "passed": passed, "reason": reason})
    rate = sum(r["passed"] for r in results) / len(results)
    print(f"pass rate: {rate:.0%}")
    return results

This is enough to get started. Save each run's results together with the prompt version and model name.

Step 4: Run it for every change

Prompt edits, model upgrades, new tools and changes to retrieval should all be evaluated before they go live. Once the evaluation is stable, add it to your CI pipeline.

Step 5: Add cases when things break

Turn every production bug into a new test case. Over time, the evaluation set becomes an accurate record of what your users need.

Things to watch

• Check the graders. A lenient grading model makes every version look good. Compare its verdicts with human judgment on a sample.
• Avoid overfitting. If you tune the prompt against the same 40 cases for months, keep a separate set of cases you rarely look at.
• Track cost and latency along with the pass rate, so a prompt that performs slightly better but doubles the cost doesn't go unnoticed.
• Allow for variation. Agents don't give identical answers every time. Run important cases several times and look at how consistent the results are.

Forty real cases and a short script are enough to start. Add a new case every time something breaks in production.