실행평가

그만큼runEvals기능을 사용하면 채점자에 대해 여러 테스트 사례를 동시에 실행하여 Agent 및 Workflow를 일괄 평가할 수 있습니다. 이는 AI 시스템의 체계적인 테스트, 성능 분석 및 검증에 필수적입니다.

사용예

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

다회전 평가

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

게이트와 문지방 포함

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

매개변수

target:

Agent | Workflow

평가할 Agent 또는 Workflow입니다.

data:

RunEvalsDataItem[]

입력 데이터와 선택적 정답을 포함하는 테스트 사례 배열입니다.

scorers?:

ScorerEntry[] | AgentScorerConfig | WorkflowScorerConfig

사용할 채점기입니다. 각 항목은 단독 MastraScorer 또는 임곗값 추적을 위한 { scorer, threshold }입니다. AgentScorerConfig 객체는 Agent 수준 채점기와 궤적 채점기를 분리합니다. WorkflowScorerConfig 객체는 Workflow 전체, 개별 단계 및 궤적의 채점기를 지정합니다. 하나 이상의 게이트가 제공되는 경우 선택 사항입니다(게이트 전용 실행).

gates?:

MastraScorer[]

실행을 통과하려면 1.0점을 받아야 하는 채점기입니다. 데이터 항목 전체에서 게이트의 평균 점수가 하나라도 1.0보다 낮으면 평결은 failed입니다. 게이트는 각 데이터 항목에서 일반 채점기보다 먼저 실행됩니다. 이 값이 제공되면 scorers를 생략할 수 있습니다.

targetOptions?:

AgentExecutionOptions | WorkflowRunOptions

실행 중 대상에 전달되는 옵션입니다. Agent의 경우 agent.generate()에 전달되는 옵션(예: maxSteps, modelSettings, instructions)입니다. Workflow의 경우 run.start()에 전달되는 옵션(예: perStep, outputOptions, initialState)입니다. 여러 턴으로 구성된 Agent 실행(inputs/turns)에서는 runEvals가 공유 스레드와 리소스를 생성하고 주입하므로 memory.thread는 선택 사항입니다. 특정 리소스를 재사용하려면 memory.resource를 제공하세요.

concurrency?:

number

= 1

동시에 실행할 테스트 사례의 수입니다.

onItemComplete?:

function

각 테스트 사례가 완료된 후 호출되는 콜백 함수입니다. 항목, 대상 결과 및 채점기 결과를 받습니다.

데이터 항목 구조

input?:

string | string[] | CoreMessage[] | any

대상의 입력 데이터입니다. Agent의 경우 메시지 또는 문자열입니다. Workflow의 경우 Workflow 입력 데이터입니다. inputs가 제공되면 선택 사항입니다.

inputs?:

(string | string[] | CoreMessage[] | any)[]

여러 턴의 입력입니다. 각 항목은 하나의 턴(input과 같은 형태)이며 동일한 스레드의 Agent에 순차적으로 전송됩니다. 채점기는 모든 턴에서 누적된 출력을 확인합니다. Agent 대상에서만 지원됩니다. 이 값이 제공되면 input을 생략할 수 있습니다. turns와 함께 사용할 수 없습니다.

turns?:

EvalTurn[]

턴별 검증 조건이 포함된 여러 턴의 대화입니다. 각 턴은 { input, gates?, scorers? } 객체이며 동일한 스레드에서 순차적으로 전송됩니다. 각 턴의 gates/scorers는 해당 턴의 입력과 출력만 평가합니다. 턴별 결과는 turnResults에 보고되고 전체 verdict에 반영됩니다. Agent 대상에서만 지원됩니다. input 및 inputs와 함께 사용할 수 없습니다.

groundTruth?:

any

채점 중 비교에 사용할 예상 출력 또는 참조 출력입니다.

expectedTrajectory?:

TrajectoryExpectation

궤적 채점을 위한 예상 궤적 구성입니다. 예상 단계, 순서, 효율성 예산, 차단 목록 및 Tool 실패 허용 범위를 포함합니다. 궤적 채점기에 run.expectedTrajectory로 전달됩니다. 채점기 생성자의 정적 기본값보다 우선합니다.

requestContext?:

RequestContext

실행 중 대상에 전달할 요청 컨텍스트입니다.

tracingContext?:

TracingContext

Observability 및 디버깅을 위한 추적 컨텍스트입니다.

startOptions?:

WorkflowRunOptions

항목별 Workflow 실행 옵션입니다(예: initialState, perStep, outputOptions). targetOptions 위에 병합되므로 항목별 값이 우선합니다. 대상이 Workflow인 경우에만 적용됩니다.

Agent 채점자 구성

Agent의 경우 AgentScorerConfig를 사용하여 Agent 수준 채점기와 궤적 채점기를 분리하세요.

agent?:

MastraScorer[]

원시 Agent 출력(MastraDBMessage[])을 받는 채점기입니다. 응답 품질, 콘텐츠 등을 평가할 때 사용합니다.

trajectory?:

MastraScorer[]

미리 추출된 Trajectory 객체를 받는 채점기입니다. 스토리지가 구성된 경우 파이프라인은 Observability Trace에서 계층적 궤적(중첩된 Tool 호출 및 Model 생성 포함)을 추출합니다. 그렇지 않으면 Agent 메시지에서 Tool 호출을 추출하는 방식으로 대체합니다.

Workflow 채점자 구성

Workflow의 경우 WorkflowScorerConfig를 사용하여 여러 수준의 채점기를 지정합니다.

workflow?:

MastraScorer[]

전체 Workflow 출력을 평가하는 채점기입니다.

steps?:

Record<string, MastraScorer[]>

개별 단계 출력을 평가하기 위한 채점기 배열에 단계 ID를 매핑하는 객체입니다.

trajectory?:

MastraScorer[]

Workflow 실행에서 미리 추출된 Trajectory를 받는 채점기입니다. 스토리지가 구성된 경우 파이프라인은 Observability Trace에서 계층적 궤적(Workflow 단계 내에 중첩된 Agent 실행 및 Tool 호출 포함)을 추출합니다. 그렇지 않으면 Workflow 출력에서 단계 결과를 추출하는 방식으로 대체합니다.

보고

scores:

Record<string, any>

채점기 이름별로 구성된 모든 테스트 사례의 평균 점수입니다.

summary:

object

실험 실행에 대한 요약 정보입니다.

summary.totalItems:

number

처리된 테스트 사례의 총수입니다.

verdict?:

'passed' | 'scored' | 'failed'

gates 또는 임곗값이 있는 채점기가 제공된 경우 표시됩니다. passed = 모든 게이트와 임곗값을 충족했습니다. scored = 게이트는 통과했지만 임곗값 하나를 충족하지 못했습니다. failed = 하나 이상의 게이트가 1.0점을 받지 못했습니다.

gateResults?:

GateResult[]

모든 데이터 항목에서 평균을 낸 게이트별 결과입니다. 각 항목에는 id, passed(부울) 및 score(0~1)가 있습니다.

thresholdResults?:

ThresholdResult[]

모든 데이터 항목에서 평균을 낸 임곗값 채점기별 결과입니다. 각 항목에는 id, passed, averageScore 및 threshold가 있습니다.

turnResults?:

TurnResult[]

데이터 항목에서 turns를 하나라도 사용하는 경우 표시됩니다. 각 항목에는 index(0부터 시작하는 턴), 선택적 gateResults, thresholdResults 및 scores(채점기 ID를 키로 사용하는 단독 채점기의 평균)가 있으며, 데이터 항목 전체에서 턴 인덱스별로 집계됩니다.

평가회전

turns 배열의 단일 턴입니다. 해당 턴의 gates/scorers는 그 턴의 입력과 출력만 평가합니다.

input:

string | string[] | CoreMessage[] | any

이 턴에서 Agent에 전송되는 입력입니다.

gates?:

MastraScorer[]

이 턴에서 1.0점을 받아야 하는 게이트입니다. 턴 게이트가 실패하면 전체 평결이 failed가 됩니다.

scorers?:

ScorerEntry[]

이 턴에 대해서만 평가되는 채점기입니다(선택적으로 임곗값 포함). 턴별 임곗값을 충족하지 못하면(게이트는 통과한 경우) 평결이 scored가 됩니다.

득점자입장

scorers 배열의 채점기 항목은 단독 채점기이거나 임곗값이 있는 채점기일 수 있습니다.

scorer:

MastraScorer

채점기 인스턴스입니다.

threshold:

number | { min?: number; max?: number }

숫자는 최소 임곗값을 의미합니다(점수가 임곗값 이상이면 통과). 범위 기반 검사에는 { min, max }를 사용하세요. 예를 들어 높은 점수가 좋지 않은 환각과 같은 채점기에는 { max: 0.3 }을 사용합니다. min과 max는 모두 0과 1 사이여야 합니다.

예

게이츠와 평결

엄격한 통과/실패 요구 사항에는 gates를 사용하고, 추적할 품질 지표에는 { scorer, threshold }를 사용하세요.

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

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

Agent 궤적 평가

Agent 응답과 Tool 호출 궤적을 모두 평가하려면 AgentScorerConfig를 사용하세요.

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

AgenttargetOptions

평가 중 Agent 동작을 사용자 지정하려면 maxSteps 또는 modelSettings와 같은 실행 옵션을 전달하세요.

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

작업 흐름 평가

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

Workflow 궤적 평가

단계 실행 순서를 검증하기 위해 Workflow 평가에 궤적 채점을 추가합니다.

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

항목별 WorkflowstartOptions

각 Workflow 실행을 사용자 지정하려면 개별 데이터 항목에서 startOptions를 사용하세요. 항목별 값이 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 },
})

다단계 대화 평가

공유 스레드에서 순차적인 턴을 전송하려면 inputs를 사용하세요. 채점기는 모든 턴에서 누적된 출력을 확인합니다.

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'

각 턴은 동일한 threadId로 agent.generate()를 실행하므로 Agent가 전체 대화 기록을 볼 수 있습니다. 또한 runEvals는 resourceId를 주입하며(Mastra Memory는 리소스와 스레드를 기준으로 메시지 범위를 지정함), 기본값은 생성된 스레드입니다. 특정 리소스를 고정하려면 targetOptions.memory.resource를 전달하세요. 턴 간 회상을 사용하려면 Agent에 Memory 저장소가 구성되어 있어야 합니다. 그렇지 않으면 턴이 서로 격리되어 실행됩니다. 동일한 data 배열에 단일 턴(input)과 여러 턴(inputs) 항목을 함께 사용할 수 있습니다. inputs를 사용하면 input을 생략할 수 있습니다. 채점은 모든 턴에서 누적된 출력을 run.output으로 사용하지만 run.input으로는 첫 번째 턴만 사용합니다. 여러 턴에서는 출력 기반 채점기(checks.includes, checks.calledTool, checks.similarity)를 사용하는 것이 좋습니다. 입력 상대적 채점기(예: faithfulness)는 첫 번째 턴의 입력만 확인합니다. Trace에서 데이터를 읽는 궤적 채점기(AgentScorerConfig.trajectory)는 마지막 턴의 Span을 기준으로 확인합니다. run.output을 읽는 Tool 호출 검사(예: checks.calledTool)에서는 여전히 모든 턴을 확인합니다.

턴별 어설션

개별 턴에 gates/scorers를 연결하려면 turns를 사용하세요. 각 턴별 검증 조건은 해당 턴의 입력과 출력만 확인하므로 이후 턴의 회귀가 이전 턴에 가려지지 않습니다.

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

턴별 게이트/채점기는 해당 턴만 평가합니다(run.input/run.output은 해당 턴의 값). 턴 게이트가 실패하면 평결은 failed가 됩니다. 턴 임곗값을 충족하지 못하면(게이트는 통과한 경우) scored가 됩니다. 최상위 scorers/gates는 여전히 누적된 대화 전체를 채점합니다. turns는 Agent에서만 사용할 수 있으며 input 또는 inputs와 함께 사용할 수 없습니다.

관련된

• 다중 턴 평가: 다회전 평가의 개념 가이드
• 게이트 및 평결: 심각도 의미에 대한 개념 가이드
• 빠른 점검: Zero-LLM 구성 가능 마이크로 스코어러
• 생성스코어러(): 실험을 위한 맞춤 채점자 생성
• 마스트라스코어러: 채점원의 구조와 방법에 대해 알아보세요.
• 궤도 정확도: 궤적 평가 채점기 내장
• 득점자 유틸리티: 궤적 데이터 추출을 위한 도우미 기능
• 맞춤 채점자: 평가 로직 구축 가이드
• 득점자 개요: 득점원 개념 이해