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

# ProviderHistoryCompat

`ProviderHistoryCompat` Processor 用于处理 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 不会自动添加此 Processor。当你需要 Provider 历史记录兼容性规则、响应式 API 错误恢复、自定义规则或可预测的 Processor 顺序时，请显式添加它。

## 构造函数参数

**opts** (`{ additionalRules?: CompatRule[] }`): Provider 历史记录兼容性规则的配置选项。

**opts.additionalRules** (`CompatRule[]`): 在内置规则之后运行的自定义兼容性规则。规则可以重写发出的提示词，也可以在匹配 API 错误后修复已持久化的消息。

## 属性

**id** (`'provider-history-compat'`): Processor 标识符。

**name** (`'Provider History Compat'`): Processor 显示名称。

**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 将消息转换为模型提示词格式之后、提示词发送给 Provider 之前，通过 `processLLMRequest` 运行。这些重写仅影响当前的 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 拒绝已持久化的消息历史记录，且修复后的历史记录应在后续轮次中重用时，请结合使用 `fix` 和 `errorPatterns`。

## 相关内容

- [Processor 接口](https://mastra.zisheng.pro/reference/processors/processor-interface)
- [Processors](https://mastra.zisheng.pro/docs/agents/processors)
- [PrefillErrorHandler](https://mastra.zisheng.pro/reference/processors/prefill-error-handler)