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

# dataset.startExperiment()

**追加バージョン：** `@mastra/core@1.4.0`

データセットで Experiment を実行し、完了を待ちます。任意のスコアリングを使用して、すべての項目を対象（Agent、Workflow、Scorer）に対して実行します。

## 使用例

```typescript
import { Mastra } from '@mastra/core'

const mastra = new Mastra({/* storage config */})

const dataset = await mastra.datasets.get({ id: 'dataset-id' })

// Run against a registered agent with a flat scorer list
const summary = await dataset.startExperiment({
  targetType: 'agent',
  targetId: 'my-agent',
  scorers: ['accuracy', 'relevancy'],
  maxConcurrency: 10,
})

// Or pass the same categorised shape accepted by runEvals
const summary2 = await dataset.startExperiment({
  targetType: 'agent',
  targetId: 'my-agent',
  scorers: {
    agent: [accuracyScorer],
    trajectory: [toolOrderScorer],
  },
})

// For workflow targets, score individual steps with their own scorers
const summary3 = await dataset.startExperiment({
  targetType: 'workflow',
  targetId: 'my-workflow',
  scorers: {
    workflow: [overallScorer],
    steps: {
      'fetch-data': [fetchScorer],
      transform: [transformScorer],
    },
    trajectory: [executionPathScorer],
  },
})

console.log(`${summary.succeededCount}/${summary.totalItems} succeeded`)
console.log(`Status: ${summary.status}`)
console.log(`${summary2.succeededCount}/${summary2.totalItems} succeeded`)
console.log(`Status: ${summary2.status}`)
```

## パラメータ

**targetType** (`'agent' | 'workflow' | 'scorer'`): 項目を実行する登録済み対象の種類。targetId と併用します。

**targetId** (`string`): 登録済み対象の ID。targetType と併用します。

**scorers** (`(MastraScorer | string)[] | AgentScorerConfig | WorkflowScorerConfig`): 各結果を評価する Scorer。MastraScorer インスタンスまたは登録済み Scorer ID の単純な配列のほか、runEvals と同じ分類済み設定形式（AgentScorerConfig / WorkflowScorerConfig）を指定できます。Trajectory Scorer（type: "trajectory"）は、指定形式にかかわらず、事前抽出された Trajectory を出力として自動的に受け取ります。Workflow の場合は scorers: { steps: { stepId: \[...] } } で Step ごとの Scorer を渡し、各 Step の出力に対して実行できます。その結果には元の stepId が含まれ、targetScope: "span" が維持されます（runEvals と同じ動作）。

**name** (`string`): 表示名 experiment.

**description** (`string`): 説明 experiment.

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

**version** (`number`): 特定のデータセットバージョンに固定します。デフォルトは最新バージョンです。

**maxConcurrency** (`number`): 項目を同時実行する最大数。デフォルトは 5 です。

**signal** (`AbortSignal`): Experiment をキャンセルするための AbortSignal。

**itemTimeout** (`number`): 項目ごとの実行タイムアウト（ミリ秒）。

**maxRetries** (`number`): 失敗時の項目ごとの最大再試行回数。デフォルトは 0（再試行なし）です。Abort エラーは再試行しません。

**unmockedToolPolicy** (`'allow' | 'deny'`): 宣言されていない Agent Tool の呼び出しを制御します。allow は実際に実行します。deny は実行前に TOOL\_MOCK\_NOT\_DECLARED で項目を失敗させます。項目単位の値は、この Experiment のデフォルト値を上書きします。 (Default: `'allow'`)

**persistence** (`ExperimentPersistencePolicy`): この実行で Experiment レコードとスコアレコードを書き込むかを制御します。対象と Scorer は引き続き実行され、結果は返される概要で確認できます。

**persistence.experiments** (`'default' | 'none'`): none に設定すると、Experiment の作成、項目結果、進行状況、最終ステータスの書き込みを省略します。

**persistence.scores** (`'default' | 'none'`): none に設定すると、Scorer を実行したままスコアの書き込みを省略します。

## 戻り値

**result** (`Promise<ExperimentSummary>`): 完了した Experiment の概要。

**result.experimentId** (`string`): 一意な ID： experiment.

**result.status** (`'pending' | 'running' | 'completed' | 'failed'`): Experiment の最終ステータス。

**result.totalItems** (`number`): データセット内の項目総数。

**result.succeededCount** (`number`): 成功した項目数。

**result.failedCount** (`number`): 失敗した項目数。

**result.skippedCount** (`number`): スキップされた項目数（Abort による場合など）。

**result.completedWithErrors** (`boolean`): 実行は完了したものの一部の項目が失敗した場合は true。

**result.startedAt** (`Date`): Experiment が開始された日時。

**result.completedAt** (`Date`): Experiment が完了した日時。

**result.results** (`ItemWithScores[]`): 全項目の結果とスコア。

**result.results.itemId** (`string`): データセット項目の ID。

**result.results.itemVersion** (`number`): 実行時の項目のデータセットバージョン。

**result.results.input** (`unknown`): 対象に渡された入力データ。

**result.results.output** (`unknown | null`): 対象からの出力。失敗した場合は null。

**result.results.groundTruth** (`unknown | null`): データセット項目の期待される出力。

**result.results.error** (`{ message: string; stack?: string; code?: string } | null`): 実行に失敗した場合の構造化エラー。

**result.results.startedAt** (`Date`): 項目の実行が開始された日時。

**result.results.completedAt** (`Date`): 項目の実行が完了した日時。

**result.results.retryCount** (`number`): 再試行回数。

**result.results.scores** (`ScorerResult[]`): この項目に対するすべての Scorer の結果。

**result.results.scores.scorerId** (`string`): Scorer の ID。

**result.results.scores.scorerName** (`string`): 表示名 scorer.

**result.results.scores.score** (`number | null`): 算出されたスコア。Scorer が失敗した場合は null。

**result.results.scores.reason** (`string | null`): スコアの理由または説明。

**result.results.scores.error** (`string | null`): Scorer が失敗した場合のエラーメッセージ。

## 関連項目

- [dataset.startExperimentAsync()](https://mastra.zisheng.pro/ja/reference/datasets/startExperimentAsync)
- [dataset.listExperiments()](https://mastra.zisheng.pro/ja/reference/datasets/listExperiments)
- [DatasetsManager.compareExperiments()](https://mastra.zisheng.pro/ja/reference/datasets/compareExperiments)