feat: Wokforce support configurable fail handling (#3488)

Author: Wendong-Fan

camel/societies/workforce/__init__.py

@@ -14,7 +14,7 @@
 
 from .role_playing_worker import RolePlayingWorker
 from .single_agent_worker import SingleAgentWorker
-from .utils import PipelineTaskBuilder
+from .utils import FailureHandlingConfig, PipelineTaskBuilder, RecoveryStrategy
 from .workflow_memory_manager import WorkflowSelectionMethod
 from .workforce import Workforce, WorkforceMode
 
@@ -25,4 +25,6 @@
     "SingleAgentWorker",
     "RolePlayingWorker",
     "WorkflowSelectionMethod",
+    "FailureHandlingConfig",
+    "RecoveryStrategy",
 ]

camel/societies/workforce/prompts.py

@@ -333,58 +333,9 @@
 
 **STEP 2: DETERMINE RECOVERY STRATEGY (if quality insufficient)**
 
-If the task quality is insufficient, select the best recovery strategy:
+If the task quality is insufficient, select the best recovery strategy from the ENABLED strategies below:
 
-**Available Strategies:**
-
-1. **retry** - Retry with the same worker and task content
-   - **Best for**:
-     * Network errors, connection timeouts, temporary API issues
-     * Random failures that are likely temporary
-     * Minor quality issues that may resolve on retry
-   - **Not suitable for**:
-     * Fundamental task misunderstandings
-     * Worker capability gaps
-     * Persistent quality problems
-
-2. **reassign** - Assign to a different worker
-   - **Best for**:
-     * Current worker lacks required skills/expertise
-     * Worker-specific quality issues
-     * Task requires different specialization
-   - **Not suitable for**:
-     * Task description is unclear (use replan instead)
-     * Task is too complex (use decompose instead)
-   - **Note**: Only available for quality issues, not failures
-
-3. **replan** - Modify task content with clearer instructions
-   - **Best for**:
-     * Unclear or ambiguous requirements
-     * Missing context or information
-     * Task description needs improvement
-   - **Requirements**:
-     * Provide modified_task_content with enhanced, clear instructions
-     * Modified task must be actionable for an AI agent
-     * Address the root cause identified in issues
-
-4. **decompose** - Break into smaller, manageable subtasks
-   - **Best for**:
-     * Task is too complex for a single worker
-     * Multiple distinct sub-problems exist
-     * Persistent failures despite retries
-     * Capability mismatches that need specialization
-   - **Consider**:
-     * Task depth (avoid if depth > 2)
-     * Whether subtasks can run in parallel
-
-5. **create_worker** - Create new specialized worker
-   - **Best for**:
-     * No existing worker has required capabilities
-     * Need specialized skills not currently available
-   - **Consider**:
-     * Whether decomposition could work instead
-     * Cost of creating new worker vs alternatives
-   - **Note**: Only available for task failures, not quality issues
+{available_strategies}
 
 **DECISION GUIDELINES:**
 
@@ -403,6 +354,7 @@
 - No explanations or text outside the JSON structure
 - Ensure all required fields are included
 - Use null for optional fields when not applicable
+- ONLY use strategies listed above as ENABLED
 """
 )
 
@@ -423,6 +375,52 @@
   "modified_task_content": "new content if replan, else null"
 }"""
 
+# Strategy descriptions for dynamic prompt generation
+STRATEGY_DESCRIPTIONS = {
+    "retry": """**retry** - Retry with the same worker and task content
+   - **Best for**:
+     * Network errors, connection timeouts, temporary API issues
+     * Random failures that are likely temporary
+     * Minor quality issues that may resolve on retry
+   - **Not suitable for**:
+     * Fundamental task misunderstandings
+     * Worker capability gaps
+     * Persistent quality problems""",
+    "reassign": """**reassign** - Assign to a different worker
+   - **Best for**:
+     * Current worker lacks required skills/expertise
+     * Worker-specific issues or errors
+     * Task requires different specialization
+   - **Not suitable for**:
+     * Task description is unclear (use replan instead)
+     * Task is too complex (use decompose instead)""",
+    "replan": """**replan** - Modify task content with clearer instructions
+   - **Best for**:
+     * Unclear or ambiguous requirements
+     * Missing context or information
+     * Task description needs improvement
+   - **Requirements**:
+     * Provide modified_task_content with enhanced, clear instructions
+     * Modified task must be actionable for an AI agent
+     * Address the root cause identified in issues""",
+    "decompose": """**decompose** - Break into smaller, manageable subtasks
+   - **Best for**:
+     * Task is too complex for a single worker
+     * Multiple distinct sub-problems exist
+     * Persistent failures despite retries
+     * Capability mismatches that need specialization
+   - **Consider**:
+     * Task depth (avoid if depth > 2)
+     * Whether subtasks can run in parallel""",
+    "create_worker": """**create_worker** - Create new specialized worker
+   - **Best for**:
+     * No existing worker has required capabilities
+     * Need specialized skills not currently available
+   - **Consider**:
+     * Whether decomposition could work instead
+     * Cost of creating new worker vs alternatives""",
+}
+
 TASK_AGENT_SYSTEM_MESSAGE = """You are an intelligent task management assistant responsible for planning, analyzing, and quality control.
 
 Your responsibilities include:

camel/societies/workforce/utils.py

@@ -224,6 +224,110 @@ def __repr__(self):
         return f"RecoveryStrategy.{self.name}"
 
 
+class FailureHandlingConfig(BaseModel):
+    r"""Configuration for failure handling behavior in Workforce.
+
+    This configuration allows users to customize how the Workforce handles
+    task failures. This config allows users to disable reassignment or other
+    recovery strategies as needed.
+
+    Args:
+        max_retries (int): Maximum number of retry attempts before giving up
+            on a task. (default: :obj:`3`)
+        enabled_strategies (Optional[List[RecoveryStrategy]]): List of recovery
+            strategies that are allowed to be used. Can be specified as
+            RecoveryStrategy enums or strings (e.g., ["retry", "replan"]).
+            If None, all strategies are enabled (with LLM analysis).
+            If an empty list, no recovery strategies are applied and failed
+            tasks are marked as failed immediately. If only ["retry"] is
+            specified, simple retry is used without LLM analysis.
+            (default: :obj:`None` - all strategies enabled)
+        halt_on_max_retries (bool): Whether to halt the entire workforce
+            when a task exceeds max retries. If False, the task is marked
+            as failed and the workflow continues (similar to PIPELINE mode
+            behavior). (default: :obj:`True` for AUTO_DECOMPOSE mode behavior)
+
+    Example:
+        >>> # Using string list (simple)
+        >>> config = FailureHandlingConfig(
+        ...     enabled_strategies=["retry", "replan", "decompose"],
+        ... )
+        >>>
+        >>> # Using enum list
+        >>> config = FailureHandlingConfig(
+        ...     enabled_strategies=[
+        ...         RecoveryStrategy.RETRY,
+        ...         RecoveryStrategy.REPLAN,
+        ...     ]
+        ... )
+        >>>
+        >>> # Simple retry only
+        >>> config = FailureHandlingConfig(
+        ...     enabled_strategies=["retry"],
+        ...     max_retries=2,
+        ... )
+        >>>
+        >>> # No recovery - failed tasks are immediately marked as failed
+        >>> config = FailureHandlingConfig(
+        ...     enabled_strategies=[],
+        ... )
+        >>>
+        >>> # Allow failures without halting
+        >>> config = FailureHandlingConfig(
+        ...     halt_on_max_retries=False,
+        ... )
+    """
+
+    max_retries: int = Field(
+        default=3,
+        ge=1,
+        description="Maximum retry attempts before giving up on a task",
+    )
+
+    enabled_strategies: Optional[List[RecoveryStrategy]] = Field(
+        default=None,
+        description="List of enabled recovery strategies. None means all "
+        "enabled. Empty list means no recovery (immediate failure). "
+        "Can be strings like ['retry', 'replan'] or RecoveryStrategy enums.",
+    )
+
+    halt_on_max_retries: bool = Field(
+        default=True,
+        description="Whether to halt workforce when max retries exceeded",
+    )
+
+    @field_validator("enabled_strategies", mode="before")
+    @classmethod
+    def validate_enabled_strategies(
+        cls, v
+    ) -> Optional[List[RecoveryStrategy]]:
+        r"""Convert string list to RecoveryStrategy enum list."""
+        if v is None:
+            return None
+        if not isinstance(v, list):
+            raise ValueError("enabled_strategies must be a list or None")
+
+        result = []
+        for item in v:
+            if isinstance(item, RecoveryStrategy):
+                result.append(item)
+            elif isinstance(item, str):
+                try:
+                    result.append(RecoveryStrategy(item.lower()))
+                except ValueError:
+                    valid = [s.value for s in RecoveryStrategy]
+                    raise ValueError(
+                        f"Invalid strategy '{item}'. "
+                        f"Valid options: {valid}"
+                    )
+            else:
+                raise ValueError(
+                    f"Strategy must be string or RecoveryStrategy, "
+                    f"got {type(item).__name__}"
+                )
+        return result
+
+
 class FailureContext(BaseModel):
     r"""Context information about a task failure."""