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

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

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

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

= 1

Nombre de cas de test à exécuter simultanément.

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 :

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

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 :

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 :

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

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 :

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 :

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 :

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 :

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 : guide conceptuel de l’évaluation à plusieurs tours
• Gates et verdicts : guide conceptuel de la sémantique de gravité
• Vérifications rapides : micro-évaluateurs composables sans LLM
• createScorer() : créez des évaluateurs personnalisés pour des expériences
• MastraScorer : découvrez la structure et les méthodes d’un évaluateur
• Précision de trajectoire : évaluateurs intégrés de l’évaluation de trajectoire
• Utilitaires d’évaluateur : fonctions utilitaires d’extraction des données de trajectoire
• Évaluateurs personnalisés : guide de création de logique d’évaluation
• Présentation des évaluateurs : comprendre les concepts d’évaluateur