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

# dataset.startExperiment()

**Ajouté dans :** `@mastra/core@1.4.0`

Exécute une expérience sur le jeu de données et attend sa fin. Exécute tous les éléments sur une cible (agent, workflow ou scorer), avec une évaluation facultative.

## Exemple d’utilisation

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

## Paramètres

**targetType** (`'agent' | 'workflow' | 'scorer'`): Type de cible enregistrée sur laquelle exécuter les éléments. À utiliser avec targetId.

**targetId** (`string`): ID de la cible enregistrée. À utiliser avec targetType.

**scorers** (`(MastraScorer | string)[] | AgentScorerConfig | WorkflowScorerConfig`): Scorers permettant d’évaluer chaque résultat. Accepte un tableau plat d’instances MastraScorer ou d’ID de scorers enregistrés, ou la même structure de configuration catégorisée qu’utilise runEvals (AgentScorerConfig / WorkflowScorerConfig). Les scorers de trajectoire (type: "trajectory") reçoivent automatiquement une Trajectory préextraite comme sortie, quelle que soit la forme utilisée. Pour les cibles de workflow, des scorers par étape peuvent être transmis via scorers: { steps: { stepId: \[...] } } et exécutés sur la sortie de chaque étape ; leurs résultats contiennent le stepId d’origine et conservent targetScope: "span" (comme avec runEvals).

**name** (`string`): Nom d’affichage de l’expérience.

**description** (`string`): Description de l’expérience.

**metadata** (`Record<string, unknown>`): Métadonnées arbitraires de l’expérience.

**version** (`number`): Épingle une version précise du jeu de données. La valeur par défaut est la version la plus récente.

**maxConcurrency** (`number`): Nombre maximal d’exécutions simultanées d’éléments. La valeur par défaut est 5.

**signal** (`AbortSignal`): AbortSignal permettant d’annuler l’expérience.

**itemTimeout** (`number`): Délai d’expiration de l’exécution par élément, en millisecondes.

**maxRetries** (`number`): Nombre maximal de tentatives par élément en cas d’échec. La valeur par défaut est 0 (aucune nouvelle tentative). Les erreurs d’annulation ne font jamais l’objet d’une nouvelle tentative.

**unmockedToolPolicy** (`'allow' | 'deny'`): Contrôle les appels d’outils d’agent non déclarés. allow les exécute réellement. deny fait échouer l’élément avec TOOL\_MOCK\_NOT\_DECLARED avant l’exécution. Une valeur définie au niveau de l’élément remplace cette valeur par défaut de l’expérience. (Default: `'allow'`)

**persistence** (`ExperimentPersistencePolicy`): Contrôle si cette exécution écrit des enregistrements d’expérience et de scores. Les cibles et les scorers sont tout de même exécutés et les résultats restent disponibles dans le récapitulatif renvoyé.

**persistence.experiments** (`'default' | 'none'`): Définissez cette valeur sur none pour ignorer la création de l’expérience ainsi que l’écriture des résultats d’éléments, de la progression et de l’état final.

**persistence.scores** (`'default' | 'none'`): Définissez cette valeur sur none pour ne pas écrire les scores tout en exécutant les scorers.

## Valeur renvoyée

**result** (`Promise<ExperimentSummary>`): Récapitulatif de l’expérience terminée.

**result.experimentId** (`string`): ID unique de l’expérience.

**result.status** (`'pending' | 'running' | 'completed' | 'failed'`): État final de l’expérience.

**result.totalItems** (`number`): Nombre total d’éléments du jeu de données.

**result.succeededCount** (`number`): Nombre d’éléments ayant réussi.

**result.failedCount** (`number`): Nombre d’éléments ayant échoué.

**result.skippedCount** (`number`): Nombre d’éléments ignorés (par exemple, à cause d’une annulation).

**result.completedWithErrors** (`boolean`): true si l’exécution est terminée, mais que certains éléments ont échoué.

**result.startedAt** (`Date`): Date et heure de début de l’expérience.

**result.completedAt** (`Date`): Date et heure de fin de l’expérience.

**result.results** (`ItemWithScores[]`): Tous les résultats d’éléments avec leurs scores.

**result.results.itemId** (`string`): ID de l’élément du jeu de données.

**result.results.itemVersion** (`number`): Version du jeu de données de l’élément au moment de son exécution.

**result.results.input** (`unknown`): Données d’entrée transmises à la cible.

**result.results.output** (`unknown | null`): Sortie de la cible, ou null en cas d’échec.

**result.results.groundTruth** (`unknown | null`): Sortie attendue de l’élément du jeu de données.

**result.results.error** (`{ message: string; stack?: string; code?: string } | null`): Erreur structurée si l’exécution a échoué.

**result.results.startedAt** (`Date`): Date et heure de début de l’exécution de l’élément.

**result.results.completedAt** (`Date`): Date et heure de fin de l’exécution de l’élément.

**result.results.retryCount** (`number`): Nombre de tentatives de nouvelle exécution.

**result.results.scores** (`ScorerResult[]`): Résultats de tous les scorers pour cet élément.

**result.results.scores.scorerId** (`string`): ID du scorer.

**result.results.scores.scorerName** (`string`): Nom d’affichage du scorer.

**result.results.scores.score** (`number | null`): Score calculé, ou null si le scorer a échoué.

**result.results.scores.reason** (`string | null`): Motif ou explication du score.

**result.results.scores.error** (`string | null`): Message d’erreur si le scorer a échoué.

## Ressources associées

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