StreamErrorRetryProcessor

StreamErrorRetryProcessor 是一种错误 Processor，用于重试暂时性的 LLM API 和流故障。它内置了对 OpenAI Responses 流错误的匹配，并支持为其他 Provider 专属错误结构添加 matcher。

core 默认不启用此 Processor。对于需要有限次数重试处理的 Agent，请将其添加到 errorProcessors。

用法示例

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

工作原理

此 Processor 会检查错误及其 cause 链中的以下内容：

• Provider 重试元数据：isRetryable === true
• 内置 OpenAI Responses 流错误匹配
• Matcher 结果：任何返回 true 的已配置 matcher

当错误可重试时，Processor 返回 { retry: true }。它不会修改消息。

设置 delayMs 后，Processor 会等待一段时间再发出重试信号。这适用于 ECONNRESET 等暂时性网络错误，因为立即重试很可能再次失败。延迟可以是固定的毫秒数，也可以是使用错误参数求值的函数（例如用于实现指数退避）。

重试限制

maxRetries 默认为 1，用于限制此 Processor 的重试请求次数。Agent 还会通过 maxProcessorRetries 限制 Processor 重试次数。如果配置了错误 Processor，但未设置 Agent 限制，则运行时上限为 10。

需要统一的重试预算时，请将两个值显式设置为相同的有限值。该调用的模型 maxRetries 应保持为 0，以免成倍增加 Provider 尝试次数。

Retry-After 处理

对于包含 Retry-After 响应标头的可重试错误，Processor 会通过错误 cause 链读取不区分大小写的 delta-seconds 和 HTTP-date 值。它会等待 delayMs 与受限服务器延迟中较长的一段时间。

maxRetryAfterMs 默认为 30_000。它只限制 Provider 给出的等待时间。显式指定的更长 delayMs 不受影响。无效或已过期的标头会被忽略。

重试未知错误

设置 retryUnknownErrors 可重试不匹配 Provider 元数据、内置 OpenAI matcher 或自定义 matcher 的错误。未知错误重试使用 Processor 级的 maxRetries 和 delayMs 值。已知的授权失败不会重试，包括 HTTP 401 和 403 响应：

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

特定 matcher 策略的优先级仍高于未知错误的值。此选项默认为 false，因此除非启用它，否则不会重试未知错误。

延迟重试

将 delayMs 与自定义 matcher 配合使用，可等待后重试暂时性的网络重置：

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

默认 OpenAI Responses matcher

isRetryableOpenAIResponsesStreamError 匹配 type: 'error' 或 type: 'response.failed' 的 OpenAI Responses 流错误块。它会重试已知的暂时性 OpenAI 错误代码；作为后备，还会重试带有 You can retry your request 等明确重试指引的错误。

StreamErrorRetryProcessor 默认包含此 matcher。你也可以导入它，并在自定义重试逻辑中重用。

构造函数参数

options?:

StreamErrorRetryProcessorOptions

重试处理的配置。

number

StreamErrorRetryMatcher[]

boolean

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

number

属性

id:

'stream-error-retry-processor'

Processor 标识符。

name:

'Stream Error Retry Processor'

Processor 显示名称。

processAPIError:

(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void

重试流错误，次数不超过配置的重试限制。

相关内容

• Processor 接口
• Processors