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

# Quick Checks

Quick Checks 是不使用 LLM、可組合的微型評分器，用於常見斷言。凡是使用評分器的地方，都能將其加入既有的 `scorers: [...]` 陣列，包括 `runEvals`、即時評分、實驗及 Studio。

在內部，它們是標準的 `createScorer()` 執行個體，因此具備與其他評分器相同的可觀測性、儲存機制及管線整合能力。

## 使用範例

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

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

console.log(result.scores)
```

## 文字檢查

### `checks.includes(expected, options?)`

若 Agent 的輸出文字包含預期子字串，評為 1 分，否則為 0 分。

```typescript
checks.includes('sunny')
checks.includes('Sunny', { ignoreCase: false })
```

**expected** (`string`): 要在輸出中搜尋的子字串。

**options.ignoreCase** (`boolean`): 比對時不區分大小寫。 (Default: `true`)

傳回值：若找到則為 `1`，否則為 `0`。

### `checks.excludes(unwanted, options?)`

若 Agent 的輸出文字不包含該子字串，評為 1 分，否則為 0 分。

```typescript
checks.excludes('error')
checks.excludes('Error', { ignoreCase: false })
```

**unwanted** (`string`): 不得出現在輸出中的子字串。

**options.ignoreCase** (`boolean`): 比對時不區分大小寫。 (Default: `true`)

傳回值：若未出現則為 `1`，否則為 `0`。

### `checks.equals(expected, options?)`

若選擇性正規化後的輸出文字與預期字串完全相同，評為 1 分。

```typescript
checks.equals('Hello, world!')
checks.equals('Hello', { ignoreCase: false })
```

**expected** (`string`): 輸出必須完全相符的字串。

**options.ignoreCase** (`boolean`): 比對時不區分大小寫。 (Default: `true`)

傳回值：若相同則為 `1`，否則為 `0`。

### `checks.matches(pattern, options?)`

若輸出與規則運算式相符，評為 1 分。

```typescript
checks.matches(/\d+°[FC]/)
checks.matches(/^hello$/, { exact: true })
```

**pattern** (`RegExp`): 用於測試輸出的規則運算式。

**options.exact** (`boolean`): 固定比對模式，使其比對完整輸出（加入 ^ 與 $）。 (Default: `false`)

傳回值：若相符則為 `1`，否則為 `0`。

### `checks.similarity(expected, options?)`

使用 Dice 係數，傳回輸出與預期字串之間的字串相似度分數（0-1）。設定 `threshold` 時，則改為傳回二元值 1/0。

```typescript
checks.similarity('Sunny, 72°F')
checks.similarity('Sunny, 72°F', { threshold: 0.7 })
```

**expected** (`string`): 用於比較的參考字串。

**options.threshold** (`number`): 傳回 1 所需的最低相似度分數（0-1）。省略時會傳回原始相似度分數。

**options.ignoreCase** (`boolean`): 比較時不區分大小寫。 (Default: `true`)

傳回值：原始相似度分數（0-1）；設定門檻時則傳回二元值 `1`/`0`，該門檻由 `threshold` 指定。

## Tool 呼叫檢查

### `checks.calledTool(toolName, options?)`

若 Agent 呼叫指定 Tool 的次數至少達到要求，評為 1 分。

```typescript
checks.calledTool('get_weather')
checks.calledTool('search', { times: 2 })
```

**toolName** (`string`): 要尋找的 Tool 名稱。

**options.times** (`number`): Tool 必須呼叫的最低次數。 (Default: `1`)

傳回值：若呼叫次數至少達到要求則為 `1`；最低次數由 `times` 指定，否則為 `0`。

### `checks.didNotCall(toolName)`

若 Agent 未呼叫指定 Tool，評為 1 分。

```typescript
checks.didNotCall('delete_user')
```

**toolName** (`string`): 不得出現的 Tool 名稱。

傳回值：若未呼叫該 Tool 則為 `1`，否則為 `0`。

### `checks.toolOrder(expectedOrder)`

若 Tool 依指定順序呼叫，評為 1 分。此檢查採用寬鬆比對，允許在預期的 Tool 之間呼叫其他 Tool。

```typescript
checks.toolOrder(['search', 'summarize', 'respond'])
```

**expectedOrder** (`string[]`): 預期呼叫順序中的 Tool 名稱。這些名稱必須以子序列形式出現在實際 Tool 呼叫中。

傳回值：若符合預期順序則為 `1`，否則為 `0`。

### `checks.maxToolCalls(max)`

若 Agent 的 Tool 呼叫次數不超過 `max`，評為 1 分。

```typescript
checks.maxToolCalls(5)
```

**max** (`number`): 允許的 Tool 呼叫次數上限。

傳回值：若未超出限制則為 `1`，否則為 `0`。

### `checks.usedNoTools()`

若 Agent 完全未呼叫任何 Tool，評為 1 分。

```typescript
checks.usedNoTools()
```

傳回值：若未呼叫任何 Tool 則為 `1`，否則為 `0`。

### `checks.noToolErrors()`

若所有 Tool 呼叫都未進入錯誤狀態，評為 1 分。此檢查可偵測錯誤結果（存在 `result.error`）與未完成的 Tool 呼叫（`state === 'call'`）。

```typescript
checks.noToolErrors()
```

傳回值：若所有 Tool 呼叫皆成功則為 `1`，否則為 `0`。

## 與其他評分器組合使用

Checks 可在同一個 `scorers` 陣列中，與以 LLM 或程式碼為基礎的評分器組合使用：

```typescript
import { checks } from '@mastra/evals/checks'
import { createAnswerRelevancyScorer } from '@mastra/evals/scorers/prebuilt'
import { runEvals } from '@mastra/core/evals'
import { myAgent } from '../agents'

const result = await runEvals({
  data: [{ input: 'What is the weather in Brooklyn?' }],
  target: myAgent,
  scorers: [
    // Zero-LLM checks
    checks.includes('Brooklyn'),
    checks.calledTool('get_weather'),
    checks.noToolErrors(),
    // LLM-based scorer
    createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
  ],
})
```

## 相關資源

- [Quick Checks 概觀](https://mastra.zisheng.pro/zh-TW/docs/evals/quick-checks)
- [內建評分器](https://mastra.zisheng.pro/zh-TW/docs/evals/built-in-scorers)
- [`createScorer()` 參考文件](https://mastra.zisheng.pro/zh-TW/reference/evals/create-scorer)
- [`runEvals()` 參考文件](https://mastra.zisheng.pro/zh-TW/reference/evals/run-evals)
- [自訂評分器](https://mastra.zisheng.pro/zh-TW/docs/evals/custom-scorers)