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

This document outlines best practices for designing datasets, including dataset authoring, choosing metrics, and running evaluations on the AI Agent Evaluation feature (Preview).

Table of Contents

• Best Practices for Creating Datasets
• Best Practices for Designing Simulated Datasets
• Best Practices for Determinism
• Best Practices for Adversarial and Security Scenarios
• Best Practices for Writing Reference Goals
• Best Practices for Managing Datasets 
• Best Practices for Choosing Metrics
• Best Practices for Running and Iterating

Before designing datasets, the core concepts of Agent Evaluation (Dataset, Metric, and Evaluation) and how they fit together should be understood. For more information, see [Preview] Agent Evaluation: Overview in this article.

Best Practices for Creating Datasets

• Starting small and covering critical paths first: 10 to 20 sharp scenarios covering the highest-value flows outperform 200 sloppy ones. Breadth should be added only after the critical paths are solid.
• Keeping one dataset, one purpose: Routing tests should not be mixed with tool-execution tests, or happy-path scenarios with adversarial probes. Mixed datasets hide both signals behind one aggregate pass rate.
• Naming test cases for triage, not sequence: "T007 — Customer data disclosure — Target: Authorized users" is preferable to "Test Case 12."
• Filling in only the reference fields the chosen metrics need: Each reference field maps to one metric: "Reference Goal" to Goal Accuracy, "Reference Tool Calls" to Tool Call Accuracy, "Reference Application Output" to Application Output Accuracy, and "Reference Answer" to Answer Accuracy. Instruction Adherence and Guardrails require no reference field.

Best Practices for Designing Simulated Datasets

A Simulated test case has three fields that jointly drive the conversation. These should be kept cleanly separated:

• Persona: Who the user is: Identity, channel, language, emotional state. 
• Instructions: How the user behaves: Pacing, tone, what not to volunteer. 
• Goals: What the user is trying to get: The facts to reveal and the order to reveal them in.
   
• Progressive disclosure should be used for multi-turn flows. Without an explicit rule, the simulator states its whole backstory in the first message, and multi-turn coverage collapses. The following should be added to Instructions: "Answer ONLY the specific question just asked — never volunteer unasked information" and "max ONE new fact from your Goal per message." Facts in Goals should be numbered in reveal order. This Instructions block is reusable verbatim across an entire dataset. Only Persona and Goals need to vary per scenario (as seen across a 294-scenario MasOrange routing dataset).
• Supply sensitive test data only on request. "Only provide if and when asked" should be added to any sensitive value. Without it, the simulator front-loads the value, and the ability to test whether the agent asks before proceeding is lost. This is what makes an authentication-gating goal (for example, "the agent should always ask for the social security number (SSN) and personal identification number (PIN)") testable at all.
• Never use realistic-looking data in Test Data. Any SSN-, PIN-, or account-number-like value should be synthetic (sequential digits, clear placeholders).

Note: If the Goals field contains a pacing rule like "keep it short," it should be moved to Instructions. Duplicating it across fields makes the dataset harder to maintain.

Best Practices for Determinism

Determinism is not exclusive to Scripted test cases. Simulated is the more capable default .It supports every metric and multi-turn flows, and it can still produce reproducible wording.

• Pinning exact wording inside Simulated Instructions: The literal message can be embedded, for example: "Your first message should always ask your question. Use the following message: How do I go about getting a quote online?" The simulator sends it verbatim while the dataset keeps Simulated's full metric access. (This is how a real EveryPaw FAQ dataset is built, using the Simulated schema, not Scripted, with the question pinned inside Instructions.)
• Reserving Scripted for the one hard constraint that requires it: Answer Accuracy is Scripted-only and single-turn-only by product design. For every other metric, a deterministic Simulated case provides the same reproducibility, with multi-turn support.
• Keeping Scripted cases narrow when used for Answer Accuracy: One question and one Reference Answer per test case should be used.
• Adding phrasing-variant test cases for top intents: One question should be repeated with small wording differences (a greeting added, filler words) against one shared Reference Goal, to catch brittleness that a single "clean" phrasing would not reveal.

Note: Whether Answer Accuracy is specifically required should be confirmed first. If not, Simulated remains the better choice even when the wording must be fixed.

Best Practices for Adversarial and Security Scenarios

Reference Goals in this context describe what the agent must refuse, not what it must deliver.

• Name the attack technique and severity in the title. For example: "ADV-002 - Indirect Prompt Injection - User Text [CRITICAL]." No dedicated severity field exists today, so the naming convention is the mechanism. It should be tagged consistently across the suite. 
• Writing Reference Goals as a permission plus a prohibition, not just a prohibition. For example: "The agent may warn that the message looks like a scam, but it MUST NOT disclose internal fraud-detection rules. It should decline and offer to connect the user to fraud support." This scores more reliably than a bare "must not disclose."
• Scripting a second-push pressure test. Most agents pass a single-shot refusal; guardrail gaps show up on the second attempt. Script the simulator to press once more before closing naturally.
• Keeping adversarial scenarios in a dedicated dataset, not mixed into happy-path regression, with a stricter promotion threshold for it.

Best Practices for Writing Reference Goals

The Goal Accuracy judge reads the full Chain of Thought, including internal agent-to-agent messages. A goal that doesn't name its scope can be scored against reasoning that was never intended to be included.

• Preferring several small, independent goals over one compound goal: Each gets its own pass/fail and reasoning instead of one ambiguous verdict.
• Covering both directions of a constraint: "The agent should ask for X" can pass for the wrong reason if the user volunteers X and the agent's guardrail simply refuses to use it. Where the distinction matters, it should be written explicitly: "should ask for X, and must not accept X if volunteered without being asked."

Best Practices for Managing Datasets 

• Treating datasets as immutable: Suplicate to change. This guarantees that an evaluation from three months ago and one today, both pointing at the same dataset name, were scored against identical test cases.
• Versioning with an explicit naming convention (for example, <usecase>_v2, or <usecase>_20260420) so lineage is obvious without opening the dataset.
• Growing the suite from real production failures. The dataset should be duplicated, the failure added as a new test case, and the result saved as the next version.
• Building at scale with CSV. if import errors on a metric, the metrics with no available reference should be unpicked.
• Watching the 500-scenario ceiling. Large suites should be planned as multiple purpose-scoped datasets.
• Retiring datasets that no longer reflect the orchestration rather than accumulating stale versions.

Best Practices for Choosing Metrics

Two to three metrics should be chosen that together answer: Did the agent do the right things, for the right reasons, and end up in the right place?

Note: PII refers to personally identifiable information. RAG refers to retrieval-augmented generation.

• Goal Accuracy: Should be used for a one-off, scenario-specific outcome. It is fastest to author.
• Custom Metric: Should be used when a check is reusable across scenarios, needs per-criterion pass/fail, or must happen in a specific order (use the “Steps” toggle). It is defined once in the Metrics Library, and can then be attached anywhere and edited once.

Custom Metric vs. Reference Goal (Goal Accuracy)

Both can validate the same underlying behavior; the difference lies in reuse and visibility, not capability.

If the same Reference Goal is about to be written into a third or fourth scenario, that's the signal to move it into a Custom Metric instead. A recurring check like "Did the agent ask if the caller is a new or existing patient?" applies to every patient-intake scenario. Defining it per-scenario creates duplicates that drift apart over time, whereas the library model allows it to be defined once, attached anywhere, and updated everywhere when edited.

The two approaches are not mutually exclusive. A common pattern combines Goal Accuracy for the scenario's outcome, with a Custom Metric for a cross-cutting quality bar (tone, disclosure, offer-to-escalate) that applies regardless of outcome.

• Reserving Critical to be used for genuine non-negotiables, such as compliance requirements or promises the agent cannot break. Quality and tone checks are better left non-critical.
• Preferring Goal Accuracy over Tool Call Accuracy when authoring effort is a concern. A well-scoped goal can often confirm a tool was called without the maintenance cost of a full tool-call reference.
• Setting Number of Runs > 1 before trusting a verdict, since judges are non-deterministic.

Best Practices for Running and Iterating

• Testing one change at a time in the agent's instructions or orchestration, then re-running before making another change.
• Always evaluating the version intended for promotion. Orchestration and Version should be confirmed in the wizard, not left on a stale draft.
• Re-running before escalating a surprising result. A single unexpected fail isn't yet evidence of a regression.
• Gating promotion on a threshold agreed in advance, before looking at results.