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

# runEvals

`runEvals` 函數可針對多個 scorer 並行執行多個測試個案，以批次評估 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')],
})
```

### 配合 gate 及 threshold

```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[]`): 包含輸入資料及可選 ground truth 的測試個案陣列。

**scorers** (`ScorerEntry[] | AgentScorerConfig | WorkflowScorerConfig`): 要使用的 scorer。每個項目可以是獨立的 MastraScorer，或用於追蹤 threshold 的 { scorer, threshold }。AgentScorerConfig 物件會分隔 Agent 層級及 trajectory scorer。WorkflowScorerConfig 物件會指定 Workflow 整體、個別步驟及 trajectory 的 scorer。提供至少一個 gate 時可省略此項（僅執行 gate）。

**gates** (`MastraScorer[]`): 必須取得 1.0 分，執行才會通過的 scorer。如果任何 gate 在所有資料項目的平均分低於 1.0，verdict 便是 failed。每個資料項目的 gate 會在一般 scorer 之前執行。提供此項時可省略 scorers。

**targetOptions** (`AgentExecutionOptions | WorkflowRunOptions`): 執行期間轉交至 target 的選項。對 Agent 而言：傳遞至 agent.generate() 的選項（例如 maxSteps、modelSettings、instructions）。對 Workflow 而言：傳遞至 run.start() 的選項（例如 perStep、outputOptions、initialState）。對多輪 Agent 執行（inputs/turns），runEvals 會產生並注入共用 thread 及 resource，因此 memory.thread 是可選的；提供 memory.resource 可重用特定 resource。

**concurrency** (`number`): 並行執行的測試個案數目。 (Default: `1`)

**onItemComplete** (`function`): 每個測試個案完成後呼叫的 callback 函數。接收項目、target 結果及 scorer 結果。

## 資料項目結構

**input** (`string | string[] | CoreMessage[] | any`): target 的輸入資料。對 Agent 而言：訊息或字串。對 Workflow 而言：Workflow 輸入資料。提供 inputs 時可省略此項。

**inputs** (`(string | string[] | CoreMessage[] | any)[]`): 多輪輸入。每個項目是一輪輸入（格式與 input 相同），並依次傳送至同一 thread 上的 Agent。Scorer 可看到所有輪次累積的輸出。只支援以 Agent 作為 target。提供此項時可省略 input。不可與 turns 同時使用。

**turns** (`EvalTurn[]`): 包含每輪 assertion 的多輪對話。每一輪都是 { input, gates?, scorers? } 物件，並依次傳送至同一 thread；其 gates/scorers 只會評估該輪的輸入及輸出。每輪結果會在 turnResults 中回報，並併入整體 verdict。只支援以 Agent 作為 target。不可與 input 及 inputs 同時使用。

**groundTruth** (`any`): 評分時用作比較的預期或參考輸出。

**expectedTrajectory** (`TrajectoryExpectation`): trajectory 評分的預期 trajectory 設定。包括預期步驟、次序、效率預算、黑名單及 Tool 失敗容許度。會以 run.expectedTrajectory 傳遞至 trajectory scorer，並覆寫 scorer constructor 中的靜態預設值。

**requestContext** (`RequestContext`): 執行期間傳遞至 target 的 Request Context。

**tracingContext** (`TracingContext`): 用於 observability 及除錯的 tracing context。

**startOptions** (`WorkflowRunOptions`): 每個項目的 Workflow 執行選項（例如 initialState、perStep、outputOptions）。這些選項會合併至 targetOptions 之上，因此每個項目的值優先。只在 target 是 Workflow 時適用。

## Agent scorer 設定

對 Agent，使用 `AgentScorerConfig` 分隔 Agent 層級 scorer 及 trajectory scorer：

**agent** (`MastraScorer[]`): 接收原始 Agent 輸出（MastraDBMessage\[]）的 scorer。用於評估回應品質、內容等。

**trajectory** (`MastraScorer[]`): 接收預先擷取的 Trajectory 物件的 scorer。設定 storage 後，pipeline 會從 observability trace 擷取階層式 trajectory（包括巢狀 Tool 呼叫及 model generation）。否則會改為從 Agent 訊息擷取 Tool 呼叫。

## Workflow scorer 設定

對 Workflow，使用 `WorkflowScorerConfig` 指定不同層級的 scorer：

**workflow** (`MastraScorer[]`): 評估整個 Workflow 輸出的 scorer。

**steps** (`Record<string, MastraScorer[]>`): 將步驟 ID 對應至 scorer 陣列，以評估個別步驟輸出的物件。

**trajectory** (`MastraScorer[]`): 接收從 Workflow 執行預先擷取的 Trajectory 的 scorer。設定 storage 後，pipeline 會從 observability trace 擷取階層式 trajectory（包括 Workflow 步驟中的巢狀 Agent 執行及 Tool 呼叫）。否則會改為從 Workflow 輸出擷取步驟結果。

## 傳回值

**scores** (`Record<string, any>`): 所有測試個案的平均分，按 scorer 名稱整理。

**summary** (`object`): 實驗執行的摘要資料。

**summary.totalItems** (`number`): 已處理的測試個案總數。

**verdict** (`'passed' | 'scored' | 'failed'`): 提供 gates 或包含 threshold 的 scorer 時存在。passed = 所有 gate 及 threshold 均符合要求。scored = gate 已通過，但有 threshold 未達標。failed = 至少一個 gate 未取得 1.0 分。

**gateResults** (`GateResult[]`): 每個 gate 在所有資料項目上的平均結果。每個項目都有 id、passed（boolean）及 score（0–1）。

**thresholdResults** (`ThresholdResult[]`): 每個 threshold scorer 在所有資料項目上的平均結果。每個項目都有 id、passed、averageScore 及 threshold。

**turnResults** (`TurnResult[]`): 任何資料項目使用 turns 時存在。每個項目都有 index（從零開始的輪次）、可選的 gateResults、thresholdResults，以及 scores（以 scorer id 作為 key 的獨立 scorer 平均分），並按輪次索引彙整各資料項目。

## EvalTurn

`turns` 陣列中的單一輪次。其 `gates`/`scorers` 只會評估該輪的輸入及輸出：

**input** (`string | string[] | CoreMessage[] | any`): 此輪傳送至 Agent 的輸入。

**gates** (`MastraScorer[]`): 此輪必須取得 1.0 分的 gate。任何一輪的 gate 失敗，都會令整體 verdict 變成 failed。

**scorers** (`ScorerEntry[]`): 只針對此輪評估的 scorer（可選擇包含 threshold）。如果每輪 threshold 未達標（而 gate 通過），verdict 便會是 scored。

## ScorerEntry

`scorers` 陣列中的 scorer 項目可以是獨立 scorer，亦可以是包含 threshold 的 scorer：

**scorer** (`MastraScorer`): scorer 實例。

**threshold** (`number | { min?: number; max?: number }`): 數字代表最低 threshold（分數等於或高於該數值即通過）。使用 { min, max } 進行範圍檢查，例如對 hallucination 等高分代表較差的 scorer 使用 { max: 0.3 }。min 及 max 都必須介乎 0 至 1。

## 範例

### Gate 及 verdict

使用 `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 trajectory 評估

使用 `AgentScorerConfig` 同時評估 Agent 回應及其 Tool 呼叫 trajectory：

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

### 配合 `targetOptions` 的 Agent

傳遞 `maxSteps` 或 `modelSettings` 等執行選項，以自訂 Agent 在評估期間的行為：

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

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

### Workflow trajectory 評估

在 Workflow 評估中加入 trajectory 評分，以驗證步驟執行次序：

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

### 配合每個項目 `startOptions` 的 Workflow

在個別資料項目使用 `startOptions`，以自訂每次 Workflow 執行。每個項目的值優先於 `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` 在共用 thread 上依次傳送多輪輸入。Scorer 可看到所有輪次累積的輸出：

```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 按 resource + thread 劃分訊息範圍），其預設值為產生的 thread。傳入 `targetOptions.memory.resource` 可固定使用特定 resource。跨輪次記憶要求 Agent 已設定 memory store，否則各輪會獨立執行。你可在同一個 `data` 陣列中混合單輪（`input`）及多輪（`inputs`）項目。使用 `inputs` 時可省略 `input`。

評分會以所有輪次的累積輸出作為 `run.output`，但只會以第一輪作為 `run.input`。進行多輪評估時，建議使用以輸出為依據的 scorer（`checks.includes`、`checks.calledTool`、`checks.similarity`）。與輸入相關的 scorer（例如 faithfulness）只會看到第一輪的輸入。從 Trace 讀取資料的 trajectory scorer（`AgentScorerConfig.trajectory`）會以最後一輪的 span 為準。讀取 `run.output` 的 Tool 呼叫檢查（例如 `checks.calledTool`）仍可看到每一輪。

### 每輪 assertion

使用 `turns` 將 `gates`/`scorers` 加至個別輪次。每輪 assertion 只會看到該輪的輸入及輸出，因此較後輪次的 regression 不會被較早輪次掩蓋：

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

每輪 gate/scorer 只會評估該輪（`run.input`/`run.output` 代表該輪的資料）。任何一輪的 gate 失敗，都會令 verdict 變成 `failed`。如果某輪的 threshold 未達標（而 gate 通過），verdict 便會變成 `scored`。最上層的 `scorers`/`gates` 仍會對累積的整段對話評分。`turns` 只適用於 Agent，且不可與 `input` 或 `inputs` 同時使用。

## 相關內容

- [多輪 Evals](https://mastra.zisheng.pro/zh-HK/docs/evals/multi-turn)：多輪評估的概念指南
- [Gate 及 verdict](https://mastra.zisheng.pro/zh-HK/docs/evals/gates-and-verdicts)：嚴重程度語義的概念指南
- [Quick Checks](https://mastra.zisheng.pro/zh-HK/reference/evals/checks)：無需 LLM、可組合的微型 scorer
- [createScorer()](https://mastra.zisheng.pro/zh-HK/reference/evals/create-scorer)：為實驗建立自訂 scorer
- [MastraScorer](https://mastra.zisheng.pro/zh-HK/reference/evals/mastra-scorer)：了解 scorer 結構及方法
- [Trajectory Accuracy](https://mastra.zisheng.pro/zh-HK/reference/evals/trajectory-accuracy)：內置 trajectory 評估 scorer
- [Scorer Utilities](https://mastra.zisheng.pro/zh-HK/reference/evals/scorer-utils)：擷取 trajectory 資料的輔助函數
- [自訂 Scorer](https://mastra.zisheng.pro/zh-HK/docs/evals/custom-scorers)：建立評估邏輯的指南
- [Scorer 概覽](https://mastra.zisheng.pro/zh-HK/docs/evals/overview)：了解 scorer 概念