> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# Trajectory 精度スコアラー

Mastra は、Agent または Workflow が期待されるアクションの順序に従っているかを評価する 2 種類の Trajectory 精度スコアラーを提供します。

1. **コードベースのスコアラー** - ステップの厳密な照合と順序による決定論的評価
2. **LLM ベースのスコアラー** - AI で Trajectory の品質と妥当性を判定する意味的評価

どちらのスコアラーも Agent と Workflow に対応します。`runEvals` パイプラインが Trajectory を自動的に抽出するため、スコアラーは `Trajectory` オブジェクトを直接受け取ります。

## Trajectory の抽出

`runEvals` パイプラインは、observability ストレージが設定されているかどうかに応じて 2 つの抽出方法を使用します。

### Trace ベースの抽出（推奨）

対象の `Mastra` インスタンスにストレージが設定されている場合、パイプラインは observability ストアから完全な実行 Trace を取得し、`extractTrajectoryFromTrace()` を呼び出します。これにより、完全な実行ツリーを捉えた、`children` がネストされた階層型 Trajectory が生成されます。このツリーには、Workflow ステップ内でネストされた Agent の実行と Tool 呼び出しに加え、モデル生成も含まれます。

たとえば、Agent を呼び出し、その Agent が Tool を呼び出す Workflow では、次のようになります。

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

### フォールバック抽出

ストレージを利用できない場合、パイプラインは次の方法にフォールバックします。

- **Agent:** `extractTrajectory()` は、Agent のメッセージ出力にある `toolInvocations` から `ToolCallStep` エントリを抽出します。Tool 呼び出しのフラットなリストを生成します。
- **Workflow:** `extractWorkflowTrajectory()` は、`stepResults` から `WorkflowStepStep` エントリを抽出します。Workflow ステップのフラットなリストを生成します。

これらのフォールバックでは、ネストされた実行や Tool 呼び出し以外の Span は取得されません。

## Trajectory の型

Trajectory ステップは `stepType` を判別プロパティとする判別共用体を使用します。各ステップ型には固有のプロパティがあります。

### `ToolCallStep`

Agent の Tool 呼び出しを表します。

**stepType** (`'tool_call'`): 判別子。

**name** (`string`): Tool 名。

**toolArgs** (`Record<string, unknown>`): Tool に渡される引数。

**toolResult** (`Record<string, unknown>`): Tool が返す結果。

**success** (`boolean`): 呼び出しが成功したかどうか。

**durationMs** (`number`): 実行時間（ミリ秒）。

**metadata** (`Record<string, unknown>`): 任意のメタデータ。

**children** (`TrajectoryStep[]`): ネストされたサブステップ。

### `WorkflowStepStep`

Workflow ステップの実行を表します。

**stepType** (`'workflow_step'`): 判別子。

**name** (`string`): ステップ識別子。

**stepId** (`string`): Workflow 内のステップ ID。

**status** (`string`): ステップ結果のステータス（success、failed、suspended など）。

**output** (`Record<string, unknown>`): ステップの出力データ。

**durationMs** (`number`): 実行時間（ミリ秒）。

**metadata** (`Record<string, unknown>`): 任意のメタデータ。

**children** (`TrajectoryStep[]`): ネストされたサブステップ（ステップ内の Tool 呼び出しなど）。

### その他のステップ型

判別共用体には、次のステップ型も含まれます。

| ステップ型                  | 主なプロパティ                                                       |
| ---------------------- | ------------------------------------------------------------- |
| `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`                                                 |

すべてのステップ型は、基本プロパティ `name`、`durationMs`、`metadata`、`children` を共有します。

## 期待されるステップ

期待される Trajectory を定義する際は、完全な `TrajectoryStep` 判別共用体ではなく `ExpectedStep` を使用します。`ExpectedStep` は `TrajectoryStep` に対応する判別共用体です。`stepType` を指定すると、そのバリアントのフィールド（たとえば `tool_call` の `toolArgs`、`model_generation` の `modelId`）が自動補完されます。バリアント固有のフィールドはすべて任意なので、必要な項目だけを検証できます。

名前だけで任意のステップに一致させるには、`stepType` を完全に省略します。

**name** (`string`): 照合するステップ名（Tool 名、Agent ID、Workflow ステップ名など）。

**stepType** (`TrajectoryStepType`): ステップ型の判別子。設定すると、そのバリアントのフィールドが自動補完されます。省略すると、指定した名前を持つ任意のステップ型に一致します。

**(variant fields)** (`varies`): 対応する TrajectoryStep バリアントの型固有フィールド。たとえば、tool\_call の toolArgs と toolResult、model\_generation の modelId、workflow\_step の output です。すべて任意で、指定したフィールドだけが比較されます。

**children** (`TrajectoryExpectation`): このステップの children に対するネストされた期待値設定。このステップの children を評価する際に親の設定を上書きします。

### 単純な期待ステップ

```typescript
const steps: ExpectedStep[] = [
  // Match by name only (any step type)
  { name: 'search' },

  // Match by name and step type (autocomplete for tool_call fields)
  { name: 'search', stepType: 'tool_call' },

  // Match with specific toolArgs (auto-compared when present)
  { name: 'search', stepType: 'tool_call', toolArgs: { query: 'weather' } },

  // Match a model generation step by model ID
  { name: 'gpt-4o', stepType: 'model_generation', modelId: 'gpt-4o' },
]
```

### ネストされた期待値

期待される各ステップには、独自の評価ルールを持つ `children` 設定を含められます。これにより、階層のレベルごとに異なる順序ルールや比較ルールを設定できます。

```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' },
    ],
  },
})
```

この例では、親 Workflow のステップには厳密な順序が必要ですが、ネストされた `research-agent` の Tool 呼び出しは任意の順序で構いません。

## スコアラーの選択

### コードベースのスコアラーが適している場合

- **決定論的で再現可能な**結果が必要
- 比較対象となる**既知の期待 Trajectory** がある
- **厳密なステップ順序**を検証したい
- 速度とコストを優先する（LLM 呼び出しなし）
- CI/CD で自動テストを実行している

### LLM ベースのスコアラーが適している場合

- ステップが適切だったかを**意味的に理解**する必要がある
- 最適な Trajectory が**事前に決まっていない**（タスク要件に基づいて評価する）
- **不要、冗長、または欠落した**ステップを検出したい
- スコア判定の**説明**が必要
- **本番環境の Agent の動作**を評価している

## コードベースの Trajectory 精度スコアラー

`@mastra/evals/scorers/prebuilt` の `createTrajectoryAccuracyScorerCode()` 関数は、期待される Trajectory に対するステップの照合と順序に基づく決定論的スコアリングを提供します。

### パラメーター

**expectedTrajectory** (`Trajectory | ExpectedStep[]`): 比較対象となる静的な期待 Trajectory。完全な Trajectory または ExpectedStep マッチャーの配列を受け取ります。省略すると、実行時に各データセット項目から expectedTrajectory を読み取ります。

**comparisonOptions** (`TrajectoryComparisonOptions`): 比較方法を制御します。

この関数は MastraScorer クラスのインスタンスを返します。`.run()` メソッドとその入出力の詳細については、[MastraScorer リファレンス](https://mastra.zisheng.pro/ja/reference/evals/mastra-scorer)を参照してください。

### 期待 Trajectory の取得元

コードベースのスコアラーは、優先順位に従って 2 つの取得元から `expectedTrajectory` を解決します。

1. **コンストラクターオプション**: スコアラーの作成時に渡す静的 Trajectory。すべてのデータセット項目に使用されます。
2. **データセット項目**: `runEvals` パイプラインを通じて渡される、データセット項目の `expectedTrajectory` フィールド。項目ごとに異なる期待 Trajectory を指定できます。

```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' }],
      },
    },
  ],
})
```

### 評価モード

コードベースのスコアラーは、`strictOrder` に応じて 2 つのモードで動作します。

#### 厳密モード（`strictOrder: true`）

厳密な一致が必要です。実際のステップは、余分なステップや欠落したステップがなく、期待されるステップと同じ順序で一致する必要があります。厳密に一致すれば `1.0`、それ以外は `0.0` を返します。

#### 緩和モード（`strictOrder: false`、デフォルト）

余分なステップを許可します。期待されるステップは正しい相対順序で現れる必要があります。スコアは一致した期待ステップの数に基づいて計算され、余分なステップや繰り返されたステップには任意でペナルティが適用されます。

## コードベースのスコアリング詳細

- **連続スコア**: 緩和モードでは 0.0〜1.0、厳密モードでは二値（0 または 1）を返します
- **決定論的**: 同じ入力からは常に同じ出力が得られます
- **高速**: 外部 API を呼び出しません

### コードベースのスコアラーの結果

```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
}
```

## コードベースのスコアラーの例

### 厳密な順序の Agent Trajectory

Agent が Tool 呼び出しの厳密な順序に従うことを検証します。

```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

期待されるステップが正しい相対順序で現れる限り、余分なステップを許可します。

```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

Workflow の実行パスを評価します。

```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'])
```

### ステップデータの比較

ステップ名とステップ固有のデータを検証します。Tool 呼び出しでは `toolArgs` と `toolResult`、Workflow ステップでは `output` を比較します。

```typescript
const scorer = createTrajectoryAccuracyScorerCode({
  expectedTrajectory: {
    steps: [
      {
        stepType: 'tool_call',
        name: 'search-tool',
        toolArgs: { query: 'weather in NYC' },
      },
    ],
  },
})
// Data fields like toolArgs are auto-compared when present on expected steps
```

## LLM ベースの Trajectory 精度スコアラー

`@mastra/evals/scorers/prebuilt` の `createTrajectoryAccuracyScorerLLM()` 関数は、LLM を使って Agent または Workflow の Trajectory が適切、効率的、かつ完全だったかを評価します。

### パラメーター

**model** (`MastraModelConfig`): Trajectory の品質評価に使用する LLM モデル。

**expectedTrajectory** (`Trajectory | ExpectedStep[]`): 比較対象となる任意の静的な期待 Trajectory。完全な Trajectory または ExpectedStep マッチャーの配列を受け取ります。省略すると、LLM はタスク要件だけに基づいて Trajectory を評価します。実行時にデータセット項目から取得することもできます。

### 機能

LLM ベースのスコアラーは次の機能を提供します。

- **タスクを考慮した評価**: ユーザーのリクエストに対して各ステップが必要だったかを判定します
- **順序の評価**: ステップが論理的な順序で実行されたかを評価します
- **欠落ステップの検出**: 実行すべきだったステップを特定します
- **冗長性の検出**: 不要なステップや繰り返されたステップを指摘します
- **理由の生成**: スコア判定について人が読める説明を提供します

### 評価プロセス

1. **Trajectory の受け取り**: パイプラインから抽出済みの `Trajectory` オブジェクトを取得します
2. **ステップの分析**: LLM を使って各ステップの必要性と順序を評価します
3. **スコアの生成**: 必要性 60%、順序 30% の重みから、欠落ペナルティ 10% を差し引いてスコアを計算します
4. **理由の生成**: 人が読める説明を提供します

## LLM ベースのスコアリング詳細

- **小数スコア**: 0.0〜1.0 の値を返します
- **コンテキストを考慮**: ユーザーの意図とタスク要件を考慮します
- **説明可能**: スコアの理由を提供します
- **柔軟**: 期待 Trajectory の有無にかかわらず動作します

### LLM ベースのスコアラーのオプション

```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 ベースのスコアラーの結果

```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
}
```

## 統合 Trajectory スコアラー

`@mastra/evals/scorers/prebuilt` の `createTrajectoryScorerCode()` 関数は、精度、効率、ブラックリスト登録された Tool、Tool の失敗パターンを 1 回で確認する多次元の Trajectory 評価を提供します。

### パラメーター

**defaults** (`TrajectoryExpectation`): すべてのデータセット項目に適用するデフォルトの期待値。項目ごとの expectedTrajectory 値がこのデフォルトを上書きします。

**weights** (`TrajectoryScoreWeights`): 各次元のスコアを組み合わせるカスタム重み。重みは合計が 1.0 になるよう正規化されます。

### スコアリング動作

統合スコアラーは 4 つの次元を評価します。

1. **精度**: 実際のステップを期待されるステップと照合します（`steps` が設定されている場合）。`ordering` モードを使用します。
2. **効率**: ステップの上限（`maxSteps`、`maxTotalTokens`、`maxTotalDurationMs`）と冗長な呼び出し（`noRedundantCalls`）を確認します。
3. **ブラックリスト**: 禁止された Tool またはシーケンスを確認します。違反があると、他の次元にかかわらず即座にスコアが **0.0** になります。
4. **Tool の失敗**: 再試行とフォールバックのパターンを検出します。引数の修正パターンも検出します。

最終スコアは有効な次元の加重和であり、有効な次元に応じて正規化されます。デフォルトの重みは、精度 0.4、効率 0.3、Tool の失敗 0.2、ブラックリスト 0.1 ですが、`weights` オプションでカスタマイズできます。ブラックリスト違反がある場合、他のすべてを上書きして 0 になります。ネストされた評価がある場合、スコアはトップレベルが 70%、ネストされた評価の平均が 30% です。

### 統合スコアラーの結果

```typescript
{
  runId: string,
  preprocessStepResult: {
    accuracy?: TrajectoryComparisonResult,
    efficiency?: TrajectoryEfficiencyResult,
    blacklist?: TrajectoryBlacklistResult,
    toolFailures?: ToolFailureAnalysisResult,
    nested?: NestedEvaluationResult[],
  },
  score: number,
  reason: string
}
```

### 項目ごとの期待値

各データセット項目は、独自の `expectedTrajectory` でデフォルトを上書きできます。これにより、プロンプトごとに期待値を変えられます。

```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' },
        ],
      },
    },
  ],
})
```

### 例: 効率とブラックリスト

```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,
  },
  // Customize how dimensions contribute to the final score
  weights: {
    accuracy: 0.5, // prioritize step accuracy
    efficiency: 0.3,
    toolFailures: 0.1,
    blacklist: 0.1,
  },
})
```

## `runEvals` で Trajectory スコアラーを使用する

Trajectory スコアラーは、スコアラー設定の `trajectory` キーに設定します。`runEvals` パイプラインが Trajectory の抽出を自動的に処理します。

### Agent Trajectory の評価

```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 の評価

```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
```

## 関連項目

- [runEvals リファレンス](https://mastra.zisheng.pro/ja/reference/evals/run-evals): Trajectory を抽出してスコアラーに渡すパイプライン
- [MastraScorer リファレンス](https://mastra.zisheng.pro/ja/reference/evals/mastra-scorer): スコアラーの基本インターフェース
- [スコアラーのユーティリティ](https://mastra.zisheng.pro/ja/reference/evals/scorer-utils): `extractTrajectory` や `compareTrajectories` などのユーティリティ関数