StreamErrorRetry프로세서

StreamErrorRetryProcessor은오류 프로세서일시적인 LLM API 및 스트림 오류를 재시도합니다. OpenAI 응답 스트림 오류에 대한 기본 일치 기능이 포함되어 있으며 다른 공급자별 오류 형태에 대한 추가 일치자를 지원합니다.

이 프로세서는 코어에서 기본적으로 활성화되지 않습니다. 제한된 재시도 처리가 필요한 Agent의 errorProcessors에 추가하세요.

사용예

errorProcessors에 StreamErrorRetryProcessor를 추가하세요.

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

작동 원리

프로세서는 다음 사항에 대해 오류와 원인 체인을 확인합니다.

• 공급자 재시도 메타데이터:isRetryable === true
• 내장된 OpenAI 응답 스트림 오류 일치
• 일치자 결과: 반환하는 구성된 모든 일치자true

오류를 재시도할 수 있으면 프로세서가 { retry: true }를 반환합니다. 메시지는 변경하지 않습니다. delayMs가 설정되면 프로세서는 재시도 신호를 보내기 전에 기다립니다. 즉시 재시도하면 다시 실패할 가능성이 높은 ECONNRESET 같은 일시적 네트워크 오류에 유용합니다. 지연 시간은 고정된 밀리초 값이나 오류 인수를 사용해 평가되는 함수(예: 지수 백오프 구현)로 지정할 수 있습니다.

재시도 한도

maxRetries의 기본값은 1이며 이 프로세서가 요청할 수 있는 재시도 횟수를 제한합니다. Agent도 maxProcessorRetries를 사용하여 프로세서 재시도를 제한합니다. Agent 제한 없이 오류 프로세서를 구성하면 런타임 상한은 10입니다. 하나의 재시도 예산을 사용하려면 두 값을 모두 명시적으로 동일한 제한 값으로 설정하세요. Provider 시도 횟수가 배가되지 않도록 해당 호출에서 Model의 maxRetries를 0으로 유지하세요.

Retry-After손질

재시도 가능한 오류에 Retry-After 응답 헤더가 있으면 프로세서는 오류 원인 체인을 따라 대소문자를 구분하지 않고 delta-seconds 및 HTTP-date 값을 읽습니다. delayMs와 제한된 서버 지연 중 더 긴 시간만큼 기다립니다. maxRetryAfterMs의 기본값은 30_000입니다. Provider가 제공한 대기 시간에만 상한을 적용합니다. 더 긴 명시적 delayMs는 변경되지 않습니다. 유효하지 않거나 만료된 헤더는 무시됩니다.

알 수 없는 오류 재시도

Provider 메타데이터, 기본 제공 OpenAI 매처 또는 사용자 지정 매처와 일치하지 않는 오류를 재시도하려면 retryUnknownErrors를 설정하세요. 알 수 없는 오류 재시도에는 프로세서 수준의 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,
    }),
  ],
})

특정 매처 정책은 여전히 알 수 없는 오류 설정에 우선합니다. 이 옵션의 기본값은 false이므로 활성화하지 않으면 알 수 없는 오류를 재시도하지 않습니다.

재시도 지연

일시적인 네트워크 연결 재설정을 일정 시간 기다린 후 재시도하려면 사용자 지정 매처와 함께 delayMs를 사용하세요.

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 응답 일치자

isRetryableOpenAIResponsesStreamError는 type: 'error' 또는 type: 'response.failed'인 OpenAI 응답 스트림 오류 청크와 일치합니다. 알려진 일시적 OpenAI 오류 코드를 재시도하며, 대체 동작으로 You can retry your request와 같은 명시적인 재시도 안내가 있는 오류도 재시도합니다. StreamErrorRetryProcessor기본적으로 이 매처를 포함합니다. 이를 가져와서 사용자 지정 재시도 논리에서 재사용할 수도 있습니다.

생성자 매개변수

options?:

StreamErrorRetryProcessorOptions

재시도 처리 구성입니다.

number

StreamErrorRetryMatcher[]

boolean

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

number

속성

id:

'stream-error-retry-processor'

프로세서 식별자입니다.

name:

'Stream Error Retry Processor'

프로세서 표시 이름입니다.

processAPIError:

(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void

구성된 재시도 제한까지 스트림 오류를 재시도합니다.

관련된

• 프로세서 인터페이스
• 프로세서