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

# ProviderHistoryCompat

The `ProviderHistoryCompat` processor handles provider-specific history incompatibilities. It can rewrite the outbound language model prompt before a provider call, or react to API errors and retry with repaired message history.

Use it when an agent may switch between model providers or reuse message history across providers. It also handles providers that reject fields emitted by another provider.

## Usage example

Add `ProviderHistoryCompat` to `inputProcessors` when you want all built-in compatibility rules available for an agent:

```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 agents don't add this processor automatically. Add it explicitly when you need provider history compatibility rules, reactive API error recovery, custom rules, or predictable processor ordering.

## Constructor parameters

**opts** (`{ additionalRules?: CompatRule[] }`): Configuration options for provider history compatibility rules.

**opts.additionalRules** (`CompatRule[]`): Custom compatibility rules to run after the built-in rules. Rules can rewrite the outbound prompt or repair persisted messages after matching an API error.

## Properties

**id** (`'provider-history-compat'`): Processor identifier.

**name** (`'Provider History Compat'`): Processor display name.

**processLLMRequest** (`(args: ProcessLLMRequestArgs) => ProcessLLMRequestResult`): Runs preemptive compatibility rules against the converted LanguageModelV2Prompt immediately before the provider call. Returned prompt changes are transient and are not persisted to memory or message history.

**processAPIError** (`(args: ProcessAPIErrorArgs) => Promise<ProcessAPIErrorResult | void>`): Runs reactive compatibility rules when a provider rejects the request. Matching rules can mutate the message list and return retry: true on the first retry attempt.

## Built-in rules

`ProviderHistoryCompat` includes these built-in compatibility rules:

| Rule                                        | Provider  | Timing                      | Behavior                                                                                                                          |
| ------------------------------------------- | --------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `anthropic-tool-id-format`                  | Anthropic | Reactive API error recovery | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` and retries the request.                                   |
| `cerebras-strip-reasoning-content`          | Cerebras  | Preemptive prompt rewrite   | Removes assistant `reasoning` parts from the outbound prompt so they're not serialized as unsupported `reasoning_content` fields. |
| `anthropic-strip-foreign-reasoning-content` | Anthropic | Preemptive prompt rewrite   | Removes non-Anthropic assistant `reasoning` parts from the outbound prompt. Anthropic-native thinking history is preserved.       |

Preemptive rules run through `processLLMRequest` after Mastra converts messages to the model prompt format and before the prompt is sent to the provider. These rewrites affect only the current provider call.

Reactive rules run through `processAPIError` after a provider rejection. They can update the persisted `messageList` and request a retry.

## `CompatRule`

A `CompatRule` defines one provider history compatibility fix:

```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`): Human-readable rule identifier for logs and debugging.

**errorPatterns** (`RegExp[]`): Patterns matched against provider API error messages and response bodies. Required for reactive rules that implement fix.

**fix** (`(messages: MastraDBMessage[]) => boolean`): Reactive fix that mutates persisted database messages after a matching API error. Return true when the rule changed messages and the request should retry.

**applyToPrompt** (`(args: { prompt: LanguageModelV2Prompt; model: unknown }) => LanguageModelV2Prompt | undefined`): Preemptive fix that rewrites the outbound prompt for the current provider call. Return undefined when no prompt change is needed.

## Custom rules

Pass custom rules through `additionalRules`. Custom rules run after the built-in rules:

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

Use `applyToPrompt` for provider-specific rewrites that shouldn't be saved to memory. Use `fix` with `errorPatterns` when the provider rejects persisted message history and the repaired history should be reused on future turns.

## Related

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