Quick Checks

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

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

使用範例

src/evals/weather-checks.ts

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 分。

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

expected:

string

要在輸出中搜尋的子字串。

options.ignoreCase?:

boolean

= true

比對時不區分大小寫。

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

checks.excludes(unwanted, options?)

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

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

unwanted:

string

不得出現在輸出中的子字串。

options.ignoreCase?:

boolean

= true

比對時不區分大小寫。

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

checks.equals(expected, options?)

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

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

expected:

string

輸出必須完全相符的字串。

options.ignoreCase?:

boolean

= true

比對時不區分大小寫。

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

checks.matches(pattern, options?)

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

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

pattern:

RegExp

用於測試輸出的規則運算式。

options.exact?:

boolean

= false

固定比對模式，使其比對完整輸出（加入 ^ 與 $）。

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

checks.similarity(expected, options?)

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

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

expected:

string

用於比較的參考字串。

options.threshold?:

number

傳回 1 所需的最低相似度分數（0-1）。省略時會傳回原始相似度分數。

options.ignoreCase?:

boolean

= true

比較時不區分大小寫。

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

Tool 呼叫檢查

checks.calledTool(toolName, options?)

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

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

toolName:

string

要尋找的 Tool 名稱。

options.times?:

number

= 1

Tool 必須呼叫的最低次數。

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

checks.didNotCall(toolName)

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

checks.didNotCall('delete_user')

toolName:

string

不得出現的 Tool 名稱。

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

checks.toolOrder(expectedOrder)

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

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

expectedOrder:

string[]

預期呼叫順序中的 Tool 名稱。這些名稱必須以子序列形式出現在實際 Tool 呼叫中。

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

checks.maxToolCalls(max)

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

checks.maxToolCalls(5)

max:

number

允許的 Tool 呼叫次數上限。

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

checks.usedNoTools()

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

checks.usedNoTools()

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

checks.noToolErrors()

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

checks.noToolErrors()

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

與其他評分器組合使用

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

src/evals/combined-eval.ts

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 概觀
• 內建評分器
• createScorer() 參考文件
• runEvals() 參考文件
• 自訂評分器