StreamErrorRetryProcessor

StreamErrorRetryProcessor est un Processor d'erreurs qui relance les appels après des défaillances temporaires de l'API du LLM et du flux. Il intègre la détection des erreurs de flux OpenAI Responses et accepte des fonctions de correspondance supplémentaires pour les structures d'erreur propres aux autres Providers.

Le Processor n'est pas activé par défaut dans le cœur de Mastra. Ajoutez-le à errorProcessors pour les Agents qui ont besoin d'un nombre limité de nouvelles tentatives.

Exemple d'utilisation

Ajoutez StreamErrorRetryProcessor à errorProcessors :

src/mastra/agents/openai-agent.ts

import { Agent } from '@mastra/core/agent'
import { StreamErrorRetryProcessor } from '@mastra/core/processors'

export const agent = new Agent({
  id: 'openai-agent',
  name: 'openai-agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5',
  errorProcessors: [new StreamErrorRetryProcessor()],
})

Fonctionnement

Le Processor recherche les éléments suivants dans l'erreur et sa chaîne de causes :

• Métadonnées de nouvelle tentative du Provider : isRetryable === true
• Détection intégrée des erreurs de flux OpenAI Responses
• Résultats des fonctions de correspondance : toute fonction configurée qui renvoie true

Lorsque l'erreur autorise une nouvelle tentative, le Processor renvoie { retry: true }. Il ne modifie pas les messages.

Lorsque delayMs est défini, le Processor attend avant de signaler une nouvelle tentative. Cette option est utile pour les erreurs réseau temporaires telles que ECONNRESET, pour lesquelles une nouvelle tentative immédiate risque d'échouer à nouveau. Le délai peut être un nombre fixe de millisecondes ou une fonction évaluée avec les arguments de l'erreur, par exemple pour mettre en œuvre un délai exponentiel.

Limites des nouvelles tentatives

La valeur par défaut de maxRetries est 1 et limite les demandes de nouvelle tentative de ce Processor. L'Agent limite également les nouvelles tentatives des Processors au moyen de maxProcessorRetries. Lorsque des Processors d'erreurs sont configurés sans limite pour l'Agent, la limite de l'environnement d'exécution est fixée à 10.

Définissez explicitement les deux valeurs sur la même limite lorsque vous avez besoin d'un budget unique de nouvelles tentatives. Conservez le paramètre maxRetries du modèle à 0 lors de cet appel afin d'éviter de multiplier les tentatives du Provider.

Gestion de Retry-After

Pour les erreurs autorisant une nouvelle tentative et dotées d'un en-tête de réponse Retry-After, le Processor lit les valeurs delta-seconds et HTTP-date sans tenir compte de la casse dans la chaîne de causes de l'erreur. Il attend le plus long des deux délais entre delayMs et le délai limité du serveur.

La valeur par défaut de maxRetryAfterMs est 30_000. Elle limite uniquement le délai d'attente fourni par le Provider. Une valeur delayMs explicite plus longue reste inchangée. Les en-têtes non valides ou expirés sont ignorés.

Nouvelle tentative après des erreurs inconnues

Définissez retryUnknownErrors pour relancer les erreurs qui ne correspondent ni aux métadonnées du Provider, ni à la fonction de correspondance OpenAI intégrée, ni à une fonction de correspondance personnalisée. Les nouvelles tentatives après une erreur inconnue utilisent les valeurs maxRetries et delayMs du Processor. Les échecs d'autorisation connus, notamment les réponses HTTP 401 et 403, ne font pas l'objet d'une nouvelle tentative :

src/mastra/agents/resilient-agent.ts

import { Agent } from '@mastra/core/agent'
import { StreamErrorRetryProcessor } from '@mastra/core/processors'

export const agent = new Agent({
  id: 'resilient-agent',
  name: 'Resilient agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5',
  errorProcessors: [
    new StreamErrorRetryProcessor({
      retryUnknownErrors: true,
      maxRetries: 2,
      delayMs: 3000,
    }),
  ],
})

Les politiques des fonctions de correspondance précises restent prioritaires sur les valeurs propres aux erreurs inconnues. La valeur par défaut de cette option est false ; les erreurs inconnues ne font donc pas l'objet d'une nouvelle tentative, sauf si vous l'activez.

Retarder les nouvelles tentatives

Utilisez delayMs avec une fonction de correspondance personnalisée afin d'attendre avant de relancer une connexion après une réinitialisation temporaire du réseau :

src/mastra/agents/resilient-agent.ts

import { Agent } from '@mastra/core/agent'
import { StreamErrorRetryProcessor } from '@mastra/core/processors'

const isECONNRESET = (error: unknown) => {
  if (!error || typeof error !== 'object') return false
  const code = (error as { code?: unknown }).code
  if (typeof code === 'string' && code.toUpperCase() === 'ECONNRESET') return true
  const message = error instanceof Error ? error.message : undefined
  return typeof message === 'string' && /econnreset|socket hang up/i.test(message)
}

export const agent = new Agent({
  id: 'resilient-agent',
  name: 'resilient-agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5',
  errorProcessors: [
    new StreamErrorRetryProcessor({
      maxRetries: 2,
      delayMs: ({ retryCount }) => Math.min(1000 * 2 ** retryCount, 30000),
      matchers: [isECONNRESET],
    }),
  ],
})

Fonction de correspondance OpenAI Responses par défaut

isRetryableOpenAIResponsesStreamError détecte les segments d'erreur de flux OpenAI Responses dont le champ vaut type: 'error' ou type: 'response.failed'. Il relance les codes d'erreur OpenAI temporaires connus et, à défaut, les erreurs qui contiennent une consigne explicite de nouvelle tentative telle que You can retry your request.

StreamErrorRetryProcessor inclut cette fonction de correspondance par défaut. Vous pouvez également l'importer et la réutiliser dans une logique personnalisée de nouvelle tentative.

Paramètres du constructeur

options?:

StreamErrorRetryProcessorOptions

Configuration de la gestion des nouvelles tentatives.

number

StreamErrorRetryMatcher[]

boolean

number | ((args: ProcessAPIErrorArgs) => number | Promise<number>)

number

Propriétés

id:

'stream-error-retry-processor'

Identifiant du Processor.

name:

'Stream Error Retry Processor'

Nom d'affichage du Processor.

processAPIError:

(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void

Relance les erreurs de flux jusqu'à la limite de nouvelles tentatives configurée.

Voir aussi

• Interface Processor
• Processors