Skip to main content

Menu

Evaluate an AI agent on the work it needs to do

AI agent evaluation tests whether an agent can complete a task with the information, tools and constraints it will encounter. Define the expected outcome, check what changed and inspect the steps that produced the result.

Sapien1 helps teams scope task sets, assess evaluation data and develop environments for testing agents. Start with one workflow and the decision you need the evaluation to support.

Turn a workflow into a testable task

A task needs a starting state, a request and observable success criteria. An agent’s final message is one part of the evidence; the resulting files, records or tool state may show whether the work was completed.

Anthropic’s guide to agent evaluations distinguishes the task, each trial, the graders, the execution trace and the outcome in the environment. Those distinctions help identify whether a failure came from the agent, the test or the environment.

For example, consider a support agent asked to change a delivery address. A test can give it an order record, a customer request and the policy that applies. The checks should reflect the actual task:

Part of the taskExample check
Identify the orderThe agent selects the order named in the request
Apply the policyIts decision matches the supplied rules and order status
Make the changeWhen the change is permitted, the requested address appears in the order record; otherwise, the address stays unchanged.
Preserve other detailsItems, quantities and unrelated records remain unchanged
Explain the resultThe reply accurately describes the action taken or the information still needed

This is an illustrative task specification. Your own policy and workflow determine the checks.

Check authorization and the resulting state

Suppose a user authorizes an agent to change the address on order A from 1 Example Lane to 2 Example Lane. Order B starts at 3 Example Lane and is outside that request. The following prewritten, fictional trace illustrates what a simulated authorization check might record:

Agent tool requestPermission decisionRecorded result
Order A: address update to 2 Example LaneAllowedUpdate executed
Order B: address update to 4 Example LaneDeniedUpdate blocked

The trace records both the permitted request and the out-of-scope request. In this example, a state check records that order A is at 2 Example Lane and order B remains at 3 Example Lane. A denied request and an executed change are different outcomes; retain the permission decision and the final state alongside the agent's reply.

Anthropic's agent-evaluation guide distinguishes the trace of a trial from its resulting state. AWS's tool-authorization guidance discusses checking agent-to-tool requests and reviewing permit or deny decisions. This fictional trace illustrates one check; it is not evidence that a system is secure.

Build a test from a completed case

Suppose a separate, fictional support history records this sequence. At 10:00, the verified owner of order A asks to change its address from 1 Example Lane to 2 Example Lane. The order is still being prepared for dispatch. The policy in force says to make a verified owner's requested address change before dispatch. At 10:05, a support note records that the address was changed.

To test the decision at 10:00, give the agent the request, the original order state and the policy in force, and start the test tools from that state. Keep the order in preparation while the agent acts. Keep the 10:05 note available to the reviewer and out of the agent's initial prompt and tool-accessible records for this test. Otherwise, the agent may see the completed outcome before it is asked to act.

The 10:00 policy gives the reviewer the expected result. Order A ends at 2 Example Lane. For this test, also require unrelated records to stay unchanged. The 10:05 note records the outcome. Use the policy to judge whether that action was correct. If you cannot establish the applicable policy or pre-action state, set the case aside for review. Before using real records, confirm permission to use them and handle sensitive fields appropriately.

Inspect's dataset guide distinguishes the input submitted to a model from a target that can be used for grading and explains that sample files can also be copied into a sandbox. Check prompts, retrieved material, tool responses and sandbox files for information intended only for the reviewer. Make those checks even when the dataset has a separate grading target.

Choose evidence that matches the decision

Use direct checks where the result is observable: a changed field, a calculation, a generated file or a passing test. Use a written rubric when a judgment needs human interpretation, such as whether an explanation is clear or a research answer supports its conclusion.

An automated judge can help review outputs at scale. Compare its decisions with human review on representative examples before relying on its scores. Keep disagreements visible so you can improve the rubric or the judge.

Record the task inputs, tools, agent configuration and results. Repeat trials when variation between runs matters to the decision. Inspect failed and unexpectedly successful runs; a high score can hide a weak test as well as strong performance. Anthropic’s guide discusses these grader and trial-design considerations.

Check case IDs before scoring

When you build a case from past records, keep its case ID on the expected result and the test result. Before scoring one result per case, check both files against the list of expected IDs. Each expected ID should appear once in each file. Resolve missing, duplicate or unexpected IDs. For repeated runs, record a trial ID as well.

Suppose you expect cases A and B. Both files contain A and a row with a missing ID. The expected and test results for A disagree. The two rows without IDs have the same label. A pandas merge can pair those missing keys even when its one-to-one check passes. Counting the joined rows gives one agreement in two pairs. Only A matches an expected ID. The identified subset has zero agreements in one case, with one of two expected cases covered. The missing IDs leave it unknown whether either row belongs to B, so the score across both expected cases remains undetermined. If you intentionally score a subset, report its coverage with its score.

Read repeated trials with the decision in mind

Suppose a team tests two tasks three times each, restoring the task's starting state before every attempt. The checks return these fictional results:

TaskFirst trialSecond trialThird trial
APassFailPass
BPassPassFail

Four of the six trials passed. Both tasks passed at least once, but neither passed all three times. Those summaries answer different questions. An occasional correct result may matter when the system can reliably check and select among several candidate outputs; repeated success matters when each attempt must work on its own. One passing attempt does not make the other attempts safe or correct.

Now suppose a seventh attempt stops because of a confirmed external sandbox outage before it can be scored. Four of the six scored attempts passed; four of seven total attempts produced confirmed passes. The unscored attempt is neither a confirmed pass nor a confirmed agent failure. The first fraction summarizes scored attempts; the second shows confirmed passes across all attempts. Different task weighting or metric settings can change a reported result.

These numbers describe only the fictional checks above; they do not establish a production success rate. Record the number of tasks and trials per task, the checks used and any trials invalidated by infrastructure problems, such as a sandbox outage. Report invalid trials separately from agent failures and state which trials each summary includes. A repeat on one task helps expose variation on that task; it does not replace testing a broader range of situations. Anthropic's agent-evaluation guide discusses how measures for at-least-once and consistent success serve different decisions.

Task coverage can change before scoring. In our GDPval reference-coverage analysis, 185 of 220 public task rows list at least one expert deliverable path; those rows have a different sector mix from the full table. A listed path does not establish access or renderability.

Use an environment when actions change state

If the agent edits records, operates software or works across multiple tools, it needs somewhere to take those actions. A repeatable environment lets you restore the starting state and inspect the result after a run.

OpenEnv is one open framework for isolated agent environments. Choosing a framework comes after defining the task: what the agent can see, what it can do and how success is checked.

For an example of how task resource declarations can vary, see the resource settings behind 66 Terminal-Bench tasks.

A brief for your first evaluation

Describe the workflow, a representative task and what a successful result looks like. Add the tools the agent uses, the information it receives and any failure that would change a release decision. If you already have examples, include a description of their source and coverage.

A scoped project can then define the task set, environment requirements, grading approach and review of the results. If the examples themselves are the gap, start with data sourcing.

Email us about agent evaluation