Agent Evals: Finally, With The Map

Before launching an agent into production, how do you establish that it does what you expect? A convincing response is only part of the evidence. You also need to examine the actions it takes, whether those actions advance its goal, and what they change in its environment. Ari Heljakka of Root Signals organizes that problem into a map with two sides: semantic evaluation and behavioral evaluation.

Semantic evaluation asks how the agent’s representations relate to reality. Behavioral evaluation asks how its actions and tools contribute to its goals and affect the environment. Each side can be examined locally or across a sequence:

The distinction determines what evidence an evaluator needs. One response can expose an inconsistency within that response; consistency across a conversation requires the history. Likewise, examining one tool call is different from assessing whether a sequence of calls makes progress.

Both sides need grounding. On the semantic side, grounding representations in data—often through retrieval-augmented generation, or RAG—supports truthfulness. On the behavioral side, available tools connect the agent’s intentions to actions it can actually perform. Heljakka treats this symmetry as more than a diagramming convenience: representing the world is itself an activity, so representations can be understood as a special case of behavior. The map separates these concerns to make evaluation manageable while keeping their connection visible.

Start with the quality of a single response. Is it consistent? Is its content safe? Does it align with stakeholder values and adhere to their policies? These properties are not inherently agentic: an ordinary language-model application needs them too. They belong on the map because they establish the semantic baseline against which the additional demands of agent behavior become clear.

Retrieval introduces another set of relationships to evaluate. Heljakka places RAG within the broader problem of attention management: what information is brought into the agent’s context? Evaluating that process means checking whether the retrieved context is correct and whether it comprehensively recalls the relevant information. Those questions concern the material supplied to the model before they concern the answer it produces.

Once there is an answer, three distinctions matter:

Faithfulness is not a guarantee of external truth. An answer can accurately reflect its reference material while that material is incomplete or wrong; it can also remain faithful while failing to answer the question. Keeping these relationships separate makes a failed evaluation more informative than a single undifferentiated quality score.

The same principle extends through the RAG pipeline: different evaluators inspect different relationships among its parts. Retrieval quality and answer quality are connected, but they are not interchangeable. The map helps identify which relationship a test actually measures before its result is used to judge the whole system.

Moving from one response to a conversation changes the unit of evaluation. Now the questions concern how the history develops: whether the conversation remains consistent and coherent, and whether it stays on topic when that is required. Topic adherence needs a policy, not just a similarity measurement. If the user is allowed to change the subject, following that change can be correct behavior; in a constrained interaction, the same shift may be a failure.

Reasoning adds another kind of semantic sequence. Motivated by the progress achieved through investment in reasoning, Heljakka includes the evaluation of reasoning traces where those traces are available. These are sequences of representational activity: how the agent develops its understanding before taking an external action. Conversation evaluation follows the exchange with the user; reasoning evaluation follows the available sequence through which the agent works toward an answer or decision.

Crossing to the behavioral side starts with individual actions. Does the agent follow instructions? Does it correctly interpret the characteristics of the available tools and choose an appropriate one? Are tool outputs of sufficient quality, and are tool-use errors handled correctly? These checks concern behavior even before there is a chain of actions to assess.

The structure of the call is a separate check. A tool request may select the right operation but supply malformed JSON or arguments that do not satisfy the tool’s contract. Conversely, a structurally valid request may select the wrong operation. For an illustrative order-lookup task, a proposed call might be represented as:

{
  "tool": "get_order",
  "arguments": {
    "order_id": "ORD-1042"
  }
}

This record makes the distinctions concrete: JSON validity concerns its syntax; argument validation concerns order_id; tool selection concerns whether get_order fits the instruction. The proposed call alone does not establish the quality of a returned order record or the handling of a tool failure. Those require evidence from the subsequent execution.

A sequence of individually acceptable calls still needs evaluation as a sequence. Are the actions converging toward the goal? Is the plan consistent, and is it good under the quality criteria that matter for this task? Local correctness cannot answer those questions on its own. The evaluator must relate the chain of behavior to the intended outcome.

This returns both halves of the map to external reality. Representations are ultimately grounded in truthfulness; behavior is grounded in goal achievement and utility. In Heljakka’s framing, the intermediate checks are proxy metrics for those ends. A tool-selection score or plan-quality score is useful because it helps explain or anticipate successful behavior, but it should not replace checking whether the agent actually accomplished something useful.

The map describes what to evaluate, but operating an agent introduces additional dimensions. Cost and latency matter because the objective is to reach the goal as cheaply and quickly as possible. The number of steps also belongs in that optimization: the route to an outcome has operational consequences as well as behavioral ones.

Tracing and debugging provide the evidence needed to locate where the agent went wrong. Error management, in this part of the discussion, specifically concerns errors in tool usage. It is distinct from semantic errors made during inference or reasoning. Keeping that distinction visible helps separate a failed interaction with a tool from a mistaken interpretation of the world.

Evaluation timing cuts across the map:

• Offline testing: What can be tried and evaluated during development?
• Online testing: What can—and should—be evaluated during the agent’s actual activity?

These are separate dimensions, omitted from the simplified diagram to keep it readable. They still need deliberate treatment in the evaluation system; a development-time test and a check during live operation answer questions under different conditions.

Application-specific evaluation extends beyond the general map. Some specialized topics are mature; others remain active research areas. The useful additions depend on what the agent does. Tool-specific metrics can be comparatively straightforward when the tool is an API call with behavior that can be measured independently.

Those tool contracts can often be tested with traditional software-testing methods. Many other measurements use LLM-as-judge techniques. An evaluation system can therefore combine conventional tests of concrete tool behavior with model judgments of qualities that require interpretation. Introducing a judge, however, creates another system whose behavior and operating costs need attention.

A common starting point is a single-tier approach: optimize the operative LLM flow—the agent—and use evaluation scores to guide that work. The omission is that the judge introduces its own cost, latency, and uncertainty. Receiving a score does not remove the need to understand the system producing it.

Heljakka recommends accounting for judge optimization early. His double-tier approach treats both flows as optimization targets:

The second tier makes evaluation itself an operational concern. The agent needs to perform its task well; the judgment flow needs to assess that performance with appropriate attention to its own uncertainty, expense, and delay.

Heljakka calls this work EvalOps. Evaluations can become sufficiently complex, expensive, and slow to require dedicated operational effort. In his framing, EvalOps is a special case of LLMOps that works with different kinds of entities and therefore needs different implementation choices, ways of thinking, and resource allocation. Building the judge into the workflow is only the start; getting the evaluations right is work that must itself be supported.

The objective is to make agents measurable and controllable so that their behavior follows the operator’s intentions. Evaluation serves that objective when it connects representations to reality, actions to intended goals, and the judgment process to a system that can itself be understood and improved.