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

# 실행평가

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

## 사용예

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

### 다회전 평가

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

### 게이트와 문지방 포함

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

## 매개변수

**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`): 동시에 실행할 테스트 사례의 수입니다. (Default: `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 }`를 사용하세요.

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

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

### Agent 궤적 평가

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

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

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

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

### 작업 흐름 평가

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

### Workflow 궤적 평가

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

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

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

### 다단계 대화 평가

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

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

각 턴은 동일한 `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`를 사용하세요. 각 턴별 검증 조건은 해당 턴의 입력과 출력만 확인하므로 이후 턴의 회귀가 이전 턴에 가려지지 않습니다.

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

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

## 관련된

- [다중 턴 평가](https://mastra.zisheng.pro/ko/docs/evals/multi-turn): 다회전 평가의 개념 가이드
- [게이트 및 평결](https://mastra.zisheng.pro/ko/docs/evals/gates-and-verdicts): 심각도 의미에 대한 개념 가이드
- [빠른 점검](https://mastra.zisheng.pro/ko/reference/evals/checks): Zero-LLM 구성 가능 마이크로 스코어러
- [생성스코어러()](https://mastra.zisheng.pro/ko/reference/evals/create-scorer): 실험을 위한 맞춤 채점자 생성
- [마스트라스코어러](https://mastra.zisheng.pro/ko/reference/evals/mastra-scorer): 채점원의 구조와 방법에 대해 알아보세요.
- [궤도 정확도](https://mastra.zisheng.pro/ko/reference/evals/trajectory-accuracy): 궤적 평가 채점기 내장
- [득점자 유틸리티](https://mastra.zisheng.pro/ko/reference/evals/scorer-utils): 궤적 데이터 추출을 위한 도우미 기능
- [맞춤 채점자](https://mastra.zisheng.pro/ko/docs/evals/custom-scorers): 평가 로직 구축 가이드
- [득점자 개요](https://mastra.zisheng.pro/ko/docs/evals/overview): 득점원 개념 이해