agno 2.2.5__py3-none-any.whl → 2.2.7__py3-none-any.whl

agno/workflow/workflow.py

@@ -29,8 +29,8 @@ from agno.exceptions import InputCheckError, OutputCheckError, RunCancelledExcep
 from agno.media import Audio, File, Image, Video
 from agno.models.message import Message
 from agno.models.metrics import Metrics
-from agno.run.agent import RunContentEvent, RunEvent
-from agno.run.base import RunStatus
+from agno.run import RunContext, RunStatus
+from agno.run.agent import RunContentEvent, RunEvent, RunOutput
 from agno.run.cancel import (
     cancel_run as cancel_run_global,
 )
@@ -68,6 +68,7 @@ from agno.utils.print_response.workflow import (
     print_response,
     print_response_stream,
 )
+from agno.workflow import WorkflowAgent
 from agno.workflow.condition import Condition
 from agno.workflow.loop import Loop
 from agno.workflow.parallel import Parallel
@@ -132,6 +133,9 @@ class Workflow:
     # Database to use for this workflow
     db: Optional[Union[BaseDb, AsyncBaseDb]] = None
 
+    # Agentic Workflow - WorkflowAgent that decides when to run the workflow
+    agent: Optional[WorkflowAgent] = None  # type: ignore
+
     # Default session_id to use for this workflow (autogenerated if not set)
     session_id: Optional[str] = None
     # Default user_id to use for this workflow
@@ -187,6 +191,7 @@ class Workflow:
         description: Optional[str] = None,
         db: Optional[Union[BaseDb, AsyncBaseDb]] = None,
         steps: Optional[WorkflowSteps] = None,
+        agent: Optional[WorkflowAgent] = None,
         session_id: Optional[str] = None,
         session_state: Optional[Dict[str, Any]] = None,
         overwrite_db_session_state: bool = False,
@@ -210,6 +215,7 @@ class Workflow:
         self.name = name
         self.description = description
         self.steps = steps
+        self.agent = agent
         self.session_id = session_id
         self.session_state = session_state
         self.overwrite_db_session_state = overwrite_db_session_state
@@ -231,6 +237,13 @@ class Workflow:
         self.num_history_runs = num_history_runs
         self._workflow_session: Optional[WorkflowSession] = None
 
+        # Warn if workflow history is enabled without a database
+        if self.add_workflow_history_to_steps and self.db is None:
+            log_warning(
+                "Workflow history is enabled (add_workflow_history_to_steps=True) but no database is configured. "
+                "History won't be persisted. Add a database to persist runs across executions. "
+            )
+
     def set_id(self) -> None:
         if self.id is None:
             if self.name is not None:
@@ -940,6 +953,20 @@ class Workflow:
 
         return workflow_data
 
+    def _broadcast_to_websocket(
+        self,
+        event: Any,
+        websocket_handler: Optional[WebSocketHandler] = None,
+    ) -> None:
+        """Broadcast events to WebSocket if available (async context only)"""
+        if websocket_handler:
+            try:
+                loop = asyncio.get_running_loop()
+                if loop:
+                    asyncio.create_task(websocket_handler.handle_event(event))
+            except RuntimeError:
+                pass
+
     def _handle_event(
         self,
         event: "WorkflowRunOutputEvent",
@@ -947,6 +974,11 @@ class Workflow:
         websocket_handler: Optional[WebSocketHandler] = None,
     ) -> "WorkflowRunOutputEvent":
         """Handle workflow events for storage - similar to Team._handle_event"""
+        from agno.run.agent import RunOutput
+        from agno.run.team import TeamRunOutput
+
+        if isinstance(event, (RunOutput, TeamRunOutput)):
+            return event
         if self.store_events:
             # Check if this event type should be skipped
             if self.events_to_skip:
@@ -967,15 +999,7 @@ class Workflow:
             workflow_run_response.events.append(event)
 
         # Broadcast to WebSocket if available (async context only)
-        if websocket_handler:
-            import asyncio
-
-            try:
-                loop = asyncio.get_running_loop()
-                if loop:
-                    asyncio.create_task(websocket_handler.handle_event(event))
-            except RuntimeError:
-                pass
+        self._broadcast_to_websocket(event, websocket_handler)
 
         return event
 
@@ -1192,7 +1216,7 @@ class Workflow:
         session: WorkflowSession,
         execution_input: WorkflowExecutionInput,
         workflow_run_response: WorkflowRunOutput,
-        session_state: Optional[Dict[str, Any]] = None,
+        run_context: RunContext,
         **kwargs: Any,
     ) -> WorkflowRunOutput:
         """Execute a specific pipeline by name synchronously"""
@@ -1259,7 +1283,7 @@ class Workflow:
                         session_id=session.session_id,
                         user_id=self.user_id,
                         workflow_run_response=workflow_run_response,
-                        session_state=session_state,
+                        session_state=run_context.session_state,
                         store_executor_outputs=self.store_executor_outputs,
                         workflow_session=session,
                         add_workflow_history_to_steps=self.add_workflow_history_to_steps
@@ -1353,7 +1377,7 @@ class Workflow:
         session: WorkflowSession,
         execution_input: WorkflowExecutionInput,
         workflow_run_response: WorkflowRunOutput,
-        session_state: Optional[Dict[str, Any]] = None,
+        run_context: RunContext,
         stream_events: bool = False,
         **kwargs: Any,
     ) -> Iterator[WorkflowRunOutputEvent]:
@@ -1444,7 +1468,7 @@ class Workflow:
                         stream_events=stream_events,
                         stream_executor_events=self.stream_executor_events,
                         workflow_run_response=workflow_run_response,
-                        session_state=session_state,
+                        session_state=run_context.session_state,
                         step_index=i,
                         store_executor_outputs=self.store_executor_outputs,
                         workflow_session=session,
@@ -2243,6 +2267,13 @@ class Workflow:
             session_id=session_id, user_id=user_id, session_state=session_state
         )
 
+        run_context = RunContext(
+            run_id=run_id,
+            session_id=session_id,
+            user_id=user_id,
+            session_state=session_state,
+        )
+
         self._prepare_steps()
 
         # Create workflow run response with PENDING status
@@ -2285,14 +2316,23 @@ class Workflow:
                 else:
                     self.save_session(session=workflow_session)
 
-                await self._aexecute(
-                    session_id=session_id,
-                    user_id=user_id,
-                    execution_input=inputs,
-                    workflow_run_response=workflow_run_response,
-                    session_state=session_state,
-                    **kwargs,
-                )
+                if self.agent is not None:
+                    self._aexecute_workflow_agent(
+                        user_input=input,  # type: ignore
+                        execution_input=inputs,
+                        run_context=run_context,
+                        stream=False,
+                        **kwargs,
+                    )
+                else:
+                    await self._aexecute(
+                        session_id=session_id,
+                        user_id=user_id,
+                        execution_input=inputs,
+                        workflow_run_response=workflow_run_response,
+                        session_state=session_state,
+                        **kwargs,
+                    )
 
                 log_debug(f"Background execution completed with status: {workflow_run_response.status}")
 
@@ -2340,6 +2380,13 @@ class Workflow:
             session_id=session_id, user_id=user_id, session_state=session_state
         )
 
+        run_context = RunContext(
+            run_id=run_id,
+            session_id=session_id,
+            user_id=user_id,
+            session_state=session_state,
+        )
+
         self._prepare_steps()
 
         # Create workflow run response with PENDING status
@@ -2353,13 +2400,6 @@ class Workflow:
             status=RunStatus.pending,
         )
 
-        # Store PENDING response immediately
-        workflow_session.upsert_run(run=workflow_run_response)
-        if self._has_async_db():
-            await self.asave_session(session=workflow_session)
-        else:
-            self.save_session(session=workflow_session)
-
         # Prepare execution input
         inputs = WorkflowExecutionInput(
             input=input,
@@ -2375,27 +2415,45 @@ class Workflow:
         async def execute_workflow_background_stream():
             """Background execution with streaming and WebSocket broadcasting"""
             try:
-                # Update status to RUNNING and save
-                workflow_run_response.status = RunStatus.running
-                if self._has_async_db():
-                    await self.asave_session(session=workflow_session)
+                if self.agent is not None:
+                    result = self._aexecute_workflow_agent(
+                        user_input=input,  # type: ignore
+                        run_context=run_context,
+                        execution_input=inputs,
+                        stream=True,
+                        websocket_handler=websocket_handler,
+                        **kwargs,
+                    )
+                    # For streaming, result is an async iterator
+                    async for event in result:  # type: ignore
+                        # Events are automatically broadcast by _handle_event in the agent execution
+                        # We just consume them here to drive the execution
+                        pass
+                    log_debug(
+                        f"Background streaming execution (workflow agent) completed with status: {workflow_run_response.status}"
+                    )
                 else:
-                    self.save_session(session=workflow_session)
+                    # Update status to RUNNING and save
+                    workflow_run_response.status = RunStatus.running
+                    if self._has_async_db():
+                        await self.asave_session(session=workflow_session)
+                    else:
+                        self.save_session(session=workflow_session)
 
-                # Execute with streaming - consume all events (they're auto-broadcast via _handle_event)
-                async for event in self._aexecute_stream(
-                    session_id=session_id,
-                    user_id=user_id,
-                    execution_input=inputs,
-                    workflow_run_response=workflow_run_response,
-                    stream_events=stream_events,
-                    session_state=session_state,
-                    websocket_handler=websocket_handler,
-                    **kwargs,
-                ):
-                    # Events are automatically broadcast by _handle_event
-                    # We just consume them here to drive the execution
-                    pass
+                    # Execute with streaming - consume all events (they're auto-broadcast via _handle_event)
+                    async for event in self._aexecute_stream(
+                        session_id=session_id,
+                        user_id=user_id,
+                        execution_input=inputs,
+                        workflow_run_response=workflow_run_response,
+                        stream_events=stream_events,
+                        run_context=run_context,
+                        websocket_handler=websocket_handler,
+                        **kwargs,
+                    ):
+                        # Events are automatically broadcast by _handle_event
+                        # We just consume them here to drive the execution
+                        pass
 
                 log_debug(f"Background streaming execution completed with status: {workflow_run_response.status}")
 
@@ -2439,6 +2497,801 @@ class Workflow:
 
         return None
 
+    def _initialize_workflow_agent(
+        self,
+        session: WorkflowSession,
+        execution_input: WorkflowExecutionInput,
+        run_context: RunContext,
+        stream: bool = False,
+    ) -> None:
+        """Initialize the workflow agent with tools (but NOT context - that's passed per-run)"""
+        from agno.tools.function import Function
+
+        workflow_tool_func = self.agent.create_workflow_tool(  # type: ignore
+            workflow=self,
+            session=session,
+            execution_input=execution_input,
+            run_context=run_context,
+            stream=stream,
+        )
+        workflow_tool = Function.from_callable(workflow_tool_func)
+
+        self.agent.tools = [workflow_tool]  # type: ignore
+        self.agent._rebuild_tools = True  # type: ignore
+
+        log_debug("Workflow agent initialized with run_workflow tool")
+
+    def _get_workflow_agent_dependencies(self, session: WorkflowSession) -> Dict[str, Any]:
+        """Build dependencies dict with workflow context to pass to agent.run()"""
+        # Get configuration from the WorkflowAgent instance
+        add_history = True
+        num_runs = 5
+
+        if self.agent and isinstance(self.agent, WorkflowAgent):
+            add_history = self.agent.add_workflow_history
+            num_runs = self.agent.num_history_runs or 5
+
+        if add_history:
+            history_context = (
+                session.get_workflow_history_context(num_runs=num_runs) or "No previous workflow runs in this session."
+            )
+        else:
+            history_context = "No workflow history available."
+
+        # Build workflow context with description and history
+        workflow_context = ""
+        if self.description:
+            workflow_context += f"Workflow Description: {self.description}\n\n"
+
+        workflow_context += history_context
+
+        return {
+            "workflow_context": workflow_context,
+        }
+
+    def _execute_workflow_agent(
+        self,
+        user_input: Union[str, Dict[str, Any], List[Any], BaseModel],
+        session: WorkflowSession,
+        execution_input: WorkflowExecutionInput,
+        run_context: RunContext,
+        stream: bool = False,
+        **kwargs: Any,
+    ) -> Union[WorkflowRunOutput, Iterator[WorkflowRunOutputEvent]]:
+        """
+        Execute the workflow agent in streaming or non-streaming mode.
+
+        The agent decides whether to run the workflow or answer directly from history.
+
+        Args:
+            user_input: The user's input
+            session: The workflow session
+            execution_input: The execution input
+            run_context: The run context
+            stream: Whether to stream the response
+            stream_intermediate_steps: Whether to stream intermediate steps
+
+        Returns:
+            WorkflowRunOutput if stream=False, Iterator[WorkflowRunOutputEvent] if stream=True
+        """
+        if stream:
+            return self._run_workflow_agent_stream(
+                agent_input=user_input,
+                session=session,
+                execution_input=execution_input,
+                run_context=run_context,
+                stream=stream,
+                **kwargs,
+            )
+        else:
+            return self._run_workflow_agent(
+                agent_input=user_input,
+                session=session,
+                execution_input=execution_input,
+                run_context=run_context,
+                stream=stream,
+            )
+
+    def _run_workflow_agent_stream(
+        self,
+        agent_input: Union[str, Dict[str, Any], List[Any], BaseModel],
+        session: WorkflowSession,
+        execution_input: WorkflowExecutionInput,
+        run_context: RunContext,
+        stream: bool = False,
+        **kwargs: Any,
+    ) -> Iterator[WorkflowRunOutputEvent]:
+        """
+        Execute the workflow agent in streaming mode.
+
+        The agent's tool (run_workflow) is a generator that yields workflow events directly.
+        These events bubble up through the agent's streaming and are yielded here.
+        We filter to only yield WorkflowRunOutputEvent to the CLI.
+
+        Yields:
+            WorkflowRunOutputEvent: Events from workflow execution (agent events are filtered)
+        """
+        from typing import get_args
+
+        from agno.run.workflow import WorkflowCompletedEvent, WorkflowRunOutputEvent
+
+        # Initialize agent with stream_intermediate_steps=True so tool yields events
+        self._initialize_workflow_agent(session, execution_input, run_context=run_context, stream=stream)
+
+        # Build dependencies with workflow context
+        run_context.dependencies = self._get_workflow_agent_dependencies(session)
+
+        # Run agent with streaming - workflow events will bubble up from the tool
+        agent_response: Optional[RunOutput] = None
+        workflow_executed = False
+
+        from agno.run.agent import RunContentEvent
+        from agno.run.team import RunContentEvent as TeamRunContentEvent
+        from agno.run.workflow import WorkflowAgentCompletedEvent, WorkflowAgentStartedEvent
+
+        log_debug(f"Executing workflow agent with streaming - input: {agent_input}...")
+
+        # Create a workflow run response upfront for potential direct answer (will be used only if workflow is not executed)
+        run_id = str(uuid4())
+        direct_reply_run_response = WorkflowRunOutput(
+            run_id=run_id,
+            input=execution_input.input,
+            session_id=session.session_id,
+            workflow_id=self.id,
+            workflow_name=self.name,
+            created_at=int(datetime.now().timestamp()),
+        )
+
+        # Yield WorkflowAgentStartedEvent at the beginning (stored in direct_reply_run_response)
+        agent_started_event = WorkflowAgentStartedEvent(
+            workflow_name=self.name,
+            workflow_id=self.id,
+            session_id=session.session_id,
+        )
+        yield agent_started_event
+
+        # Run the agent in streaming mode and yield all events
+        for event in self.agent.run(  # type: ignore[union-attr]
+            input=agent_input,
+            stream=True,
+            stream_intermediate_steps=True,
+            yield_run_response=True,
+            session_id=session.session_id,
+            dependencies=run_context.dependencies,  # Pass context dynamically per-run
+            session_state=run_context.session_state,  # Pass session state dynamically per-run
+        ):  # type: ignore
+            if isinstance(event, tuple(get_args(WorkflowRunOutputEvent))):
+                yield event  # type: ignore[misc]
+
+                # Track if workflow was executed by checking for WorkflowCompletedEvent
+                if isinstance(event, WorkflowCompletedEvent):
+                    workflow_executed = True
+            elif isinstance(event, (RunContentEvent, TeamRunContentEvent)):
+                if event.step_name is None:
+                    # This is from the workflow agent itself
+                    # Enrich with metadata to mark it as a workflow agent event
+
+                    if workflow_executed:
+                        continue  # Skip if workflow was already executed
+
+                    # workflow_agent field is used by consumers of the events to distinguish between workflow agent and regular agent
+                    event.workflow_agent = True  # type: ignore
+                yield event  # type: ignore[misc]
+
+            # Capture the final RunOutput (but don't yield it)
+            if isinstance(event, RunOutput):
+                agent_response = event
+
+        # Handle direct answer case (no workflow execution)
+        if not workflow_executed:
+            # Update the pre-created workflow run response with the direct answer
+            direct_reply_run_response.content = agent_response.content if agent_response else ""
+            direct_reply_run_response.status = RunStatus.completed
+            direct_reply_run_response.workflow_agent_run = agent_response
+
+            workflow_run_response = direct_reply_run_response
+
+            # Store the full agent RunOutput and establish parent-child relationship
+            if agent_response:
+                agent_response.parent_run_id = workflow_run_response.run_id
+                agent_response.workflow_id = workflow_run_response.workflow_id
+
+            log_debug(f"Agent decision: workflow_executed={workflow_executed}")
+
+            # Yield WorkflowAgentCompletedEvent (user internally by print_response_stream)
+            agent_completed_event = WorkflowAgentCompletedEvent(
+                run_id=agent_response.run_id if agent_response else None,
+                workflow_name=self.name,
+                workflow_id=self.id,
+                session_id=session.session_id,
+                content=workflow_run_response.content,
+            )
+            yield agent_completed_event
+
+            # Yield a workflow completed event with the agent's direct response
+            completed_event = WorkflowCompletedEvent(
+                run_id=workflow_run_response.run_id or "",
+                content=workflow_run_response.content,
+                workflow_name=workflow_run_response.workflow_name,
+                workflow_id=workflow_run_response.workflow_id,
+                session_id=workflow_run_response.session_id,
+                step_results=[],
+                metadata={"agent_direct_response": True},
+            )
+            yield completed_event
+
+            # Update the run in session
+            session.upsert_run(run=workflow_run_response)
+            # Save session
+            self.save_session(session=session)
+
+        else:
+            # Workflow was executed by the tool
+            reloaded_session = self.get_session(session_id=session.session_id)
+
+            if reloaded_session and reloaded_session.runs and len(reloaded_session.runs) > 0:
+                # Get the last run (which is the one just created by the tool)
+                last_run = reloaded_session.runs[-1]
+
+                # Yield WorkflowAgentCompletedEvent
+                agent_completed_event = WorkflowAgentCompletedEvent(
+                    run_id=agent_response.run_id if agent_response else None,
+                    workflow_name=self.name,
+                    workflow_id=self.id,
+                    session_id=session.session_id,
+                    content=agent_response.content if agent_response else None,
+                )
+                yield agent_completed_event
+
+                # Update the last run with workflow_agent_run
+                last_run.workflow_agent_run = agent_response
+
+                # Store the full agent RunOutput and establish parent-child relationship
+                if agent_response:
+                    agent_response.parent_run_id = last_run.run_id
+                    agent_response.workflow_id = last_run.workflow_id
+
+                # Save the reloaded session (which has the updated run)
+                self.save_session(session=reloaded_session)
+
+            else:
+                log_warning("Could not reload session or no runs found after workflow execution")
+
+    def _run_workflow_agent(
+        self,
+        agent_input: Union[str, Dict[str, Any], List[Any], BaseModel],
+        session: WorkflowSession,
+        execution_input: WorkflowExecutionInput,
+        run_context: RunContext,
+        stream: bool = False,
+    ) -> WorkflowRunOutput:
+        """
+        Execute the workflow agent in non-streaming mode.
+
+        The agent decides whether to run the workflow or answer directly from history.
+
+        Returns:
+            WorkflowRunOutput: The workflow run output with agent response
+        """
+
+        # Initialize the agent
+        self._initialize_workflow_agent(session, execution_input, run_context=run_context, stream=stream)
+
+        # Build dependencies with workflow context
+        run_context.dependencies = self._get_workflow_agent_dependencies(session)
+
+        # Run the agent
+        agent_response: RunOutput = self.agent.run(  # type: ignore[union-attr]
+            input=agent_input,
+            session_id=session.session_id,
+            dependencies=run_context.dependencies,
+            session_state=run_context.session_state,
+            stream=stream,
+        )  # type: ignore
+
+        # Check if the agent called the workflow tool
+        workflow_executed = False
+        if agent_response.messages:
+            for message in agent_response.messages:
+                if message.role == "assistant" and message.tool_calls:
+                    # Check if the tool call is specifically for run_workflow
+                    for tool_call in message.tool_calls:
+                        # Handle both dict and object formats
+                        if isinstance(tool_call, dict):
+                            tool_name = tool_call.get("function", {}).get("name", "")
+                        else:
+                            tool_name = tool_call.function.name if hasattr(tool_call, "function") else ""
+
+                        if tool_name == "run_workflow":
+                            workflow_executed = True
+                            break
+                    if workflow_executed:
+                        break
+
+        log_debug(f"Workflow agent execution complete. Workflow executed: {workflow_executed}")
+
+        # Handle direct answer case (no workflow execution)
+        if not workflow_executed:
+            # Create a new workflow run output for the direct answer
+            run_id = str(uuid4())
+            workflow_run_response = WorkflowRunOutput(
+                run_id=run_id,
+                input=execution_input.input,
+                session_id=session.session_id,
+                workflow_id=self.id,
+                workflow_name=self.name,
+                created_at=int(datetime.now().timestamp()),
+                content=agent_response.content,
+                status=RunStatus.completed,
+                workflow_agent_run=agent_response,
+            )
+
+            # Store the full agent RunOutput and establish parent-child relationship
+            if agent_response:
+                agent_response.parent_run_id = workflow_run_response.run_id
+                agent_response.workflow_id = workflow_run_response.workflow_id
+
+            # Update the run in session
+            session.upsert_run(run=workflow_run_response)
+            self.save_session(session=session)
+
+            log_debug(f"Agent decision: workflow_executed={workflow_executed}")
+
+            return workflow_run_response
+        else:
+            # Workflow was executed by the tool
+            reloaded_session = self.get_session(session_id=session.session_id)
+
+            if reloaded_session and reloaded_session.runs and len(reloaded_session.runs) > 0:
+                # Get the last run (which is the one just created by the tool)
+                last_run = reloaded_session.runs[-1]
+
+                # Update the last run directly with workflow_agent_run
+                last_run.workflow_agent_run = agent_response
+
+                # Store the full agent RunOutput and establish parent-child relationship
+                if agent_response:
+                    agent_response.parent_run_id = last_run.run_id
+                    agent_response.workflow_id = last_run.workflow_id
+
+                # Save the reloaded session (which has the updated run)
+                self.save_session(session=reloaded_session)
+
+                # Return the last run directly (WRO2 from inner workflow)
+                return last_run
+            else:
+                log_warning("Could not reload session or no runs found after workflow execution")
+                # Return a placeholder error response
+                return WorkflowRunOutput(
+                    run_id=str(uuid4()),
+                    input=execution_input.input,
+                    session_id=session.session_id,
+                    workflow_id=self.id,
+                    workflow_name=self.name,
+                    created_at=int(datetime.now().timestamp()),
+                    content="Error: Workflow execution failed",
+                    status=RunStatus.error,
+                )
+
+    def _async_initialize_workflow_agent(
+        self,
+        session: WorkflowSession,
+        execution_input: WorkflowExecutionInput,
+        run_context: RunContext,
+        websocket_handler: Optional[WebSocketHandler] = None,
+        stream: bool = False,
+    ) -> None:
+        """Initialize the workflow agent with async tools (but NOT context - that's passed per-run)"""
+        from agno.tools.function import Function
+
+        workflow_tool_func = self.agent.async_create_workflow_tool(  # type: ignore
+            workflow=self,
+            session=session,
+            execution_input=execution_input,
+            run_context=run_context,
+            stream=stream,
+            websocket_handler=websocket_handler,
+        )
+        workflow_tool = Function.from_callable(workflow_tool_func)
+
+        self.agent.tools = [workflow_tool]  # type: ignore
+        self.agent._rebuild_tools = True  # type: ignore
+
+        log_debug("Workflow agent initialized with async run_workflow tool")
+
+    async def _aload_session_for_workflow_agent(
+        self,
+        session_id: str,
+        user_id: Optional[str],
+        session_state: Optional[Dict[str, Any]],
+    ) -> Tuple[WorkflowSession, Dict[str, Any]]:
+        """Helper to load or create session for workflow agent execution"""
+        return await self._aload_or_create_session(session_id=session_id, user_id=user_id, session_state=session_state)
+
+    def _aexecute_workflow_agent(
+        self,
+        user_input: Union[str, Dict[str, Any], List[Any], BaseModel],
+        run_context: RunContext,
+        execution_input: WorkflowExecutionInput,
+        stream: bool = False,
+        websocket_handler: Optional[WebSocketHandler] = None,
+        **kwargs: Any,
+    ):
+        """
+        Execute the workflow agent asynchronously in streaming or non-streaming mode.
+
+        The agent decides whether to run the workflow or answer directly from history.
+
+        Args:
+            user_input: The user's input
+            session: The workflow session
+            run_context: The run context
+            execution_input: The execution input
+            stream: Whether to stream the response
+            websocket_handler: The WebSocket handler
+
+        Returns:
+            Coroutine[WorkflowRunOutput] if stream=False, AsyncIterator[WorkflowRunOutputEvent] if stream=True
+        """
+
+        if stream:
+
+            async def _stream():
+                session, session_state_loaded = await self._aload_session_for_workflow_agent(
+                    run_context.session_id, run_context.user_id, run_context.session_state
+                )
+                async for event in self._arun_workflow_agent_stream(
+                    agent_input=user_input,
+                    session=session,
+                    execution_input=execution_input,
+                    run_context=run_context,
+                    stream=stream,
+                    websocket_handler=websocket_handler,
+                    **kwargs,
+                ):
+                    yield event
+
+            return _stream()
+        else:
+
+            async def _execute():
+                session, session_state_loaded = await self._aload_session_for_workflow_agent(
+                    run_context.session_id, run_context.user_id, run_context.session_state
+                )
+                return await self._arun_workflow_agent(
+                    agent_input=user_input,
+                    session=session,
+                    execution_input=execution_input,
+                    run_context=run_context,
+                    stream=stream,
+                )
+
+            return _execute()
+
+    async def _arun_workflow_agent_stream(
+        self,
+        agent_input: Union[str, Dict[str, Any], List[Any], BaseModel],
+        session: WorkflowSession,
+        execution_input: WorkflowExecutionInput,
+        run_context: RunContext,
+        stream: bool = False,
+        websocket_handler: Optional[WebSocketHandler] = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[WorkflowRunOutputEvent]:
+        """
+        Execute the workflow agent asynchronously in streaming mode.
+
+        The agent's tool (run_workflow) is an async generator that yields workflow events directly.
+        These events bubble up through the agent's streaming and are yielded here.
+        We filter to only yield WorkflowRunOutputEvent to the CLI.
+
+        Yields:
+            WorkflowRunOutputEvent: Events from workflow execution (agent events are filtered)
+        """
+        from typing import get_args
+
+        from agno.run.workflow import WorkflowCompletedEvent, WorkflowRunOutputEvent
+
+        logger.info("Workflow agent enabled - async streaming mode")
+        log_debug(f"User input: {agent_input}")
+
+        self._async_initialize_workflow_agent(
+            session,
+            execution_input,
+            run_context=run_context,
+            stream=stream,
+            websocket_handler=websocket_handler,
+        )
+
+        run_context.dependencies = self._get_workflow_agent_dependencies(session)
+
+        agent_response: Optional[RunOutput] = None
+        workflow_executed = False
+
+        from agno.run.agent import RunContentEvent
+        from agno.run.team import RunContentEvent as TeamRunContentEvent
+        from agno.run.workflow import WorkflowAgentCompletedEvent, WorkflowAgentStartedEvent
+
+        log_debug(f"Executing async workflow agent with streaming - input: {agent_input}...")
+
+        # Create a workflow run response upfront for potential direct answer (will be used only if workflow is not executed)
+        run_id = str(uuid4())
+        direct_reply_run_response = WorkflowRunOutput(
+            run_id=run_id,
+            input=execution_input.input,
+            session_id=session.session_id,
+            workflow_id=self.id,
+            workflow_name=self.name,
+            created_at=int(datetime.now().timestamp()),
+        )
+
+        # Yield WorkflowAgentStartedEvent at the beginning (stored in direct_reply_run_response)
+        agent_started_event = WorkflowAgentStartedEvent(
+            workflow_name=self.name,
+            workflow_id=self.id,
+            session_id=session.session_id,
+        )
+        self._broadcast_to_websocket(agent_started_event, websocket_handler)
+        yield agent_started_event
+
+        # Run the agent in streaming mode and yield all events
+        async for event in self.agent.arun(  # type: ignore[union-attr]
+            input=agent_input,
+            stream=True,
+            stream_intermediate_steps=True,
+            yield_run_response=True,
+            session_id=session.session_id,
+            dependencies=run_context.dependencies,  # Pass context dynamically per-run
+            session_state=run_context.session_state,  # Pass session state dynamically per-run
+        ):  # type: ignore
+            if isinstance(event, tuple(get_args(WorkflowRunOutputEvent))):
+                yield event  # type: ignore[misc]
+
+                if isinstance(event, WorkflowCompletedEvent):
+                    workflow_executed = True
+                    log_debug("Workflow execution detected via WorkflowCompletedEvent")
+
+            elif isinstance(event, (RunContentEvent, TeamRunContentEvent)):
+                if event.step_name is None:
+                    # This is from the workflow agent itself
+                    # Enrich with metadata to mark it as a workflow agent event
+
+                    if workflow_executed:
+                        continue  # Skip if workflow was already executed
+
+                    # workflow_agent field is used by consumers of the events to distinguish between workflow agent and regular agent
+                    event.workflow_agent = True  # type: ignore
+
+                    # Broadcast to WebSocket if available (async context only)
+                    self._broadcast_to_websocket(event, websocket_handler)
+
+                yield event  # type: ignore[misc]
+
+            # Capture the final RunOutput (but don't yield it)
+            if isinstance(event, RunOutput):
+                agent_response = event
+                log_debug(
+                    f"Agent response: {str(agent_response.content)[:100] if agent_response.content else 'None'}..."
+                )
+
+        # Handle direct answer case (no workflow execution)
+        if not workflow_executed:
+            # Update the pre-created workflow run response with the direct answer
+            direct_reply_run_response.content = agent_response.content if agent_response else ""
+            direct_reply_run_response.status = RunStatus.completed
+            direct_reply_run_response.workflow_agent_run = agent_response
+
+            workflow_run_response = direct_reply_run_response
+
+            # Store the full agent RunOutput and establish parent-child relationship
+            if agent_response:
+                agent_response.parent_run_id = workflow_run_response.run_id
+                agent_response.workflow_id = workflow_run_response.workflow_id
+
+            # Yield WorkflowAgentCompletedEvent
+            agent_completed_event = WorkflowAgentCompletedEvent(
+                workflow_name=self.name,
+                workflow_id=self.id,
+                run_id=agent_response.run_id if agent_response else None,
+                session_id=session.session_id,
+                content=workflow_run_response.content,
+            )
+            self._broadcast_to_websocket(agent_completed_event, websocket_handler)
+            yield agent_completed_event
+
+            # Yield a workflow completed event with the agent's direct response (user internally by aprint_response_stream)
+            completed_event = WorkflowCompletedEvent(
+                run_id=workflow_run_response.run_id or "",
+                content=workflow_run_response.content,
+                workflow_name=workflow_run_response.workflow_name,
+                workflow_id=workflow_run_response.workflow_id,
+                session_id=workflow_run_response.session_id,
+                step_results=[],
+                metadata={"agent_direct_response": True},
+            )
+            yield completed_event
+
+            # Update the run in session
+            session.upsert_run(run=workflow_run_response)
+            # Save session
+            if self._has_async_db():
+                await self.asave_session(session=session)
+            else:
+                self.save_session(session=session)
+
+        else:
+            # Workflow was executed by the tool
+            if self._has_async_db():
+                reloaded_session = await self.aget_session(session_id=session.session_id)
+            else:
+                reloaded_session = self.get_session(session_id=session.session_id)
+
+            if reloaded_session and reloaded_session.runs and len(reloaded_session.runs) > 0:
+                # Get the last run (which is the one just created by the tool)
+                last_run = reloaded_session.runs[-1]
+
+                # Yield WorkflowAgentCompletedEvent
+                agent_completed_event = WorkflowAgentCompletedEvent(
+                    run_id=agent_response.run_id if agent_response else None,
+                    workflow_name=self.name,
+                    workflow_id=self.id,
+                    session_id=session.session_id,
+                    content=agent_response.content if agent_response else None,
+                )
+
+                self._broadcast_to_websocket(agent_completed_event, websocket_handler)
+
+                yield agent_completed_event
+
+                # Update the last run with workflow_agent_run
+                last_run.workflow_agent_run = agent_response
+
+                # Store the full agent RunOutput and establish parent-child relationship
+                if agent_response:
+                    agent_response.parent_run_id = last_run.run_id
+                    agent_response.workflow_id = last_run.workflow_id
+
+                # Save the reloaded session (which has the updated run)
+                if self._has_async_db():
+                    await self.asave_session(session=reloaded_session)
+                else:
+                    self.save_session(session=reloaded_session)
+
+            else:
+                log_warning("Could not reload session or no runs found after workflow execution")
+
+    async def _arun_workflow_agent(
+        self,
+        agent_input: Union[str, Dict[str, Any], List[Any], BaseModel],
+        session: WorkflowSession,
+        execution_input: WorkflowExecutionInput,
+        run_context: RunContext,
+        stream: bool = False,
+    ) -> WorkflowRunOutput:
+        """
+        Execute the workflow agent asynchronously in non-streaming mode.
+
+        The agent decides whether to run the workflow or answer directly from history.
+
+        Returns:
+            WorkflowRunOutput: The workflow run output with agent response
+        """
+        # Initialize the agent
+        self._async_initialize_workflow_agent(session, execution_input, run_context=run_context, stream=stream)
+
+        # Build dependencies with workflow context
+        run_context.dependencies = self._get_workflow_agent_dependencies(session)
+
+        # Run the agent
+        agent_response: RunOutput = await self.agent.arun(  # type: ignore[union-attr]
+            input=agent_input,
+            session_id=session.session_id,
+            dependencies=run_context.dependencies,
+            session_state=run_context.session_state,
+            stream=stream,
+        )  # type: ignore
+
+        # Check if the agent called the workflow tool
+        workflow_executed = False
+        if agent_response.messages:
+            for message in agent_response.messages:
+                if message.role == "assistant" and message.tool_calls:
+                    # Check if the tool call is specifically for run_workflow
+                    for tool_call in message.tool_calls:
+                        # Handle both dict and object formats
+                        if isinstance(tool_call, dict):
+                            tool_name = tool_call.get("function", {}).get("name", "")
+                        else:
+                            tool_name = tool_call.function.name if hasattr(tool_call, "function") else ""
+
+                        if tool_name == "run_workflow":
+                            workflow_executed = True
+                            break
+                    if workflow_executed:
+                        break
+
+        # Handle direct answer case (no workflow execution)
+        if not workflow_executed:
+            # Create a new workflow run output for the direct answer
+            run_id = str(uuid4())
+            workflow_run_response = WorkflowRunOutput(
+                run_id=run_id,
+                input=execution_input.input,
+                session_id=session.session_id,
+                workflow_id=self.id,
+                workflow_name=self.name,
+                created_at=int(datetime.now().timestamp()),
+                content=agent_response.content,
+                status=RunStatus.completed,
+                workflow_agent_run=agent_response,
+            )
+
+            # Store the full agent RunOutput and establish parent-child relationship
+            if agent_response:
+                agent_response.parent_run_id = workflow_run_response.run_id
+                agent_response.workflow_id = workflow_run_response.workflow_id
+
+            # Update the run in session
+            session.upsert_run(run=workflow_run_response)
+            if self._has_async_db():
+                await self.asave_session(session=session)
+            else:
+                self.save_session(session=session)
+
+            log_debug(f"Agent decision: workflow_executed={workflow_executed}")
+
+            return workflow_run_response
+        else:
+            # Workflow was executed by the tool
+            logger.info("=" * 80)
+            logger.info("WORKFLOW AGENT: Called run_workflow tool (async)")
+            logger.info("  ➜ Workflow was executed, retrieving results...")
+            logger.info("=" * 80)
+
+            log_debug("Reloading session from database to get the latest workflow run...")
+            if self._has_async_db():
+                reloaded_session = await self.aget_session(session_id=session.session_id)
+            else:
+                reloaded_session = self.get_session(session_id=session.session_id)
+
+            if reloaded_session and reloaded_session.runs and len(reloaded_session.runs) > 0:
+                # Get the last run (which is the one just created by the tool)
+                last_run = reloaded_session.runs[-1]
+                log_debug(f"Retrieved latest workflow run: {last_run.run_id}")
+                log_debug(f"Total workflow runs in session: {len(reloaded_session.runs)}")
+
+                # Update the last run with workflow_agent_run
+                last_run.workflow_agent_run = agent_response
+
+                # Store the full agent RunOutput and establish parent-child relationship
+                if agent_response:
+                    agent_response.parent_run_id = last_run.run_id
+                    agent_response.workflow_id = last_run.workflow_id
+
+                # Save the reloaded session (which has the updated run)
+                if self._has_async_db():
+                    await self.asave_session(session=reloaded_session)
+                else:
+                    self.save_session(session=reloaded_session)
+
+                log_debug(f"Agent decision: workflow_executed={workflow_executed}")
+
+                # Return the last run directly (WRO2 from inner workflow)
+                return last_run
+            else:
+                log_warning("Could not reload session or no runs found after workflow execution")
+                # Return a placeholder error response
+                return WorkflowRunOutput(
+                    run_id=str(uuid4()),
+                    input=execution_input.input,
+                    session_id=session.session_id,
+                    workflow_id=self.id,
+                    workflow_name=self.name,
+                    created_at=int(datetime.now().timestamp()),
+                    content="Error: Workflow execution failed",
+                    status=RunStatus.error,
+                )
+
     def cancel_run(self, run_id: str) -> bool:
         """Cancel a running workflow execution.
 
@@ -2529,6 +3382,14 @@ class Workflow:
         # Update session state from DB
         session_state = self._load_session_state(session=workflow_session, session_state=session_state)
 
+        # Initialize run context
+        run_context = RunContext(
+            run_id=run_id,
+            session_id=session_id,
+            user_id=user_id,
+            session_state=session_state,
+        )
+
         log_debug(f"Workflow Run Start: {self.name}", center=True)
 
         # Use simple defaults
@@ -2547,16 +3408,6 @@ class Workflow:
         # Prepare steps
         self._prepare_steps()
 
-        # Create workflow run response that will be updated by reference
-        workflow_run_response = WorkflowRunOutput(
-            run_id=run_id,
-            input=input,
-            session_id=session_id,
-            workflow_id=self.id,
-            workflow_name=self.name,
-            created_at=int(datetime.now().timestamp()),
-        )
-
         inputs = WorkflowExecutionInput(
             input=input,
             additional_data=additional_data,
@@ -2571,13 +3422,34 @@ class Workflow:
 
         self.update_agents_and_teams_session_info()
 
+        # Execute workflow agent if configured
+        if self.agent is not None:
+            return self._execute_workflow_agent(
+                user_input=input,  # type: ignore
+                session=workflow_session,
+                execution_input=inputs,
+                run_context=run_context,
+                stream=stream,
+                **kwargs,
+            )
+
+        # Create workflow run response for regular workflow execution
+        workflow_run_response = WorkflowRunOutput(
+            run_id=run_id,
+            input=input,
+            session_id=session_id,
+            workflow_id=self.id,
+            workflow_name=self.name,
+            created_at=int(datetime.now().timestamp()),
+        )
+
         if stream:
             return self._execute_stream(
                 session=workflow_session,
                 execution_input=inputs,  # type: ignore[arg-type]
                 workflow_run_response=workflow_run_response,
                 stream_events=stream_events,
-                session_state=session_state,
+                run_context=run_context,
                 **kwargs,
             )
         else:
@@ -2585,7 +3457,7 @@ class Workflow:
                 session=workflow_session,
                 execution_input=inputs,  # type: ignore[arg-type]
                 workflow_run_response=workflow_run_response,
-                session_state=session_state,
+                run_context=run_context,
                 **kwargs,
             )
 
@@ -2700,6 +3572,14 @@ class Workflow:
         self.initialize_workflow()
         session_id, user_id = self._initialize_session(session_id=session_id, user_id=user_id)
 
+        # Initialize run context
+        run_context = RunContext(
+            run_id=run_id,
+            session_id=session_id,
+            user_id=user_id,
+            session_state=session_state,
+        )
+
         log_debug(f"Async Workflow Run Start: {self.name}", center=True)
 
         # Use simple defaults
@@ -2717,16 +3597,6 @@ class Workflow:
         # Prepare steps
         self._prepare_steps()
 
-        # Create workflow run response that will be updated by reference
-        workflow_run_response = WorkflowRunOutput(
-            run_id=run_id,
-            input=input,
-            session_id=session_id,
-            workflow_id=self.id,
-            workflow_name=self.name,
-            created_at=int(datetime.now().timestamp()),
-        )
-
         inputs = WorkflowExecutionInput(
             input=input,
             additional_data=additional_data,
@@ -2741,6 +3611,25 @@ class Workflow:
 
         self.update_agents_and_teams_session_info()
 
+        if self.agent is not None:
+            return self._aexecute_workflow_agent(  # type: ignore
+                user_input=input,  # type: ignore
+                execution_input=inputs,
+                run_context=run_context,
+                stream=stream,
+                **kwargs,
+            )
+
+        # Create workflow run response for regular workflow execution
+        workflow_run_response = WorkflowRunOutput(
+            run_id=run_id,
+            input=input,
+            session_id=session_id,
+            workflow_id=self.id,
+            workflow_name=self.name,
+            created_at=int(datetime.now().timestamp()),
+        )
+
         if stream:
             return self._aexecute_stream(  # type: ignore
                 execution_input=inputs,
@@ -2782,6 +3671,12 @@ class Workflow:
                     step_name = step.name or f"step_{i + 1}"
                     log_debug(f"Step {i + 1}: Team '{step_name}' with {len(step.members)} members")
                     prepared_steps.append(Step(name=step_name, description=step.description, team=step))
+                elif isinstance(step, Step) and step.add_workflow_history is True and self.db is None:
+                    log_warning(
+                        f"Step '{step.name or f'step_{i + 1}'}' has add_workflow_history=True "
+                        "but no database is configured in the Workflow. "
+                        "History won't be persisted. Add a database to persist runs across executions."
+                    )
                 elif isinstance(step, (Step, Steps, Loop, Parallel, Condition, Router)):
                     step_type = type(step).__name__
                     step_name = getattr(step, "name", f"unnamed_{step_type.lower()}")
@@ -2822,6 +3717,7 @@ class Workflow:
             audio: Audio input
             images: Image input
             videos: Video input
+            files: File input
             stream: Whether to stream the response content
             stream_events: Whether to stream intermediate steps
             markdown: Whether to render content as markdown
@@ -2915,6 +3811,7 @@ class Workflow:
             audio: Audio input
             images: Image input
             videos: Video input
+            files: Files input
             stream: Whether to stream the response content
             stream_events: Whether to stream intermediate steps
             markdown: Whether to render content as markdown
@@ -3021,7 +3918,7 @@ class Workflow:
                 step_dict["team"] = step.team if hasattr(step, "team") else None  # type: ignore
 
             # Handle nested steps for Router/Loop
-            if isinstance(step, (Router)):
+            if isinstance(step, Router):
                 step_dict["steps"] = (
                     [serialize_step(step) for step in step.choices] if hasattr(step, "choices") else None
                 )