agno 2.1.2__py3-none-any.whl → 2.3.13__py3-none-any.whl

agno/workflow/agent.py

@@ -0,0 +1,299 @@
+"""WorkflowAgent - A restricted Agent for workflow orchestration"""
+
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+from agno.agent import Agent
+from agno.models.base import Model
+from agno.run import RunContext
+from agno.workflow.types import WebSocketHandler
+
+if TYPE_CHECKING:
+    from agno.session.workflow import WorkflowSession
+    from agno.workflow.types import WorkflowExecutionInput
+
+
+class WorkflowAgent(Agent):
+    """
+    A restricted Agent class specifically designed for workflow orchestration.
+    This agent can:
+    1. Decide whether to run the workflow or answer directly from history
+    2. Call the workflow execution tool when needed
+    3. Access workflow session history for context
+    Restrictions:
+    - Only model configuration allowed
+    - No custom tools (tools are set by workflow)
+    - No knowledge base
+    - Limited configuration options
+    """
+
+    def __init__(
+        self,
+        model: Model,
+        instructions: Optional[str] = None,
+        add_workflow_history: bool = True,
+        num_history_runs: int = 5,
+    ):
+        """
+        Initialize WorkflowAgent with restricted parameters.
+        Args:
+            model: The model to use for the agent (required)
+            instructions: Custom instructions (will be combined with workflow context)
+            add_workflow_history: Whether to add workflow history to context (default: True)
+            num_history_runs: Number of previous workflow runs to include in context (default: 5)
+        """
+        self.add_workflow_history = add_workflow_history
+
+        default_instructions = """You are a workflow orchestration agent. Your job is to help users by either:
+1. **Answering directly** from the workflow history context if the question can be answered from previous runs
+2. **Running the workflow** by calling the run_workflow tool ONCE when you need to process a new query
+
+Guidelines:
+- ALWAYS check the workflow history first before calling the tool
+- Answer directly from history if:
+    * The user asks about something already in history
+    * The user asks for comparisons/analysis of things in history (e.g., "compare X and Y")
+    * The user asks follow-up questions about previous results
+- Only call the run_workflow tool for NEW topics not covered in history
+- IMPORTANT: Do NOT call the tool multiple times. Call it once and use the result.
+- Keep your responses concise and helpful
+- When you must call the workflow, pass a clear and concise query
+
+{workflow_context}
+"""
+
+        if instructions:
+            if "{workflow_context}" not in instructions:
+                # Add the workflow context placeholder
+                final_instructions = f"{instructions}\n\n{{workflow_context}}"
+            else:
+                final_instructions = instructions
+        else:
+            final_instructions = default_instructions
+
+        super().__init__(
+            model=model,
+            instructions=final_instructions,
+            resolve_in_context=True,
+            num_history_runs=num_history_runs,
+        )
+
+    def create_workflow_tool(
+        self,
+        workflow: "Any",  # Workflow type
+        session: "WorkflowSession",
+        execution_input: "WorkflowExecutionInput",
+        run_context: RunContext,
+        stream: bool = False,
+    ) -> Callable:
+        """
+        Create the workflow execution tool that this agent can call.
+        This is similar to how Agent has search_knowledge_base() method.
+        Args:
+            workflow: The workflow instance
+            session: The workflow session
+            execution_input: The execution input
+            run_context: The run context
+            stream: Whether to stream the workflow execution
+        Returns:
+            Callable tool function
+        """
+        from datetime import datetime
+        from uuid import uuid4
+
+        from pydantic import BaseModel
+
+        from agno.run.workflow import WorkflowRunOutput
+        from agno.utils.log import log_debug
+        from agno.workflow.types import WorkflowExecutionInput
+
+        def run_workflow(query: str):
+            """
+            Execute the complete workflow with the given query.
+            Use this tool when you need to run the workflow to answer the user's question.
+
+            Args:
+                query: The input query/question to process through the workflow
+            Returns:
+                The workflow execution result (str in non-streaming, generator in streaming)
+            """
+            # Reload session to get latest data from database
+            # This ensures we don't overwrite any updates made after the tool was created
+            session_from_db = workflow.get_session(session_id=session.session_id)
+            if session_from_db is None:
+                session_from_db = session  # Fallback to closure session if reload fails
+                log_debug(f"Fallback to closure session: {len(session_from_db.runs or [])} runs")
+            else:
+                log_debug(f"Reloaded session before tool execution: {len(session_from_db.runs or [])} runs")
+
+            # Create a new run ID for this execution
+            run_id = str(uuid4())
+
+            workflow_run_response = WorkflowRunOutput(
+                run_id=run_id,
+                input=execution_input.input,  # Use original user input
+                session_id=session_from_db.session_id,
+                workflow_id=workflow.id,
+                workflow_name=workflow.name,
+                created_at=int(datetime.now().timestamp()),
+            )
+
+            workflow_execution_input = WorkflowExecutionInput(
+                input=query,  # Agent's refined query for execution
+                additional_data=execution_input.additional_data,
+                audio=execution_input.audio,
+                images=execution_input.images,
+                videos=execution_input.videos,
+                files=execution_input.files,
+            )
+
+            # ===== EXECUTION LOGIC (Based on streaming mode) =====
+            if stream:
+                final_content = ""
+                for event in workflow._execute_stream(
+                    session=session_from_db,
+                    run_context=run_context,
+                    execution_input=workflow_execution_input,
+                    workflow_run_response=workflow_run_response,
+                    stream_events=True,
+                ):
+                    yield event
+
+                    # Capture final content from WorkflowCompletedEvent
+                    from agno.run.workflow import WorkflowCompletedEvent
+
+                    if isinstance(event, WorkflowCompletedEvent):
+                        final_content = str(event.content) if event.content else ""
+
+                return final_content
+            else:
+                # NON-STREAMING MODE: Execute synchronously
+                result = workflow._execute(
+                    session=session_from_db,
+                    execution_input=workflow_execution_input,
+                    workflow_run_response=workflow_run_response,
+                    run_context=run_context,
+                )
+
+                if isinstance(result.content, str):
+                    return result.content
+                elif isinstance(result.content, BaseModel):
+                    return result.content.model_dump_json(exclude_none=True)
+                else:
+                    return str(result.content)
+
+        return run_workflow
+
+    def async_create_workflow_tool(
+        self,
+        workflow: "Any",  # Workflow type
+        session: "WorkflowSession",
+        execution_input: "WorkflowExecutionInput",
+        run_context: RunContext,
+        stream: bool = False,
+        websocket_handler: Optional[WebSocketHandler] = None,
+    ) -> Callable:
+        """
+        Create the async workflow execution tool that this agent can call.
+        This is the async counterpart of create_workflow_tool.
+
+        Args:
+            workflow: The workflow instance
+            session: The workflow session
+            execution_input: The execution input
+            run_context: The run context
+            stream: Whether to stream the workflow execution
+
+        Returns:
+            Async callable tool function
+        """
+        from datetime import datetime
+        from uuid import uuid4
+
+        from pydantic import BaseModel
+
+        from agno.run.workflow import WorkflowRunOutput
+        from agno.utils.log import log_debug
+        from agno.workflow.types import WorkflowExecutionInput
+
+        async def run_workflow(query: str):
+            """
+            Execute the complete workflow with the given query asynchronously.
+            Use this tool when you need to run the workflow to answer the user's question.
+
+            Args:
+                query: The input query/question to process through the workflow
+
+            Returns:
+                The workflow execution result (str in non-streaming, async generator in streaming)
+            """
+            # Reload session to get latest data from database
+            # This ensures we don't overwrite any updates made after the tool was created
+            # Use async or sync method based on database type
+            if workflow._has_async_db():
+                session_from_db = await workflow.aget_session(session_id=session.session_id)
+            else:
+                session_from_db = workflow.get_session(session_id=session.session_id)
+
+            if session_from_db is None:
+                session_from_db = session  # Fallback to closure session if reload fails
+                log_debug(f"Fallback to closure session: {len(session_from_db.runs or [])} runs")
+            else:
+                log_debug(f"Reloaded session before async tool execution: {len(session_from_db.runs or [])} runs")
+
+            # Create a new run ID for this execution
+            run_id = str(uuid4())
+
+            workflow_run_response = WorkflowRunOutput(
+                run_id=run_id,
+                input=execution_input.input,  # Use original user input
+                session_id=session_from_db.session_id,
+                workflow_id=workflow.id,
+                workflow_name=workflow.name,
+                created_at=int(datetime.now().timestamp()),
+            )
+
+            workflow_execution_input = WorkflowExecutionInput(
+                input=query,  # Agent's refined query for execution
+                additional_data=execution_input.additional_data,
+                audio=execution_input.audio,
+                images=execution_input.images,
+                videos=execution_input.videos,
+                files=execution_input.files,
+            )
+
+            if stream:
+                final_content = ""
+                async for event in workflow._aexecute_stream(
+                    session_id=session_from_db.session_id,
+                    user_id=session_from_db.user_id,
+                    execution_input=workflow_execution_input,
+                    workflow_run_response=workflow_run_response,
+                    run_context=run_context,
+                    stream_events=True,
+                    websocket_handler=websocket_handler,
+                ):
+                    yield event
+
+                    from agno.run.workflow import WorkflowCompletedEvent
+
+                    if isinstance(event, WorkflowCompletedEvent):
+                        final_content = str(event.content) if event.content else ""
+
+                yield final_content
+            else:
+                result = await workflow._aexecute(
+                    session_id=session_from_db.session_id,
+                    user_id=session_from_db.user_id,
+                    execution_input=workflow_execution_input,
+                    workflow_run_response=workflow_run_response,
+                    run_context=run_context,
+                )
+
+                if isinstance(result.content, str):
+                    yield result.content
+                elif isinstance(result.content, BaseModel):
+                    yield result.content.model_dump_json(exclude_none=True)
+                else:
+                    yield str(result.content)
+
+        return run_workflow

agno/workflow/condition.py

@@ -1,9 +1,11 @@
 import inspect
+import warnings
 from dataclasses import dataclass
 from typing import Any, AsyncIterator, Awaitable, Callable, Dict, Iterator, List, Optional, Union
 from uuid import uuid4
 
 from agno.run.agent import RunOutputEvent
+from agno.run.base import RunContext
 from agno.run.team import TeamRunOutputEvent
 from agno.run.workflow import (
     ConditionExecutionCompletedEvent,
@@ -11,6 +13,7 @@ from agno.run.workflow import (
     WorkflowRunOutput,
     WorkflowRunOutputEvent,
 )
+from agno.session.workflow import WorkflowSession
 from agno.utils.log import log_debug, logger
 from agno.workflow.step import Step
 from agno.workflow.types import StepInput, StepOutput, StepType
@@ -110,13 +113,16 @@ class Condition:
             audio=current_audio + all_audio,
         )
 
-    def _evaluate_condition(self, step_input: StepInput) -> bool:
+    def _evaluate_condition(self, step_input: StepInput, session_state: Optional[Dict[str, Any]] = None) -> bool:
         """Evaluate the condition and return boolean result"""
         if isinstance(self.evaluator, bool):
             return self.evaluator
 
         if callable(self.evaluator):
-            result = self.evaluator(step_input)
+            if session_state is not None and self._evaluator_has_session_state_param():
+                result = self.evaluator(step_input, session_state=session_state)  # type: ignore[call-arg]
+            else:
+                result = self.evaluator(step_input)
 
             if isinstance(result, bool):
                 return result
@@ -126,16 +132,24 @@ class Condition:
 
         return False
 
-    async def _aevaluate_condition(self, step_input: StepInput) -> bool:
+    async def _aevaluate_condition(self, step_input: StepInput, session_state: Optional[Dict[str, Any]] = None) -> bool:
         """Async version of condition evaluation"""
         if isinstance(self.evaluator, bool):
             return self.evaluator
 
         if callable(self.evaluator):
+            has_session_state = session_state is not None and self._evaluator_has_session_state_param()
+
             if inspect.iscoroutinefunction(self.evaluator):
-                result = await self.evaluator(step_input)
+                if has_session_state:
+                    result = await self.evaluator(step_input, session_state=session_state)  # type: ignore[call-arg]
+                else:
+                    result = await self.evaluator(step_input)
             else:
-                result = self.evaluator(step_input)
+                if has_session_state:
+                    result = self.evaluator(step_input, session_state=session_state)  # type: ignore[call-arg]
+                else:
+                    result = self.evaluator(step_input)
 
             if isinstance(result, bool):
                 return result
@@ -145,6 +159,17 @@ class Condition:
 
         return False
 
+    def _evaluator_has_session_state_param(self) -> bool:
+        """Check if the evaluator function has a session_state parameter"""
+        if not callable(self.evaluator):
+            return False
+
+        try:
+            sig = inspect.signature(self.evaluator)
+            return "session_state" in sig.parameters
+        except Exception:
+            return False
+
     def execute(
         self,
         step_input: StepInput,
@@ -152,7 +177,12 @@ class Condition:
         user_id: Optional[str] = None,
         workflow_run_response: Optional[WorkflowRunOutput] = None,
         store_executor_outputs: bool = True,
+        run_context: Optional[RunContext] = None,
         session_state: Optional[Dict[str, Any]] = None,
+        workflow_session: Optional[WorkflowSession] = None,
+        add_workflow_history_to_steps: Optional[bool] = False,
+        num_history_runs: int = 3,
+        background_tasks: Optional[Any] = None,
     ) -> StepOutput:
         """Execute the condition and its steps with sequential chaining if condition is true"""
         log_debug(f"Condition Start: {self.name}", center=True, symbol="-")
@@ -162,7 +192,11 @@ class Condition:
         self._prepare_steps()
 
         # Evaluate the condition
-        condition_result = self._evaluate_condition(step_input)
+        if run_context is not None and run_context.session_state is not None:
+            condition_result = self._evaluate_condition(step_input, session_state=run_context.session_state)
+        else:
+            condition_result = self._evaluate_condition(step_input, session_state=session_state)
+
         log_debug(f"Condition {self.name} evaluated to: {condition_result}")
 
         if not condition_result:
@@ -188,7 +222,12 @@ class Condition:
                     user_id=user_id,
                     workflow_run_response=workflow_run_response,
                     store_executor_outputs=store_executor_outputs,
+                    run_context=run_context,
                     session_state=session_state,
+                    workflow_session=workflow_session,
+                    add_workflow_history_to_steps=add_workflow_history_to_steps,
+                    num_history_runs=num_history_runs,
+                    background_tasks=background_tasks,
                 )
 
                 # Handle both single StepOutput and List[StepOutput] (from Loop/Condition/Router steps)
@@ -249,12 +288,19 @@ class Condition:
         step_input: StepInput,
         session_id: Optional[str] = None,
         user_id: Optional[str] = None,
-        stream_intermediate_steps: bool = False,
+        stream_events: bool = False,
+        stream_intermediate_steps: bool = False,  # type: ignore
+        stream_executor_events: bool = True,
         workflow_run_response: Optional[WorkflowRunOutput] = None,
         step_index: Optional[Union[int, tuple]] = None,
         store_executor_outputs: bool = True,
+        run_context: Optional[RunContext] = None,
         session_state: Optional[Dict[str, Any]] = None,
         parent_step_id: Optional[str] = None,
+        workflow_session: Optional[WorkflowSession] = None,
+        add_workflow_history_to_steps: Optional[bool] = False,
+        num_history_runs: int = 3,
+        background_tasks: Optional[Any] = None,
     ) -> Iterator[Union[WorkflowRunOutputEvent, StepOutput]]:
         """Execute the condition with streaming support - mirrors Loop logic"""
         log_debug(f"Condition Start: {self.name}", center=True, symbol="-")
@@ -264,10 +310,22 @@ class Condition:
         self._prepare_steps()
 
         # Evaluate the condition
-        condition_result = self._evaluate_condition(step_input)
+        if run_context is not None and run_context.session_state is not None:
+            condition_result = self._evaluate_condition(step_input, session_state=run_context.session_state)
+        else:
+            condition_result = self._evaluate_condition(step_input, session_state=session_state)
         log_debug(f"Condition {self.name} evaluated to: {condition_result}")
 
-        if stream_intermediate_steps and workflow_run_response:
+        # Considering both stream_events and stream_intermediate_steps (deprecated)
+        if stream_intermediate_steps is not None:
+            warnings.warn(
+                "The 'stream_intermediate_steps' parameter is deprecated and will be removed in future versions. Use 'stream_events' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        stream_events = stream_events or stream_intermediate_steps
+
+        if stream_events and workflow_run_response:
             # Yield condition started event
             yield ConditionExecutionStartedEvent(
                 run_id=workflow_run_response.run_id or "",
@@ -282,7 +340,7 @@ class Condition:
             )
 
         if not condition_result:
-            if stream_intermediate_steps and workflow_run_response:
+            if stream_events and workflow_run_response:
                 # Yield condition completed event for empty case
                 yield ConditionExecutionCompletedEvent(
                     run_id=workflow_run_response.run_id or "",
@@ -321,12 +379,18 @@ class Condition:
                     current_step_input,
                     session_id=session_id,
                     user_id=user_id,
-                    stream_intermediate_steps=stream_intermediate_steps,
+                    stream_events=stream_events,
+                    stream_executor_events=stream_executor_events,
                     workflow_run_response=workflow_run_response,
                     step_index=child_step_index,
                     store_executor_outputs=store_executor_outputs,
+                    run_context=run_context,
                     session_state=session_state,
                     parent_step_id=conditional_step_id,
+                    workflow_session=workflow_session,
+                    add_workflow_history_to_steps=add_workflow_history_to_steps,
+                    num_history_runs=num_history_runs,
+                    background_tasks=background_tasks,
                 ):
                     if isinstance(event, StepOutput):
                         step_outputs_for_step.append(event)
@@ -374,7 +438,7 @@ class Condition:
                 break
 
         log_debug(f"Condition End: {self.name} ({len(all_results)} results)", center=True, symbol="-")
-        if stream_intermediate_steps and workflow_run_response:
+        if stream_events and workflow_run_response:
             # Yield condition completed event
             yield ConditionExecutionCompletedEvent(
                 run_id=workflow_run_response.run_id or "",
@@ -406,7 +470,12 @@ class Condition:
         user_id: Optional[str] = None,
         workflow_run_response: Optional[WorkflowRunOutput] = None,
         store_executor_outputs: bool = True,
+        run_context: Optional[RunContext] = None,
         session_state: Optional[Dict[str, Any]] = None,
+        workflow_session: Optional[WorkflowSession] = None,
+        add_workflow_history_to_steps: Optional[bool] = False,
+        num_history_runs: int = 3,
+        background_tasks: Optional[Any] = None,
     ) -> StepOutput:
         """Async execute the condition and its steps with sequential chaining"""
         log_debug(f"Condition Start: {self.name}", center=True, symbol="-")
@@ -416,7 +485,10 @@ class Condition:
         self._prepare_steps()
 
         # Evaluate the condition
-        condition_result = await self._aevaluate_condition(step_input)
+        if run_context is not None and run_context.session_state is not None:
+            condition_result = await self._aevaluate_condition(step_input, session_state=run_context.session_state)
+        else:
+            condition_result = await self._aevaluate_condition(step_input, session_state=session_state)
         log_debug(f"Condition {self.name} evaluated to: {condition_result}")
 
         if not condition_result:
@@ -444,7 +516,12 @@ class Condition:
                     user_id=user_id,
                     workflow_run_response=workflow_run_response,
                     store_executor_outputs=store_executor_outputs,
+                    run_context=run_context,
                     session_state=session_state,
+                    workflow_session=workflow_session,
+                    add_workflow_history_to_steps=add_workflow_history_to_steps,
+                    num_history_runs=num_history_runs,
+                    background_tasks=background_tasks,
                 )
 
                 # Handle both single StepOutput and List[StepOutput]
@@ -503,12 +580,19 @@ class Condition:
         step_input: StepInput,
         session_id: Optional[str] = None,
         user_id: Optional[str] = None,
+        stream_events: bool = False,
         stream_intermediate_steps: bool = False,
+        stream_executor_events: bool = True,
         workflow_run_response: Optional[WorkflowRunOutput] = None,
         step_index: Optional[Union[int, tuple]] = None,
         store_executor_outputs: bool = True,
+        run_context: Optional[RunContext] = None,
         session_state: Optional[Dict[str, Any]] = None,
         parent_step_id: Optional[str] = None,
+        workflow_session: Optional[WorkflowSession] = None,
+        add_workflow_history_to_steps: Optional[bool] = False,
+        num_history_runs: int = 3,
+        background_tasks: Optional[Any] = None,
     ) -> AsyncIterator[Union[WorkflowRunOutputEvent, TeamRunOutputEvent, RunOutputEvent, StepOutput]]:
         """Async execute the condition with streaming support - mirrors Loop logic"""
         log_debug(f"Condition Start: {self.name}", center=True, symbol="-")
@@ -518,10 +602,22 @@ class Condition:
         self._prepare_steps()
 
         # Evaluate the condition
-        condition_result = await self._aevaluate_condition(step_input)
+        if run_context is not None and run_context.session_state is not None:
+            condition_result = await self._aevaluate_condition(step_input, session_state=run_context.session_state)
+        else:
+            condition_result = await self._aevaluate_condition(step_input, session_state=session_state)
         log_debug(f"Condition {self.name} evaluated to: {condition_result}")
 
-        if stream_intermediate_steps and workflow_run_response:
+        # Considering both stream_events and stream_intermediate_steps (deprecated)
+        if stream_intermediate_steps is not None:
+            warnings.warn(
+                "The 'stream_intermediate_steps' parameter is deprecated and will be removed in future versions. Use 'stream_events' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        stream_events = stream_events or stream_intermediate_steps
+
+        if stream_events and workflow_run_response:
             # Yield condition started event
             yield ConditionExecutionStartedEvent(
                 run_id=workflow_run_response.run_id or "",
@@ -536,7 +632,7 @@ class Condition:
             )
 
         if not condition_result:
-            if stream_intermediate_steps and workflow_run_response:
+            if stream_events and workflow_run_response:
                 # Yield condition completed event for empty case
                 yield ConditionExecutionCompletedEvent(
                     run_id=workflow_run_response.run_id or "",
@@ -577,12 +673,18 @@ class Condition:
                     current_step_input,
                     session_id=session_id,
                     user_id=user_id,
-                    stream_intermediate_steps=stream_intermediate_steps,
+                    stream_events=stream_events,
+                    stream_executor_events=stream_executor_events,
                     workflow_run_response=workflow_run_response,
                     step_index=child_step_index,
                     store_executor_outputs=store_executor_outputs,
+                    run_context=run_context,
                     session_state=session_state,
                     parent_step_id=conditional_step_id,
+                    workflow_session=workflow_session,
+                    add_workflow_history_to_steps=add_workflow_history_to_steps,
+                    num_history_runs=num_history_runs,
+                    background_tasks=background_tasks,
                 ):
                     if isinstance(event, StepOutput):
                         step_outputs_for_step.append(event)
@@ -631,7 +733,7 @@ class Condition:
 
         log_debug(f"Condition End: {self.name} ({len(all_results)} results)", center=True, symbol="-")
 
-        if stream_intermediate_steps and workflow_run_response:
+        if stream_events and workflow_run_response:
             # Yield condition completed event
             yield ConditionExecutionCompletedEvent(
                 run_id=workflow_run_response.run_id or "",