跳至主要內容

快速檢查

Quick Checks 是可組合的微型評分器，用於「輸出包含 X」或「Agent 呼叫了 Tool Y」等常見斷言。它們無需 LLM、可即時執行，並可像其他評分器一樣加入同一個 scorers: [...] 陣列。

何時使用 Quick Checks
何時使用 Quick Checks 的直接連結

當你需要快速、確定的斷言時，可使用 Quick Checks：

  • 驗證輸出文字包含或不包含指定字串
  • 確認 Agent 呼叫了（或沒有呼叫）指定 Tool
  • 驗證 Tool 呼叫順序及次數上限
  • 以零成本的二元檢查作為 CI pipeline 的閘門
  • 與基於 LLM 的評分器配合，進行分層評估

如要進行主觀或語義評估，請改用基於 LLM 的評分器。

快速開始
快速開始 的直接連結

src/evals/weather-checks.ts
import { checks } from '@mastra/evals/checks'
import { runEvals } from '@mastra/core/evals'
import { weatherAgent } from '../agents'

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

console.log(result.scores)
// { 'check-includes': 1, 'check-called-tool': 1, 'check-no-tool-errors': 1 }

可用的檢查
可用的檢查 的直接連結

Quick Checks 分為以下類別：

文字檢查
文字檢查 的直接連結

這些評分器會評估 Agent 的文字輸出：

檢查功能分數
checks.includes(str)輸出包含子字串1 或 0
checks.excludes(str)輸出不包含子字串1 或 0
checks.equals(str)輸出與字串完全相同1 或 0
checks.matches(regex)輸出符合正規表達式1 或 0
checks.similarity(str)與字串的 Dice coefficient 相似度0-1（如設有 threshold，則為二元分數）

Tool 呼叫檢查
Tool 呼叫檢查 的直接連結

這些評分器會評估 Agent 執行期間的 Tool 使用情況：

檢查功能分數
checks.calledTool(name)Tool 至少被呼叫 N 次1 或 0
checks.didNotCall(name)Tool 未被呼叫1 或 0
checks.toolOrder([...])Tool 按預期順序呼叫1 或 0
checks.maxToolCalls(n)Tool 呼叫總數不超過 N 次1 或 0
checks.usedNoTools()完全沒有呼叫 Tool1 或 0
checks.noToolErrors()所有 Tool 呼叫均沒有發生錯誤1 或 0

結合檢查與 LLM 評分器
結合檢查與 LLM 評分器 的直接連結

檢查可在單次 runEvals 呼叫中與基於 LLM 的評分器配合使用。使用檢查作為確定性閘門，並以 LLM 評分器進行定性評估：

src/evals/layered-eval.ts
import { checks } from '@mastra/evals/checks'
import { createFaithfulnessScorer } 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?',
      context: ['Brooklyn weather data: sunny, 72°F'],
    },
  ],
  target: myAgent,
  scorers: [
    // Deterministic checks (instant, free)
    checks.includes('Brooklyn'),
    checks.calledTool('get_weather'),
    checks.excludes('error'),
    checks.noToolErrors(),

    // LLM-based scorer (semantic, costs tokens)
    createFaithfulnessScorer({ model: 'openai/gpt-5-mini' }),
  ],
})

在即時評分中使用檢查
在即時評分中使用檢查 的直接連結

將檢查附加至 Agent，以持續監察：

src/agents/weather-agent.ts
import { Agent } from '@mastra/core/agent'
import { checks } from '@mastra/evals/checks'

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: 'Answer weather questions using the get_weather tool.',
  model: 'openai/gpt-5.6-sol',
  tools: { get_weather: weatherTool },
  scorers: {
    noErrors: {
      scorer: checks.noToolErrors(),
      sampling: { type: 'ratio', rate: 1 },
    },
    mentionCity: {
      scorer: checks.includes('Brooklyn'),
      sampling: { type: 'ratio', rate: 0.5 },
    },
  },
})

檢查的運作方式
檢查的運作方式 的直接連結

每項檢查都是標準的 createScorer() 實例，包含一個 preprocess 步驟和一個 generateScore 步驟。它們與其他評分器一樣，遵循相同的四步 pipeline：

  1. preprocess：從 Agent 執行結果中擷取並標準化相關資料（文字內容、Tool 呼叫）
  2. generateScore：將預處理結果轉換為分數（通常是二元分數 1 或 0）

由於檢查會略過 analyze 和 generateReason 步驟，而且不會呼叫 LLM，因此能在數微秒內完成。請參閱 Quick Checks 參考資料，了解完整 API，包括每項檢查的所有參數和選項。

On this page