メインコンテンツへ移動

ProviderHistoryCompat

ProviderHistoryCompat Processor は、Provider 固有の履歴非互換性を処理します。Provider を呼び出す前に送信する言語モデルのプロンプトを書き換えたり、API エラーに応じてメッセージ履歴を修復して再試行したりできます。

Agent がモデル Provider を切り替える可能性がある場合や、複数の Provider 間でメッセージ履歴を再利用する場合に使用します。別の Provider が出力したフィールドを拒否する Provider にも対応します。

使用例
使用例への直接リンク

Agent ですべての組み込み互換性ルールを利用するには、ProviderHistoryCompat を inputProcessors に追加します。

src/mastra/agents/my-agent.ts
import { Agent } from '@mastra/core/agent'
import { ProviderHistoryCompat } from '@mastra/core/processors'

export const agent = new Agent({
  id: 'my-agent',
  name: 'my-agent',
  instructions: 'You are a helpful assistant.',
  model: 'anthropic/claude-sonnet-4-5',
  inputProcessors: [new ProviderHistoryCompat()],
})

Mastra Agent は、この Processor を自動では追加しません。Provider 履歴の互換性ルール、リアクティブな API エラー復旧、カスタムルール、予測可能な Processor の実行順序が必要な場合は、明示的に追加してください。

コンストラクターパラメーター
コンストラクターパラメーターへの直接リンク

opts?:

{ additionalRules?: CompatRule[] }
Provider 履歴の互換性ルールに関する設定オプション。
Options

additionalRules?:

CompatRule[]
組み込みルールの後に実行するカスタム互換性ルール。送信プロンプトを書き換えたり、API エラーとの一致後に永続化済みメッセージを修復したりできます。

プロパティ
プロパティへの直接リンク

id:

'provider-history-compat'
Processor の識別子。

name:

'Provider History Compat'
Processor の表示名。

processLLMRequest:

(args: ProcessLLMRequestArgs) => ProcessLLMRequestResult
Provider の呼び出し直前に、変換済みの LanguageModelV2Prompt に対して事前互換性ルールを実行します。返されたプロンプトの変更は一時的なもので、Memory やメッセージ履歴には永続化されません。

processAPIError:

(args: ProcessAPIErrorArgs) => Promise<ProcessAPIErrorResult | void>
Provider がリクエストを拒否したときに、リアクティブな互換性ルールを実行します。一致したルールはメッセージリストを変更し、最初の再試行時に retry: true を返せます。

組み込みルール
組み込みルールへの直接リンク

ProviderHistoryCompat には、次の互換性ルールが組み込まれています。

ルールProviderタイミング動作
anthropic-tool-id-formatAnthropicリアクティブな API エラー復旧[a-zA-Z0-9_-] 以外の文字を含む Tool 呼び出し ID を書き換え、リクエストを再試行します。
cerebras-strip-reasoning-contentCerebras事前プロンプト書き換え送信プロンプトから Assistant の reasoning part を削除し、未対応の reasoning_content フィールドとしてシリアライズされないようにします。
anthropic-strip-foreign-reasoning-contentAnthropic事前プロンプト書き換え送信プロンプトから Anthropic 以外の Assistant の reasoning part を削除します。Anthropic ネイティブの思考履歴は保持されます。

事前ルールは、Mastra がメッセージをモデルのプロンプト形式に変換した後、プロンプトを Provider に送信する前に processLLMRequest を通じて実行されます。この書き換えは現在の Provider 呼び出しだけに影響します。

リアクティブルールは、Provider がリクエストを拒否した後に processAPIError を通じて実行されます。永続化される messageList を更新し、再試行を要求できます。

CompatRule
compatruleへの直接リンク

CompatRule は、Provider 履歴の互換性修正を1つ定義します。

import type { CompatRule } from '@mastra/core/processors'

const removeUnsupportedPromptParts: CompatRule = {
  name: 'remove-unsupported-prompt-parts',
  applyToPrompt({ prompt, model }) {
    // Return a modified LanguageModelV2Prompt, or undefined to leave it unchanged.
    return undefined
  },
}

name:

string
ログとデバッグに使用する、人が読めるルール識別子。

errorPatterns?:

RegExp[]
Provider の API エラーメッセージおよびレスポンス本文と照合するパターン。fix を実装するリアクティブルールでは必須です。

fix?:

(messages: MastraDBMessage[]) => boolean
一致する API エラーの発生後に、永続化済みのデータベースメッセージを変更するリアクティブな修正。ルールがメッセージを変更し、リクエストを再試行する必要がある場合は true を返します。

applyToPrompt?:

(args: { prompt: LanguageModelV2Prompt; model: unknown }) => LanguageModelV2Prompt | undefined
現在の Provider 呼び出しで送信するプロンプトを書き換える事前修正。プロンプトを変更する必要がない場合は undefined を返します。

カスタムルール
カスタムルールへの直接リンク

カスタムルールは additionalRules で渡します。カスタムルールは組み込みルールの後に実行されます。

src/mastra/agents/custom-provider-compat.ts
import { Agent } from '@mastra/core/agent'
import { ProviderHistoryCompat, type CompatRule } from '@mastra/core/processors'

const stripUnsupportedAssistantMetadata: CompatRule = {
  name: 'strip-unsupported-assistant-metadata',
  applyToPrompt({ prompt, model }) {
    if (typeof model !== 'string' || !model.startsWith('example-provider/')) {
      return undefined
    }

    let changed = false
    const nextPrompt = prompt.map(message => {
      if (message.role !== 'assistant' || typeof message.content === 'string') {
        return message
      }

      const nextContent = message.content.map(part => {
        if (!('providerOptions' in part)) return part
        changed = true
        const { providerOptions: _providerOptions, ...rest } = part
        return rest
      })

      return { ...message, content: nextContent }
    })

    return changed ? nextPrompt : undefined
  },
}

export const agent = new Agent({
  id: 'custom-provider-agent',
  name: 'custom-provider-agent',
  instructions: 'You are a helpful assistant.',
  model: 'example-provider/model',
  inputProcessors: [
    new ProviderHistoryCompat({
      additionalRules: [stripUnsupportedAssistantMetadata],
    }),
  ],
})

Memory に保存すべきでない Provider 固有の書き換えには applyToPrompt を使用します。Provider が永続化済みのメッセージ履歴を拒否し、修復した履歴を今後のターンでも再利用する必要がある場合は、errorPatterns とともに fix を使用します。

On this page