跳到主要内容

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 运行预防性兼容规则。返回的提示词更改是临时的，不会持久化到内存或消息历史记录中。

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

On this page