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

# runEvals

La fonction `runEvals` permet l’évaluation par lots d’agents et de workflows en exécutant simultanément plusieurs cas de test avec des évaluateurs. Elle est essentielle pour les tests systématiques, l’analyse des performances et la validation des systèmes d’IA.

## Exemple d’utilisation

```typescript
import { runEvals } from '@mastra/core/evals'
import { myAgent } from './agents/my-agent'
import { myScorer1, myScorer2 } from './scorers'

const result = await runEvals({
  target: myAgent,
  data: [
    { input: 'What is machine learning?' },
    { input: 'Explain neural networks' },
    { input: 'How does AI work?' },
  ],
  scorers: [myScorer1, myScorer2],
  targetOptions: { maxSteps: 5 },
  concurrency: 2,
  onItemComplete: ({ item, targetResult, scorerResults }) => {
    console.log(`Completed: ${item.input}`)
    console.log(`Scores:`, scorerResults)
  },
})

console.log(`Average scores:`, result.scores)
console.log(`Processed ${result.summary.totalItems} items`)
```

### Évaluation à plusieurs tours

```typescript
import { runEvals } from '@mastra/core/evals'
import { checks } from '@mastra/evals/checks'
import { weatherAgent } from './agents/weather-agent'

const result = await runEvals({
  target: weatherAgent,
  data: [
    {
      inputs: [
        'What is the weather in Brooklyn?',
        'What about tomorrow?',
        'Compare the two forecasts.',
      ],
    },
  ],
  scorers: [checks.calledTool('get_weather', { times: 2 }), checks.includes('Brooklyn')],
})
```

### Avec des gates et des seuils

```typescript
import { runEvals } from '@mastra/core/evals'
import { checks } from '@mastra/evals/checks'
import { faithfulnessScorer } from './scorers'

const result = await runEvals({
  target: myAgent,
  data: [{ input: 'What is the weather in Brooklyn?' }],
  gates: [checks.calledTool('get_weather'), checks.noToolErrors()],
  scorers: [{ scorer: faithfulnessScorer, threshold: 0.7 }, checks.includes('Brooklyn')],
})

result.verdict // 'passed' | 'scored' | 'failed'
result.gateResults // [{ id, passed, score }]
result.thresholdResults // [{ id, passed, averageScore, threshold }]
```

## Paramètres

**target** (`Agent | Workflow`): Agent ou workflow à évaluer.

**data** (`RunEvalsDataItem[]`): Tableau de cas de test avec des données d’entrée et une vérité terrain facultative.

**scorers** (`ScorerEntry[] | AgentScorerConfig | WorkflowScorerConfig`): Évaluateurs à utiliser. Chaque entrée est soit un MastraScorer seul, soit { scorer, threshold } pour le suivi des seuils. Un objet AgentScorerConfig sépare les évaluateurs au niveau de l’agent de ceux de trajectoire. Un objet WorkflowScorerConfig spécifie les évaluateurs du workflow, de ses étapes individuelles et de sa trajectoire. Facultatif lorsqu’au moins un gate est fourni (exécutions avec gates uniquement).

**gates** (`MastraScorer[]`): Évaluateurs qui doivent obtenir 1.0 pour que l’exécution réussisse. Si la moyenne d’un gate est inférieure à 1.0 pour les éléments de données, le verdict est failed. Les gates s’exécutent avant les évaluateurs ordinaires pour chaque élément de données. Lorsque des gates sont fournis, scorers peut être omis.

**targetOptions** (`AgentExecutionOptions | WorkflowRunOptions`): Options transmises à la cible lors de l’exécution. Pour les agents : options passées à agent.generate() (par ex. maxSteps, modelSettings, instructions). Pour les workflows : options passées à run.start() (par ex. perStep, outputOptions, initialState). Pour les exécutions d’agents à plusieurs tours (inputs/turns), runEvals génère et injecte le thread partagé et une ressource ; memory.thread est donc facultatif. Fournissez memory.resource pour réutiliser une ressource donnée.

**concurrency** (`number`): Nombre de cas de test à exécuter simultanément. (Default: `1`)

**onItemComplete** (`function`): Fonction de rappel appelée une fois chaque cas de test terminé. Reçoit l’élément, le résultat de la cible et les résultats des évaluateurs.

## Structure d’un élément de données

**input** (`string | string[] | CoreMessage[] | any`): Données d’entrée pour la cible. Pour les agents : messages ou chaînes. Pour les workflows : données d’entrée du workflow. Facultatif lorsque inputs est fourni.

**inputs** (`(string | string[] | CoreMessage[] | any)[]`): Entrées à plusieurs tours. Chaque entrée est un tour (de même forme que input) envoyé séquentiellement à l’agent dans le même thread. Les évaluateurs voient la sortie cumulée de tous les tours. Pris en charge uniquement pour les cibles Agent. Lorsque fourni, input peut être omis. Mutuellement exclusif avec turns.

**turns** (`EvalTurn[]`): Conversation à plusieurs tours avec des assertions par tour. Chaque tour est un objet { input, gates?, scorers? } envoyé séquentiellement dans le même thread ; ses gates/scorers n’évaluent que l’entrée et la sortie de ce tour. Les résultats par tour sont signalés dans turnResults et intégrés au verdict global. Pris en charge uniquement pour les cibles Agent. Mutuellement exclusif avec input et inputs.

**groundTruth** (`any`): Sortie attendue ou de référence pour la comparaison pendant la notation.

**expectedTrajectory** (`TrajectoryExpectation`): Configuration de trajectoire attendue pour la notation de trajectoire. Inclut les étapes attendues, leur ordre, les budgets d’efficacité, les listes noires et la tolérance aux échecs d’outils. Transmise aux évaluateurs de trajectoire sous la forme run.expectedTrajectory. Remplace les valeurs par défaut statiques des constructeurs d’évaluateurs.

**requestContext** (`RequestContext`): Contexte de requête à transmettre à la cible pendant l’exécution.

**tracingContext** (`TracingContext`): Contexte de traçage pour l’observabilité et le débogage.

**startOptions** (`WorkflowRunOptions`): Options d’exécution de workflow par élément (par ex. initialState, perStep, outputOptions). Elles sont fusionnées par-dessus targetOptions, les valeurs par élément sont donc prioritaires. Applicable uniquement lorsque la cible est un workflow.

## Configuration de l’évaluateur d’agent

Pour les agents, utilisez `AgentScorerConfig` afin de séparer les évaluateurs au niveau de l’agent de ceux de trajectoire :

**agent** (`MastraScorer[]`): Évaluateurs qui reçoivent la sortie brute de l’agent (MastraDBMessage\[]). À utiliser pour évaluer la qualité des réponses, le contenu, etc.

**trajectory** (`MastraScorer[]`): Évaluateurs qui reçoivent un objet Trajectory préextrait. Lorsque le stockage est configuré, le pipeline extrait une trajectoire hiérarchique à partir des traces d’observabilité (y compris les appels d’outils imbriqués et les générations de modèle). Sinon, il extrait les appels d’outils des messages de l’agent.

## Configuration de l’évaluateur de workflow

Pour les workflows, utilisez `WorkflowScorerConfig` pour spécifier des évaluateurs à différents niveaux :

**workflow** (`MastraScorer[]`): Évaluateurs de l’ensemble de la sortie du workflow.

**steps** (`Record<string, MastraScorer[]>`): Objet associant les identifiants d’étape à des tableaux d’évaluateurs pour évaluer les sorties de chaque étape.

**trajectory** (`MastraScorer[]`): Évaluateurs qui reçoivent une Trajectory préextraite de l’exécution du workflow. Lorsque le stockage est configuré, le pipeline extrait une trajectoire hiérarchique à partir des traces d’observabilité (y compris les exécutions d’agents imbriquées et les appels d’outils au sein des étapes du workflow). Sinon, il extrait les résultats des étapes de la sortie du workflow.

## Valeurs renvoyées

**scores** (`Record<string, any>`): Scores moyens de tous les cas de test, organisés par nom d’évaluateur.

**summary** (`object`): Informations récapitulatives sur l’exécution de l’expérience.

**summary.totalItems** (`number`): Nombre total de cas de test traités.

**verdict** (`'passed' | 'scored' | 'failed'`): Présent lorsque des gates ou des évaluateurs avec seuil sont fournis. passed = tous les gates et seuils sont atteints. scored = les gates sont réussis, mais un seuil n’est pas atteint. failed = au moins un gate n’a pas obtenu 1.0.

**gateResults** (`GateResult[]`): Résultats par gate, moyennés sur tous les éléments de données. Chaque entrée contient id, passed (booléen) et score (0–1).

**thresholdResults** (`ThresholdResult[]`): Résultats par évaluateur avec seuil, moyennés sur tous les éléments de données. Chaque entrée contient id, passed, averageScore et threshold.

**turnResults** (`TurnResult[]`): Présent lorsqu’un élément de données utilise turns. Chaque entrée contient index (tour indexé à partir de zéro), ainsi que les gateResults, thresholdResults et scores facultatifs (moyennes des évaluateurs seuls, indexées par identifiant d’évaluateur), agrégés par index de tour sur les éléments de données.

## EvalTurn

Un tour individuel dans un tableau `turns`. Ses `gates`/`scorers` n’évaluent que l’entrée et la sortie de ce tour :

**input** (`string | string[] | CoreMessage[] | any`): Entrée envoyée à l’agent pour ce tour.

**gates** (`MastraScorer[]`): Gates qui doivent obtenir 1.0 pour ce tour. Un gate de tour échoué rend le verdict global failed.

**scorers** (`ScorerEntry[]`): Évaluateurs (éventuellement avec seuils) évalués uniquement pour ce tour. Un seuil par tour non atteint (avec des gates réussis) rend le verdict scored.

## ScorerEntry

Une entrée d’évaluateur dans le tableau `scorers` peut être un évaluateur seul ou un évaluateur avec un seuil :

**scorer** (`MastraScorer`): Instance de l’évaluateur.

**threshold** (`number | { min?: number; max?: number }`): Un nombre implique un seuil minimal (un score égal ou supérieur réussit). Utilisez { min, max } pour des vérifications par plage — par ex. { max: 0.3 } pour des évaluateurs tels que hallucination, pour lesquels un score élevé est mauvais. min et max doivent tous deux être compris entre 0 et 1.

## Exemples

### Gates et verdict

Utilisez `gates` pour des exigences strictes de réussite ou d’échec et `{ scorer, threshold }` pour des métriques de qualité suivies :

```typescript
import { runEvals } from '@mastra/core/evals'
import { checks } from '@mastra/evals/checks'

const result = await runEvals({
  target: weatherAgent,
  data: [{ input: 'What is the weather in Brooklyn?' }],
  gates: [checks.calledTool('get_weather'), checks.noToolErrors()],
  scorers: [
    { scorer: faithfulnessScorer, threshold: 0.7 }, // min threshold (number shorthand)
    { scorer: hallucinationScorer, threshold: { max: 0.3 } }, // max threshold (high = bad)
    { scorer: toneScorer, threshold: { min: 0.5, max: 0.9 } }, // range threshold
    checks.includes('Brooklyn'), // bare scorer, no threshold
  ],
})

if (result.verdict === 'failed') {
  console.log(
    'Gate failures:',
    result.gateResults?.filter(g => !g.passed),
  )
} else if (result.verdict === 'scored') {
  console.log(
    'Threshold misses:',
    result.thresholdResults?.filter(t => !t.passed),
  )
}
```

### Évaluation d’agent

```typescript
import { createScorer, runEvals } from '@mastra/core/evals'

const myScorer = createScorer({
  id: 'my-scorer',
  description: "Check if Agent's response contains ground truth",
  type: 'agent',
}).generateScore(({ run }) => {
  const response = run.output[0]?.content || ''
  const expectedResponse = run.groundTruth
  return response.includes(expectedResponse) ? 1 : 0
})

const result = await runEvals({
  target: chatAgent,
  data: [
    {
      input: 'What is AI?',
      groundTruth: 'AI is a field of computer science that creates intelligent machines.',
    },
    {
      input: 'How does machine learning work?',
      groundTruth: 'Machine learning uses algorithms to learn patterns from data.',
    },
  ],
  scorers: [relevancyScorer],
  concurrency: 3,
})
```

### Évaluation de la trajectoire d’agent

Utilisez `AgentScorerConfig` pour évaluer à la fois la réponse de l’agent et sa trajectoire d’appels d’outils :

```typescript
import { runEvals } from '@mastra/core/evals'
import { createTrajectoryAccuracyScorerCode } from '@mastra/evals/scorers/code/trajectory'

const trajectoryScorer = createTrajectoryAccuracyScorerCode()

const result = await runEvals({
  target: chatAgent,
  data: [
    {
      input: 'What is the weather in London?',
      expectedTrajectory: {
        steps: [{ stepType: 'tool_call', name: 'weatherTool' }],
      },
    },
  ],
  scorers: {
    // agent: [responseQualityScorer], // Optional: add agent-level scorers
    trajectory: [trajectoryScorer],
  },
})

// result.scores.agent — average agent-level scores
// result.scores.trajectory — average trajectory scores
```

### Agent avec `targetOptions`

Transmettez des options d’exécution telles que `maxSteps` ou `modelSettings` pour personnaliser le comportement de l’agent lors de l’évaluation :

```typescript
const result = await runEvals({
  target: chatAgent,
  data: [{ input: 'Summarize this article' }, { input: 'Translate to French' }],
  scorers: [relevancyScorer],
  targetOptions: {
    maxSteps: 5,
    modelSettings: { temperature: 0 },
  },
})
```

### Évaluation de workflow

```typescript
const workflowResult = await runEvals({
  target: myWorkflow,
  data: [
    { input: { query: 'Process this data', priority: 'high' } },
    { input: { query: 'Another task', priority: 'low' } },
  ],
  scorers: {
    workflow: [outputQualityScorer],
    steps: {
      'validation-step': [validationScorer],
      'processing-step': [processingScorer],
    },
  },
  onItemComplete: ({ item, targetResult, scorerResults }) => {
    console.log(`Workflow completed for: ${item.inputData.query}`)
    if (scorerResults.workflow) {
      console.log('Workflow scores:', scorerResults.workflow)
    }
    if (scorerResults.steps) {
      console.log('Step scores:', scorerResults.steps)
    }
  },
})
```

### Évaluation de la trajectoire de workflow

Ajoutez une notation de trajectoire aux évaluations de workflow afin de valider l’ordre d’exécution des étapes :

```typescript
const workflowResult = await runEvals({
  target: myWorkflow,
  data: [
    {
      input: { query: 'Process this data' },
      expectedTrajectory: {
        steps: [
          { stepType: 'workflow_step', name: 'validate' },
          { stepType: 'workflow_step', name: 'process' },
          { stepType: 'workflow_step', name: 'output' },
        ],
      },
    },
  ],
  scorers: {
    workflow: [outputQualityScorer],
    steps: {
      validate: [validationScorer],
    },
    trajectory: [trajectoryScorer],
  },
})

// result.scores.trajectory — workflow trajectory scores
```

### Workflow avec `startOptions` par élément

Utilisez `startOptions` sur les éléments de données individuels pour personnaliser chaque exécution de workflow. Les valeurs par élément sont prioritaires sur `targetOptions` :

```typescript
const result = await runEvals({
  target: myWorkflow,
  data: [
    {
      input: { query: 'hello' },
      startOptions: { initialState: { counter: 1 } },
    },
    {
      input: { query: 'world' },
      startOptions: { initialState: { counter: 2 } },
    },
  ],
  scorers: [outputQualityScorer],
  targetOptions: { perStep: true },
})
```

### Évaluation de conversation à plusieurs tours

Utilisez `inputs` pour envoyer des tours séquentiels dans un thread partagé. Les évaluateurs voient la sortie cumulée de tous les tours :

```typescript
const result = await runEvals({
  target: chatAgent,
  data: [
    {
      inputs: ['My favorite city is Brooklyn.', 'What is the weather in my favorite city?'],
    },
  ],
  gates: [checks.calledTool('get_weather')],
  scorers: [{ scorer: checks.similarity('Brooklyn weather forecast'), threshold: 0.5 }],
})

// result.verdict: 'passed' | 'scored' | 'failed'
```

Chaque tour exécute `agent.generate()` avec le même `threadId`, afin que l’agent voie l’historique complet de la conversation. `runEvals` injecte également un `resourceId` (la mémoire Mastra délimite les messages par ressource + thread), qui est par défaut le thread généré. Transmettez `targetOptions.memory.resource` pour en fixer un en particulier. Le rappel entre les tours exige que l’agent ait un magasin de mémoire configuré. Sinon, les tours s’exécutent de manière isolée. Mélangez des éléments à un tour (`input`) et à plusieurs tours (`inputs`) dans le même tableau `data`. Lorsque vous utilisez `inputs`, `input` peut être omis.

La notation utilise la sortie cumulée de tous les tours comme `run.output`, mais seulement le premier tour comme `run.input`. Préférez des évaluateurs fondés sur la sortie (`checks.includes`, `checks.calledTool`, `checks.similarity`) pour plusieurs tours. Les évaluateurs relatifs à l’entrée (par ex. faithfulness) ne voient que l’entrée du premier tour. Les évaluateurs de trajectoire qui lisent la trace (`AgentScorerConfig.trajectory`) sont résolus par rapport au span du dernier tour. Les vérifications d’appels d’outils qui lisent `run.output` (comme `checks.calledTool`) voient toujours chaque tour.

### Assertions par tour

Utilisez `turns` pour associer des `gates`/`scorers` à des tours individuels. Chaque assertion par tour ne voit que l’entrée et la sortie de ce tour ; une régression lors d’un tour ultérieur ne peut donc pas être masquée par un tour antérieur :

```typescript
const result = await runEvals({
  target: chatAgent,
  data: [
    {
      turns: [
        {
          input: 'What is the weather in Brooklyn?',
          gates: [checks.calledTool('get_weather')],
        },
        {
          input: 'What about tomorrow?',
          gates: [checks.calledTool('get_weather')], // must call again this turn
          scorers: [{ scorer: checks.similarity('tomorrow forecast'), threshold: 0.5 }],
        },
      ],
    },
  ],
})

result.verdict // folds in per-turn gate/threshold outcomes
result.turnResults // [{ index, gateResults, thresholdResults, scores }]
```

Les gates/scorers par tour n’évaluent que ce tour (`run.input`/`run.output` sont ceux de ce tour). Un gate de tour échoué donne le verdict `failed`. Un seuil de tour non atteint (gates réussis) donne `scored`. Les `scorers`/`gates` de niveau supérieur notent toujours l’ensemble de la conversation cumulée. `turns` est réservé aux Agent et ne peut pas être combiné avec `input` ou `inputs`.

## Ressources associées

- [Évaluations à plusieurs tours](https://mastra.zisheng.pro/fr/docs/evals/multi-turn) : guide conceptuel de l’évaluation à plusieurs tours
- [Gates et verdicts](https://mastra.zisheng.pro/fr/docs/evals/gates-and-verdicts) : guide conceptuel de la sémantique de gravité
- [Vérifications rapides](https://mastra.zisheng.pro/fr/reference/evals/checks) : micro-évaluateurs composables sans LLM
- [createScorer()](https://mastra.zisheng.pro/fr/reference/evals/create-scorer) : créez des évaluateurs personnalisés pour des expériences
- [MastraScorer](https://mastra.zisheng.pro/fr/reference/evals/mastra-scorer) : découvrez la structure et les méthodes d’un évaluateur
- [Précision de trajectoire](https://mastra.zisheng.pro/fr/reference/evals/trajectory-accuracy) : évaluateurs intégrés de l’évaluation de trajectoire
- [Utilitaires d’évaluateur](https://mastra.zisheng.pro/fr/reference/evals/scorer-utils) : fonctions utilitaires d’extraction des données de trajectoire
- [Évaluateurs personnalisés](https://mastra.zisheng.pro/fr/docs/evals/custom-scorers) : guide de création de logique d’évaluation
- [Présentation des évaluateurs](https://mastra.zisheng.pro/fr/docs/evals/overview) : comprendre les concepts d’évaluateur