Evaluating agents

What it is

Evaluating an agent means running it against a set of representative inputs and scoring the outputs with scorers — some are LLM judges, some are plain code — instead of eyeballing transcripts. mlflow.genai.evaluate() is the entry point: give it an agent (or a static set of already-collected outputs), a dataset, and a list of scorers, and it produces a table of per-example and aggregate scores tied to an MLflow run.

Why it exists

An agent built with Agents on Databricks can regress silently: a prompt tweak that fixes one question can break five others, and a model swap can change tone without changing correctness. Manual spot-checking doesn’t scale and doesn’t catch regressions consistently. Systematic evaluation turns “does this feel better” into a repeatable score you can compare across versions, and the same scoring logic that runs at development time can keep running once the agent is live.

How it works

Evaluation datasets from traces

The most useful evaluation examples come from real usage, not invented ones. Every call to an Agents on Databricks agent produces an MLflow trace; you curate a set of these traces — optionally after human reviewers have attached expert feedback to them — into an evaluation dataset, which is stored in Unity Catalog and therefore versioned, governed and shareable like anything else there. This keeps the test set anchored to how people actually use the agent instead of a wishlist a developer imagined.

Built-in judges

Databricks ships a handful of ready-made LLM judges as scorers so you don’t have to write a prompt for common quality dimensions:

Alongside those there is now a set of judges that score a whole conversation rather than one exchange — ConversationCompleteness, UserFrustration, KnowledgeRetention, ConversationalSafety among them. They matter for anything the user talks to more than once: an agent can answer every single turn acceptably and still lose the thread, or quietly exhaust the person asking.

Groundedness is deliberately a separate judge from correctness: an answer can be correct by accident without being backed by the retrieved chunks, and a grounded answer can still be wrong if the retrieved chunks themselves were bad — see the retrieval-vs-generation split in Building a RAG pipeline.

Custom scorers

Not every quality dimension has a built-in judge. A custom scorer is a Python function decorated with @scorer, whose arguments are all optional and taken by keyword: inputs, outputs, expectations (the ground truth, when you have it) and trace (the whole span tree, when the answer alone is not enough to judge). It returns a boolean, a number, a string or a Feedback. For a judge written as plain-English criteria rather than code, make_judge() builds one. It can call an LLM with your own judge prompt, or run plain code (a regex check, a schema validator) when a judge is overkill.

Aligning judges with human feedback

An LLM judge is itself a model and can disagree with what a human expert would say. Alignment means collecting a small set of examples where a person has labeled the “correct” verdict — often via the review app — and using that labeled set to calibrate the judge until its verdicts track the human’s more closely. In MLflow this is judge.align(traces), which uses the MemAlign optimizer unless you pass another; the documentation asks for at least ten labelled traces and suggests fifty to a hundred. It needs MLflow 3.14.0 or above, and the human feedback has to be logged under exactly the judge’s name, or the judge never sees it. The whole-conversation judges cannot be aligned. Skipping this step means trusting a judge that was never checked against your actual definition of quality.

Scoring from the UI, without writing anything

Evaluation no longer has to start in a notebook. In the experiment’s Traces tab you can tick a few traces, choose Actions → Evaluate, pick judges in the Run scorer dialog and run them; the verdicts come back attached to those traces as feedback, and the run is recorded under Evaluation runs. The same menu exports the selected traces into an evaluation dataset. It is the fastest way to find out whether a judge says what you think it says before wiring it into anything.

Production monitoring on traces

The same scorers used during development can run continuously against live production traces instead of a fixed test set, flagging quality drift as it happens rather than at the next scheduled evaluation. You register a judge and start it with a sampling rate rather than calling it per request. This closes the loop: development evaluation decides whether a change ships, production monitoring watches what ships once real traffic hits it. It is a Beta feature and documented apart from evaluation itself.

Example

import mlflow
from mlflow.genai.scorers import Correctness, Guidelines, RetrievalGroundedness, scorer

@scorer
def answer_has_citation(outputs, trace):
    return "source:" in outputs["content"].lower()

results = mlflow.genai.evaluate(
    predict_fn=my_agent.predict,
    data=eval_dataset,
    scorers=[
        Correctness(),
        Guidelines(guidelines="Never mention internal ticket numbers."),
        RetrievalGroundedness(),
        answer_has_citation,
    ],
)

mlflow.genai.evaluate(
    predict_fn=my_agent.predict,
    data=production_traces,  # scored continuously as a monitor, not a one-off run
    scorers=[Correctness(), RetrievalGroundedness()],
)

Common mistakes

• Building an evaluation dataset from hand-written questions instead of real traces, then being surprised production quality doesn’t match the eval score.
• Treating a judge’s verdict as ground truth without ever aligning it against a human label.
• Running Correctness on a RAG agent but never RetrievalGroundedness, so a well-worded but unsupported answer scores fine.
• Evaluating only at development time and finding out about drift from user complaints instead of production monitoring.