Class●Since v1.1

ModelRetryMiddleware

Middleware that automatically retries failed model calls with configurable backoff.

Supports retrying on specific exceptions and exponential backoff.

ModelRetryMiddleware(
  self,
  *,
  max_retries: int = 2,
  retry_on: RetryOn = (Exception,),
  on_failure: OnFailure = 'continue',
  backoff_factor: float = 2.0,
  initial_delay: float = 1.0,
  max_delay: float = 60.0,
  jitter: bool = True
)

Bases

AgentMiddleware[AgentState[ResponseT], ContextT, ResponseT]

Parameters

Name	Type	Description
`max_retries`	`int`	Default:`2` Maximum number of retry attempts after the initial call. Must be `>= 0`.
`retry_on`	`RetryOn`	Default:`(Exception,)` Either a tuple of exception types to retry on, or a callable that takes an exception and returns `True` if it should be retried. Default is to retry on all exceptions.
`on_failure`	`OnFailure`	Default:`'continue'` Behavior when all retries are exhausted. Options: `'continue'`: Return an `AIMessage` with error details, allowing the agent to continue with an error response. `'error'`: Re-raise the exception, stopping agent execution. Custom callable: Function that takes the exception and returns a string for the `AIMessage` content, allowing custom error formatting.
`backoff_factor`	`float`	Default:`2.0` Multiplier for exponential backoff. Each retry waits `initial_delay * (backoff_factor ** retry_number)` seconds. Set to `0.0` for constant delay.
`initial_delay`	`float`	Default:`1.0` Initial delay in seconds before first retry.
`max_delay`	`float`	Default:`60.0` Maximum delay in seconds between retries. Caps exponential backoff growth.
`jitter`	`bool`	Default:`True` Whether to add random jitter (`±25%`) to delay to avoid thundering herd.