跳至主要內容

ProviderHistoryCompat

ProviderHistoryCompat 處理器會處理 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 不會自動加入此處理器。需要 Provider 歷史記錄相容性規則、針對 API 錯誤的反應式復原、自訂規則，或可預期的處理器順序時，請明確加入此處理器。

建構函式參數
「建構函式參數」的直接連結

opts?:

{ additionalRules?: CompatRule[] }
Provider 歷史記錄相容性規則的設定選項。
Options

additionalRules?:

CompatRule[]
在內建規則之後執行的自訂相容性規則。規則可以改寫要送出的提示詞，或在比對到 API 錯誤後修復保存的訊息。

屬性
「屬性」的直接連結

id:

'provider-history-compat'
處理器識別碼。

name:

'Provider History Compat'
處理器顯示名稱。

processLLMRequest:

(args: ProcessLLMRequestArgs) => ProcessLLMRequestResult
在呼叫 Provider 前一刻，對轉換後的 LanguageModelV2Prompt 執行預先相容性規則。回傳的提示詞變更是暫時性的，不會保存至記憶體或訊息歷史記錄。

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 部分，避免序列化為不支援的 reasoning_content 欄位。
anthropic-strip-foreign-reasoning-contentAnthropic預先改寫提示詞從要送出的提示詞移除非 Anthropic 的 assistant reasoning 部分。保留 Anthropic 原生的思考歷史記錄。

Mastra 將訊息轉換為模型提示詞格式後，會透過 processLLMRequest 執行預先規則，接著才將提示詞傳送至 Provider。這些改寫只會影響目前的 Provider 呼叫。

Provider 拒絕請求後，會透過 processAPIError 執行反應式規則。這些規則可以更新保存的 messageList 並要求重試。

CompatRule
「compatrule」的直接連結

CompatRule 定義一項 Provider 歷史記錄相容性修正：

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],
    }),
  ],
})

若要執行不應儲存至記憶體的 Provider 專屬改寫，請使用 applyToPrompt。若 Provider 拒絕保存的訊息歷史記錄，而且修復後的歷史記錄應在後續對話輪次重複使用，請搭配 errorPatterns 使用 fix。

On this page