> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# ProviderHistoryCompat

`ProviderHistoryCompat` 處理器會處理 Provider 專屬的歷史記錄不相容問題。它可以在呼叫 Provider 前改寫要送出的語言模型提示詞，也可以在發生 API 錯誤時作出反應，以修復後的訊息歷史記錄重試。

當 Agent 可能在不同模型 Provider 之間切換，或跨 Provider 重複使用訊息歷史記錄時，可使用此處理器。它也能處理 Provider 拒絕其他 Provider 所產生欄位的情況。

## 使用範例

如果要讓 Agent 使用所有內建相容性規則，請將 `ProviderHistoryCompat` 加入 `inputProcessors`：

```typescript
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 歷史記錄相容性規則的設定選項。

**opts.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-format`                  | Anthropic | 反應式 API 錯誤復原 | 改寫包含 `[a-zA-Z0-9_-]` 以外字元的 Tool 呼叫 ID，並重試請求。                             |
| `cerebras-strip-reasoning-content`          | Cerebras  | 預先改寫提示詞      | 從要送出的提示詞移除 assistant `reasoning` 部分，避免序列化為不支援的 `reasoning_content` 欄位。   |
| `anthropic-strip-foreign-reasoning-content` | Anthropic | 預先改寫提示詞      | 從要送出的提示詞移除非 Anthropic 的 assistant `reasoning` 部分。保留 Anthropic 原生的思考歷史記錄。 |

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

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

## `CompatRule`

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

```typescript
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` 傳入自訂規則。自訂規則會在內建規則之後執行：

```typescript
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`。

## 相關資源

- [處理器介面](https://mastra.zisheng.pro/zh-TW/reference/processors/processor-interface)
- [處理器](https://mastra.zisheng.pro/zh-TW/docs/agents/processors)
- [PrefillErrorHandler](https://mastra.zisheng.pro/zh-TW/reference/processors/prefill-error-handler)