fix: Agent runtime lacks structured retry/backoff for tool failures

src/praisonai-agents/praisonaiagents/__init__.py

@@ -380,6 +380,7 @@ def _get_lazy_cache():
     'CachingConfig': ('praisonaiagents.config.feature_configs', 'CachingConfig'),
     'HooksConfig': ('praisonaiagents.config.feature_configs', 'HooksConfig'),
     'SkillsConfig': ('praisonaiagents.config.feature_configs', 'SkillsConfig'),
+    'ToolRetryConfig': ('praisonaiagents.config.feature_configs', 'ToolRetryConfig'),
     'AutonomyConfig': ('praisonaiagents.agent.autonomy', 'AutonomyConfig'),
     'EscalationStage': ('praisonaiagents.escalation.types', 'EscalationStage'),
     'EscalationPipeline': ('praisonaiagents.escalation.pipeline', 'EscalationPipeline'),

src/praisonai-agents/praisonaiagents/agent/agent.py

@@ -597,6 +597,7 @@ def __init__(
         interrupt_controller: Optional['InterruptController'] = None,  # G2: Cooperative cancellation
         tool_search: Optional[Union[bool, str, Dict[str, Any], 'ToolSearchConfig']] = False,  # Progressive tool disclosure
         message_steering: Optional[Union[bool, 'MessageSteeringProtocol']] = False,  # Real-time message steering during execution
+        tool_retry_config: Optional['ToolRetryConfig'] = None,  # Automatic retry/backoff for tool failures
         sandbox: Optional[Union[bool, 'SandboxConfig']] = None,  # Sandbox for safe code execution
         retry: Optional[Union[bool, Dict[str, Any], 'RetryBackoffConfig']] = None,  # Retry configuration with exponential backoff
     ):
@@ -713,6 +714,10 @@ def __init__(
                 When enabled, replaces large tool schemas with bridge tools (tool_search,
                 tool_describe, tool_call) to save context. Core SDK tools never defer.
                 Auto mode activates based on token threshold. Opt-in feature.
+            tool_retry_config: Automatic retry with exponential backoff for transient tool failures.
+                When configured, retryable ToolExecutionErrors (network timeouts, rate limits,
+                external service errors) will automatically retry before surfacing to the model.
+                Default: None (no retry, preserves current behavior). Accepts ToolRetryConfig instance.
 
         Raises:
             ValueError: If all of name, role, goal, backstory, and instructions are None.
@@ -1513,6 +1518,26 @@ def __init__(
                     "tool_search must be False/None, True, a mode string, "
                     "a dict of ToolSearchConfig fields, or ToolSearchConfig"
                 )
+
+        # ─────────────────────────────────────────────────────────────────────
+        # Resolve TOOL_RETRY_CONFIG param  
+        # ─────────────────────────────────────────────────────────────────────
+        # Support bool/dict for API consistency with other params
+        if tool_retry_config is None or tool_retry_config is False:
+            self.tool_retry_config = None
+        elif tool_retry_config is True:
+            from ..config import ToolRetryConfig
+            self.tool_retry_config = ToolRetryConfig()
+        elif isinstance(tool_retry_config, dict):
+            from ..config import ToolRetryConfig
+            self.tool_retry_config = ToolRetryConfig(**tool_retry_config)
+        else:
+            # Validate it's a ToolRetryConfig instance
+            from ..config import ToolRetryConfig
+            if isinstance(tool_retry_config, ToolRetryConfig):
+                self.tool_retry_config = tool_retry_config
+            else:
+                raise TypeError("tool_retry_config must be None, bool, dict, or ToolRetryConfig instance")
 
         # Process tool_config and artifact storage (moved from tool_output)
         self._artifact_store = None

src/praisonai-agents/praisonaiagents/agent/tool_execution_fixed.py

@@ -0,0 +1,132 @@
+"""
+Tool execution mixin for the Agent class.
+
+Contains all methods for tool resolution, execution, approval,
+cost tracking, and hook integration. Extracted from agent.py
+for maintainability.
+"""
+
+import os
+import time
+import json
+import logging
+import asyncio
+import inspect
+import contextvars
+import concurrent.futures
+import random
+from typing import List, Optional, Any, Dict, Union, TYPE_CHECKING
+from ..errors import ToolExecutionError
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    pass
+
+
+class ToolExecutionMixin:
+    """Mixin providing tool execution methods for the Agent class."""
+
+    def _get_existing_stream_emitter(self):
+        """Return an already-initialized stream emitter without creating one."""
+        emitter = getattr(self, "_stream_emitter", None)
+        if emitter is not None:
+            return emitter
+
+        # Support name-mangled private attributes across class renames/inheritance.
+        for cls in type(self).mro():
+            mangled = f"_{cls.__name__}__stream_emitter"
+            if hasattr(self, mangled):
+                emitter = getattr(self, mangled, None)
+                if emitter is not None:
+                    return emitter
+        return None
+
+    def _resolve_tool_names(self, tool_names):
+        """Resolve tool names to actual tool instances from registry.
+
+        Args:
+            tool_names: List of tool name strings
+
+        Returns:
+            List of resolved tool instances
+        """
+        resolved = []
+        try:
+            from ..tools.registry import get_registry
+            registry = get_registry()
+
+            for name in tool_names:
+                tool = registry.get(name)
+                if tool is not None:
+                    resolved.append(tool)
+                else:
+                    logging.warning(f"Tool '{name}' not found in registry")
+        except ImportError:
+            logging.warning("Tool registry not available, cannot resolve tool names")
+
+        return resolved
+
+    def _cast_arguments(self, func, arguments):
+        """Cast arguments to their expected types based on function signature."""
+        if not callable(func) or not arguments:
+            return arguments
+
+        try:
+            sig = inspect.signature(func)
+            valid_params = set(sig.parameters.keys()) - {'self'}
+            casted_args = {}
+
+            # Sanitize argument names: strip trailing '=', whitespace, and
+            # other invalid chars that LLMs sometimes hallucinate in kwarg names
+            sanitized = {}
+            for raw_name, arg_value in arguments.items():
+                clean = raw_name.strip().rstrip('=').strip()
+                # If the cleaned name matches a valid param, use it;
+                # otherwise try case-insensitive match
+                if clean in valid_params:
+                    sanitized[clean] = arg_value
+                elif clean.lower() in {p.lower() for p in valid_params}:
+                    # Case-insensitive fuzzy match
+                    matched = next(p for p in valid_params if p.lower() == clean.lower())
+                    sanitized[matched] = arg_value
+                else:
+                    sanitized[clean] = arg_value
+            arguments = sanitized
+
+            for param_name, arg_value in arguments.items():
+                if param_name in sig.parameters:
+                    param = sig.parameters[param_name]
+                    if param.annotation != inspect.Parameter.empty:
+                        # Try to cast to the expected type
+                        annotation = param.annotation
+                        # Handle Optional types
+                        if hasattr(annotation, '__origin__'):
+                            if annotation.__origin__ is Union:
+                                # Get non-None type from Union
+                                types = [t for t in annotation.__args__ if t != type(None)]
+                                if types:
+                                    annotation = types[0]
+
+                        # Cast if it's a basic type
+                        if annotation in (int, float, str, bool):
+                            try:
+                                if annotation is bool and isinstance(arg_value, str):
+                                    # Special handling for bool strings
+                                    casted_args[param_name] = arg_value.lower() in ('true', '1', 'yes')
+                                else:
+                                    casted_args[param_name] = annotation(arg_value)
+                            except (ValueError, TypeError):
+                                casted_args[param_name] = arg_value
+                        else:
+                            casted_args[param_name] = arg_value
+                    else:
+                        casted_args[param_name] = arg_value
+                else:
+                    # Keep unexpected parameters as is (function may use **kwargs)
+                    casted_args[param_name] = arg_value
+
+            return casted_args
+        except Exception:
+            # If signature inspection fails, return arguments as is
+            return arguments

src/praisonai-agents/praisonaiagents/config/__init__.py

@@ -41,6 +41,7 @@
     "HooksConfig",
     "SkillsConfig",
     "ToolSearchConfig",
+    "ToolRetryConfig",
     # Type aliases
     "MemoryParam",
     "KnowledgeParam",
@@ -126,6 +127,7 @@
     "HooksConfig": "feature_configs",
     "SkillsConfig": "feature_configs",
     "ToolSearchConfig": "feature_configs",
+    "ToolRetryConfig": "feature_configs",
     "MemoryParam": "feature_configs",
     "KnowledgeParam": "feature_configs",
     "PlanningParam": "feature_configs",

src/praisonai-agents/praisonaiagents/config/feature_configs.py

@@ -1361,6 +1361,81 @@ class AutonomyLevel(str, Enum):
     AUTO_EDIT = "auto_edit"
     FULL_AUTO = "full_auto"
 
+
+@dataclass
+class ToolRetryConfig:
+    """
+    Configuration for automatic retry with exponential backoff on tool failures.
+
+    Provides structured retry/backoff for transient tool failures like network 
+    timeouts, rate limits, and external service errors. When enabled, retryable 
+    ToolExecutionErrors will automatically retry with configurable exponential 
+    backoff before surfacing to the model.
+
+    Usage:
+        # Simple enable with defaults
+        agent = Agent(tool_retry_config=ToolRetryConfig())
+
+        # Custom configuration 
+        agent = Agent(
+            tool_retry_config=ToolRetryConfig(
+                max_attempts=5,
+                initial_delay_s=2.0,
+                max_delay_s=60.0,
+                factor=3.0,
+                jitter=0.2,
+                retryable_on=["network", "timeout", "rate_limit"],
+            )
+        )
+
+        # Disable (default)
+        agent = Agent(tool_retry_config=None)
+    """
+    # Maximum retry attempts (including initial attempt)
+    max_attempts: int = 3
+
+    # Initial delay in seconds before first retry
+    initial_delay_s: float = 1.0
+
+    # Maximum delay cap in seconds
+    max_delay_s: float = 30.0
+
+    # Exponential backoff factor
+    factor: float = 2.0
+
+    # Random jitter factor (0-1) to avoid thundering herd
+    jitter: float = 0.1
+
+    # Error categories to retry on (maps to ToolExecutionError.error_category)
+    retryable_on: List[str] = field(default_factory=lambda: ["network", "timeout", "rate_limit"])
+
+    def __post_init__(self):
+        """Validate configuration parameters."""
+        if self.max_attempts < 1:
+            raise ValueError("max_attempts must be at least 1")
+        if self.initial_delay_s <= 0:
+            raise ValueError("initial_delay_s must be positive")
+        if self.max_delay_s <= 0:
+            raise ValueError("max_delay_s must be positive")
+        if self.initial_delay_s > self.max_delay_s:
+            raise ValueError("initial_delay_s cannot be greater than max_delay_s")
+        if self.factor < 1.0:
+            raise ValueError("factor must be >= 1.0 for exponential backoff")
+        if not 0 <= self.jitter <= 1.0:
+            raise ValueError("jitter must be between 0 and 1")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "max_attempts": self.max_attempts,
+            "initial_delay_s": self.initial_delay_s,
+            "max_delay_s": self.max_delay_s,
+            "factor": self.factor,
+            "jitter": self.jitter,
+            "retryable_on": self.retryable_on,
+        }
+
+
 # Type aliases for Union types used in Agent.__init__
 MemoryParam = Union[bool, MemoryConfig, Any]  # Any = MemoryManager instance
 KnowledgeParam = Union[bool, List[str], KnowledgeConfig, Any]  # Any = KnowledgeBase instance
@@ -1582,6 +1657,7 @@ def resolve_tools(value: ToolParam) -> Optional[ToolConfig]:
     "SkillsConfig",
     "AutonomyConfig",
     "ToolSearchConfig",
+    "ToolRetryConfig",
     # Config classes (Multi-Agent)
     "MultiAgentHooksConfig",
     "MultiAgentOutputConfig",

src/praisonai-agents/praisonaiagents/hooks/events.py

@@ -180,18 +180,17 @@ def to_dict(self) -> Dict[str, Any]:
 class OnRetryInput(HookInput):
     """Input for OnRetry hooks fired during tool execution retries."""
     tool_name: str = ""
-    attempt: int = 1
+    attempt: int = 1  # Current attempt number (1-based)
     delay_ms: int = 0
-    error: str = ""
-    max_attempts: int = 0
+    error: str = ""  # Error message from failed attempt
+    max_attempts: int = 0  # Total max attempts
     error_type: str = "unknown"
     # Legacy fields for backward compatibility
     retry_count: int = 0
     max_retries: int = 3
     error_message: str = ""
     operation: str = ""  # tool_call, llm_request, etc.
-    delay_seconds: float = 0.0  # Delay before retry
-    attempt: int = 0  # Current attempt number (0-based)
+    retry_delay_seconds: float = 0.0  # Calculated delay before next retry
 
     def to_dict(self) -> Dict[str, Any]:
         base = super().to_dict()
@@ -202,13 +201,12 @@ def to_dict(self) -> Dict[str, Any]:
             "error": self.error,
             "max_attempts": self.max_attempts,
             "error_type": self.error_type,
+            "retry_delay_seconds": self.retry_delay_seconds,
             # Legacy fields
             "retry_count": self.retry_count,
             "max_retries": self.max_retries,
             "error_message": self.error_message,
-            "operation": self.operation,
-            "delay_seconds": self.delay_seconds,
-            "attempt": self.attempt
+            "operation": self.operation
         })
         return base