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
• 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.

There are two dataset types:

• 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.

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, single-turn cases only).
• 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.

Custom Metric

A Custom Metric allows to define a specific evaluation criteria 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 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) and a per-test-case table.

The Agent Evaluation Workflow

1. Create a Dataset. Define the scenarios (up to 500 per dataset), select a dataset type (Simulated or Scripted), and add test cases with the appropriate reference fields — including one or more Reference Goals for Simulated test cases — for the metrics you want to validate.
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.
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.

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 dataset type. The main rules:

Note: When selecting "Compatible Metrics" while creating a dataset, the UI shows only the combinations valid for that dataset type. Some metrics require a reference field within the dataset. Custom metric selection happens during Evaluation Setup, in the "Metrics" selection.

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.

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.