Eval と Scorer

評価 API は、新しい Scorer システムに統合され、命名規則と設定要件も更新されました。

変更

getScorers から listScorers へ

getScorers() メソッドは listScorers() に改名されました。この変更は、複数の値を取得する getter メソッドに list プレフィックスを使用する API 全体の命名規則に合わせたものです。

移行するには、getScorers() の呼び出しをすべて listScorers() に置き換えます。

- const scorers = mastra.getScorers();
+ const scorers = mastra.listScorers();

Codemod

Mastra の codemod CLI を使用すると、コードを自動更新できます。

npx @mastra/codemod@latest v1/mastra-plural-apis .

runExperiment から runEvals へ

runExperiment() 関数は、評価を実行することが分かるよう runEvals() に改名されました。

移行するには、関数呼び出しを runExperiment から runEvals に更新します。

- import { createScorer, runExperiment } from '@mastra/core/evals';
+ import { createScorer, runEvals } from '@mastra/core/evals';
  import { myAgent } from './agents/my-agent';

  const scorer = createScorer({
    id: 'helpfulness-scorer',
    // ...
  });

- const result = await runExperiment({ target: myAgent, scorers: [scorer], data: inputs });
+ const result = await runEvals({ target: myAgent, scorers: [scorer], data: inputs });

Codemod

Mastra の codemod CLI を使用すると、コードを自動更新できます。

npx @mastra/codemod@latest v1/evals-run-experiment .

getScorerByName から getScorerById へ

getScorerByName() メソッドは getScorerById() に改名されました。Scorer では、name の代わりに id フィールドが必須になりました。この変更は、エンティティの識別に id を使用する API 全体のパターンに合わせたものです。

移行するには、メソッド呼び出しと Scorer 設定を更新し、name の代わりに id を使用します。

  const scorer = createScorer({
-   name: 'helpfulness-scorer',
+   id: 'helpfulness-scorer',
    // ...
  });
  
- const scorer = mastra.getScorerByName('helpfulness-scorer');
+ const scorer = mastra.getScorerById('helpfulness-scorer');

Codemod

Mastra の codemod CLI を使用すると、コードを自動更新できます。

npx @mastra/codemod@latest v1/evals-scorer-by-name .

Scorer 設定の name から id へ

Scorer では、name の代わりに id フィールドが必須になりました。name フィールドは任意になりました。この変更により、他の Mastra エンティティとの一貫性が保たれます。

移行するには、Scorer の定義を更新し、id を必須フィールドとして使用します。

  const scorer = createScorer({
-   name: 'helpfulness-scorer',
+   id: 'helpfulness-scorer',
+   name: 'Helpfulness Scorer', // optional
    // ...
  });

Score の Storage API を listScoresBy* パターンへ変更

Score の Storage API は、listScoresBy* パターンに従うよう改名されました。この変更は、Storage API 全体の命名規則に合わせたものです。

移行するには、Score のクエリメソッドを新しい命名パターンに更新します。

- const scores = await storage.getScores({ scorerName: 'helpfulness-scorer' });
+ const scores = await storage.listScoresByScorerId({
+   scorerId: 'helpfulness-scorer',
+ });

// Also available:
// - listScoresByRunId
// - listScoresByEntityId  
// - listScoresBySpan

ビルトイン Scorer の import を scorers/prebuilt パスへ変更

ビルトイン Scorer の import は、個別の scorers/llm パスと scorers/code パスではなく、単一の @mastra/evals/scorers/prebuilt パスに集約されました。この変更により import が簡素化され、ビルトイン Scorer の構成が明確になります。

移行するには、import 文を新しい scorers/prebuilt パスを使用するよう更新します。

  // LLM-based scorers
- import { createHallucinationScorer } from '@mastra/evals/scorers/llm';
- import { createFaithfulnessScorer } from '@mastra/evals/scorers/llm';
+ import { createHallucinationScorer } from '@mastra/evals/scorers/prebuilt';
+ import { createFaithfulnessScorer } from '@mastra/evals/scorers/prebuilt';

  // Code-based scorers
- import { createContentSimilarityScorer } from '@mastra/evals/scorers/code';
- import { createCompletenessScorer } from '@mastra/evals/scorers/code';
+ import { createContentSimilarityScorer } from '@mastra/evals/scorers/prebuilt';
+ import { createCompletenessScorer } from '@mastra/evals/scorers/prebuilt';

Codemod

Mastra の codemod CLI を使用すると、コードを自動更新できます。

npx @mastra/codemod@latest v1/evals-prebuilt-imports .

Scorer のメッセージ型を UIMessage から MastraDBMessage へ変更

Scorer の入力型と出力型は、UIMessage ではなく MastraDBMessage[] を使用するようになりました。この変更により、Framework 全体で一貫してデータベースに永続化されるメッセージ形式を使用します。

移行するには、Scorer の実装で MastraDBMessage 型を使用し、ネストされた content 構造からメッセージ内容へアクセスするよう更新します。

  import type {
    ScorerRunInputForAgent,
    ScorerRunOutputForAgent
  } from '@mastra/core/evals';

- // ScorerRunInputForAgent uses UIMessage[]
- const inputMessages: UIMessage[] = run.input.inputMessages;
+ // ScorerRunInputForAgent now uses MastraDBMessage[]
+ import type { MastraDBMessage } from '@mastra/core/agent';
+ const inputMessages: MastraDBMessage[] = run.input.inputMessages;

メッセージ内容をネストされた構造へ変更

Tool の呼び出しとテキスト内容は、メッセージのフラットなプロパティではなく、ネストされた content オブジェクトからアクセスするようになりました。このネスト構造は、データベースメッセージ形式とその型に対応しています。

移行するには、Tool の呼び出しには message.content.toolInvocations、テキストには message.content.content でアクセスするか、getTextContentFromMastraDBMessage() ヘルパーを使用します。

+ import { getTextContentFromMastraDBMessage } from '@mastra/evals';
+
  const run = await scorer.run(testRun);

  // Accessing text content
- const text = message.content;
+ const text = getTextContentFromMastraDBMessage(message);
+ // or directly: message.content.content

  // Accessing tool invocations
- const toolCalls = message.toolInvocations;
+ const toolCalls = message.content.toolInvocations;

削除

レガシー Eval コード

レガシー Eval コードが @mastra/core から削除されました。これには、レガシーな評価指標、Scorer/Judge モジュール、Hook ベースの自動評価コードが含まれます。この変更により、古い評価手法を削除してコードベースを簡素化しています。

移行するには、@mastra/core/evals または @mastra/evals の新しい Eval/Scorer API を使用します。

- // Legacy evals APIs
+ import { createScorer, runEvals } from '@mastra/core/evals';
+ 
+ const scorer = createScorer({
+   id: 'my-scorer',
+   // Use new scorer API
+ });

Agent の TMetrics ジェネリックパラメーター

TMetrics ジェネリックパラメーターが AgentConfig と Agent コンストラクターから削除されました。Metric/Scorer は Agent の型システムの一部ではなく、Scorer API を使用して設定するようになりました。この変更により、Agent の型シグネチャが簡素化されます。

移行するには、TMetrics ジェネリックパラメーターを削除し、Scorer API を使用して Scorer を設定します。

- const agent = new Agent<AgentId, Tools, Metrics>({
+ const agent = new Agent<AgentId, Tools>({
    // ...
  });

Eval 関連の型 export

DeprecatedOutputOptions、Metric、Processor オプション型など、複数の Eval 関連の型 export が削除されました。これらの型は内部専用になったか、新しい Scorer API に置き換えられました。この変更により、API サーフェスが縮小されます。

移行するには、削除された型への参照を削除し、新しい Scorer API を使用します。

- import type {
-   DeprecatedOutputOptions,
-   Metric,
-   LanguageDetectorOptions,
-   ModerationOptions,
- } from '@mastra/core';
+ // Use new scorers API types
+ import type { Scorer } from '@mastra/core/evals';

createUIMessage テストヘルパー

createUIMessage() テストヘルパーが削除され、createTestMessage() に置き換えられました。新しいヘルパーは、ネストされた content 構造を持つ MastraDBMessage オブジェクトを作成し、任意の Tool 呼び出しにも対応します。この変更により、テストユーティリティが新しいメッセージ形式と一致します。

移行するには、createUIMessage() の呼び出しを createTestMessage() に置き換え、MastraDBMessage 型を使用するよう更新します。

- import { createUIMessage } from '@mastra/evals';
+ import { createTestMessage } from '@mastra/evals';

  // Creating test messages
- const message = createUIMessage({
-   id: 'test-1',
+ const message = createTestMessage({
+   id: 'test-1', // optional, defaults to 'test-message'
    role: 'user',
    content: 'Hello',
    toolInvocations: [], // optional
  });