agno 2.4.6__py3-none-any.whl → 2.4.8__py3-none-any.whl

agno/workflow/loop.py

@@ -3,6 +3,7 @@ from dataclasses import dataclass
 from typing import Any, AsyncIterator, Awaitable, Callable, Dict, Iterator, List, Optional, Union
 from uuid import uuid4
 
+from agno.registry import Registry
 from agno.run.agent import RunOutputEvent
 from agno.run.base import RunContext
 from agno.run.team import TeamRunOutputEvent
@@ -16,6 +17,7 @@ from agno.run.workflow import (
 )
 from agno.session.workflow import WorkflowSession
 from agno.utils.log import log_debug, logger
+from agno.workflow.cel import CEL_AVAILABLE, evaluate_cel_loop_end_condition, is_cel_expression
 from agno.workflow.step import Step
 from agno.workflow.types import StepInput, StepOutput, StepType
 
@@ -36,7 +38,27 @@ WorkflowSteps = List[
 
 @dataclass
 class Loop:
-    """A loop of steps that execute in order"""
+    """A loop of steps that execute in order.
+
+    The end_condition can be:
+        - A callable function that takes List[StepOutput] and returns bool
+        - A CEL (Common Expression Language) expression string
+        - None (loop runs for max_iterations)
+
+    CEL expressions for end_condition have access to:
+        - current_iteration: Current iteration number (1-indexed, after completion)
+        - max_iterations: Maximum iterations configured for the loop
+        - all_success: Boolean - True if all steps in this iteration succeeded
+        - last_step_content: Content string from the last step in the iteration
+        - step_outputs: Map of step name to content string from the current iteration
+
+    Example CEL expressions:
+        - 'current_iteration >= 2'
+        - 'current_iteration >= max_iterations'
+        - 'all_success'
+        - 'last_step_content.contains("DONE")'
+        - 'all_success && current_iteration >= 2'
+    """
 
     steps: WorkflowSteps
 
@@ -44,7 +66,7 @@ class Loop:
     description: Optional[str] = None
 
     max_iterations: int = 3  # Default to 3
-    end_condition: Optional[Callable[[List[StepOutput]], bool]] = None
+    end_condition: Optional[Union[Callable[[List[StepOutput]], bool], str]] = None
 
     def __init__(
         self,
@@ -52,7 +74,7 @@ class Loop:
         name: Optional[str] = None,
         description: Optional[str] = None,
         max_iterations: int = 3,
-        end_condition: Optional[Callable[[List[StepOutput]], bool]] = None,
+        end_condition: Optional[Union[Callable[[List[StepOutput]], bool], str]] = None,
     ):
         self.steps = steps
         self.name = name
@@ -60,6 +82,142 @@ class Loop:
         self.max_iterations = max_iterations
         self.end_condition = end_condition
 
+    def to_dict(self) -> Dict[str, Any]:
+        result: Dict[str, Any] = {
+            "type": "Loop",
+            "name": self.name,
+            "description": self.description,
+            "steps": [step.to_dict() for step in self.steps if hasattr(step, "to_dict")],
+            "max_iterations": self.max_iterations,
+        }
+        # Serialize end_condition
+        if self.end_condition is None:
+            result["end_condition"] = None
+            result["end_condition_type"] = None
+        elif isinstance(self.end_condition, str):
+            result["end_condition"] = self.end_condition
+            result["end_condition_type"] = "cel"
+        elif callable(self.end_condition):
+            result["end_condition"] = self.end_condition.__name__
+            result["end_condition_type"] = "function"
+        else:
+            raise ValueError(f"Invalid end_condition type: {type(self.end_condition).__name__}")
+
+        return result
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: Dict[str, Any],
+        registry: Optional["Registry"] = None,
+        db: Optional[Any] = None,
+        links: Optional[List[Dict[str, Any]]] = None,
+    ) -> "Loop":
+        from agno.workflow.condition import Condition
+        from agno.workflow.parallel import Parallel
+        from agno.workflow.router import Router
+        from agno.workflow.steps import Steps
+
+        def deserialize_step(step_data: Dict[str, Any]) -> Any:
+            step_type = step_data.get("type", "Step")
+            if step_type == "Loop":
+                return cls.from_dict(step_data, registry=registry, db=db, links=links)
+            elif step_type == "Parallel":
+                return Parallel.from_dict(step_data, registry=registry, db=db, links=links)
+            elif step_type == "Steps":
+                return Steps.from_dict(step_data, registry=registry, db=db, links=links)
+            elif step_type == "Condition":
+                return Condition.from_dict(step_data, registry=registry, db=db, links=links)
+            elif step_type == "Router":
+                return Router.from_dict(step_data, registry=registry, db=db, links=links)
+            else:
+                return Step.from_dict(step_data, registry=registry, db=db, links=links)
+
+        # Deserialize end_condition
+        end_condition_data = data.get("end_condition")
+        end_condition_type = data.get("end_condition_type")
+        end_condition: Optional[Union[Callable[[List[StepOutput]], bool], str]] = None
+
+        if end_condition_data is None:
+            end_condition = None
+        elif isinstance(end_condition_data, str):
+            if end_condition_type == "cel" or (end_condition_type is None and is_cel_expression(end_condition_data)):
+                end_condition = end_condition_data
+            else:
+                if registry:
+                    end_condition = registry.get_function(end_condition_data)
+                    if end_condition is None:
+                        raise ValueError(f"End condition function '{end_condition_data}' not found in registry")
+                else:
+                    raise ValueError(f"Registry required to deserialize end_condition function '{end_condition_data}'")
+
+        return cls(
+            name=data.get("name"),
+            description=data.get("description"),
+            steps=[deserialize_step(step) for step in data.get("steps", [])],
+            max_iterations=data.get("max_iterations", 3),
+            end_condition=end_condition,
+        )
+
+    def _evaluate_end_condition(self, iteration_results: List[StepOutput], current_iteration: int = 0) -> bool:
+        """Evaluate the end condition and return whether the loop should stop."""
+        if self.end_condition is None:
+            return False
+
+        if isinstance(self.end_condition, str):
+            if not CEL_AVAILABLE:
+                logger.error(
+                    "CEL expression used but cel-python is not installed. Install with: pip install cel-python"
+                )
+                return False
+            try:
+                return evaluate_cel_loop_end_condition(
+                    self.end_condition, iteration_results, current_iteration, self.max_iterations
+                )
+            except Exception as e:
+                logger.warning(f"CEL end condition evaluation failed: {e}")
+                return False
+
+        if callable(self.end_condition):
+            try:
+                return self.end_condition(iteration_results)
+            except Exception as e:
+                logger.warning(f"End condition evaluation failed: {e}")
+                return False
+
+        return False
+
+    async def _aevaluate_end_condition(self, iteration_results: List[StepOutput], current_iteration: int = 0) -> bool:
+        """Async evaluate the end condition."""
+        if self.end_condition is None:
+            return False
+
+        if isinstance(self.end_condition, str):
+            if not CEL_AVAILABLE:
+                logger.error(
+                    "CEL expression used but cel-python is not installed. Install with: pip install cel-python"
+                )
+                return False
+            try:
+                return evaluate_cel_loop_end_condition(
+                    self.end_condition, iteration_results, current_iteration, self.max_iterations
+                )
+            except Exception as e:
+                logger.warning(f"CEL end condition evaluation failed: {e}")
+                return False
+
+        if callable(self.end_condition):
+            try:
+                if inspect.iscoroutinefunction(self.end_condition):
+                    return await self.end_condition(iteration_results)
+                else:
+                    return self.end_condition(iteration_results)
+            except Exception as e:
+                logger.warning(f"End condition evaluation failed: {e}")
+                return False
+
+        return False
+
     def _prepare_steps(self):
         """Prepare the steps for execution - mirrors workflow logic"""
         from agno.agent.agent import Agent
@@ -204,13 +362,8 @@ class Loop:
             iteration += 1
 
             # Check end condition
-            if self.end_condition and callable(self.end_condition):
-                try:
-                    should_break = self.end_condition(iteration_results)
-                    if should_break:
-                        break
-                except Exception as e:
-                    logger.warning(f"End condition evaluation failed: {e}")
+            if self._evaluate_end_condition(iteration_results, iteration):
+                break
 
             # Break out of iteration loop if early termination was requested
             if early_termination:
@@ -365,16 +518,13 @@ class Loop:
                         )
 
             all_results.append(iteration_results)
+            iteration += 1
 
             # Check end condition
             should_continue = True
-            if self.end_condition and callable(self.end_condition):
-                try:
-                    should_break = self.end_condition(iteration_results)
-                    should_continue = not should_break
-                    log_debug(f"End condition returned: {should_break}, should_continue: {should_continue}")
-                except Exception as e:
-                    logger.warning(f"End condition evaluation failed: {e}")
+            if self._evaluate_end_condition(iteration_results, iteration):
+                should_continue = False
+                log_debug("End condition met, loop will stop")
 
             if early_termination:
                 should_continue = False
@@ -389,7 +539,7 @@ class Loop:
                     session_id=workflow_run_response.session_id or "",
                     step_name=self.name,
                     step_index=step_index,
-                    iteration=iteration + 1,
+                    iteration=iteration,
                     max_iterations=self.max_iterations,
                     iteration_results=iteration_results,
                     should_continue=should_continue,
@@ -397,10 +547,8 @@ class Loop:
                     parent_step_id=parent_step_id,
                 )
 
-            iteration += 1
-
             if not should_continue:
-                log_debug(f"Loop ending early due to end_condition at iteration {iteration}")
+                log_debug(f"Loop ending early at iteration {iteration}")
                 break
 
         log_debug(f"Loop End: {self.name} ({iteration} iterations)", center=True, symbol="=")
@@ -515,23 +663,14 @@ class Loop:
             iteration += 1
 
             # Check end condition
-            if self.end_condition and callable(self.end_condition):
-                try:
-                    if inspect.iscoroutinefunction(self.end_condition):
-                        should_break = await self.end_condition(iteration_results)
-                    else:
-                        should_break = self.end_condition(iteration_results)
-                    if should_break:
-                        break
-                except Exception as e:
-                    logger.warning(f"End condition evaluation failed: {e}")
+            if await self._aevaluate_end_condition(iteration_results, iteration):
+                break
 
             # Break out of iteration loop if early termination was requested
             if early_termination:
                 log_debug(f"Loop ending early due to step termination request at iteration {iteration}")
                 break
 
-        # Use workflow logger for async loop completion
         log_debug(f"Async Loop End: {self.name} ({iteration} iterations)", center=True, symbol="=")
 
         # Return flattened results from all iterations
@@ -680,19 +819,13 @@ class Loop:
                         )
 
             all_results.append(iteration_results)
+            iteration += 1
 
             # Check end condition
             should_continue = True
-            if self.end_condition and callable(self.end_condition):
-                try:
-                    if inspect.iscoroutinefunction(self.end_condition):
-                        should_break = await self.end_condition(iteration_results)
-                    else:
-                        should_break = self.end_condition(iteration_results)
-                    should_continue = not should_break
-                    log_debug(f"End condition returned: {should_break}, should_continue: {should_continue}")
-                except Exception as e:
-                    logger.warning(f"End condition evaluation failed: {e}")
+            if await self._aevaluate_end_condition(iteration_results, iteration):
+                should_continue = False
+                log_debug("End condition met, loop will stop")
 
             if early_termination:
                 should_continue = False
@@ -707,7 +840,7 @@ class Loop:
                     session_id=workflow_run_response.session_id or "",
                     step_name=self.name,
                     step_index=step_index,
-                    iteration=iteration + 1,
+                    iteration=iteration,
                     max_iterations=self.max_iterations,
                     iteration_results=iteration_results,
                     should_continue=should_continue,
@@ -715,10 +848,8 @@ class Loop:
                     parent_step_id=parent_step_id,
                 )
 
-            iteration += 1
-
             if not should_continue:
-                log_debug(f"Loop ending early due to end_condition at iteration {iteration}")
+                log_debug(f"Loop ending early at iteration {iteration}")
                 break
 
         log_debug(f"Loop End: {self.name} ({iteration} iterations)", center=True, symbol="=")

agno/workflow/parallel.py

@@ -7,6 +7,7 @@ from typing import Any, AsyncIterator, Awaitable, Callable, Dict, Iterator, List
 from uuid import uuid4
 
 from agno.models.metrics import Metrics
+from agno.registry import Registry
 from agno.run.agent import RunOutputEvent
 from agno.run.base import RunContext
 from agno.run.team import TeamRunOutputEvent
@@ -40,7 +41,16 @@ WorkflowSteps = List[
 
 @dataclass
 class Parallel:
-    """A list of steps that execute in parallel"""
+    """A list of steps that execute in parallel.
+
+    Unlike sequential constructs (Steps, Loop), Parallel uses variadic arguments
+    to emphasize that the steps are independent and unordered.
+
+    Supports flexible calling conventions:
+        Parallel(step1, step2, step3)                      # Steps only (name defaults to "Parallel")
+        Parallel(step1, step2, name="my_parallel")         # Name as keyword (at end)
+        Parallel("my_parallel", step1, step2)              # Name as first positional arg
+    """
 
     steps: WorkflowSteps
 
@@ -49,14 +59,75 @@ class Parallel:
 
     def __init__(
         self,
-        *steps: WorkflowSteps,
+        *args: Union[str, WorkflowSteps],
         name: Optional[str] = None,
         description: Optional[str] = None,
     ):
-        self.steps = list(steps)
-        self.name = name
+        resolved_name = name
+        resolved_steps: List[Any] = []
+
+        if args:
+            first_arg = args[0]
+            # Check if first argument is a plain string (likely a name, not a step)
+            if isinstance(first_arg, str):
+                # First arg is the name, rest are steps
+                resolved_name = first_arg
+                resolved_steps = list(args[1:])
+            else:
+                # All args are steps
+                resolved_steps = list(args)
+
+        # If name was provided as keyword, it takes precedence
+        if name is not None:
+            resolved_name = name
+
+        self.steps = resolved_steps
+        self.name = resolved_name
         self.description = description
 
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "type": "Parallel",
+            "name": self.name,
+            "description": self.description,
+            "steps": [step.to_dict() for step in self.steps if hasattr(step, "to_dict")],
+        }
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: Dict[str, Any],
+        registry: Optional["Registry"] = None,
+        db: Optional[Any] = None,
+        links: Optional[List[Dict[str, Any]]] = None,
+    ) -> "Parallel":
+        from agno.workflow.condition import Condition
+        from agno.workflow.loop import Loop
+        from agno.workflow.router import Router
+        from agno.workflow.steps import Steps
+
+        def deserialize_step(step_data: Dict[str, Any]) -> Any:
+            step_type = step_data.get("type", "Step")
+            if step_type == "Loop":
+                return Loop.from_dict(step_data, registry=registry, db=db, links=links)
+            elif step_type == "Parallel":
+                return cls.from_dict(step_data, registry=registry, db=db, links=links)
+            elif step_type == "Steps":
+                return Steps.from_dict(step_data, registry=registry, db=db, links=links)
+            elif step_type == "Condition":
+                return Condition.from_dict(step_data, registry=registry, db=db, links=links)
+            elif step_type == "Router":
+                return Router.from_dict(step_data, registry=registry, db=db, links=links)
+            else:
+                return Step.from_dict(step_data, registry=registry, db=db, links=links)
+
+        deserialized_steps = [deserialize_step(step) for step in data.get("steps", [])]
+        return cls(
+            *deserialized_steps,
+            name=data.get("name"),
+            description=data.get("description"),
+        )
+
     def _prepare_steps(self):
         """Prepare the steps for execution - mirrors workflow logic"""
         from agno.agent.agent import Agent