How can we help?

Important Note: This feature is available in Preview for select customers. During the Preview phase, AI Agent Evaluation is accessed inside the AI Agent Platform. At General Availability (GA), the experience will move to CXA Operations Center (formerly AI Trainer).

• Core Concepts
• Dataset
• Metric
• Custom Metric
• Evaluation
• The Agent Evaluation Workflow
• Testing in Production
• Dataset × Metric Compatibility
• Reading the Results
• Reading Latency Results
• Writing Effective Reference Goals
• Writing Effective Custom Metrics

Agent Evaluation is a feature that lets you test an AI Agent Orchestration against a set of predefined scenarios and measure how the AI Agent behaves. It is designed to help AI Agent Ops and Admins answer three questions before deploying or promoting a version of an AI Agent to production:

• Did the Agent achieve the goals the user was asking for?
• Did it call the right tools, in the right order, with the right arguments?
• Did it stay within its allowed scope and follow its instructions?

This article provides a high-level walkthrough of Agent Evaluation. For step-by-step instructions on building datasets and running evaluations, see the linked articles at the bottom.

Core Concepts

Agent Evaluation is built around three concepts: Dataset, Metric, and Evaluation. Please read the following for details on each.

Dataset

A Dataset is a collection of test cases that represent the scenarios you want to validate against your AI Agent Orchestration. Each test case captures the inputs to send to the Agent (or to the simulated user), the expected behaviour, and the references used to score the outcome. A dataset can contain up to 500 scenarios.

Each test case is one of two types. A dataset can contain either type of test case or both:

• Simulated: The user side of the conversation is played by an LLM driven by a Persona, a Goal, and behavioural Instructions. Useful for multi-turn flows: Bookings, eligibility checks, troubleshooting resolutions. Expected behaviour for a Simulated test case is captured as one or more Reference Goals (up to 10 per test case) — each describing a distinct outcome the AI Agent should achieve. All Reference Goals for a test case are evaluated together as the ground truth for scoring.
• Scripted: The user side is a literal, predefined sequence of messages that is sent to the Agent exactly as written. Useful for deterministic regression tests: FAQ responses, adversarial probes, single-turn Q&A.

Because the type is set per test case, a dataset can mix Simulated and Scripted test cases, for example a multi-turn authentication flow alongside fixed-wording FAQ checks for the same use case. Datasets can also be edited directly after they are saved, so scenarios can be corrected, added, or removed without duplicating the dataset first.

Metric

A Metric is a check applied to each test case when the evaluation runs. Every metric produces a per-case score between 0 and 1, plus a reasoning explanation. The product supports the following metrics:

• Goal Accuracy: Did the AI Agent achieve the goal?
  • The Goal Accuracy judge does not look only at the agent's reply to the user. It evaluates the full chain of thought of the run, including internal thoughts, generated insights, and messages exchanged between sub-agents.
• Answer Accuracy: Does the AI Agent's reply match the expected answer?
  • Compare the agent's reply against the Reference Answer provided (available on Scripted, in datasets where every scenario is Scripted).
• Tool Call Accuracy: Did the AI Agent call the right tools, in the right order, with the right arguments?
  • Checks the tools the agent actually called against the Reference Tool Calls, matching both tool name and arguments.
• Guardrails: Did the AI Agent identify and block out-of-scope requests or prompt injection attempts?
  • Judged from the transcript by checking whether the agent refused, redirected, or deflected prompt injection attempts when it should have.
• Application Output Accuracy: Does the end-of-automation output match the expected routing label?
  • This is a deterministic check. The output is matched exactly against the reference, with no LLM judge involved.
• Instruction Adherence: Did the AI Agent follow the behavioural rules in its prompt?
  • This metric checks whether any action the agent takes conflicts with a specific instruction in its prompt.

Note: Latency is not a metric. It is reported on every evaluation for visibility only and cannot be selected or scored. See “Reading Latency Results” section.

Custom Metric

A Custom Metric allows you to define a specific evaluation criterion and attach it to scenarios, either alongside the built-in metrics or as an alternative to Goal Accuracy for scoring a dataset.

Custom Metric vs. Goal Accuracy:

• Goal Accuracy is the fastest path when a scenario just needs a quick, one-off goal defined directly on the test case. E.g., "the agent books the appointment."
• Custom Metric is the better choice when that same check needs to be reused across many scenarios, or when it’s necessary to know which individual criterion passed or failed, rather than a single pass/fail for the whole goal.

Custom Metrics are created and managed from the Metrics Library (top of the Agent Evaluation home page, next to Datasets). From there:

• Define once: Select + New Custom Metric, give it a name, and add one or more criteria with a short judge instruction describing what "pass" looks like.
• Mark criteria as Critical: Toggling a criterion to Critical means that failing that one criterion fails the whole metric. Use this for non-negotiable requirements, and leave it off for softer, quality-style checks.
• Attach anywhere: Reuse the same Custom Metric across any number of scenarios, with no copy-paste.

The Custom Metric editor includes a Steps toggle for evaluating criteria in sequence rather than independently. This makes it possible to assess not only whether each step occurred, but also whether it occurred at the right point in the flow.

The order of the metrics can also be adjusted by dragging and dropping them, which is especially important when the Steps toggle is enabled.

When to use it: When a check needs to be shared across scenarios, when pass/fail visibility is needed for each criterion rather than a single score for the entire goal, or when steps in a flow must occur in a specific order.

Evaluation

An Evaluation is a single run. It ties together:

• The AI Agent Orchestration and the version to test.
• The Dataset to run against.
• The subset of Metrics to compute.
• The Number of Runs — how many times to repeat the full dataset within this evaluation session.

Because AI Agent behaviour is non-deterministic, running the same dataset more than once helps confirm results are consistent before you trust a pass/fail verdict. Set Number of Runs greater than 1 to have the evaluation repeat automatically; results are aggregated per test case across all runs.

When the evaluation finishes, results are displayed in summary cards (one per metric), a Latency panel, and a per-test-case table. The Latency panel is always included, regardless of which metrics are selected.

The Agent Evaluation Workflow

1. Create a Dataset. Define the scenarios (up to 500 per dataset), add test cases of the Simulated type, the Scripted type, or both, and fill in the appropriate reference fields — including one or more Reference Goals for Simulated test cases — for the metrics you want to validate. Edit the dataset directly whenever scenarios need to change.
2. Create an Evaluation. Select the Orchestration, the version, the dataset, and the metrics to compute. Run the evaluation.
3. Read the results. Review the per-metric KPI %, drill into individual test cases, and investigate reasoning strings when a metric scores below expectation. Check the Latency panel to confirm response times are acceptable and to find the slowest sessions.
4. Iterate. Adjust AI Agent instructions, prompts, skills, or Orchestration structure. Re-run the same evaluation against the new version to confirm the regression is resolved and that response times have not degraded.

Testing in Production

Evaluations run against the real AI Agent Orchestration, including versions promoted to production. This is intentional: Testing against the actual orchestration is what makes results trustworthy. However, understanding what is simulated and what is not is essential.

What's self-contained

The evaluation conversation, including the simulated user, the transcript, metric scores, and any terminal status shown in results, such as an "Escalated" outcome, is isolated to the evaluation. It does not write into production analytics, reporting, or dashboards. A simulated escalation in an evaluation does not appear as a real escalation in CX metrics.

What's not self-contained: Skill calls

If the Orchestration under test invokes a skill that reaches a real backend system (a payment processor, a booking system, a CRM, or an inventory or account update), that call happens for real. The Agent cannot distinguish between a simulated user and a live one once a skill executes. The action the skill performs (charge, transfer, booking, record update, or outbound message) is not reversed or intercepted because the conversation originated from an evaluation.

Note: Review the Orchestration's skills before running an evaluation against production, since consequential actions execute regardless of the conversation's origin.

Recommended practices before testing 

Before running an evaluation, complete the following steps:

• Check which skills the Orchestration under test can call. Review whether it invokes any skill that writes to or executes against a production system, such as payments, bookings, refunds, or account or data updates.
• Use test data or a test endpoint for those skills where possible. Depending on the use case, this means swapping in a test API key, a test account, or test records instead of real customer data, so the skill executes against a non-production target during the evaluation.
• Use a sandbox environment where available. Running evaluations in a sandbox instance is the safest option when the Orchestration calls skills with real-world side effects, since actions execute against sandbox systems rather than production.
• Scope the dataset if no test data or sandbox is available. Exclude scenarios that trigger consequential skill calls (financial transactions, irreversible writes, outbound communications), or review each scenario's expected tool calls manually before running the evaluation against production.

Dataset × Metric Compatibility

Not every metric works with every test case type. The columns below refer to the type of each test case, and a dataset can contain both. For a dataset that mixes both types, only the metrics supported by both are available. The main rules:

Note: Compatible Metrics apply to the whole dataset, so only metrics supported by every test case in the dataset are available. Answer Accuracy is supported only for single-turn Scripted test cases, so it is not compatible with a dataset that contains any Simulated test case or any multi-turn Scripted test case. To use Answer Accuracy, all test cases in the dataset must be single-turn Scripted. A warning appears when a test case makes a selected metric incompatible.

Reading the Results

Once the evaluation completes, click View on the evaluation row to open the results page. The results page shows:

• Summary cards: One per metric, with the aggregate KPI % and a pass/fail badge.
• Inputs table: Every test case with its per-metric verdict.
• Click View on any row to drill into the transcript, chain-of-thought, skill details, and per-metric reasoning.
• Latency panel: The P95 turn latency, P50, P99, and worst turn, plus a chart of how turn latency is distributed. For details, see the “Reading Latency Results” section.

Reading Latency Results

Latency measures how long the AI Agent takes to reply in each turn of a conversation. Every evaluation reports it, so response speed can be reviewed alongside quality before a version is promoted. Latency is reported for visibility only: it does not change the run result, the Best and Worst Metric, or the pass, partial, and fail counts of any metric. The panel states this in the line “No latency SLO set — P50/P95/P99 shown for visibility only; latency does not affect the run result.”

Latency Summary

The left side of the panel summarizes turn latency across every session in the evaluation:

• P95 turn latency: The headline value. 95% of turns completed within this time, which makes it the most useful single indicator of the experience most users get.
• P50: The median, or typical, turn latency. Half of the turns were faster, and half were slower.
• P99: The latency of the slowest 1% of turns.
• Worst turn: The single slowest turn in the evaluation.

The total number of sessions and turns included appears in the top-right corner of the panel.

Latency Chart

The chart is a histogram of per-turn latency. Each bar is a time range, and its height is the number of turns that fall within that range. Dashed markers show where P50 (“Typical”), P95 (“95% mark”), and P99 (“Slowest 1%”) fall in the distribution.

• Hover over a bar to see the exact count for that range.
• Select a bar to filter the Scenario Sessions table to the sessions that contain at least one turn in that range. A “Showing sessions with a turn in:” label appears above the table with the selected range, for example “Latency ≥ 8.2s”. Click the X next to the range to clear the filter.

Latency in Conversation Details

Opening a session with View shows its latency at session and turn level:

• Session P95: Shown under the scenario name, this is the P95 turn latency for that session only.
• Turn duration: Each AI Agent reply in the transcript shows how long that turn took, next to its timestamp.
• Turn latency breakdown: Hovering over a turn duration shows how that time was spent, split into LLM inference and the execution of each skill called during the turn. Each component appears as an absolute time and as a percentage of the turn total.

The breakdown helps identify whether a slow turn is caused by the model itself or by a specific skill, such as a slow backend call, which points to where to optimize.

Note: The downloadable evaluation report includes the same latency summary as the results page: the P95 turn latency, P50, P99, worst turn, and the number of sessions and turns. The latency chart and the turn latency breakdown are available on the results page only.

Using Latency Effectively

• Compare versions with the same dataset. Latency is most meaningful as a comparison. Re-running the same dataset against a new version shows whether a change to prompts, skills, or Orchestration structure made the AI Agent faster or slower.
• Investigate the slowest range first. Select the bar beyond the P95 marker to isolate the sessions with the slowest turns, then open them and use the turn latency breakdown to find the skill or step responsible.
• Look at P95, not only the average. A low typical latency can hide a small number of very slow turns. P95 and P99 show how slow the experience gets for the users who wait the longest.

Writing Effective Reference Goals

Reference Goals are the ground truth against which the Goal Accuracy judge scores. The judge reads the agent's full chain of thought, not just the reply the user sees. A goal that does not name its scope can be scored against internal reasoning or inter-agent messages that were never intended to be included. The following points turn that risk into a checklist:

• Naming the actor and the surface: State whose behavior and which part of the interaction is being judged, the user-facing reply versus internal reasoning or inter-agent messages.
• Splitting compound goals: Write several small, independent goals rather than one that bundles multiple conditions, so each gets its own pass/fail and reasoning. Up to ten Reference Goals per Simulated test case are evaluated together.
• Covering both directions of a constraint: "The agent asks for X" can pass for the wrong reason if the user volunteers X unprompted and the agent simply does not reject it. Where the distinction matters, the goal should state it directly: "...and must not accept X if volunteered without being asked."
• Spelling out deterministic rules exactly: Hard rules, such as an exact phrase or a specific escalation trigger, should state the literal condition rather than leaving it to the judge to infer.
• Adding an explicit exclusion for recurring mis-scoring: If a goal keeps mis-scoring, rule out the internal reasoning or agent-to-agent traffic the judge would otherwise pick up on.

Vague goals should be scoped instead:

Worked example: One test case can carry three independent goals rather than one broad goal. For a member calling to check a balance:

• The agent discloses no balance until the member's identity is verified through the required check.
• The agent's replies to the member never claim to be human; if asked, it discloses that it is an AI.
• If the member asks to speak with a person, the agent offers and initiates a handoff to a human agent.

Each goal names a single behavior and scopes it to "the member" or "the reply," leaving the judge no internal reasoning to misread it against.

Writing Effective Custom Metrics

Once a check belongs in a Custom Metric rather than a one-off Reference Goal, the way the criteria are written determines whether the metric stays reusable and trustworthy.

• Testing one behavior per criterion, phrased as "The Agent...": A short, declarative instruction that tests exactly one thing is scored more consistently than a paragraph covering several behaviors.
• Grouping criteria by theme, not by scenario: One Custom Metric should cover one coherent theme (for example, "never leaks internal text" or "escalates cleanly"). A single metric with fifteen unrelated criteria should be split into several focused metrics instead.
• Naming criteria for triage: Short names, such as no_internal_notes or second_person_voice, make a failing criterion identifiable in results without opening the judge's reasoning.
• Reserving "Critical" for genuine non-negotiables: "Critical" should be turned on for compliance requirements or promises the agent cannot break, since a failure there fails the whole metric. Tone and quality checks are better left non-critical so they surface as signal without blocking a pass.
• Using the "Steps" toggle only when order matters: "Steps" should be turned on for a genuine sequence (for example, authentication before disclosure) and left off for independent quality checks that can each be true or false regardless of order.
• Grounding criteria in observed failures, not hypotheticals: The most reliable Custom Metrics are reverse-engineered from real evaluation failures, with one criterion per recurring failure pattern, rather than a checklist written before seeing how the agent actually fails.
• Watching the ten-criteria ceiling: A theme needing more than seven or eight checks usually signals two themes; splitting the metric is preferable.

Worked example: A single-theme metric, with "Steps" off since these are independent checks:

Each criterion scores independently and rolls up into one metric-level pass rate; a fourth, non-critical criterion for tone could be added the same way.

Note: Pasting the same Reference Goal into a third or fourth scenario is the signal to promote it into a Custom Metric instead. Defined once in the Metrics Library, it can then be attached anywhere, edited once, and reused across different datasets.