ProviderHistoryCompat

Le Processor ProviderHistoryCompat gère les incompatibilités de l’historique propres aux Providers. Il peut réécrire le prompt sortant du modèle de langage avant l’appel d’un Provider, ou réagir aux erreurs de l’API et effectuer une nouvelle tentative avec un historique de messages corrigé.

Utilisez-le lorsqu’un Agent peut passer d’un Provider de modèles à un autre ou réutiliser un historique de messages entre plusieurs Providers. Il gère également les Providers qui rejettent les champs émis par un autre Provider.

Exemple d’utilisation

Ajoutez ProviderHistoryCompat à inputProcessors lorsque vous souhaitez mettre toutes les règles de compatibilité intégrées à la disposition d’un Agent :

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

Les Agents Mastra n’ajoutent pas automatiquement ce Processor. Ajoutez-le explicitement lorsque vous avez besoin de règles de compatibilité de l’historique des Providers, d’une récupération réactive après une erreur de l’API, de règles personnalisées ou d’un ordre prévisible des Processors.

Paramètres du constructeur

opts?:

{ additionalRules?: CompatRule[] }

Options de configuration des règles de compatibilité de l’historique des Providers.

Options

additionalRules?:

CompatRule[]

Règles de compatibilité personnalisées à exécuter après les règles intégrées. Elles peuvent réécrire le prompt sortant ou corriger les messages persistants après avoir identifié une erreur de l’API correspondante.

Propriétés

id:

'provider-history-compat'

Identifiant du Processor.

name:

'Provider History Compat'

Nom d’affichage du Processor.

processLLMRequest:

(args: ProcessLLMRequestArgs) => ProcessLLMRequestResult

Exécute des règles de compatibilité préventives sur le LanguageModelV2Prompt converti juste avant l’appel du Provider. Les modifications du prompt renvoyé sont temporaires et ne sont conservées ni dans la mémoire ni dans l’historique des messages.

processAPIError:

(args: ProcessAPIErrorArgs) => Promise<ProcessAPIErrorResult | void>

Exécute des règles de compatibilité réactives lorsqu’un Provider rejette la requête. Les règles correspondantes peuvent modifier la liste des messages et renvoyer retry: true lors de la première nouvelle tentative.

Règles intégrées

ProviderHistoryCompat comprend les règles de compatibilité intégrées suivantes :

Règle	Provider	Moment	Comportement
anthropic-tool-id-format	Anthropic	Récupération réactive après une erreur de l’API	Réécrit les ID d’appel de Tool qui contiennent des caractères extérieurs à [a-zA-Z0-9_-], puis effectue une nouvelle tentative.
cerebras-strip-reasoning-content	Cerebras	Réécriture préventive du prompt	Supprime les parties reasoning de l’assistant dans le prompt sortant afin qu’elles ne soient pas sérialisées sous forme de champs reasoning_content non pris en charge.
anthropic-strip-foreign-reasoning-content	Anthropic	Réécriture préventive du prompt	Supprime du prompt sortant les parties reasoning de l’assistant qui ne proviennent pas d’Anthropic. L’historique de réflexion natif d’Anthropic est conservé.

Les règles préventives s’exécutent par l’intermédiaire de processLLMRequest, après que Mastra a converti les messages au format de prompt du modèle et avant l’envoi du prompt au Provider. Ces réécritures concernent uniquement l’appel actuel du Provider.

Les règles réactives s’exécutent par l’intermédiaire de processAPIError après le rejet d’un Provider. Elles peuvent mettre à jour la messageList persistante et demander une nouvelle tentative.

CompatRule

Une CompatRule définit un correctif de compatibilité de l’historique d’un 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

Identifiant lisible de la règle pour les logs et le débogage.

errorPatterns?:

RegExp[]

Motifs comparés aux messages d’erreur et aux corps de réponse de l’API du Provider. Requis pour les règles réactives qui implémentent fix.

fix?:

(messages: MastraDBMessage[]) => boolean

Correctif réactif qui modifie les messages persistants de la base de données après une erreur correspondante de l’API. Renvoie true lorsque la règle a modifié les messages et que la requête doit être retentée.

applyToPrompt?:

(args: { prompt: LanguageModelV2Prompt; model: unknown }) => LanguageModelV2Prompt | undefined

Correctif préventif qui réécrit le prompt sortant pour l’appel actuel du Provider. Renvoie undefined lorsqu’aucune modification du prompt n’est nécessaire.

Règles personnalisées

Transmettez les règles personnalisées au moyen de additionalRules. Elles s’exécutent après les règles intégrées :

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

Utilisez applyToPrompt pour les réécritures propres au Provider qui ne doivent pas être enregistrées dans la mémoire. Utilisez fix avec errorPatterns lorsque le Provider rejette un historique de messages persistant et que l’historique corrigé doit être réutilisé lors des tours suivants.

Voir aussi

• Interface Processor
• Processors
• PrefillErrorHandler