Skip to content

The agent engineering platform.

feat: `ModelRetryMiddleware` (#34027)

Sydney Runkleb296f103a969
diff --git a/libs/langchain_v1/langchain/agents/middleware/__init__.py b/libs/langchain_v1/langchain/agents/middleware/__init__.py
index 44389008aa..94bd872d57 100644
--- a/libs/langchain_v1/langchain/agents/middleware/__init__.py
+++ b/libs/langchain_v1/langchain/agents/middleware/__init__.py
@@ -11,6 +11,7 @@ from .human_in_the_loop import (
)
from .model_call_limit import ModelCallLimitMiddleware
from .model_fallback import ModelFallbackMiddleware
+from .model_retry import ModelRetryMiddleware
from .pii import PIIDetectionError, PIIMiddleware
from .shell_tool import (
CodexSandboxExecutionPolicy,
@@ -57,6 +58,7 @@ __all__ = [
"ModelFallbackMiddleware",
"ModelRequest",
"ModelResponse",
+ "ModelRetryMiddleware",
"PIIDetectionError",
"PIIMiddleware",
"RedactionRule",
diff --git a/libs/langchain_v1/langchain/agents/middleware/_retry.py b/libs/langchain_v1/langchain/agents/middleware/_retry.py
new file mode 100644
index 0000000000..6139abb0bb
--- /dev/null
+++ b/libs/langchain_v1/langchain/agents/middleware/_retry.py
@@ -0,0 +1,123 @@
+"""Shared retry utilities for agent middleware.
+
+This module contains common constants, utilities, and logic used by both
+model and tool retry middleware implementations.
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable
+from typing import Literal
+
+# Type aliases
+RetryOn = tuple[type[Exception], ...] | Callable[[Exception], bool]
+"""Type for specifying which exceptions to retry on.
+
+Can be either:
+- A tuple of exception types to retry on (based on `isinstance` checks)
+- A callable that takes an exception and returns `True` if it should be retried
+"""
+
+OnFailure = Literal["error", "continue"] | Callable[[Exception], str]
+"""Type for specifying failure handling behavior.
+
+Can be either:
+- A literal action string (`'error'` or `'continue'`)
+ - `'error'`: Re-raise the exception, stopping agent execution.
+ - `'continue'`: Inject a message with the error details, allowing the agent to continue.
+ For tool retries, a `ToolMessage` with the error details will be injected.
+ For model retries, an `AIMessage` with the error details will be returned.
+- A callable that takes an exception and returns a string for error message content
+"""
+
+
+def validate_retry_params(
+ max_retries: int,
+ initial_delay: float,
+ max_delay: float,
+ backoff_factor: float,
+) -> None:
+ """Validate retry parameters.
+
+ Args:
+ max_retries: Maximum number of retry attempts.
+ initial_delay: Initial delay in seconds before first retry.
+ max_delay: Maximum delay in seconds between retries.
+ backoff_factor: Multiplier for exponential backoff.
+
+ Raises:
+ ValueError: If any parameter is invalid (negative values).
+ """
+ if max_retries < 0:
+ msg = "max_retries must be >= 0"
+ raise ValueError(msg)
+ if initial_delay < 0:
+ msg = "initial_delay must be >= 0"
+ raise ValueError(msg)
+ if max_delay < 0:
+ msg = "max_delay must be >= 0"
+ raise ValueError(msg)
+ if backoff_factor < 0:
+ msg = "backoff_factor must be >= 0"
+ raise ValueError(msg)
+
+
+def should_retry_exception(
+ exc: Exception,
+ retry_on: RetryOn,
+) -> bool:
+ """Check if an exception should trigger a retry.
+
+ Args:
+ exc: The exception that occurred.
+ retry_on: Either a tuple of exception types to retry on, or a callable
+ that takes an exception and returns `True` if it should be retried.
+
+ Returns:
+ `True` if the exception should be retried, `False` otherwise.
+ """
+ if callable(retry_on):
+ return retry_on(exc)
+ return isinstance(exc, retry_on)
+
+
+def calculate_delay(
+ retry_number: int,
+ *,
+ backoff_factor: float,
+ initial_delay: float,
+ max_delay: float,
+ jitter: bool,
+) -> float:
+ """Calculate delay for a retry attempt with exponential backoff and optional jitter.
+
+ Args:
+ retry_number: The retry attempt number (0-indexed).
+ backoff_factor: Multiplier for exponential backoff.
+
+ Set to `0.0` for constant delay.
+ initial_delay: Initial delay in seconds before first retry.
+ max_delay: Maximum delay in seconds between retries.
+
+ Caps exponential backoff growth.
+ jitter: Whether to add random jitter to delay to avoid thundering herd.
+
+ Returns:
+ Delay in seconds before next retry.
+ """
+ if backoff_factor == 0.0:
+ delay = initial_delay
+ else:
+ delay = initial_delay * (backoff_factor**retry_number)
+
+ # Cap at max_delay
+ delay = min(delay, max_delay)
+
+ if jitter and delay > 0:
+ jitter_amount = delay * 0.25 # ±25% jitter
+ delay = delay + random.uniform(-jitter_amount, jitter_amount) # noqa: S311
+ # Ensure delay is not negative after jitter
+ delay = max(0, delay)
+
+ return delay
diff --git a/libs/langchain_v1/langchain/agents/middleware/model_retry.py b/libs/langchain_v1/langchain/agents/middleware/model_retry.py
new file mode 100644
index 0000000000..1299f869a7
--- /dev/null
+++ b/libs/langchain_v1/langchain/agents/middleware/model_retry.py
@@ -0,0 +1,300 @@
+"""Model retry middleware for agents."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import TYPE_CHECKING
+
+from langchain_core.messages import AIMessage
+
+from langchain.agents.middleware._retry import (
+ OnFailure,
+ RetryOn,
+ calculate_delay,
+ should_retry_exception,
+ validate_retry_params,
+)
+from langchain.agents.middleware.types import AgentMiddleware, ModelResponse
+
+if TYPE_CHECKING:
+ from collections.abc import Awaitable, Callable
+
+ from langchain.agents.middleware.types import ModelRequest
+
+
+class ModelRetryMiddleware(AgentMiddleware):
+ """Middleware that automatically retries failed model calls with configurable backoff.
+
+ Supports retrying on specific exceptions and exponential backoff.
+
+ Examples:
+ !!! example "Basic usage with default settings (2 retries, exponential backoff)"
+
+ ```python
+ from langchain.agents import create_agent
+ from langchain.agents.middleware import ModelRetryMiddleware
+
+ agent = create_agent(model, tools=[search_tool], middleware=[ModelRetryMiddleware()])
+ ```
+
+ !!! example "Retry specific exceptions only"
+
+ ```python
+ from anthropic import RateLimitError
+ from openai import APITimeoutError
+
+ retry = ModelRetryMiddleware(
+ max_retries=4,
+ retry_on=(APITimeoutError, RateLimitError),
+ backoff_factor=1.5,
+ )
+ ```
+
+ !!! example "Custom exception filtering"
+
+ ```python
+ from anthropic import APIStatusError
+
+
+ def should_retry(exc: Exception) -> bool:
+ # Only retry on 5xx errors
+ if isinstance(exc, APIStatusError):
+ return 500 <= exc.status_code < 600
+ return False
+
+
+ retry = ModelRetryMiddleware(
+ max_retries=3,
+ retry_on=should_retry,
+ )
+ ```
+
+ !!! example "Custom error handling"
+
+ ```python
+ def format_error(exc: Exception) -> str:
+ return "Model temporarily unavailable. Please try again later."
+
+
+ retry = ModelRetryMiddleware(
+ max_retries=4,
+ on_failure=format_error,
+ )
+ ```
+
+ !!! example "Constant backoff (no exponential growth)"
+
+ ```python
+ retry = ModelRetryMiddleware(
+ max_retries=5,
+ backoff_factor=0.0, # No exponential growth
+ initial_delay=2.0, # Always wait 2 seconds
+ )
+ ```
+
+ !!! example "Raise exception on failure"
+
+ ```python
+ retry = ModelRetryMiddleware(
+ max_retries=2,
+ on_failure="error", # Re-raise exception instead of returning message
+ )
+ ```
+ """
+
+ def __init__(
+ 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,
+ ) -> None:
+ """Initialize `ModelRetryMiddleware`.
+
+ Args:
+ max_retries: Maximum number of retry attempts after the initial call.
+
+ Must be `>= 0`.
+ retry_on: 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: 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: Multiplier for exponential backoff.
+
+ Each retry waits `initial_delay * (backoff_factor ** retry_number)`
+ seconds.
+
+ Set to `0.0` for constant delay.
+ initial_delay: Initial delay in seconds before first retry.
+ max_delay: Maximum delay in seconds between retries.
+
+ Caps exponential backoff growth.
+ jitter: Whether to add random jitter (`±25%`) to delay to avoid thundering herd.
+
+ Raises:
+ ValueError: If `max_retries < 0` or delays are negative.
+ """
+ super().__init__()
+
+ # Validate parameters
+ validate_retry_params(max_retries, initial_delay, max_delay, backoff_factor)
+
+ self.max_retries = max_retries
+ self.tools = [] # No additional tools registered by this middleware
+ self.retry_on = retry_on
+ self.on_failure = on_failure
+ self.backoff_factor = backoff_factor
+ self.initial_delay = initial_delay
+ self.max_delay = max_delay
+ self.jitter = jitter
+
+ def _format_failure_message(self, exc: Exception, attempts_made: int) -> AIMessage:
+ """Format the failure message when retries are exhausted.
+
+ Args:
+ exc: The exception that caused the failure.
+ attempts_made: Number of attempts actually made.
+
+ Returns:
+ `AIMessage` with formatted error message.
+ """
+ exc_type = type(exc).__name__
+ exc_msg = str(exc)
+ attempt_word = "attempt" if attempts_made == 1 else "attempts"
+ content = (
+ f"Model call failed after {attempts_made} {attempt_word} with {exc_type}: {exc_msg}"
+ )
+ return AIMessage(content=content)
+
+ def _handle_failure(self, exc: Exception, attempts_made: int) -> ModelResponse:
+ """Handle failure when all retries are exhausted.
+
+ Args:
+ exc: The exception that caused the failure.
+ attempts_made: Number of attempts actually made.
+
+ Returns:
+ `ModelResponse` with error details.
+
+ Raises:
+ Exception: If `on_failure` is `'error'`, re-raises the exception.
+ """
+ if self.on_failure == "error":
+ raise exc
+
+ if callable(self.on_failure):
+ content = self.on_failure(exc)
+ ai_msg = AIMessage(content=content)
+ else:
+ ai_msg = self._format_failure_message(exc, attempts_made)
+
+ return ModelResponse(result=[ai_msg])
+
+ def wrap_model_call(
+ self,
+ request: ModelRequest,
+ handler: Callable[[ModelRequest], ModelResponse],
+ ) -> ModelResponse | AIMessage:
+ """Intercept model execution and retry on failure.
+
+ Args:
+ request: Model request with model, messages, state, and runtime.
+ handler: Callable to execute the model (can be called multiple times).
+
+ Returns:
+ `ModelResponse` or `AIMessage` (the final result).
+ """
+ # Initial attempt + retries
+ for attempt in range(self.max_retries + 1):
+ try:
+ return handler(request)
+ except Exception as exc: # noqa: BLE001
+ attempts_made = attempt + 1 # attempt is 0-indexed
+
+ # Check if we should retry this exception
+ if not should_retry_exception(exc, self.retry_on):
+ # Exception is not retryable, handle failure immediately
+ return self._handle_failure(exc, attempts_made)
+
+ # Check if we have more retries left
+ if attempt < self.max_retries:
+ # Calculate and apply backoff delay
+ delay = calculate_delay(
+ attempt,
+ backoff_factor=self.backoff_factor,
+ initial_delay=self.initial_delay,
+ max_delay=self.max_delay,
+ jitter=self.jitter,
+ )
+ if delay > 0:
+ time.sleep(delay)
+ # Continue to next retry
+ else:
+ # No more retries, handle failure
+ return self._handle_failure(exc, attempts_made)
+
+ # Unreachable: loop always returns via handler success or _handle_failure
+ msg = "Unexpected: retry loop completed without returning"
+ raise RuntimeError(msg)
+
+ async def awrap_model_call(
+ self,
+ request: ModelRequest,
+ handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+ ) -> ModelResponse | AIMessage:
+ """Intercept and control async model execution with retry logic.
+
+ Args:
+ request: Model request with model, messages, state, and runtime.
+ handler: Async callable to execute the model and returns `ModelResponse`.
+
+ Returns:
+ `ModelResponse` or `AIMessage` (the final result).
+ """
+ # Initial attempt + retries
+ for attempt in range(self.max_retries + 1):
+ try:
+ return await handler(request)
+ except Exception as exc: # noqa: BLE001
+ attempts_made = attempt + 1 # attempt is 0-indexed
+
+ # Check if we should retry this exception
+ if not should_retry_exception(exc, self.retry_on):
+ # Exception is not retryable, handle failure immediately
+ return self._handle_failure(exc, attempts_made)
+
+ # Check if we have more retries left
+ if attempt < self.max_retries:
+ # Calculate and apply backoff delay
+ delay = calculate_delay(
+ attempt,
+ backoff_factor=self.backoff_factor,
+ initial_delay=self.initial_delay,
+ max_delay=self.max_delay,
+ jitter=self.jitter,
+ )
+ if delay > 0:
+ await asyncio.sleep(delay)
+ # Continue to next retry
+ else:
+ # No more retries, handle failure
+ return self._handle_failure(exc, attempts_made)
+
+ # Unreachable: loop always returns via handler success or _handle_failure
+ msg = "Unexpected: retry loop completed without returning"
+ raise RuntimeError(msg)
diff --git a/libs/langchain_v1/langchain/agents/middleware/tool_retry.py b/libs/langchain_v1/langchain/agents/middleware/tool_retry.py
index 0eb2a2b109..baf3a9ee61 100644
--- a/libs/langchain_v1/langchain/agents/middleware/tool_retry.py
+++ b/libs/langchain_v1/langchain/agents/middleware/tool_retry.py
@@ -3,12 +3,19 @@
from __future__ import annotations
import asyncio
-import random
import time
-from typing import TYPE_CHECKING, Literal
+import warnings
+from typing import TYPE_CHECKING
from langchain_core.messages import ToolMessage
+from langchain.agents.middleware._retry import (
+ OnFailure,
+ RetryOn,
+ calculate_delay,
+ should_retry_exception,
+ validate_retry_params,
+)
from langchain.agents.middleware.types import AgentMiddleware
if TYPE_CHECKING:
@@ -113,7 +120,7 @@ class ToolRetryMiddleware(AgentMiddleware):
```python
retry = ToolRetryMiddleware(
max_retries=2,
- on_failure="raise", # Re-raise exception instead of returning message
+ on_failure="error", # Re-raise exception instead of returning message
)
```
"""
@@ -123,10 +130,8 @@ class ToolRetryMiddleware(AgentMiddleware):
*,
max_retries: int = 2,
tools: list[BaseTool | str] | None = None,
- retry_on: tuple[type[Exception], ...] | Callable[[Exception], bool] = (Exception,),
- on_failure: (
- Literal["raise", "return_message"] | Callable[[Exception], str]
- ) = "return_message",
+ retry_on: RetryOn = (Exception,),
+ on_failure: OnFailure = "continue",
backoff_factor: float = 2.0,
initial_delay: float = 1.0,
max_delay: float = 60.0,
@@ -137,8 +142,6 @@ class ToolRetryMiddleware(AgentMiddleware):
Args:
max_retries: Maximum number of retry attempts after the initial call.
- Default is `2` retries (`3` total attempts).
-
Must be `>= 0`.
tools: Optional list of tools or tool names to apply retry logic to.
@@ -153,12 +156,17 @@ class ToolRetryMiddleware(AgentMiddleware):
Options:
- - `'return_message'`: Return a `ToolMessage` with error details,
+ - `'continue'`: Return a `ToolMessage` with error details,
allowing the LLM to handle the failure and potentially recover.
- - `'raise'`: Re-raise the exception, stopping agent execution.
+ - `'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: Multiplier for exponential backoff.
Each retry waits `initial_delay * (backoff_factor ** retry_number)`
@@ -177,18 +185,23 @@ class ToolRetryMiddleware(AgentMiddleware):
super().__init__()
# Validate parameters
- if max_retries < 0:
- msg = "max_retries must be >= 0"
- raise ValueError(msg)
- if initial_delay < 0:
- msg = "initial_delay must be >= 0"
- raise ValueError(msg)
- if max_delay < 0:
- msg = "max_delay must be >= 0"
- raise ValueError(msg)
- if backoff_factor < 0:
- msg = "backoff_factor must be >= 0"
- raise ValueError(msg)
+ validate_retry_params(max_retries, initial_delay, max_delay, backoff_factor)
+
+ # Handle backwards compatibility for deprecated on_failure values
+ if on_failure == "raise": # type: ignore[comparison-overlap]
+ msg = (
+ "on_failure='raise' is deprecated and will be removed in a future version. "
+ "Use on_failure='error' instead."
+ )
+ warnings.warn(msg, DeprecationWarning, stacklevel=2)
+ on_failure = "error"
+ elif on_failure == "return_message": # type: ignore[comparison-overlap]
+ msg = (
+ "on_failure='return_message' is deprecated and will be removed "
+ "in a future version. Use on_failure='continue' instead."
+ )
+ warnings.warn(msg, DeprecationWarning, stacklevel=2)
+ on_failure = "continue"
self.max_retries = max_retries
@@ -220,44 +233,6 @@ class ToolRetryMiddleware(AgentMiddleware):
return True
return tool_name in self._tool_filter
- def _should_retry_exception(self, exc: Exception) -> bool:
- """Check if the exception should trigger a retry.
-
- Args:
- exc: The exception that occurred.
-
- Returns:
- `True` if the exception should be retried, `False` otherwise.
- """
- if callable(self.retry_on):
- return self.retry_on(exc)
- return isinstance(exc, self.retry_on)
-
- def _calculate_delay(self, retry_number: int) -> float:
- """Calculate delay for the given retry attempt.
-
- Args:
- retry_number: The retry attempt number (0-indexed).
-
- Returns:
- Delay in seconds before next retry.
- """
- if self.backoff_factor == 0.0:
- delay = self.initial_delay
- else:
- delay = self.initial_delay * (self.backoff_factor**retry_number)
-
- # Cap at max_delay
- delay = min(delay, self.max_delay)
-
- if self.jitter and delay > 0:
- jitter_amount = delay * 0.25
- delay = delay + random.uniform(-jitter_amount, jitter_amount) # noqa: S311
- # Ensure delay is not negative after jitter
- delay = max(0, delay)
-
- return delay
-
def _format_failure_message(self, tool_name: str, exc: Exception, attempts_made: int) -> str:
"""Format the failure message when retries are exhausted.
@@ -270,8 +245,12 @@ class ToolRetryMiddleware(AgentMiddleware):
Formatted error message string.
"""
exc_type = type(exc).__name__
+ exc_msg = str(exc)
attempt_word = "attempt" if attempts_made == 1 else "attempts"
- return f"Tool '{tool_name}' failed after {attempts_made} {attempt_word} with {exc_type}"
+ return (
+ f"Tool '{tool_name}' failed after {attempts_made} {attempt_word} "
+ f"with {exc_type}: {exc_msg}. Please try again."
+ )
def _handle_failure(
self, tool_name: str, tool_call_id: str | None, exc: Exception, attempts_made: int
@@ -288,9 +267,9 @@ class ToolRetryMiddleware(AgentMiddleware):
`ToolMessage` with error details.
Raises:
- Exception: If `on_failure` is `'raise'`, re-raises the exception.
+ Exception: If `on_failure` is `'error'`, re-raises the exception.
"""
- if self.on_failure == "raise":
+ if self.on_failure == "error":
raise exc
if callable(self.on_failure):
@@ -335,14 +314,20 @@ class ToolRetryMiddleware(AgentMiddleware):
attempts_made = attempt + 1 # attempt is 0-indexed
# Check if we should retry this exception
- if not self._should_retry_exception(exc):
+ if not should_retry_exception(exc, self.retry_on):
# Exception is not retryable, handle failure immediately
return self._handle_failure(tool_name, tool_call_id, exc, attempts_made)
# Check if we have more retries left
if attempt < self.max_retries:
# Calculate and apply backoff delay
- delay = self._calculate_delay(attempt)
+ delay = calculate_delay(
+ attempt,
+ backoff_factor=self.backoff_factor,
+ initial_delay=self.initial_delay,
+ max_delay=self.max_delay,
+ jitter=self.jitter,
+ )
if delay > 0:
time.sleep(delay)
# Continue to next retry
@@ -385,14 +370,20 @@ class ToolRetryMiddleware(AgentMiddleware):
attempts_made = attempt + 1 # attempt is 0-indexed
# Check if we should retry this exception
- if not self._should_retry_exception(exc):
+ if not should_retry_exception(exc, self.retry_on):
# Exception is not retryable, handle failure immediately
return self._handle_failure(tool_name, tool_call_id, exc, attempts_made)
# Check if we have more retries left
if attempt < self.max_retries:
# Calculate and apply backoff delay
- delay = self._calculate_delay(attempt)
+ delay = calculate_delay(
+ attempt,
+ backoff_factor=self.backoff_factor,
+ initial_delay=self.initial_delay,
+ max_delay=self.max_delay,
+ jitter=self.jitter,
+ )
if delay > 0:
await asyncio.sleep(delay)
# Continue to next retry
diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_model_retry.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_model_retry.py
new file mode 100644
index 0000000000..0ce3261362
--- /dev/null
+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_model_retry.py
@@ -0,0 +1,689 @@
+"""Tests for ModelRetryMiddleware functionality."""
+
+import asyncio
+import time
+from typing import Any
+
+import pytest
+from langchain_core.callbacks import CallbackManagerForLLMRun
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
+from langchain_core.outputs import ChatGeneration, ChatResult
+from langgraph.checkpoint.memory import InMemorySaver
+from pydantic import Field
+
+from langchain.agents.factory import create_agent
+from langchain.agents.middleware._retry import calculate_delay
+from langchain.agents.middleware.model_retry import ModelRetryMiddleware
+from tests.unit_tests.agents.model import FakeToolCallingModel
+
+
+class TemporaryFailureModel(FakeToolCallingModel):
+ """Model that fails a certain number of times before succeeding."""
+
+ fail_count: int = Field(default=0)
+ attempt: int = Field(default=0)
+
+ def _generate(
+ self,
+ messages: list[BaseMessage],
+ stop: list[str] | None = None,
+ run_manager: CallbackManagerForLLMRun | None = None,
+ **kwargs: Any,
+ ) -> ChatResult:
+ """Execute the model.
+
+ Args:
+ messages: Input messages.
+ stop: Optional stop sequences.
+ run_manager: Optional callback manager.
+ **kwargs: Additional keyword arguments.
+
+ Returns:
+ ChatResult with success message if attempt >= fail_count.
+
+ Raises:
+ ValueError: If attempt < fail_count.
+ """
+ self.attempt += 1
+ if self.attempt <= self.fail_count:
+ msg = f"Temporary failure {self.attempt}"
+ raise ValueError(msg)
+ # Return success message
+ ai_msg = AIMessage(content=f"Success after {self.attempt} attempts", id=str(self.index))
+ self.index += 1
+ return ChatResult(generations=[ChatGeneration(message=ai_msg)])
+
+
+class AlwaysFailingModel(FakeToolCallingModel):
+ """Model that always fails with a specific exception."""
+
+ error_message: str = Field(default="Model error")
+ error_type: type[Exception] = Field(default=ValueError)
+
+ def _generate(
+ self,
+ messages: list[BaseMessage],
+ stop: list[str] | None = None,
+ run_manager: CallbackManagerForLLMRun | None = None,
+ **kwargs: Any,
+ ) -> ChatResult:
+ """Execute the model and raise exception.
+
+ Args:
+ messages: Input messages.
+ stop: Optional stop sequences.
+ run_manager: Optional callback manager.
+ **kwargs: Additional keyword arguments.
+
+ Raises:
+ Exception: Always raises the configured exception.
+ """
+ raise self.error_type(self.error_message)
+
+
+def test_model_retry_initialization_defaults() -> None:
+ """Test ModelRetryMiddleware initialization with default values."""
+ retry = ModelRetryMiddleware()
+
+ assert retry.max_retries == 2
+ assert retry.tools == []
+ assert retry.on_failure == "continue"
+ assert retry.backoff_factor == 2.0
+ assert retry.initial_delay == 1.0
+ assert retry.max_delay == 60.0
+ assert retry.jitter is True
+
+
+def test_model_retry_initialization_custom() -> None:
+ """Test ModelRetryMiddleware initialization with custom values."""
+ retry = ModelRetryMiddleware(
+ max_retries=5,
+ retry_on=(ValueError, RuntimeError),
+ on_failure="error",
+ backoff_factor=1.5,
+ initial_delay=0.5,
+ max_delay=30.0,
+ jitter=False,
+ )
+
+ assert retry.max_retries == 5
+ assert retry.tools == []
+ assert retry.retry_on == (ValueError, RuntimeError)
+ assert retry.on_failure == "error"
+ assert retry.backoff_factor == 1.5
+ assert retry.initial_delay == 0.5
+ assert retry.max_delay == 30.0
+ assert retry.jitter is False
+
+
+def test_model_retry_invalid_max_retries() -> None:
+ """Test ModelRetryMiddleware raises error for invalid max_retries."""
+ with pytest.raises(ValueError, match="max_retries must be >= 0"):
+ ModelRetryMiddleware(max_retries=-1)
+
+
+def test_model_retry_invalid_initial_delay() -> None:
+ """Test ModelRetryMiddleware raises error for invalid initial_delay."""
+ with pytest.raises(ValueError, match="initial_delay must be >= 0"):
+ ModelRetryMiddleware(initial_delay=-1.0)
+
+
+def test_model_retry_invalid_max_delay() -> None:
+ """Test ModelRetryMiddleware raises error for invalid max_delay."""
+ with pytest.raises(ValueError, match="max_delay must be >= 0"):
+ ModelRetryMiddleware(max_delay=-1.0)
+
+
+def test_model_retry_invalid_backoff_factor() -> None:
+ """Test ModelRetryMiddleware raises error for invalid backoff_factor."""
+ with pytest.raises(ValueError, match="backoff_factor must be >= 0"):
+ ModelRetryMiddleware(backoff_factor=-1.0)
+
+
+def test_model_retry_working_model_no_retry_needed() -> None:
+ """Test ModelRetryMiddleware with a working model (no retry needed)."""
+ model = FakeToolCallingModel()
+
+ retry = ModelRetryMiddleware(max_retries=2, initial_delay=0.01, jitter=False)
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ result = agent.invoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert len(ai_messages) >= 1
+ assert "Hello" in ai_messages[-1].content
+
+
+def test_model_retry_failing_model_returns_message() -> None:
+ """Test ModelRetryMiddleware with failing model returns error message."""
+ model = AlwaysFailingModel(error_message="Model error", error_type=ValueError)
+
+ retry = ModelRetryMiddleware(
+ max_retries=2,
+ initial_delay=0.01,
+ jitter=False,
+ on_failure="continue",
+ )
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ result = agent.invoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert len(ai_messages) >= 1
+ # Should contain error message with attempts
+ last_msg = ai_messages[-1].content
+ assert "failed after 3 attempts" in last_msg
+ assert "ValueError" in last_msg
+
+
+def test_model_retry_failing_model_raises() -> None:
+ """Test ModelRetryMiddleware with on_failure='error' re-raises exception."""
+ model = AlwaysFailingModel(error_message="Model error", error_type=ValueError)
+
+ retry = ModelRetryMiddleware(
+ max_retries=2,
+ initial_delay=0.01,
+ jitter=False,
+ on_failure="error",
+ )
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ # Should raise the ValueError from the model
+ with pytest.raises(ValueError, match="Model error"):
+ agent.invoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+
+def test_model_retry_custom_failure_formatter() -> None:
+ """Test ModelRetryMiddleware with custom failure message formatter."""
+
+ def custom_formatter(exc: Exception) -> str:
+ return f"Custom error: {type(exc).__name__}"
+
+ model = AlwaysFailingModel(error_message="Model error", error_type=ValueError)
+
+ retry = ModelRetryMiddleware(
+ max_retries=1,
+ initial_delay=0.01,
+ jitter=False,
+ on_failure=custom_formatter,
+ )
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ result = agent.invoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert len(ai_messages) >= 1
+ assert "Custom error: ValueError" in ai_messages[-1].content
+
+
+def test_model_retry_succeeds_after_retries() -> None:
+ """Test ModelRetryMiddleware succeeds after temporary failures."""
+ model = TemporaryFailureModel(fail_count=2)
+
+ retry = ModelRetryMiddleware(
+ max_retries=3,
+ initial_delay=0.01,
+ jitter=False,
+ )
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ result = agent.invoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert len(ai_messages) >= 1
+ # Should succeed on 3rd attempt
+ assert "Success after 3 attempts" in ai_messages[-1].content
+ assert model.attempt == 3
+
+
+def test_model_retry_specific_exceptions() -> None:
+ """Test ModelRetryMiddleware only retries specific exception types."""
+ # This model will fail with RuntimeError, which we won't retry
+ model = AlwaysFailingModel(error_message="Runtime error", error_type=RuntimeError)
+
+ # Only retry ValueError
+ retry = ModelRetryMiddleware(
+ max_retries=2,
+ retry_on=(ValueError,),
+ initial_delay=0.01,
+ jitter=False,
+ on_failure="continue",
+ )
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ result = agent.invoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert len(ai_messages) >= 1
+ # RuntimeError should fail immediately (1 attempt only)
+ assert "1 attempt" in ai_messages[-1].content
+
+
+def test_model_retry_custom_exception_filter() -> None:
+ """Test ModelRetryMiddleware with custom exception filter function."""
+
+ class CustomError(Exception):
+ """Custom exception with retry_me attribute."""
+
+ def __init__(self, message: str, retry_me: bool):
+ """Initialize custom error.
+
+ Args:
+ message: Error message.
+ retry_me: Whether this error should be retried.
+ """
+ super().__init__(message)
+ self.retry_me = retry_me
+
+ attempt_count = {"value": 0}
+
+ class CustomErrorModel(FakeToolCallingModel):
+ """Model that raises CustomError."""
+
+ def _generate(
+ self,
+ messages: list[BaseMessage],
+ stop: list[str] | None = None,
+ run_manager: CallbackManagerForLLMRun | None = None,
+ **kwargs: Any,
+ ) -> ChatResult:
+ """Execute the model and raise CustomError.
+
+ Args:
+ messages: Input messages.
+ stop: Optional stop sequences.
+ run_manager: Optional callback manager.
+ **kwargs: Additional keyword arguments.
+
+ Raises:
+ CustomError: Always raises CustomError.
+ """
+ attempt_count["value"] += 1
+ if attempt_count["value"] == 1:
+ raise CustomError("Retryable error", retry_me=True)
+ raise CustomError("Non-retryable error", retry_me=False)
+
+ def should_retry(exc: Exception) -> bool:
+ return isinstance(exc, CustomError) and exc.retry_me
+
+ model = CustomErrorModel()
+
+ retry = ModelRetryMiddleware(
+ max_retries=3,
+ retry_on=should_retry,
+ initial_delay=0.01,
+ jitter=False,
+ on_failure="continue",
+ )
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ result = agent.invoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert len(ai_messages) >= 1
+
+ # Should retry once (attempt 1 with retry_me=True), then fail on attempt 2 (retry_me=False)
+ assert attempt_count["value"] == 2
+ assert "2 attempts" in ai_messages[-1].content
+
+
+def test_model_retry_backoff_timing() -> None:
+ """Test ModelRetryMiddleware applies correct backoff delays."""
+ model = TemporaryFailureModel(fail_count=3)
+
+ retry = ModelRetryMiddleware(
+ max_retries=3,
+ initial_delay=0.1,
+ backoff_factor=2.0,
+ jitter=False,
+ )
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ start_time = time.time()
+ result = agent.invoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+ elapsed = time.time() - start_time
+
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert len(ai_messages) >= 1
+
+ # Expected delays: 0.1 + 0.2 + 0.4 = 0.7 seconds
+ # Allow some margin for execution time
+ assert elapsed >= 0.6, f"Expected at least 0.6s, got {elapsed}s"
+
+
+def test_model_retry_constant_backoff() -> None:
+ """Test ModelRetryMiddleware with constant backoff (backoff_factor=0)."""
+ model = TemporaryFailureModel(fail_count=2)
+
+ retry = ModelRetryMiddleware(
+ max_retries=2,
+ initial_delay=0.1,
+ backoff_factor=0.0, # Constant backoff
+ jitter=False,
+ )
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ start_time = time.time()
+ result = agent.invoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+ elapsed = time.time() - start_time
+
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert len(ai_messages) >= 1
+
+ # Expected delays: 0.1 + 0.1 = 0.2 seconds (constant)
+ assert elapsed >= 0.15, f"Expected at least 0.15s, got {elapsed}s"
+ assert elapsed < 0.5, f"Expected less than 0.5s (exponential would be longer), got {elapsed}s"
+
+
+def test_model_retry_max_delay_cap() -> None:
+ """Test calculate_delay caps delay at max_delay."""
+ # Test delay calculation with aggressive backoff and max_delay cap
+ delay_0 = calculate_delay(
+ 0,
+ backoff_factor=10.0, # Very aggressive backoff
+ initial_delay=1.0,
+ max_delay=2.0, # Cap at 2 seconds
+ jitter=False,
+ ) # 1.0
+ delay_1 = calculate_delay(
+ 1,
+ backoff_factor=10.0,
+ initial_delay=1.0,
+ max_delay=2.0,
+ jitter=False,
+ ) # 10.0 -> capped to 2.0
+ delay_2 = calculate_delay(
+ 2,
+ backoff_factor=10.0,
+ initial_delay=1.0,
+ max_delay=2.0,
+ jitter=False,
+ ) # 100.0 -> capped to 2.0
+
+ assert delay_0 == 1.0
+ assert delay_1 == 2.0
+ assert delay_2 == 2.0
+
+
+def test_model_retry_jitter_variation() -> None:
+ """Test calculate_delay adds jitter to delays."""
+ # Generate multiple delays and ensure they vary
+ delays = [
+ calculate_delay(
+ 0,
+ backoff_factor=1.0,
+ initial_delay=1.0,
+ max_delay=60.0,
+ jitter=True,
+ )
+ for _ in range(10)
+ ]
+
+ # All delays should be within ±25% of 1.0 (i.e., between 0.75 and 1.25)
+ for delay in delays:
+ assert 0.75 <= delay <= 1.25
+
+ # Delays should vary (not all the same)
+ assert len(set(delays)) > 1
+
+
+async def test_model_retry_async_working_model() -> None:
+ """Test ModelRetryMiddleware with async execution and working model."""
+ model = FakeToolCallingModel()
+
+ retry = ModelRetryMiddleware(max_retries=2, initial_delay=0.01, jitter=False)
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ result = await agent.ainvoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert len(ai_messages) >= 1
+ assert "Hello" in ai_messages[-1].content
+
+
+async def test_model_retry_async_failing_model() -> None:
+ """Test ModelRetryMiddleware with async execution and failing model."""
+ model = AlwaysFailingModel(error_message="Model error", error_type=ValueError)
+
+ retry = ModelRetryMiddleware(
+ max_retries=2,
+ initial_delay=0.01,
+ jitter=False,
+ on_failure="continue",
+ )
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ result = await agent.ainvoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert len(ai_messages) >= 1
+ last_msg = ai_messages[-1].content
+ assert "failed after 3 attempts" in last_msg
+ assert "ValueError" in last_msg
+
+
+async def test_model_retry_async_succeeds_after_retries() -> None:
+ """Test ModelRetryMiddleware async execution succeeds after temporary failures."""
+ model = TemporaryFailureModel(fail_count=2)
+
+ retry = ModelRetryMiddleware(
+ max_retries=3,
+ initial_delay=0.01,
+ jitter=False,
+ )
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ result = await agent.ainvoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert len(ai_messages) >= 1
+ assert "Success after 3 attempts" in ai_messages[-1].content
+
+
+async def test_model_retry_async_backoff_timing() -> None:
+ """Test ModelRetryMiddleware async applies correct backoff delays."""
+ model = TemporaryFailureModel(fail_count=3)
+
+ retry = ModelRetryMiddleware(
+ max_retries=3,
+ initial_delay=0.1,
+ backoff_factor=2.0,
+ jitter=False,
+ )
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ start_time = time.time()
+ result = await agent.ainvoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+ elapsed = time.time() - start_time
+
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert len(ai_messages) >= 1
+
+ # Expected delays: 0.1 + 0.2 + 0.4 = 0.7 seconds
+ assert elapsed >= 0.6, f"Expected at least 0.6s, got {elapsed}s"
+
+
+def test_model_retry_zero_retries() -> None:
+ """Test ModelRetryMiddleware with max_retries=0 (no retries)."""
+ model = AlwaysFailingModel(error_message="Model error", error_type=ValueError)
+
+ retry = ModelRetryMiddleware(
+ max_retries=0, # No retries
+ on_failure="continue",
+ )
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ result = agent.invoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert len(ai_messages) >= 1
+ # Should fail after 1 attempt (no retries)
+ assert "1 attempt" in ai_messages[-1].content
+
+
+def test_model_retry_multiple_middleware_composition() -> None:
+ """Test ModelRetryMiddleware composes correctly with other middleware."""
+ call_log = []
+
+ # Custom middleware that logs calls
+ from langchain.agents.middleware.types import wrap_model_call
+
+ @wrap_model_call
+ def logging_middleware(request, handler):
+ call_log.append("before_model")
+ response = handler(request)
+ call_log.append("after_model")
+ return response
+
+ model = FakeToolCallingModel()
+
+ retry = ModelRetryMiddleware(max_retries=2, initial_delay=0.01, jitter=False)
+
+ agent = create_agent(
+ model=model,
+ tools=[],
+ middleware=[logging_middleware, retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ result = agent.invoke(
+ {"messages": [HumanMessage("Hello")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+ # Both middleware should be called
+ assert call_log == ["before_model", "after_model"]
+
+ ai_messages = [m for m in result["messages"] if isinstance(m, AIMessage)]
+ assert len(ai_messages) >= 1
+ assert "Hello" in ai_messages[-1].content
diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_retry.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_retry.py
index 5e18d1cae4..2f81e3af17 100644
--- a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_retry.py
+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_retry.py
@@ -10,6 +10,7 @@ from langchain_core.tools import tool
from langgraph.checkpoint.memory import InMemorySaver
from langchain.agents.factory import create_agent
+from langchain.agents.middleware._retry import calculate_delay
from langchain.agents.middleware.tool_retry import ToolRetryMiddleware
from tests.unit_tests.agents.model import FakeToolCallingModel
@@ -65,7 +66,7 @@ def test_tool_retry_initialization_defaults() -> None:
assert retry.max_retries == 2
assert retry._tool_filter is None
assert retry.tools == []
- assert retry.on_failure == "return_message"
+ assert retry.on_failure == "continue"
assert retry.backoff_factor == 2.0
assert retry.initial_delay == 1.0
assert retry.max_delay == 60.0
@@ -78,7 +79,7 @@ def test_tool_retry_initialization_custom() -> None:
max_retries=5,
tools=["tool1", "tool2"],
retry_on=(ValueError, RuntimeError),
- on_failure="raise",
+ on_failure="error",
backoff_factor=1.5,
initial_delay=0.5,
max_delay=30.0,
@@ -89,7 +90,7 @@ def test_tool_retry_initialization_custom() -> None:
assert retry._tool_filter == ["tool1", "tool2"]
assert retry.tools == []
assert retry.retry_on == (ValueError, RuntimeError)
- assert retry.on_failure == "raise"
+ assert retry.on_failure == "error"
assert retry.backoff_factor == 1.5
assert retry.initial_delay == 0.5
assert retry.max_delay == 30.0
@@ -188,7 +189,7 @@ def test_tool_retry_failing_tool_returns_message() -> None:
max_retries=2,
initial_delay=0.01,
jitter=False,
- on_failure="return_message",
+ on_failure="continue",
)
agent = create_agent(
@@ -213,7 +214,7 @@ def test_tool_retry_failing_tool_returns_message() -> None:
def test_tool_retry_failing_tool_raises() -> None:
- """Test ToolRetryMiddlewarewith on_failure='raise' re-raises exception."""
+ """Test ToolRetryMiddlewarewith on_failure='error' re-raises exception."""
model = FakeToolCallingModel(
tool_calls=[
[ToolCall(name="failing_tool", args={"input": "test"}, id="1")],
@@ -225,7 +226,7 @@ def test_tool_retry_failing_tool_raises() -> None:
max_retries=2,
initial_delay=0.01,
jitter=False,
- on_failure="raise",
+ on_failure="error",
)
agent = create_agent(
@@ -339,7 +340,7 @@ def test_tool_retry_specific_tools_only() -> None:
tools=["failing_tool"],
initial_delay=0.01,
jitter=False,
- on_failure="return_message",
+ on_failure="continue",
)
agent = create_agent(
@@ -386,7 +387,7 @@ def test_tool_retry_specific_tools_with_base_tool() -> None:
tools=[failing_tool], # Pass BaseTool instance
initial_delay=0.01,
jitter=False,
- on_failure="return_message",
+ on_failure="continue",
)
agent = create_agent(
@@ -446,7 +447,7 @@ def test_tool_retry_specific_exceptions() -> None:
retry_on=(ValueError,),
initial_delay=0.01,
jitter=False,
- on_failure="return_message",
+ on_failure="continue",
)
agent = create_agent(
@@ -514,7 +515,7 @@ def test_tool_retry_custom_exception_filter() -> None:
retry_on=should_retry,
initial_delay=0.01,
jitter=False,
- on_failure="return_message",
+ on_failure="continue",
)
agent = create_agent(
@@ -628,19 +629,29 @@ def test_tool_retry_constant_backoff() -> None:
def test_tool_retry_max_delay_cap() -> None:
- """Test ToolRetryMiddlewarecaps delay at max_delay."""
- retry = ToolRetryMiddleware(
- max_retries=5,
- initial_delay=1.0,
+ """Test calculate_delay caps delay at max_delay."""
+ # Test delay calculation with aggressive backoff and max_delay cap
+ delay_0 = calculate_delay(
+ 0,
backoff_factor=10.0, # Very aggressive backoff
+ initial_delay=1.0,
max_delay=2.0, # Cap at 2 seconds
jitter=False,
- )
-
- # Test delay calculation
- delay_0 = retry._calculate_delay(0) # 1.0
- delay_1 = retry._calculate_delay(1) # 10.0 -> capped to 2.0
- delay_2 = retry._calculate_delay(2) # 100.0 -> capped to 2.0
+ ) # 1.0
+ delay_1 = calculate_delay(
+ 1,
+ backoff_factor=10.0,
+ initial_delay=1.0,
+ max_delay=2.0,
+ jitter=False,
+ ) # 10.0 -> capped to 2.0
+ delay_2 = calculate_delay(
+ 2,
+ backoff_factor=10.0,
+ initial_delay=1.0,
+ max_delay=2.0,
+ jitter=False,
+ ) # 100.0 -> capped to 2.0
assert delay_0 == 1.0
assert delay_1 == 2.0
@@ -648,16 +659,18 @@ def test_tool_retry_max_delay_cap() -> None:
def test_tool_retry_jitter_variation() -> None:
- """Test ToolRetryMiddlewareadds jitter to delays."""
- retry = ToolRetryMiddleware(
- max_retries=1,
- initial_delay=1.0,
- backoff_factor=1.0,
- jitter=True,
- )
-
+ """Test calculate_delay adds jitter to delays."""
# Generate multiple delays and ensure they vary
- delays = [retry._calculate_delay(0) for _ in range(10)]
+ delays = [
+ calculate_delay(
+ 0,
+ backoff_factor=1.0,
+ initial_delay=1.0,
+ max_delay=60.0,
+ jitter=True,
+ )
+ for _ in range(10)
+ ]
# All delays should be within ±25% of 1.0 (i.e., between 0.75 and 1.25)
for delay in delays:
@@ -710,7 +723,7 @@ async def test_tool_retry_async_failing_tool() -> None:
max_retries=2,
initial_delay=0.01,
jitter=False,
- on_failure="return_message",
+ on_failure="continue",
)
agent = create_agent(
@@ -828,7 +841,7 @@ def test_tool_retry_zero_retries() -> None:
retry = ToolRetryMiddleware(
max_retries=0, # No retries
- on_failure="return_message",
+ on_failure="continue",
)
agent = create_agent(
@@ -893,3 +906,101 @@ def test_tool_retry_multiple_middleware_composition() -> None:
tool_messages = [m for m in result["messages"] if isinstance(m, ToolMessage)]
assert len(tool_messages) == 1
assert "Success: test" in tool_messages[0].content
+
+
+def test_tool_retry_deprecated_raise_keyword() -> None:
+ """Test ToolRetryMiddleware with deprecated 'raise' keyword shows deprecation warning."""
+ with pytest.warns(DeprecationWarning, match="on_failure='raise' is deprecated"):
+ retry = ToolRetryMiddleware(
+ max_retries=2,
+ on_failure="raise",
+ )
+
+ # Should be converted to 'error'
+ assert retry.on_failure == "error"
+
+
+def test_tool_retry_deprecated_return_message_keyword() -> None:
+ """Test ToolRetryMiddleware with deprecated 'return_message' keyword shows deprecation warning."""
+ # Use string concatenation to avoid batch replace affecting test code
+ deprecated_value = "return" + "_message"
+ with pytest.warns(DeprecationWarning, match="on_failure='return_message' is deprecated"):
+ retry = ToolRetryMiddleware(
+ max_retries=2,
+ on_failure=deprecated_value, # type: ignore[arg-type]
+ )
+
+ # Should be converted to 'continue'
+ assert retry.on_failure == "continue"
+
+
+def test_tool_retry_deprecated_raise_behavior() -> None:
+ """Test ToolRetryMiddleware with deprecated 'raise' forwards to 'error' behavior."""
+ model = FakeToolCallingModel(
+ tool_calls=[
+ [ToolCall(name="failing_tool", args={"input": "test"}, id="1")],
+ [],
+ ]
+ )
+
+ with pytest.warns(DeprecationWarning, match="on_failure='raise' is deprecated"):
+ retry = ToolRetryMiddleware(
+ max_retries=2,
+ initial_delay=0.01,
+ jitter=False,
+ on_failure="raise",
+ )
+
+ agent = create_agent(
+ model=model,
+ tools=[failing_tool],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ # Should raise the ValueError from the tool (same as 'error')
+ with pytest.raises(ValueError, match="Failed: test"):
+ agent.invoke(
+ {"messages": [HumanMessage("Use failing tool")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+
+def test_tool_retry_deprecated_return_message_behavior() -> None:
+ """Test ToolRetryMiddleware with deprecated 'return_message' forwards to 'continue' behavior."""
+ model = FakeToolCallingModel(
+ tool_calls=[
+ [ToolCall(name="failing_tool", args={"input": "test"}, id="1")],
+ [],
+ ]
+ )
+
+ # Use string concatenation to avoid batch replace affecting test code
+ deprecated_value = "return" + "_message"
+ with pytest.warns(DeprecationWarning, match="on_failure='return_message' is deprecated"):
+ retry = ToolRetryMiddleware(
+ max_retries=2,
+ initial_delay=0.01,
+ jitter=False,
+ on_failure=deprecated_value, # type: ignore[arg-type]
+ )
+
+ agent = create_agent(
+ model=model,
+ tools=[failing_tool],
+ middleware=[retry],
+ checkpointer=InMemorySaver(),
+ )
+
+ result = agent.invoke(
+ {"messages": [HumanMessage("Use failing tool")]},
+ {"configurable": {"thread_id": "test"}},
+ )
+
+ tool_messages = [m for m in result["messages"] if isinstance(m, ToolMessage)]
+ assert len(tool_messages) == 1
+ # Should contain error message (same as 'continue')
+ assert "failing_tool" in tool_messages[0].content
+ assert "3 attempts" in tool_messages[0].content
+ assert "ValueError" in tool_messages[0].content
+ assert tool_messages[0].status == "error"
diff --git a/libs/langchain_v1/uv.lock b/libs/langchain_v1/uv.lock
index c9157176b9..d8cb747db7 100644
--- a/libs/langchain_v1/uv.lock
+++ b/libs/langchain_v1/uv.lock
@@ -2174,7 +2174,7 @@ wheels = [
[[package]]
name = "langchain-core"
-version = "1.0.5"
+version = "1.0.6"
source = { editable = "../core" }
dependencies = [
{ name = "jsonpatch" },
@@ -2395,7 +2395,7 @@ wheels = [
[[package]]
name = "langchain-openai"
-version = "1.0.2"
+version = "1.0.3"
source = { editable = "../partners/openai" }
dependencies = [
{ name = "langchain-core" },