@mastra/evals 1.1.2 → 1.2.0-alpha.0

package/dist/docs/references/reference-evals-toxicity.md

@@ -1,4 +1,4 @@
-# Toxicity Scorer
+# Toxicity scorer
 
 The `createToxicityScorer()` function evaluates whether an LLM's output contains racist, biased, or toxic elements. It uses a judge-based system to analyze responses for various forms of toxicity including personal attacks, mockery, hate speech, dismissive statements, and threats.
 
@@ -6,25 +6,25 @@ The `createToxicityScorer()` function evaluates whether an LLM's output contains
 
 The `createToxicityScorer()` function accepts a single options object with the following properties:
 
-**model:** (`LanguageModel`): Configuration for the model used to evaluate toxicity.
+**model** (`LanguageModel`): Configuration for the model used to evaluate toxicity.
 
-**scale:** (`number`): Maximum score value (default is 1). (Default: `1`)
+**scale** (`number`): Maximum score value (default is 1). (Default: `1`)
 
 This function returns an instance of the MastraScorer class. The `.run()` method accepts the same input as other scorers (see the [MastraScorer reference](https://mastra.ai/reference/evals/mastra-scorer)), but the return value includes LLM-specific fields as documented below.
 
-## .run() Returns
+## `.run()` returns
 
-**runId:** (`string`): The id of the run (optional).
+**runId** (`string`): The id of the run (optional).
 
-**analyzeStepResult:** (`object`): Object with verdicts: { verdicts: Array<{ verdict: 'yes' | 'no', reason: string }> }
+**analyzeStepResult** (`object`): Object with verdicts: { verdicts: Array<{ verdict: 'yes' | 'no', reason: string }> }
 
-**analyzePrompt:** (`string`): The prompt sent to the LLM for the analyze step (optional).
+**analyzePrompt** (`string`): The prompt sent to the LLM for the analyze step (optional).
 
-**score:** (`number`): Toxicity score (0 to scale, default 0-1).
+**score** (`number`): Toxicity score (0 to scale, default 0-1).
 
-**reason:** (`string`): Detailed explanation of the toxicity assessment.
+**reason** (`string`): Detailed explanation of the toxicity assessment.
 
-**generateReasonPrompt:** (`string`): The prompt sent to the LLM for the generateReason step (optional).
+**generateReasonPrompt** (`string`): The prompt sent to the LLM for the generateReason step (optional).
 
 `.run()` returns a result in the following shape:
 
@@ -41,7 +41,7 @@ This function returns an instance of the MastraScorer class. The `.run()` method
 }
 ```
 
-## Scoring Details
+## Scoring details
 
 The scorer evaluates toxicity through multiple aspects:
 
@@ -82,22 +82,22 @@ A toxicity score between 0 and 1:
 Evaluate agent responses for toxic, biased, or harmful content:
 
 ```typescript
-import { runEvals } from "@mastra/core/evals";
-import { createToxicityScorer } from "@mastra/evals/scorers/prebuilt";
-import { myAgent } from "./agent";
+import { runEvals } from '@mastra/core/evals'
+import { createToxicityScorer } from '@mastra/evals/scorers/prebuilt'
+import { myAgent } from './agent'
 
-const scorer = createToxicityScorer({ model: "openai/gpt-4o" });
+const scorer = createToxicityScorer({ model: 'openai/gpt-5.4' })
 
 const result = await runEvals({
   data: [
     {
-      input: "What do you think about the new team member?",
+      input: 'What do you think about the new team member?',
     },
     {
-      input: "How was the meeting discussion?",
+      input: 'How was the meeting discussion?',
     },
     {
-      input: "Can you provide feedback on the project proposal?",
+      input: 'Can you provide feedback on the project proposal?',
     },
   ],
   scorers: [scorer],
@@ -106,11 +106,11 @@ const result = await runEvals({
     console.log({
       score: scorerResults[scorer.id].score,
       reason: scorerResults[scorer.id].reason,
-    });
+    })
   },
-});
+})
 
-console.log(result.scores);
+console.log(result.scores)
 ```
 
 For more details on `runEvals`, see the [runEvals reference](https://mastra.ai/reference/evals/run-evals).

package/dist/docs/references/reference-evals-trajectory-accuracy.md

@@ -0,0 +1,613 @@
+# Trajectory accuracy scorers
+
+Mastra provides two trajectory accuracy scorers for evaluating whether an agent or workflow follows an expected sequence of actions:
+
+1. **Code-based scorer** - Deterministic evaluation using exact step matching and ordering
+2. **LLM-based scorer** - Semantic evaluation using AI to assess trajectory quality and appropriateness
+
+Both scorers work with agents and workflows. The `runEvals` pipeline automatically extracts trajectories, so scorers receive a `Trajectory` object directly.
+
+## Trajectory extraction
+
+The `runEvals` pipeline uses two extraction strategies, depending on whether observability storage is configured:
+
+### Trace-based extraction (preferred)
+
+When the target's `Mastra` instance has storage configured, the pipeline fetches the full execution trace from the observability store and calls `extractTrajectoryFromTrace()`. This produces a hierarchical trajectory with nested `children`, capturing the complete execution tree — including nested agent runs, tool calls within workflow steps, and model generations.
+
+For example, a workflow that calls an agent, which in turn calls tools, produces:
+
+```text
+workflow_run
+  └─ workflow_step (validate-input)
+  └─ workflow_step (process-data)
+       └─ agent_run (my-agent)
+            └─ model_generation
+            └─ tool_call (search)
+            └─ model_generation
+            └─ tool_call (summarize)
+  └─ workflow_step (save-result)
+```
+
+### Fallback extraction
+
+When storage is not available, the pipeline falls back to:
+
+- **Agents:** `extractTrajectory()` — Extracts `ToolCallStep` entries from `toolInvocations` in the agent's message output. Produces a flat list of tool calls.
+- **Workflows:** `extractWorkflowTrajectory()` — Extracts `WorkflowStepStep` entries from `stepResults`. Produces a flat list of workflow steps.
+
+These fallbacks don't capture nested execution or non-tool-call spans.
+
+## Trajectory types
+
+Trajectory steps use a discriminated union on `stepType`. Each step type has specific properties:
+
+### `ToolCallStep`
+
+Represents an agent tool call.
+
+**stepType** (`'tool_call'`): Discriminant.
+
+**name** (`string`): Tool name.
+
+**toolArgs** (`Record<string, unknown>`): Arguments passed to the tool.
+
+**toolResult** (`Record<string, unknown>`): Result returned by the tool.
+
+**success** (`boolean`): Whether the call succeeded.
+
+**durationMs** (`number`): Execution time in milliseconds.
+
+**metadata** (`Record<string, unknown>`): Arbitrary metadata.
+
+**children** (`TrajectoryStep[]`): Nested sub-steps.
+
+### `WorkflowStepStep`
+
+Represents a workflow step execution.
+
+**stepType** (`'workflow_step'`): Discriminant.
+
+**name** (`string`): Step identifier.
+
+**stepId** (`string`): Step ID in the workflow.
+
+**status** (`string`): Step result status (success, failed, suspended, etc.).
+
+**output** (`Record<string, unknown>`): Step output data.
+
+**durationMs** (`number`): Execution time in milliseconds.
+
+**metadata** (`Record<string, unknown>`): Arbitrary metadata.
+
+**children** (`TrajectoryStep[]`): Nested sub-steps (e.g. tool calls inside the step).
+
+### Other step types
+
+The discriminated union includes these additional step types:
+
+| Step type              | Key properties                                                |
+| ---------------------- | ------------------------------------------------------------- |
+| `mcp_tool_call`        | `toolArgs`, `toolResult`, `mcpServer`, `success`              |
+| `model_generation`     | `modelId`, `promptTokens`, `completionTokens`, `finishReason` |
+| `agent_run`            | `agentId`                                                     |
+| `workflow_run`         | `workflowId`, `status`                                        |
+| `workflow_conditional` | `conditionCount`, `selectedSteps`                             |
+| `workflow_parallel`    | `branchCount`, `parallelSteps`                                |
+| `workflow_loop`        | `loopType`, `totalIterations`                                 |
+| `workflow_sleep`       | `durationMs`, `sleepType`                                     |
+| `workflow_wait_event`  | `eventName`, `eventReceived`                                  |
+| `processor_run`        | `processorId`                                                 |
+
+All step types share the base properties `name`, `durationMs`, `metadata`, and `children`.
+
+## Expected steps
+
+When defining expected trajectories, use `ExpectedStep` instead of the full `TrajectoryStep` discriminated union. `ExpectedStep` is a simpler type designed for expectations:
+
+**name** (`string`): Step name to match (tool name, agent ID, workflow step name, etc.).
+
+**stepType** (`TrajectoryStepType`): Step type to match. If omitted, matches any step type with the given name.
+
+**data** (`Record<string, unknown>`): Expected step data. Compared against the actual step's type-specific data (toolArgs for tool\_call, output for workflow\_step, etc.).
+
+**children** (`TrajectoryExpectation`): Nested expectation config for this step's children. Overrides the parent config for evaluating children of this step.
+
+### Simple expected steps
+
+```typescript
+const steps: ExpectedStep[] = [
+  // Match by name only (any step type)
+  { name: 'search' },
+
+  // Match by name and step type
+  { name: 'search', stepType: 'tool_call' },
+
+  // Match with expected data
+  { name: 'search', stepType: 'tool_call', data: { input: { query: 'weather' } } },
+]
+```
+
+### Nested expectations
+
+Each expected step can include a `children` config with its own evaluation rules. This lets you set different ordering or comparison rules at each level of the hierarchy.
+
+```typescript
+const scorer = createTrajectoryScorerCode({
+  defaults: {
+    ordering: 'strict',
+    steps: [
+      { name: 'validate-input', stepType: 'workflow_step' },
+      {
+        name: 'research-agent',
+        stepType: 'agent_run',
+        children: {
+          // Sub-agent can call tools in any order
+          ordering: 'unordered',
+          steps: [
+            { name: 'search', stepType: 'tool_call' },
+            { name: 'summarize', stepType: 'tool_call' },
+          ],
+        },
+      },
+      { name: 'save-result', stepType: 'workflow_step' },
+    ],
+  },
+})
+```
+
+In this example, the parent workflow requires strict ordering of its steps, but the nested `research-agent` allows its tool calls in any order.
+
+## Choosing between scorers
+
+### Use the code-based scorer when:
+
+- You need **deterministic, reproducible** results
+- You have a **known expected trajectory** to compare against
+- You want to validate **exact step sequences**
+- Speed and cost are priorities (no LLM calls)
+- You are running automated tests in CI/CD
+
+### Use the LLM-based scorer when:
+
+- You need **semantic understanding** of whether steps were appropriate
+- The optimal trajectory is **not predetermined** (evaluate based on task requirements)
+- You want to detect **unnecessary, redundant, or missing** steps
+- You need **explanations** for scoring decisions
+- You are evaluating **production agent behavior**
+
+## Code-based trajectory accuracy scorer
+
+The `createTrajectoryAccuracyScorerCode()` function from `@mastra/evals/scorers/prebuilt` provides deterministic scoring based on step matching and ordering against an expected trajectory.
+
+### Parameters
+
+**expectedTrajectory** (`TrajectoryExpectation`): Static expected trajectory to compare against. When provided, all dataset items use this trajectory. When omitted, the scorer reads expectedTrajectory from each dataset item at runtime.
+
+**comparisonOptions** (`TrajectoryComparisonOptions`): Controls how the comparison is performed.
+
+This function returns an instance of the MastraScorer class. See the [MastraScorer reference](https://mastra.ai/reference/evals/mastra-scorer) for details on the `.run()` method and its input/output.
+
+### Expected trajectory sources
+
+The code-based scorer resolves `expectedTrajectory` from two sources, in order of priority:
+
+1. **Constructor option** — A static trajectory passed when creating the scorer. Used for all dataset items.
+2. **Dataset item** — An `expectedTrajectory` field on the dataset item, passed through the `runEvals` pipeline. Allows different expected trajectories per item.
+
+```typescript
+// Static: same expected trajectory for all items
+const scorer = createTrajectoryAccuracyScorerCode({
+  expectedTrajectory: {
+    steps: [
+      { stepType: 'tool_call', name: 'search' },
+      { stepType: 'tool_call', name: 'summarize' },
+    ],
+  },
+})
+```
+
+```typescript
+// Per-item: each dataset item has its own expectedTrajectory
+const scorer = createTrajectoryAccuracyScorerCode()
+
+await runEvals({
+  target: myAgent,
+  scorers: { trajectory: [scorer] },
+  data: [
+    {
+      input: 'Search and summarize weather',
+      expectedTrajectory: {
+        steps: [
+          { stepType: 'tool_call', name: 'search' },
+          { stepType: 'tool_call', name: 'summarize' },
+        ],
+      },
+    },
+    {
+      input: 'Just search for weather',
+      expectedTrajectory: {
+        steps: [{ stepType: 'tool_call', name: 'search' }],
+      },
+    },
+  ],
+})
+```
+
+### Evaluation modes
+
+The code-based scorer operates in two modes based on `strictOrder`:
+
+#### Strict mode (`strictOrder: true`)
+
+Requires an exact match. The actual steps must match the expected steps in the same order with no extra or missing steps. Returns `1.0` for an exact match and `0.0` otherwise.
+
+#### Relaxed mode (`strictOrder: false`, default)
+
+Allows extra steps. Expected steps must appear in the correct relative order. The score is calculated based on how many expected steps were matched, with optional penalties for extra or repeated steps.
+
+## Code-based scoring details
+
+- **Continuous scores**: Returns values between 0.0 and 1.0 in relaxed mode; binary (0 or 1) in strict mode
+- **Deterministic**: Same input always produces the same output
+- **Fast**: No external API calls
+
+### Code-based scorer results
+
+```typescript
+{
+  runId: string,
+  preprocessStepResult: {
+    actualTrajectory: Trajectory,
+    expectedTrajectory: Trajectory,
+    comparison: {
+      score: number,
+      matchedSteps: number,
+      totalExpectedSteps: number,
+      totalActualSteps: number,
+      missingSteps: string[],
+      extraSteps: string[],
+      outOfOrderSteps: string[],
+      repeatedSteps: string[]
+    },
+    actualStepNames: string[],
+    expectedStepNames: string[]
+  },
+  score: number
+}
+```
+
+## Code-based scorer examples
+
+### Agent trajectory with strict ordering
+
+Validates that an agent follows an exact sequence of tool calls:
+
+```typescript
+import { createTrajectoryAccuracyScorerCode } from '@mastra/evals/scorers/prebuilt'
+import { runEvals } from '@mastra/core/evals'
+
+const scorer = createTrajectoryAccuracyScorerCode({
+  expectedTrajectory: {
+    steps: [
+      { stepType: 'tool_call', name: 'auth-tool' },
+      { stepType: 'tool_call', name: 'fetch-tool' },
+    ],
+  },
+  comparisonOptions: { strictOrder: true },
+})
+
+const result = await runEvals({
+  target: myAgent,
+  scorers: { trajectory: [scorer] },
+  data: [{ input: 'Get my data' }],
+})
+
+console.log(result.scores.trajectory['trajectory-accuracy']) // 1.0
+```
+
+### Agent trajectory with relaxed ordering
+
+Allows extra steps as long as expected steps appear in the correct relative order:
+
+```typescript
+const scorer = createTrajectoryAccuracyScorerCode({
+  expectedTrajectory: {
+    steps: [
+      { stepType: 'tool_call', name: 'search-tool' },
+      { stepType: 'tool_call', name: 'summarize-tool' },
+    ],
+  },
+  comparisonOptions: { strictOrder: false },
+})
+
+// Agent called search-tool → log-tool → summarize-tool
+// The extra log-tool is allowed in relaxed mode
+// score: 0.75 — all expected steps matched, small penalty for extra step
+```
+
+### Workflow trajectory
+
+Evaluates a workflow's execution path:
+
+```typescript
+import { createTrajectoryAccuracyScorerCode } from '@mastra/evals/scorers/prebuilt'
+import { runEvals } from '@mastra/core/evals'
+
+const scorer = createTrajectoryAccuracyScorerCode({
+  expectedTrajectory: {
+    steps: [
+      { stepType: 'workflow_step', name: 'validate-input' },
+      { stepType: 'workflow_step', name: 'process-data' },
+      { stepType: 'workflow_step', name: 'save-result' },
+    ],
+  },
+})
+
+const result = await runEvals({
+  target: myWorkflow,
+  scorers: { trajectory: [scorer] },
+  data: [{ input: { data: 'test' } }],
+})
+
+console.log(result.scores.trajectory['trajectory-accuracy'])
+```
+
+### Comparing step data
+
+Validates not just the step names but also step-specific data. For tool calls, this compares `toolArgs` and `toolResult`. For workflow steps, this compares `output`.
+
+```typescript
+const scorer = createTrajectoryAccuracyScorerCode({
+  expectedTrajectory: {
+    steps: [
+      {
+        stepType: 'tool_call',
+        name: 'search-tool',
+        toolArgs: { query: 'weather in NYC' },
+      },
+    ],
+  },
+  comparisonOptions: { compareStepData: true },
+})
+```
+
+## LLM-based trajectory accuracy scorer
+
+The `createTrajectoryAccuracyScorerLLM()` function from `@mastra/evals/scorers/prebuilt` uses an LLM to evaluate whether an agent's or workflow's trajectory was appropriate, efficient, and complete.
+
+### Parameters
+
+**model** (`MastraModelConfig`): The LLM model to use for evaluating trajectory quality.
+
+**expectedTrajectory** (`TrajectoryExpectation`): Optional static expected trajectory to compare against. When omitted, the LLM evaluates the trajectory based on the task requirements alone. Can also come from dataset items at runtime.
+
+### Features
+
+The LLM-based scorer provides:
+
+- **Task-aware evaluation**: Assesses whether each step was necessary given the user's request
+- **Ordering assessment**: Evaluates whether steps were taken in a logical order
+- **Missing step detection**: Identifies steps that should have been taken
+- **Redundancy detection**: Flags unnecessary or repeated steps
+- **Reasoning generation**: Provides human-readable explanations for scoring decisions
+
+### Evaluation process
+
+1. **Receive trajectory**: Gets a pre-extracted `Trajectory` object from the pipeline
+2. **Analyze steps**: Evaluates each step for necessity and ordering using the LLM
+3. **Generate score**: Calculates score weighted as 60% necessity, 30% ordering, minus 10% missing penalty
+4. **Generate reasoning**: Provides a human-readable explanation
+
+## LLM-based scoring details
+
+- **Fractional scores**: Returns values between 0.0 and 1.0
+- **Context-aware**: Considers user intent and task requirements
+- **Explanatory**: Provides reasoning for scores
+- **Flexible**: Works with or without an expected trajectory
+
+### LLM-based scorer options
+
+```typescript
+// Evaluate based on task requirements (no expected trajectory)
+const openScorer = createTrajectoryAccuracyScorerLLM({
+  model: { provider: 'openai', name: 'gpt-5.4' },
+})
+
+// Evaluate against a static expected trajectory
+const guidedScorer = createTrajectoryAccuracyScorerLLM({
+  model: { provider: 'openai', name: 'gpt-5.4' },
+  expectedTrajectory: {
+    steps: [
+      { stepType: 'tool_call', name: 'search-tool' },
+      { stepType: 'tool_call', name: 'summarize-tool' },
+    ],
+  },
+})
+```
+
+### LLM-based scorer results
+
+```typescript
+{
+  runId: string,
+  preprocessStepResult: {
+    actualTrajectory: Trajectory,
+    actualTrajectoryFormatted: string,
+    expectedTrajectoryFormatted?: string,
+    hasSteps: boolean
+  },
+  analyzeStepResult: {
+    stepEvaluations: Array<{
+      stepName: string,
+      wasNecessary: boolean,
+      wasInOrder: boolean,
+      reasoning: string
+    }>,
+    missingSteps?: string[],
+    extraSteps?: string[],
+    overallAssessment: string
+  },
+  score: number,
+  reason: string
+}
+```
+
+## Unified trajectory scorer
+
+The `createTrajectoryScorerCode()` function from `@mastra/evals/scorers/prebuilt` provides a multi-dimensional trajectory evaluation that checks accuracy, efficiency, blacklisted tools, and tool failure patterns in a single pass.
+
+### Parameters
+
+**defaults** (`TrajectoryExpectation`): Default expectations applied to all dataset items. Per-item expectedTrajectory values override these defaults.
+
+**weights** (`object`): Weights for combining dimension scores into the final score.
+
+### Scoring behavior
+
+The unified scorer evaluates four dimensions:
+
+1. **Accuracy** — Matches actual steps against expected steps (if `steps` is configured). Uses the `ordering` mode.
+2. **Efficiency** — Checks step budgets (`maxSteps`, `maxTotalTokens`, `maxTotalDurationMs`) and redundant calls (`noRedundantCalls`).
+3. **Blacklist** — Checks for forbidden tools or sequences. Any violation immediately results in a score of **0.0** regardless of other dimensions.
+4. **Tool failures** — Detects retry patterns, fallback patterns, and argument correction patterns.
+
+The final score is a weighted average of accuracy, efficiency, and tool failures. Blacklist violations override everything to 0.
+
+### Unified scorer results
+
+```typescript
+{
+  runId: string,
+  preprocessStepResult: {
+    accuracy?: TrajectoryComparisonResult,
+    efficiency: TrajectoryEfficiencyResult,
+    blacklist: TrajectoryBlacklistResult,
+    toolFailures: ToolFailureAnalysisResult,
+  },
+  score: number
+}
+```
+
+### Per-item expectations
+
+Each dataset item can override the defaults with its own `expectedTrajectory`. This lets you vary expectations per prompt:
+
+```typescript
+import { createTrajectoryScorerCode } from '@mastra/evals/scorers/prebuilt'
+import { runEvals } from '@mastra/core/evals'
+
+// Default blacklist applies to all items
+const scorer = createTrajectoryScorerCode({
+  defaults: {
+    blacklistedTools: ['deleteAll'],
+    maxSteps: 5,
+  },
+})
+
+const result = await runEvals({
+  target: myAgent,
+  scorers: { trajectory: [scorer] },
+  data: [
+    {
+      input: 'Search for weather',
+      expectedTrajectory: {
+        steps: [{ stepType: 'tool_call', name: 'search' }],
+        maxSteps: 2,
+      },
+    },
+    {
+      input: 'Search and summarize',
+      expectedTrajectory: {
+        steps: [
+          { stepType: 'tool_call', name: 'search' },
+          { stepType: 'tool_call', name: 'summarize' },
+        ],
+      },
+    },
+  ],
+})
+```
+
+### Example: efficiency and blacklist
+
+```typescript
+import { createTrajectoryScorerCode } from '@mastra/evals/scorers/prebuilt'
+
+const scorer = createTrajectoryScorerCode({
+  defaults: {
+    blacklistedTools: ['escalate', 'admin-override'],
+    blacklistedSequences: [['escalate', 'admin-override']],
+    maxSteps: 10,
+    noRedundantCalls: true,
+    maxRetriesPerTool: 2,
+  },
+})
+```
+
+## Using trajectory scorers with `runEvals`
+
+Trajectory scorers are configured under the `trajectory` key in the scorer config. The `runEvals` pipeline handles trajectory extraction automatically.
+
+### Agent trajectory evaluation
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { createTrajectoryAccuracyScorerCode } from '@mastra/evals/scorers/prebuilt'
+
+const trajectoryScorer = createTrajectoryAccuracyScorerCode({
+  expectedTrajectory: {
+    steps: [
+      { stepType: 'tool_call', name: 'search' },
+      { stepType: 'tool_call', name: 'format' },
+    ],
+  },
+})
+
+const result = await runEvals({
+  target: myAgent,
+  scorers: {
+    agent: [qualityScorer], // receives raw MastraDBMessage[] output
+    trajectory: [trajectoryScorer], // receives pre-extracted Trajectory
+  },
+  data: [{ input: 'Find and format the data' }],
+})
+
+// result.scores.agent['quality'] — agent-level score
+// result.scores.trajectory['trajectory-accuracy'] — trajectory score
+```
+
+### Workflow trajectory evaluation
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { createTrajectoryAccuracyScorerCode } from '@mastra/evals/scorers/prebuilt'
+
+const workflowTrajectoryScorer = createTrajectoryAccuracyScorerCode({
+  expectedTrajectory: {
+    steps: [
+      { stepType: 'workflow_step', name: 'validate' },
+      { stepType: 'workflow_step', name: 'process' },
+      { stepType: 'workflow_step', name: 'notify' },
+    ],
+  },
+})
+
+const result = await runEvals({
+  target: myWorkflow,
+  scorers: {
+    workflow: [outputScorer], // receives workflow output
+    trajectory: [workflowTrajectoryScorer], // receives pre-extracted Trajectory from step results
+  },
+  data: [{ input: { userId: '123' } }],
+})
+
+// result.scores.workflow['output-quality'] — workflow-level score
+// result.scores.trajectory['trajectory-accuracy'] — trajectory score
+```
+
+## Related
+
+- [runEvals reference](https://mastra.ai/reference/evals/run-evals) — Pipeline that extracts trajectories and passes them to scorers
+- [MastraScorer reference](https://mastra.ai/reference/evals/mastra-scorer) — Base scorer interface
+- [Scorer utils](https://mastra.ai/reference/evals/scorer-utils) — Utility functions including `extractTrajectory` and `compareTrajectories`