> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt # 궤도 정확도 채점자 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는 다음을 생성합니다. ```text 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`): Arguments passed to the tool. **toolResult** (`Record`): Tool이 반환한 결과입니다. **success** (`boolean`): Whether the call succeeded. **durationMs** (`number`): Execution time in milliseconds. **metadata** (`Record`): 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`): Step output data. **durationMs** (`number`): Execution time in milliseconds. **metadata** (`Record`): 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`): 이 단계의 하위 항목에 적용할 중첩된 예상 구성입니다. 이 단계의 하위 항목을 평가할 때 상위 구성을 재정의합니다. ### 간단한 예상 단계 ```typescript 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` 구성을 포함할 수 있습니다. 이를 통해 계층 구조의 각 수준에서 서로 다른 순서 또는 비교 규칙을 설정할 수 있습니다. ```typescript 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`): 비교 수행 방식을 제어합니다. 이 함수는 MastraScorer 클래스의 인스턴스를 반환합니다. `.run()` 메서드와 해당 입력/출력에 관한 자세한 내용은 [MastraScorer 참조](https://mastra.zisheng.pro/ko/reference/evals/mastra-scorer)를 확인하세요. ### 예상 궤적 소스 코드 기반 채점자는 다음 두 소스에서 우선순위에 따라 `expectedTrajectory`를 결정합니다. 1. **생성자 옵션**: 채점자를 생성할 때 전달되는 정적 궤적입니다. 모든 데이터세트 항목에 사용됩니다. 2. **데이터세트 항목**: `runEvals` 파이프라인을 통해 전달되는 데이터세트 항목의 `expectedTrajectory` 필드입니다. 항목마다 서로 다른 예상 궤적을 사용할 수 있습니다. ```typescript // Static: same expected trajectory for all items const scorer = createTrajectoryAccuracyScorerCode({ expectedTrajectory: { steps: [ { stepType: 'tool_call', name: 'search' }, { stepType: 'tool_call', name: 'summarize' }, ], }, }) ``` ```typescript // 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 호출 없음 ### 코드 기반 채점자 결과 ```typescript { 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 호출의 정확한 순서를 따르는지 확인합니다. ```typescript 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 궤적 예상 단계가 올바른 상대 순서로 나타나는 한 추가 단계를 허용합니다. ```typescript 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의 실행 경로를 평가합니다. ```typescript 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`을 비교합니다. ```typescript 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 기반 채점자 옵션 ```typescript // 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 기반 득점자 결과 ```typescript { 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 값이 이 기본값을 재정의합니다. **weights** (`TrajectoryScoreWeights`): 차원별 점수를 결합할 때 사용할 사용자 지정 가중치입니다. 가중치 합이 1.0이 되도록 정규화됩니다. ### 채점 행동 통합 채점원은 다음 네 가지 차원을 평가합니다. 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%를 반영합니다. ### 통합 득점자 결과 ```typescript { runId: string, preprocessStepResult: { accuracy?: TrajectoryComparisonResult, efficiency?: TrajectoryEfficiencyResult, blacklist?: TrajectoryBlacklistResult, toolFailures?: ToolFailureAnalysisResult, nested?: NestedEvaluationResult[], }, score: number, reason: string } ``` ### 품목별 기대치 각 데이터세트 항목은 자체 `expectedTrajectory`로 기본값을 재정의할 수 있습니다. 이를 통해 Prompt마다 예상값을 다르게 설정할 수 있습니다. ```typescript 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' }, ], }, }, ], }) ``` ### 예: 효율성 및 블랙리스트 ```typescript 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 궤적 평가 ```typescript 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 궤적 평가 ```typescript 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 참조](https://mastra.zisheng.pro/ko/reference/evals/run-evals): 궤적을 추출하여 채점자에게 전달하는 파이프라인 - [MastraScorer 참조](https://mastra.zisheng.pro/ko/reference/evals/mastra-scorer): 기본 채점자 인터페이스 - [채점자 유틸리티](https://mastra.zisheng.pro/ko/reference/evals/scorer-utils): `extractTrajectory`와 `compareTrajectories`를 포함한 유틸리티 함수