Quick checks

Quick Checks 是可组合的微型 scorer，用于常见断言，例如“输出包含 X”或“agent 调用了工具 Y”。它们无需 LLM 即可即时运行，并可像其他 scorer 一样插入相同的 scorers: [...] 数组。

何时使用 Quick Checks

当你需要快速、确定性的断言时，请使用 Quick Checks：

• 验证输出文本包含或不包含特定字符串
• 确认 agent 调用（或避免调用）了特定工具
• 校验工具调用的顺序和次数限制
• 用零成本的二元检查为 CI 流水线设置关卡
• 与基于 LLM 的 scorer 组合，实现分层评估

如需主观或语义评估，请改用基于 LLM 的 scorer。

快速开始

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 分为以下类别：

文本检查

这些 scorer 评估 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 系数相似度	0-1（使用 threshold 时为二元值）

工具调用检查

这些 scorer 评估 agent 运行中的工具使用情况：

检查	作用	得分
checks.calledTool(name)	工具被调用至少 N 次	1 或 0
checks.didNotCall(name)	工具未被调用	1 或 0
checks.toolOrder([...])	工具按预期顺序调用	1 或 0
checks.maxToolCalls(n)	工具调用总数不超过 N 次	1 或 0
checks.usedNoTools()	未调用任何工具	1 或 0
checks.noToolErrors()	没有工具调用发生错误	1 或 0

将检查与 LLM scorer 组合

Checks 可以在单次 runEvals 调用中与基于 LLM 的 scorer 组合。使用 checks 进行确定性关卡，使用 LLM scorer 进行定性评估：

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

在实时评分中使用检查

将 checks 附加到 agents 以实现持续监控：

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 步骤。它们遵循与其他 scorer 相同的四步流水线：

1. preprocess：从 agent 运行中提取并归一化相关数据（文本内容、工具调用）
2. generateScore：将预处理结果转换为得分（通常是二元值 1 或 0）

由于 checks 跳过 analyze 和 generateReason 步骤，并且不进行 LLM 调用，因此它们在微秒级内运行。完整 API（包括每个检查的所有参数和选项）请参阅 Quick Checks reference。

相关内容

• Quick Checks reference
• Built-in Scorers
• Custom Scorers
• runEvals() reference