Evaluations

Create an eval

Binds an agent under test to a dataset and a list of scorers. The agent and the dataset must belong to the same project as the eval; a cross-project reference is rejected with 400.

Scorer config is frozen here rather than read from the agent at run time, so two runs of the same eval are always judged by the same criteria and their comparison measures the agent instead of the config drifting underneath it. Each scorer type may appear at most once.

post/v1/projects/{project_id}/evals

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/evals
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Request body

namestring required

Unique name within the project

agent_idstring required

The agent under test

dataset_idstring required

The dataset to run it against

pass_thresholdnumber nullable

0–1. The run passes iff its pass rate — passed items over non-errored items — is at least this. Null reports scores without gating on them.

group_bystring nullable

A key of the items' metadata. A run rolls its scores up per string value of that key in aggregate_scores.grouping. Null reports no grouping.

Example request

{
  "name": "billing-regression-suite",
  "agent_id": "agent_V1StGXR8Z5jdHi6B",
  "dataset_id": "dset_V1StGXR8Z5jdHi6B",
  "scorers": [
    {
      "value": "invoice"
    }
  ],
  "pass_threshold": 0.8,
  "group_by": "kind"
}

Response

Eval created successfully

idstring
project_idstring
namestring
agent_idstring
dataset_idstring
pass_thresholdnumber nullable
group_bystring nullable

The item metadata key a run rolls its scores up by; null when the eval groups nothing

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "eval_V1StGXR8Z5jdHi6B",
  "agent_id": "agent_V1StGXR8Z5jdHi6B",
  "dataset_id": "dset_V1StGXR8Z5jdHi6B",
  "scorers": [
    {
      "value": "invoice"
    }
  ],
  "group_by": "kind"
}

Changes

No recorded changes to this operation across all 1 revision of this API.