궤도 정확도 채점자

Mastra는 Agent 또는 Workflow가 예상되는 작업 순서를 따르는지 여부를 평가하기 위해 두 가지 궤적 정확도 점수 측정기를 제공합니다.

1. 코드 기반 득점자- 정확한 스텝 매칭과 정렬을 이용한 결정론적 평가
2. LLM 기반 채점자- AI를 활용한 의미론적 평가로 궤적 품질 및 적합성 평가

두 채점기 모두 Agent 및 Workflow와 함께 작동합니다. runEvals 파이프라인이 궤적을 자동으로 추출하므로 채점기는 Trajectory 객체를 직접 받습니다.

궤적 추출

runEvals 파이프라인은 Observability 스토리지의 구성 여부에 따라 두 가지 추출 전략을 사용합니다.

추적 기반 추출(선호)

대상의 Mastra 인스턴스에 스토리지가 구성되어 있으면 파이프라인은 Observability 저장소에서 전체 실행 Trace를 가져와 extractTrajectoryFromTrace()를 호출합니다. 그러면 전체 실행 트리를 포착하는 중첩된 children이 있는 계층적 궤적이 생성됩니다. 이 트리에는 Workflow 단계 내의 중첩된 Agent 실행과 Tool 호출이 포함됩니다. Model 생성도 포함됩니다. 예를 들어 Agent를 호출하고 Agent가 Tool을 호출하는 Workflow는 다음을 생성합니다.

workflow_run
  └─ workflow_step (validate-input)
  └─ workflow_step (process-data)
       └─ agent_run (my-agent)
            └─ model_generation
            └─ tool_call (search)
            └─ model_generation
            └─ tool_call (summarize)
  └─ workflow_step (save-result)

대체 추출

스토리지를 사용할 수 없는 경우 파이프라인은 다음으로 대체됩니다.

• Agent: extractTrajectory(), Agent의 메시지 출력에 있는 toolInvocations에서 ToolCallStep 항목을 추출합니다. 평면적인 Tool 호출 목록을 생성합니다.
• Workflow: extractWorkflowTrajectory(), stepResults에서 WorkflowStepStep 항목을 추출합니다. 평면적인 Workflow 단계 목록을 생성합니다. 이러한 대체는 중첩된 실행이나 Tool 호출이 아닌 범위를 캡처하지 않습니다.

궤적 유형

궤적 단계에서는 stepType을 기준으로 판별되는 유니온을 사용합니다. 각 단계 유형에는 고유한 속성이 있습니다.

ToolCallStep

Agent Tool 호출을 나타냅니다.

stepType:

'tool_call'

Discriminant.

name:

string

Tool name.

toolArgs?:

Record<string, unknown>

Arguments passed to the tool.

toolResult?:

Record<string, unknown>

Tool이 반환한 결과입니다.

success?:

boolean

Whether the call succeeded.

durationMs?:

number

Execution time in milliseconds.

metadata?:

Record<string, unknown>

Arbitrary metadata.

children?:

TrajectoryStep[]

Nested sub-steps.

WorkflowStepStep

Workflow 단계 실행을 나타냅니다.

stepType:

'workflow_step'

Discriminant.

name:

string

Step identifier.

stepId?:

string

Step ID in the workflow.

status?:

string

단계 결과 상태입니다(success, failed, suspended 등).

output?:

Record<string, unknown>

Step output data.

durationMs?:

number

Execution time in milliseconds.

metadata?:

Record<string, unknown>

Arbitrary metadata.

children?:

TrajectoryStep[]

중첩된 하위 단계입니다(예: 단계 내부의 Tool 호출).

기타 단계 유형

구별된 공용체에는 다음과 같은 추가 단계 유형이 포함됩니다.

단계 유형	주요 속성
mcp_tool_call	toolArgs, toolResult, mcpServer, success
model_generation	modelId, promptTokens, completionTokens, finishReason
agent_run	agentId
workflow_run	workflowId, status
workflow_conditional	conditionCount, selectedSteps
workflow_parallel	branchCount, parallelSteps
workflow_loop	loopType, totalIterations
workflow_sleep	durationMs, sleepType
workflow_wait_event	eventName, eventReceived
processor_run	processorId

모든 단계 유형은 기본 속성인 name, durationMs, metadata 및 children을 공유합니다.

예상 단계

예상 궤적을 정의할 때 전체 TrajectoryStep 판별 유니온 대신 ExpectedStep을 사용하세요. ExpectedStep은 TrajectoryStep을 반영하는 판별 유니온입니다. stepType을 지정하면 해당 변형의 필드(예: tool_call의 toolArgs, model_generation의 modelId)가 자동 완성됩니다. 변형별 필드는 모두 선택 사항이므로 원하는 항목만 검증할 수 있습니다. 이름만으로 모든 단계와 일치시키려면 stepType을 완전히 생략하세요.

name:

string

일치시킬 단계 이름입니다(Tool 이름, Agent ID, Workflow 단계 이름 등).

stepType?:

TrajectoryStepType

단계 유형 판별자입니다. 설정하면 해당 변형의 필드에 자동 완성이 활성화됩니다. 생략하면 주어진 이름을 가진 모든 단계 유형과 일치합니다.

(variant fields)?:

varies

해당 TrajectoryStep 변형의 유형별 필드입니다. 예를 들어 tool_call에는 toolArgs와 toolResult, model_generation에는 modelId, workflow_step에는 output이 있습니다. 모두 선택 사항이며, 지정된 필드만 비교합니다.

children?:

TrajectoryExpectation

이 단계의 하위 항목에 적용할 중첩된 예상 구성입니다. 이 단계의 하위 항목을 평가할 때 상위 구성을 재정의합니다.

간단한 예상 단계

const steps: ExpectedStep[] = [
  // Match by name only (any step type)
  { name: 'search' },

  // Match by name and step type (autocomplete for tool_call fields)
  { name: 'search', stepType: 'tool_call' },

  // Match with specific toolArgs (auto-compared when present)
  { name: 'search', stepType: 'tool_call', toolArgs: { query: 'weather' } },

  // Match a model generation step by model ID
  { name: 'gpt-4o', stepType: 'model_generation', modelId: 'gpt-4o' },
]

중첩된 기대

각 예상 단계에는 자체 평가 규칙이 있는 children 구성을 포함할 수 있습니다. 이를 통해 계층 구조의 각 수준에서 서로 다른 순서 또는 비교 규칙을 설정할 수 있습니다.

const scorer = createTrajectoryScorerCode({
  defaults: {
    ordering: 'strict',
    steps: [
      { name: 'validate-input', stepType: 'workflow_step' },
      {
        name: 'research-agent',
        stepType: 'agent_run',
        children: {
          // Sub-agent can call tools in any order
          ordering: 'unordered',
          steps: [
            { name: 'search', stepType: 'tool_call' },
            { name: 'summarize', stepType: 'tool_call' },
          ],
        },
      },
      { name: 'save-result', stepType: 'workflow_step' },
    ],
  },
})

이 예에서 상위 Workflow는 단계의 엄격한 순서를 요구하지만, 중첩된 research-agent는 Tool 호출을 어떤 순서로든 허용합니다.

득점자 중에서 선택

다음과 같은 경우 코드 기반 채점기를 사용하세요.

• 결정적이고 재현 가능한 결과가 필요한 경우
• 비교할 알려진 예상 궤적이 있는 경우
• 정확한 단계 시퀀스를 검증하려는 경우
• 속도와 비용이 우선인 경우(LLM 호출 없음)
• CI/CD에서 자동화된 테스트를 실행하는 경우

다음과 같은 경우 LLM 기반 채점자를 사용하세요.

• 단계가 적절했는지에 대한 의미론적 이해가 필요한 경우
• 최적의 궤적이 미리 정해져 있지 않은 경우(작업 요구 사항을 기준으로 평가)
• 불필요하거나 중복되거나 누락된 단계를 감지하려는 경우
• 채점 결정에 대한 설명이 필요한 경우
• 프로덕션 Agent 동작을 평가하는 경우

코드 기반 궤도 정확도 채점기

@mastra/evals/scorers/prebuilt의 createTrajectoryAccuracyScorerCode() 함수는 예상 궤적과 단계 일치 여부 및 순서를 비교해 결정론적으로 채점합니다.

매개변수

expectedTrajectory?:

Trajectory | ExpectedStep[]

비교할 정적 예상 궤적입니다. 전체 Trajectory 또는 ExpectedStep 매처 배열을 허용합니다. 생략하면 채점자가 런타임에 각 데이터세트 항목의 expectedTrajectory를 읽습니다.

comparisonOptions?:

TrajectoryComparisonOptions

비교 수행 방식을 제어합니다.

boolean

boolean

이 함수는 MastraScorer 클래스의 인스턴스를 반환합니다. .run() 메서드와 해당 입력/출력에 관한 자세한 내용은 MastraScorer 참조를 확인하세요.

예상 궤적 소스

코드 기반 채점자는 다음 두 소스에서 우선순위에 따라 expectedTrajectory를 결정합니다.

1. 생성자 옵션: 채점자를 생성할 때 전달되는 정적 궤적입니다. 모든 데이터세트 항목에 사용됩니다.
2. 데이터세트 항목: runEvals 파이프라인을 통해 전달되는 데이터세트 항목의 expectedTrajectory 필드입니다. 항목마다 서로 다른 예상 궤적을 사용할 수 있습니다.

src/static-expected.ts

// Static: same expected trajectory for all items
const scorer = createTrajectoryAccuracyScorerCode({
  expectedTrajectory: {
    steps: [
      { stepType: 'tool_call', name: 'search' },
      { stepType: 'tool_call', name: 'summarize' },
    ],
  },
})

src/per-item-expected.ts

// Per-item: each dataset item has its own expectedTrajectory
const scorer = createTrajectoryAccuracyScorerCode()

await runEvals({
  target: myAgent,
  scorers: { trajectory: [scorer] },
  data: [
    {
      input: 'Search and summarize weather',
      expectedTrajectory: {
        steps: [
          { stepType: 'tool_call', name: 'search' },
          { stepType: 'tool_call', name: 'summarize' },
        ],
      },
    },
    {
      input: 'Just search for weather',
      expectedTrajectory: {
        steps: [{ stepType: 'tool_call', name: 'search' }],
      },
    },
  ],
})

평가 모드

코드 기반 채점기는 다음을 기반으로 두 가지 모드로 작동합니다.strictOrder:

엄격 모드(strictOrder: true)

정확히 일치해야 합니다. 실제 단계는 추가되거나 누락된 단계 없이 예상 단계와 같은 순서로 일치해야 합니다. 정확히 일치하면 1.0, 그렇지 않으면 0.0을 반환합니다.

편안한 모드(strictOrder: false, default)

추가 단계를 허용합니다. 예상 단계는 올바른 상대 순서로 나타나야 합니다. 점수는 일치하는 예상 단계 수를 기준으로 계산되며, 추가 또는 반복 단계에 대한 선택적인 페널티도 포함됩니다.

코드 기반 채점 세부정보

• 연속 점수: 완화 모드에서 0.0에서 1.0 사이의 값을 반환합니다. 엄격 모드의 이진수(0 또는 1)
• 결정론적: 동일한 입력은 항상 동일한 출력을 생성합니다.
• 빠른: 외부 API 호출 없음

코드 기반 채점자 결과

{
  runId: string,
  preprocessStepResult: {
    actualTrajectory: Trajectory,
    expectedTrajectory: Trajectory,
    comparison: {
      score: number,
      matchedSteps: number,
      totalExpectedSteps: number,
      totalActualSteps: number,
      missingSteps: string[],
      extraSteps: string[],
      outOfOrderSteps: string[],
      repeatedSteps: string[]
    },
    actualStepNames: string[],
    expectedStepNames: string[]
  },
  score: number
}

코드 기반 채점기의 예

엄격한 순서를 적용한 Agent 궤적

Agent가 Tool 호출의 정확한 순서를 따르는지 확인합니다.

src/example-strict-trajectory.ts

import { createTrajectoryAccuracyScorerCode } from '@mastra/evals/scorers/prebuilt'
import { runEvals } from '@mastra/core/evals'

const scorer = createTrajectoryAccuracyScorerCode({
  expectedTrajectory: {
    steps: [
      { stepType: 'tool_call', name: 'auth-tool' },
      { stepType: 'tool_call', name: 'fetch-tool' },
    ],
  },
  comparisonOptions: { strictOrder: true },
})

const result = await runEvals({
  target: myAgent,
  scorers: { trajectory: [scorer] },
  data: [{ input: 'Get my data' }],
})

console.log(result.scores.trajectory['trajectory-accuracy']) // 1.0

편안한 순서의 Agent 궤적

예상 단계가 올바른 상대 순서로 나타나는 한 추가 단계를 허용합니다.

src/example-relaxed-trajectory.ts

const scorer = createTrajectoryAccuracyScorerCode({
  expectedTrajectory: {
    steps: [
      { stepType: 'tool_call', name: 'search-tool' },
      { stepType: 'tool_call', name: 'summarize-tool' },
    ],
  },
  comparisonOptions: { strictOrder: false },
})

// Agent called search-tool → log-tool → summarize-tool
// The extra log-tool is allowed in relaxed mode
// score: 0.75 — all expected steps matched, small penalty for extra step

Workflow 궤적

Workflow의 실행 경로를 평가합니다.

src/example-workflow-trajectory.ts

import { createTrajectoryAccuracyScorerCode } from '@mastra/evals/scorers/prebuilt'
import { runEvals } from '@mastra/core/evals'

const scorer = createTrajectoryAccuracyScorerCode({
  expectedTrajectory: {
    steps: [
      { stepType: 'workflow_step', name: 'validate-input' },
      { stepType: 'workflow_step', name: 'process-data' },
      { stepType: 'workflow_step', name: 'save-result' },
    ],
  },
})

const result = await runEvals({
  target: myWorkflow,
  scorers: { trajectory: [scorer] },
  data: [{ input: { data: 'test' } }],
})

console.log(result.scores.trajectory['trajectory-accuracy'])

걸음 수 데이터 비교

단계 이름과 단계별 데이터를 검증합니다. Tool 호출에서는 toolArgs와 toolResult를 검증합니다. Workflow 단계에서는 output을 비교합니다.

src/example-trajectory-with-data.ts

const scorer = createTrajectoryAccuracyScorerCode({
  expectedTrajectory: {
    steps: [
      {
        stepType: 'tool_call',
        name: 'search-tool',
        toolArgs: { query: 'weather in NYC' },
      },
    ],
  },
})
// Data fields like toolArgs are auto-compared when present on expected steps

LLM 기반 궤도 정확도 채점기

@mastra/evals/scorers/prebuilt의 createTrajectoryAccuracyScorerLLM() 함수는 LLM을 사용하여 Agent 또는 Workflow의 궤적이 적절하고 효율적이며 완전했는지 평가합니다.

매개변수

model:

MastraModelConfig

궤적 품질 평가에 사용할 LLM Model입니다.

expectedTrajectory?:

Trajectory | ExpectedStep[]

비교할 선택적 정적 예상 궤적입니다. 전체 Trajectory 또는 ExpectedStep 매처 배열을 허용합니다. 생략하면 LLM이 작업 요구 사항만을 기준으로 궤적을 평가합니다. 런타임에 데이터세트 항목에서 가져올 수도 있습니다.

특징

LLM 기반 채점자는 다음을 제공합니다.

• 과제 인식 평가: 사용자의 요청에 따라 각 단계가 필요한지 여부를 평가합니다.
• 평가 주문: 단계가 논리적 순서대로 수행되었는지 평가합니다.
• 누락된 걸음 감지: 취했어야 하는 단계를 식별합니다.
• 중복 감지: 불필요하거나 반복되는 단계에 플래그를 지정합니다.
• 추론 생성: 채점 결정에 대해 사람이 읽을 수 있는 설명을 제공합니다.

평가과정

1. 궤적 수신: 파이프라인에서 미리 추출된 Trajectory 객체를 가져옵니다.
2. 단계 분석: LLM을 사용하여 각 단계의 필요성과 순서를 평가합니다.
3. 점수 생성: 필요성 60%, 순서 30%, 누락 페널티 10%의 가중치로 점수를 계산합니다.
4. 추론 생성: 사람이 읽을 수 있는 설명을 제공합니다.

LLM 기반 점수 세부 정보

• 분수 점수: 0.0에서 1.0 사이의 값을 반환합니다.
• 상황 인식: 사용자 의도 및 작업 요구사항을 고려합니다.
• 설명: 점수에 대한 추론 제공
• 유연한: 예상 궤적 유무에 관계없이 작동합니다.

LLM 기반 채점자 옵션

// Evaluate based on task requirements (no expected trajectory)
const openScorer = createTrajectoryAccuracyScorerLLM({
  model: { provider: 'openai', name: 'gpt-5.4' },
})

// Evaluate against a static expected trajectory
const guidedScorer = createTrajectoryAccuracyScorerLLM({
  model: { provider: 'openai', name: 'gpt-5.4' },
  expectedTrajectory: {
    steps: [
      { stepType: 'tool_call', name: 'search-tool' },
      { stepType: 'tool_call', name: 'summarize-tool' },
    ],
  },
})

LLM 기반 득점자 결과

{
  runId: string,
  preprocessStepResult: {
    actualTrajectory: Trajectory,
    actualTrajectoryFormatted: string,
    expectedTrajectoryFormatted?: string,
    hasSteps: boolean
  },
  analyzeStepResult: {
    stepEvaluations: Array<{
      stepName: string,
      wasNecessary: boolean,
      wasInOrder: boolean,
      reasoning: string
    }>,
    missingSteps?: string[],
    extraSteps?: string[],
    overallAssessment: string
  },
  score: number,
  reason: string
}

통합 궤적 득점자

@mastra/evals/scorers/prebuilt의 createTrajectoryScorerCode() 함수는 정확성, 효율성, 블랙리스트에 포함된 Tool, Tool 실패 패턴을 한 번에 검사하는 다차원 궤적 평가를 제공합니다.

매개변수

defaults?:

TrajectoryExpectation

모든 데이터세트 항목에 적용되는 기본 예상입니다. 항목별 expectedTrajectory 값이 이 기본값을 재정의합니다.

ExpectedStep[]

'strict' | 'relaxed' | 'unordered'

boolean

number

number

number

boolean

string[]

string[][]

number

weights?:

TrajectoryScoreWeights

차원별 점수를 결합할 때 사용할 사용자 지정 가중치입니다. 가중치 합이 1.0이 되도록 정규화됩니다.

number

number

number

number

채점 행동

통합 채점원은 다음 네 가지 차원을 평가합니다.

1. 정확성: steps가 구성된 경우 예상 단계와 실제 단계를 일치시킵니다. ordering 모드를 사용합니다.
2. 효율성: 단계 한도(maxSteps, maxTotalTokens, maxTotalDurationMs)와 중복 호출(noRedundantCalls)을 확인합니다.
3. 블랙리스트: 금지된 Tool 또는 시퀀스를 확인합니다. 위반 시 다른 차원과 관계없이 즉시 0.0점을 부여합니다.
4. Tool 실패: 재시도 및 대체 패턴을 감지합니다. 인수 수정 패턴도 감지합니다. 최종 점수는 활성 차원의 가중치 조합이며, 활성 차원에 맞게 정규화됩니다. 기본 가중치는 정확성 0.4, 효율성 0.3, Tool 실패 0.2, 블랙리스트 0.1이지만 weights 옵션으로 사용자 지정할 수 있습니다. 블랙리스트 위반 시 모든 결과를 재정의하여 점수가 0이 됩니다. 중첩된 평가가 있으면 최상위 점수 70%와 중첩된 평균 점수 30%를 반영합니다.

통합 득점자 결과

{
  runId: string,
  preprocessStepResult: {
    accuracy?: TrajectoryComparisonResult,
    efficiency?: TrajectoryEfficiencyResult,
    blacklist?: TrajectoryBlacklistResult,
    toolFailures?: ToolFailureAnalysisResult,
    nested?: NestedEvaluationResult[],
  },
  score: number,
  reason: string
}

품목별 기대치

각 데이터세트 항목은 자체 expectedTrajectory로 기본값을 재정의할 수 있습니다. 이를 통해 Prompt마다 예상값을 다르게 설정할 수 있습니다.

src/unified-per-item.ts

import { createTrajectoryScorerCode } from '@mastra/evals/scorers/prebuilt'
import { runEvals } from '@mastra/core/evals'

// Default blacklist applies to all items
const scorer = createTrajectoryScorerCode({
  defaults: {
    blacklistedTools: ['deleteAll'],
    maxSteps: 5,
  },
})

const result = await runEvals({
  target: myAgent,
  scorers: { trajectory: [scorer] },
  data: [
    {
      input: 'Search for weather',
      expectedTrajectory: {
        steps: [{ stepType: 'tool_call', name: 'search' }],
        maxSteps: 2,
      },
    },
    {
      input: 'Search and summarize',
      expectedTrajectory: {
        steps: [
          { stepType: 'tool_call', name: 'search' },
          { stepType: 'tool_call', name: 'summarize' },
        ],
      },
    },
  ],
})

예: 효율성 및 블랙리스트

src/unified-scorer.ts

import { createTrajectoryScorerCode } from '@mastra/evals/scorers/prebuilt'

const scorer = createTrajectoryScorerCode({
  defaults: {
    blacklistedTools: ['escalate', 'admin-override'],
    blacklistedSequences: [['escalate', 'admin-override']],
    maxSteps: 10,
    noRedundantCalls: true,
    maxRetriesPerTool: 2,
  },
  // Customize how dimensions contribute to the final score
  weights: {
    accuracy: 0.5, // prioritize step accuracy
    efficiency: 0.3,
    toolFailures: 0.1,
    blacklist: 0.1,
  },
})

궤적 스코어러 사용runEvals

궤적 채점자는 채점자 구성의 trajectory 키에 설정됩니다. runEvals 파이프라인은 궤적 추출을 자동으로 처리합니다.

Agent 궤적 평가

src/agent-trajectory-eval.ts

import { runEvals } from '@mastra/core/evals'
import { createTrajectoryAccuracyScorerCode } from '@mastra/evals/scorers/prebuilt'

const trajectoryScorer = createTrajectoryAccuracyScorerCode({
  expectedTrajectory: {
    steps: [
      { stepType: 'tool_call', name: 'search' },
      { stepType: 'tool_call', name: 'format' },
    ],
  },
})

const result = await runEvals({
  target: myAgent,
  scorers: {
    agent: [qualityScorer], // receives raw MastraDBMessage[] output
    trajectory: [trajectoryScorer], // receives pre-extracted Trajectory
  },
  data: [{ input: 'Find and format the data' }],
})

// result.scores.agent['quality'] — agent-level score
// result.scores.trajectory['trajectory-accuracy'] — trajectory score

Workflow 궤적 평가

src/workflow-trajectory-eval.ts

import { runEvals } from '@mastra/core/evals'
import { createTrajectoryAccuracyScorerCode } from '@mastra/evals/scorers/prebuilt'

const workflowTrajectoryScorer = createTrajectoryAccuracyScorerCode({
  expectedTrajectory: {
    steps: [
      { stepType: 'workflow_step', name: 'validate' },
      { stepType: 'workflow_step', name: 'process' },
      { stepType: 'workflow_step', name: 'notify' },
    ],
  },
})

const result = await runEvals({
  target: myWorkflow,
  scorers: {
    workflow: [outputScorer], // receives workflow output
    trajectory: [workflowTrajectoryScorer], // receives pre-extracted Trajectory from step results
  },
  data: [{ input: { userId: '123' } }],
})

// result.scores.workflow['output-quality'] — workflow-level score
// result.scores.trajectory['trajectory-accuracy'] — trajectory score

관련된

• runEvals 참조: 궤적을 추출하여 채점자에게 전달하는 파이프라인
• MastraScorer 참조: 기본 채점자 인터페이스
• 채점자 유틸리티: extractTrajectory와 compareTrajectories를 포함한 유틸리티 함수