득점자 유틸리티

Mastra는 득점자 실행 입력 및 출력에서 ​​데이터를 추출하고 처리하는 데 도움이 되는 유틸리티 기능을 제공합니다. 이러한 유틸리티는 다음과 같은 경우에 특히 유용합니다.preprocess커스텀 스코어러 단계.

수입

import {
  getAssistantMessageFromRunOutput,
  getReasoningFromRunOutput,
  getUserMessageFromRunInput,
  getSystemMessagesFromRunInput,
  getCombinedSystemPrompt,
  extractToolCalls,
  extractInputMessages,
  extractAgentResponseMessages,
  compareTrajectories,
  createTrajectoryTestRun,
} from '@mastra/evals/scorers/utils'

궤적 추출 기능은 다음에서 사용할 수 있습니다.@mastra/core/evals:

import {
  extractTrajectory,
  extractWorkflowTrajectory,
  extractTrajectoryFromTrace,
} from '@mastra/core/evals'

메시지 추출

getAssistantMessageFromRunOutput

실행 출력의 첫 번째 보조 메시지에서 텍스트 콘텐츠를 추출합니다.

const scorer = createScorer({
  id: 'my-scorer',
  description: 'My scorer',
  type: 'agent',
})
  .preprocess(({ run }) => {
    const response = getAssistantMessageFromRunOutput(run.output)
    return { response }
  })
  .generateScore(({ results }) => {
    return results.preprocessStepResult?.response ? 1 : 0
  })

output?:

ScorerRunOutputForAgent

채점기 실행 출력(MastraDBMessage 배열)

반환: string | undefined - 어시스턴트 메시지 텍스트이며, 어시스턴트 메시지를 찾을 수 없으면 undefined입니다.

getUserMessageFromRunInput

실행 입력의 첫 번째 사용자 메시지에서 텍스트 콘텐츠를 추출합니다.

.preprocess(({ run }) => {
  const userMessage = getUserMessageFromRunInput(run.input);
  return { userMessage };
})

input?:

ScorerRunInputForAgent

입력 메시지를 포함하는 채점기 실행 입력

반환: string | undefined - 사용자 메시지 텍스트이며, 사용자 메시지를 찾을 수 없으면 undefined입니다.

extractInputMessages

모든 입력 메시지에서 텍스트 콘텐츠를 배열로 추출합니다.

.preprocess(({ run }) => {
  const allUserMessages = extractInputMessages(run.input);
  return { conversationHistory: allUserMessages.join("\n") };
})

반환: string[] - 각 입력 메시지에서 가져온 텍스트 문자열 배열입니다.

extractAgentResponseMessages

모든 어시스턴트 응답 메시지에서 텍스트 콘텐츠를 배열로 추출합니다.

.preprocess(({ run }) => {
  const allResponses = extractAgentResponseMessages(run.output);
  return { allResponses };
})

반환: string[] - 각 어시스턴트 메시지에서 가져온 텍스트 문자열 배열입니다.

추론 추출

getReasoningFromRunOutput

실행 출력에서 추론 텍스트를 추출합니다. 이는 사고 과정 추론을 생성하는 deepseek-reasoner와 같은 추론 Model의 응답을 평가할 때 특히 유용합니다. 추론은 두 위치에 저장될 수 있습니다.

1. content.reasoning- 메시지 내용의 문자열 필드
2. content.parts- 부품으로type: 'reasoning' containing details

import {
  getReasoningFromRunOutput,
  getAssistantMessageFromRunOutput,
} from '@mastra/evals/scorers/utils'

const reasoningQualityScorer = createScorer({
  id: 'reasoning-quality',
  name: 'Reasoning Quality',
  description: 'Evaluates the quality of model reasoning',
  type: 'agent',
})
  .preprocess(({ run }) => {
    const reasoning = getReasoningFromRunOutput(run.output)
    const response = getAssistantMessageFromRunOutput(run.output)
    return { reasoning, response }
  })
  .analyze(({ results }) => {
    const { reasoning } = results.preprocessStepResult || {}
    return {
      hasReasoning: !!reasoning,
      reasoningLength: reasoning?.length || 0,
      hasStepByStep: reasoning?.includes('step') || false,
    }
  })
  .generateScore(({ results }) => {
    const { hasReasoning, reasoningLength } = results.analyzeStepResult || {}
    if (!hasReasoning) return 0
    // Score based on reasoning length (normalized to 0-1)
    return Math.min(reasoningLength / 500, 1)
  })
  .generateReason(({ results, score }) => {
    const { hasReasoning, reasoningLength } = results.analyzeStepResult || {}
    if (!hasReasoning) {
      return 'No reasoning was provided by the model.'
    }
    return `Model provided ${reasoningLength} characters of reasoning. Score: ${score}`
  })

output?:

ScorerRunOutputForAgent

채점기 실행 출력(MastraDBMessage 배열)

반환: string | undefined - 추론 텍스트이며, 추론이 없으면 undefined입니다.

시스템 메시지 추출

getSystemMessagesFromRunInput

표준 시스템 메시지와 태그가 지정된 시스템 메시지(Memory 지침과 같은 특수 Prompt)를 모두 포함하여 실행 입력에서 모든 시스템 메시지를 추출합니다.

.preprocess(({ run }) => {
  const systemMessages = getSystemMessagesFromRunInput(run.input);
  return { 
    systemPromptCount: systemMessages.length,
    systemPrompts: systemMessages 
  };
})

반환: string[] - 시스템 메시지 문자열 배열입니다.

getCombinedSystemPrompt

모든 시스템 메시지를 이중 줄 바꿈으로 결합된 단일 Prompt 문자열로 결합합니다.

.preprocess(({ run }) => {
  const fullSystemPrompt = getCombinedSystemPrompt(run.input);
  return { fullSystemPrompt };
})

보고: string - Combined system prompt string.

Tool 호출 추출

extractToolCalls

Tool 이름, 호출 ID 및 메시지 배열에서의 해당 위치를 포함하여 실행 출력에서 ​​모든 Tool 호출에 대한 정보를 추출합니다.

const toolUsageScorer = createScorer({
  id: 'tool-usage',
  description: 'Evaluates tool usage patterns',
  type: 'agent',
})
  .preprocess(({ run }) => {
    const { tools, toolCallInfos } = extractToolCalls(run.output)
    return {
      toolsUsed: tools,
      toolCount: tools.length,
      toolDetails: toolCallInfos,
    }
  })
  .generateScore(({ results }) => {
    const { toolCount } = results.preprocessStepResult || {}
    // Score based on appropriate tool usage
    return toolCount > 0 ? 1 : 0
  })

보고:

{
  tools: string[];           // Array of tool names
  toolCallInfos: ToolCallInfo[];  // Detailed tool call information
}

여기서 ToolCallInfo는 다음과 같습니다.

type ToolCallInfo = {
  toolName: string // Name of the tool
  toolCallId: string // Unique call identifier
  messageIndex: number // Index in the output array
  invocationIndex: number // Index within message's tool invocations
}

테스트 유틸리티

이러한 유틸리티는 채점자 개발을 위한 테스트 데이터를 생성하는 데 도움이 됩니다.

createTestMessage

테스트용 MastraDBMessage 객체를 생성합니다.

import { createTestMessage } from '@mastra/evals/scorers/utils'

const userMessage = createTestMessage({
  content: 'What is the weather?',
  role: 'user',
})

const assistantMessage = createTestMessage({
  content: 'The weather is sunny.',
  role: 'assistant',
  toolInvocations: [
    {
      toolCallId: 'call-1',
      toolName: 'weatherTool',
      args: { location: 'London' },
      result: { temp: 20 },
      state: 'result',
    },
  ],
})

createAgentTestRun

채점자 테스트를 위한 완전한 테스트 실행 개체를 생성합니다.

import { createAgentTestRun, createTestMessage } from '@mastra/evals/scorers/utils'

const testRun = createAgentTestRun({
  inputMessages: [createTestMessage({ content: 'Hello', role: 'user' })],
  output: [createTestMessage({ content: 'Hi there!', role: 'assistant' })],
})

// Run your scorer with the test data
const result = await myScorer.run({
  input: testRun.input,
  output: testRun.output,
})

궤적 유틸리티

extractTrajectory

Agent 출력 메시지(MastraDBMessage[])에서 Trajectory를 추출합니다. Tool 호출을 ToolCallStep 객체로 변환합니다. runEvals 파이프라인은 궤적 채점기에 대해 이를 자동으로 호출하므로 직접 테스트할 때만 필요합니다. 에서 사용 가능@mastra/core/evals.

import { extractTrajectory } from '@mastra/core/evals'

const trajectory = extractTrajectory(agentOutputMessages)
// trajectory.steps — ToolCallStep[] extracted from toolInvocations
// trajectory.rawOutput — the original MastraDBMessage[] array

반환: Trajectory: steps: TrajectoryStep[], totalDurationMs 및 rawOutput을 포함합니다.

extractWorkflowTrajectory

Workflow 단계 결과에서 Trajectory를 추출합니다. 실행 경로 순서를 준수하여 StepResult 레코드를 WorkflowStepStep 객체로 변환합니다. 에서 사용 가능@mastra/core/evals.

import { extractWorkflowTrajectory } from '@mastra/core/evals'

const trajectory = extractWorkflowTrajectory(
  workflowResult.steps, // Record<string, StepResult>
  workflowResult.stepExecutionPath, // string[] (optional)
)
// trajectory.steps — WorkflowStepStep[] in execution order

반환: Trajectory: steps: TrajectoryStep[], totalDurationMs 및 rawWorkflowResult를 포함합니다.

extractTrajectoryFromTrace

Observability Trace Span(SpanRecord[])에서 계층적 Trajectory를 구축합니다. 부모-자식 Span 트리를 재구성하고 각 Span을 중첩된 children이 있는 적절한 TrajectoryStep 판별 유니온 유형에 매핑합니다. 스토리지가 있는 경우 권장되는 추출 방법입니다. 대상의 Mastra 인스턴스에 스토리지 백엔드가 구성되어 있으면 runEvals 파이프라인이 이를 자동으로 호출합니다. 중첩된 Agent 실행, Tool 호출 및 Model 생성을 비롯한 전체 실행 트리를 포착하므로 extractTrajectory 또는 extractWorkflowTrajectory보다 더 풍부한 궤적을 생성합니다. 에서 사용 가능@mastra/core/evals.

import { extractTrajectoryFromTrace } from '@mastra/core/evals'

// After fetching a trace from the observability store
const traceData = await observabilityStore.getTrace({ traceId })
const trajectory = extractTrajectoryFromTrace(traceData.spans, rootSpanId)
// trajectory.steps — hierarchical TrajectoryStep[] with children

매개변수:

• spans (SpanRecord[]): Trace 쿼리에서 가져온 Span 레코드 배열입니다.
• rootSpanId (string, 선택 사항): 시작점으로 사용할 Span ID입니다. 생략하면 부모가 없는 Span을 사용합니다. 반환: Trajectory: 재귀적 children이 있는 steps: TrajectoryStep[]와 totalDurationMs를 포함합니다.

스팬 유형 매핑

Span 유형	궤적 단계 유형	추출되는 주요 필드
TOOL_CALL	tool_call	toolArgs, toolResult, success
MCP_TOOL_CALL	mcp_tool_call	toolArgs, toolResult, mcpServer, success
MODEL_GENERATION	model_generation	modelId, promptTokens, completionTokens, finishReason
AGENT_RUN	agent_run	agentId(엔터티 ID에서 가져옴)
WORKFLOW_RUN	workflow_run	workflowId(엔터티 ID에서 가져옴)
WORKFLOW_STEP	workflow_step	output
WORKFLOW_CONDITIONAL	workflow_conditional	conditionCount, selectedSteps
WORKFLOW_PARALLEL	workflow_parallel	branchCount, parallelSteps
WORKFLOW_LOOP	workflow_loop	loopType, totalIterations
WORKFLOW_SLEEP	workflow_sleep	sleepDurationMs, sleepType
WORKFLOW_WAIT_EVENT	workflow_wait_event	eventName, eventReceived
PROCESSOR_RUN	processor_run	processorId
유형이 GENERIC, MODEL_STEP, MODEL_CHUNK 및 WORKFLOW_CONDITIONAL_EVAL인 Span은 노이즈로 간주되어 건너뜁니다.

compareTrajectories

실제 궤적과 예상 궤적을 비교하고 자세한 비교 결과를 반환합니다. 내부적으로 사용됨createTrajectoryAccuracyScorerCode.

expected 매개변수에는 Trajectory(실제 궤적) 또는 { steps: ExpectedStep[] }를 전달할 수 있습니다. ExpectedStep[]를 사용할 때는 이름만으로 일치시키거나 이름과 stepType으로 일치시킬 수 있습니다. 비교할 데이터를 포함할 수도 있습니다. 자세한 내용은 예상 단계를 참조하세요.

import { compareTrajectories } from '@mastra/evals/scorers/utils'

// Using ExpectedStep[] (recommended for expectations)
// Data fields (e.g. toolArgs) are auto-compared when present on expected steps
const result = compareTrajectories(
  actualTrajectory,
  { steps: [{ name: 'search' }, { name: 'summarize', stepType: 'tool_call' }] },
  { allowRepeatedSteps: true },
)
// result.score — 0.0 to 1.0
// result.missingSteps — step names not found
// result.extraSteps — unexpected step names
// result.outOfOrderSteps — steps found but in wrong order

보고: TrajectoryComparisonResult

createTrajectoryTestRun

궤적 채점기용 테스트 실행 객체를 만듭니다. Trajectory를 예상되는 ScorerRun 형식으로 래핑합니다.

import { createTrajectoryTestRun } from '@mastra/evals/scorers/utils'

const run = createTrajectoryTestRun({
  steps: [
    { stepType: 'tool_call', name: 'search', toolArgs: { q: 'test' } },
    { stepType: 'tool_call', name: 'summarize' },
  ],
})

const result = await trajectoryScorer.run(run)

checkTrajectoryEfficiency

단계, 토큰 및 기간 예산에 대해 궤적 효율성을 평가합니다. 또한 중복 호출을 감지합니다(동일한 인수를 가진 동일한 Tool).

import { checkTrajectoryEfficiency } from '@mastra/evals/scorers/utils'

const result = checkTrajectoryEfficiency(trajectory, {
  maxSteps: 5,
  maxTotalTokens: 2000,
  maxTotalDurationMs: 5000,
  noRedundantCalls: true,
})
// result.score — 1.0 if within all budgets, lower with penalties
// result.redundantCalls — duplicate tool+args combos
// result.overStepBudget — true if maxSteps exceeded
// result.overTokenBudget — true if maxTotalTokens exceeded
// result.overDurationBudget — true if maxTotalDurationMs exceeded

보고: TrajectoryEfficiencyResult

checkTrajectoryBlacklist

궤적에 금지된 Tool나 Tool 호출 순서가 포함되어 있는지 확인합니다.

import { checkTrajectoryBlacklist } from '@mastra/evals/scorers/utils'

const result = checkTrajectoryBlacklist(trajectory, {
  blacklistedTools: ['deleteAll', 'admin-override'],
  blacklistedSequences: [['escalate', 'admin-override']],
})
// result.score — 1.0 if no violations, 0.0 if any found
// result.violatedTools — blacklisted tools that were called
// result.violatedSequences — blacklisted sequences that were detected

보고: TrajectoryBlacklistResult

analyzeToolFailures

재시도, 대체, 인수 수정을 포함한 Tool 오류 패턴을 감지합니다.

import { analyzeToolFailures } from '@mastra/evals/scorers/utils'

const result = analyzeToolFailures(trajectory, {
  maxRetriesPerTool: 2,
})
// result.score — 1.0 if no failure patterns, lower if patterns detected
// result.patterns — detected patterns (retry, fallback, arg_correction)

보고: ToolFailureAnalysisResult

완전한 예

다음은 여러 유틸리티를 함께 사용하는 방법을 보여주는 전체 예입니다.

import { createScorer } from '@mastra/core/evals'
import {
  getAssistantMessageFromRunOutput,
  getReasoningFromRunOutput,
  getUserMessageFromRunInput,
  getCombinedSystemPrompt,
  extractToolCalls,
} from '@mastra/evals/scorers/utils'

const comprehensiveScorer = createScorer({
  id: 'comprehensive-analysis',
  name: 'Comprehensive Analysis',
  description: 'Analyzes all aspects of an agent response',
  type: 'agent',
})
  .preprocess(({ run }) => {
    // Extract all relevant data
    const userMessage = getUserMessageFromRunInput(run.input)
    const response = getAssistantMessageFromRunOutput(run.output)
    const reasoning = getReasoningFromRunOutput(run.output)
    const systemPrompt = getCombinedSystemPrompt(run.input)
    const { tools, toolCallInfos } = extractToolCalls(run.output)

    return {
      userMessage,
      response,
      reasoning,
      systemPrompt,
      toolsUsed: tools,
      toolCount: tools.length,
    }
  })
  .generateScore(({ results }) => {
    const { response, reasoning, toolCount } = results.preprocessStepResult || {}

    let score = 0
    if (response && response.length > 0) score += 0.4
    if (reasoning) score += 0.3
    if (toolCount > 0) score += 0.3

    return score
  })
  .generateReason(({ results, score }) => {
    const { response, reasoning, toolCount } = results.preprocessStepResult || {}

    const parts = []
    if (response) parts.push('provided a response')
    if (reasoning) parts.push('included reasoning')
    if (toolCount > 0) parts.push(`used ${toolCount} tool(s)`)

    return `Score: ${score}. The agent ${parts.join(', ')}.`
  })