Evaluation Is the Missing Loop in Agent Workflows

Agent workflows are unusually easy to improve by accident.

You change an instruction. The next run looks good. You add another rule. A different task breaks. You give the model a stronger prompt. The original failure disappears, but a new one appears somewhere else.

After a few weeks, you have a growing pile of instructions and no reliable answer to the only question that matters: is the agent actually better?

If you do not replay the same work, you are measuring your mood about the last run, not the quality of the system.

The demo is not an evaluation

A successful demo proves that one path worked once. Agent workflows need more than that because the system is probabilistic and stateful. Small changes in context, tool output, or task wording can produce a different path.

An evaluation starts with representative work. Real tickets. Real repository structure. Real conventions. Not a toy prompt that makes the workflow look clean.

The task should have a clear expected result, but not necessarily one exact sequence of actions. If the agent takes a different safe path and produces the right change, that should count as success. Evaluate the outcome and the important constraints, not theatrical obedience.

What to measure

Correctness comes first: did the implementation solve the task? Then check the engineering constraints: did it touch the right boundary, preserve existing behavior, run the required checks, and produce a reviewable change?

There are operational measures too. How many tool calls did the run take? How often did it ask for help? How much did it cost? Did it retry the same action? Did it stop at the right boundary?

You do not need a giant scorecard. Start with five or ten tasks that represent the work you actually care about and a short list of pass conditions for each.

A task can pass while still teaching you something. The agent may have reached the result through a fragile route, used twice as many calls as necessary, or relied on a lucky document lookup. Record those details. Evaluation is not just a gate; it is a source of better design.

Keep failures concrete

"The agent was confused" is not a useful failure record. Write what happened: it selected the wrong package because two tools had overlapping names; it guessed a story-point estimate when the ticket was ambiguous; it changed a shared component without checking its consumers.

Then classify the failure. Was context missing? Was a tool too broad? Was the instruction ambiguous? Was the permission wrong? Did the task itself lack an expected outcome?

This classification keeps the fix proportional. Do not add a paragraph of prompt text to solve a permission problem. Do not add a new tool to solve a missing acceptance criterion.

Test the workflow, not only the final diff

The final code can look correct while the path to it is unsafe. An agent may edit production configuration, ignore a required check, or make a destructive action and then repair the result. The diff hides that story.

For important workflows, record the trace: the decisions, tool calls, approvals, retries, and stop conditions. You are looking for behavior that will fail on a slightly different task.

This is where the previous articles meet. The context should be sufficient. The tools should be narrow. The agent should ask at sharp edges. The guardrails should cap the run. Evaluation is the feedback loop that tells you which of those parts is weak.

Do not overfit the benchmark

A benchmark can become another form of theater. If you keep rewriting the test until the agent passes, you are measuring how well the test has adapted to the agent.

Keep some tasks private or rotate them. Add a fresh real task occasionally. Compare the agent's performance against a human review standard, not only against yesterday's score.

Also keep a manual path. An agent that passes a benchmark but makes work harder for the person reviewing it is not helping. The system should reduce cognitive load, not move the same uncertainty to the final reviewer.

The reframe

Prompt editing feels like progress because the feedback is immediate. Evaluation feels slower because it asks you to repeat work you already did. That repetition is the point. Without it, every improvement is anecdotal and every regression can hide in a different task.

I would rather have a small honest suite of real tasks than a dashboard full of synthetic numbers. The goal is not to prove that the agent is intelligent. It is to know whether it can perform the specific work I am asking it to perform, within the boundaries I am willing to give it.

Take the last five agent tasks that required correction. Turn them into a tiny evaluation set. Write down what success means, replay them after the next change, and keep the failures visible. That is how an agent workflow becomes an engineered system instead of a collection of hopeful instructions.