Class●Since v1.0

ToolRetryMiddleware

Middleware that automatically retries failed tool calls with configurable backoff.

Supports retrying on specific exceptions and exponential backoff.

ToolRetryMiddleware(
  self,
  *,
  max_retries: int = 2,
  tools: list[BaseTool | str] | None = None,
  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`.
`tools`	`list[BaseTool \| str] \| None`	Default:`None` Optional list of tools or tool names to apply retry logic to. Can be a list of `BaseTool` instances or tool name strings. If `None`, applies to all tools.
`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 a `ToolMessage` with error details, allowing the LLM to handle the failure and potentially recover. `'error'`: Re-raise the exception, stopping agent execution. Custom callable: Function that takes the exception and returns a string for the `ToolMessage` content, allowing custom error formatting. Deprecated values (for backwards compatibility): `'return_message'`: Use `'continue'` instead. `'raise'`: Use `'error'` instead.
`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.