agno 2.3.4__py3-none-any.whl → 2.3.6__py3-none-any.whl

agno/workflow/workflow.py

@@ -186,6 +186,9 @@ class Workflow:
     # Deprecated. Use stream_events instead.
     stream_intermediate_steps: bool = False
 
+    # If True, run hooks as FastAPI background tasks (non-blocking). Set by AgentOS.
+    _run_hooks_in_background: bool = False
+
     def __init__(
         self,
         id: Optional[str] = None,
@@ -198,6 +201,7 @@ class Workflow:
         session_state: Optional[Dict[str, Any]] = None,
         overwrite_db_session_state: bool = False,
         user_id: Optional[str] = None,
+        debug_level: Literal[1, 2] = 1,
         debug_mode: Optional[bool] = False,
         stream: Optional[bool] = None,
         stream_events: bool = False,
@@ -223,6 +227,7 @@ class Workflow:
         self.overwrite_db_session_state = overwrite_db_session_state
         self.user_id = user_id
         self.debug_mode = debug_mode
+        self.debug_level = debug_level
         self.store_events = store_events
         self.events_to_skip = events_to_skip or []
         self.stream = stream
@@ -1105,9 +1110,12 @@ class Workflow:
         """Set debug mode and configure logging"""
         if self.debug_mode or getenv("AGNO_DEBUG", "false").lower() == "true":
             use_workflow_logger()
+            debug_level: Literal[1, 2] = (
+                cast(Literal[1, 2], int(env)) if (env := getenv("AGNO_DEBUG_LEVEL")) in ("1", "2") else self.debug_level
+            )
 
             self.debug_mode = True
-            set_log_level_to_debug(source_type="workflow")
+            set_log_level_to_debug(source_type="workflow", level=debug_level)
 
             # Propagate to steps - only if steps is iterable (not callable)
             if self.steps and not callable(self.steps):
@@ -1282,14 +1290,13 @@ class Workflow:
         execution_input: WorkflowExecutionInput,
         workflow_run_response: WorkflowRunOutput,
         run_context: RunContext,
+        background_tasks: Optional[Any] = None,
         **kwargs: Any,
     ) -> WorkflowRunOutput:
         """Execute a specific pipeline by name synchronously"""
         from inspect import isasyncgenfunction, iscoroutinefunction, isgeneratorfunction
 
         workflow_run_response.status = RunStatus.running
-        if workflow_run_response.run_id:
-            register_run(workflow_run_response.run_id)  # type: ignore
 
         if callable(self.steps):
             if iscoroutinefunction(self.steps) or isasyncgenfunction(self.steps):
@@ -1355,6 +1362,7 @@ class Workflow:
                         if self.add_workflow_history_to_steps
                         else None,
                         num_history_runs=self.num_history_runs,
+                        background_tasks=background_tasks,
                     )
 
                     # Check for cancellation after step execution
@@ -1455,6 +1463,7 @@ class Workflow:
         workflow_run_response: WorkflowRunOutput,
         run_context: RunContext,
         stream_events: bool = False,
+        background_tasks: Optional[Any] = None,
         **kwargs: Any,
     ) -> Iterator[WorkflowRunOutputEvent]:
         """Execute a specific pipeline by name with event streaming"""
@@ -1462,10 +1471,6 @@ class Workflow:
 
         workflow_run_response.status = RunStatus.running
 
-        # Register run for cancellation tracking
-        if workflow_run_response.run_id:
-            register_run(workflow_run_response.run_id)
-
         workflow_started_event = WorkflowStartedEvent(
             run_id=workflow_run_response.run_id or "",
             workflow_name=workflow_run_response.workflow_name,
@@ -1552,6 +1557,7 @@ class Workflow:
                         if self.add_workflow_history_to_steps
                         else None,
                         num_history_runs=self.num_history_runs,
+                        background_tasks=background_tasks,
                     ):
                         raise_if_cancelled(workflow_run_response.run_id)  # type: ignore
 
@@ -1831,7 +1837,7 @@ class Workflow:
         self._update_metadata(session=workflow_session)
 
         # Update session state from DB
-        _session_state = session_state or {}
+        _session_state = session_state if session_state is not None else {}
         _session_state = self._load_session_state(session=workflow_session, session_state=_session_state)
 
         return workflow_session, _session_state
@@ -1843,6 +1849,7 @@ class Workflow:
         execution_input: WorkflowExecutionInput,
         workflow_run_response: WorkflowRunOutput,
         run_context: RunContext,
+        background_tasks: Optional[Any] = None,
         **kwargs: Any,
     ) -> WorkflowRunOutput:
         """Execute a specific pipeline by name asynchronously"""
@@ -1855,10 +1862,6 @@ class Workflow:
 
         workflow_run_response.status = RunStatus.running
 
-        # Register run for cancellation tracking
-        if workflow_run_response.run_id:
-            register_run(workflow_run_response.run_id)  # type: ignore
-
         if callable(self.steps):
             # Execute the workflow with the custom executor
             content = ""
@@ -1931,6 +1934,7 @@ class Workflow:
                         if self.add_workflow_history_to_steps
                         else None,
                         num_history_runs=self.num_history_runs,
+                        background_tasks=background_tasks,
                     )
 
                     # Check for cancellation after step execution
@@ -2031,6 +2035,7 @@ class Workflow:
         run_context: RunContext,
         stream_events: bool = False,
         websocket_handler: Optional[WebSocketHandler] = None,
+        background_tasks: Optional[Any] = None,
         **kwargs: Any,
     ) -> AsyncIterator[WorkflowRunOutputEvent]:
         """Execute a specific pipeline by name with event streaming"""
@@ -2043,10 +2048,6 @@ class Workflow:
 
         workflow_run_response.status = RunStatus.running
 
-        # Register run for cancellation tracking
-        if workflow_run_response.run_id:
-            register_run(workflow_run_response.run_id)
-
         workflow_started_event = WorkflowStartedEvent(
             run_id=workflow_run_response.run_id or "",
             workflow_name=workflow_run_response.workflow_name,
@@ -2141,6 +2142,7 @@ class Workflow:
                         if self.add_workflow_history_to_steps
                         else None,
                         num_history_runs=self.num_history_runs,
+                        background_tasks=background_tasks,
                     ):
                         if workflow_run_response.run_id:
                             raise_if_cancelled(workflow_run_response.run_id)
@@ -3457,6 +3459,7 @@ class Workflow:
         stream_events: Optional[bool] = None,
         stream_intermediate_steps: Optional[bool] = None,
         background: Optional[bool] = False,
+        background_tasks: Optional[Any] = None,
     ) -> WorkflowRunOutput: ...
 
     @overload
@@ -3475,6 +3478,7 @@ class Workflow:
         stream_events: Optional[bool] = None,
         stream_intermediate_steps: Optional[bool] = None,
         background: Optional[bool] = False,
+        background_tasks: Optional[Any] = None,
     ) -> Iterator[WorkflowRunOutputEvent]: ...
 
     def run(
@@ -3492,20 +3496,23 @@ class Workflow:
         stream_events: Optional[bool] = None,
         stream_intermediate_steps: Optional[bool] = None,
         background: Optional[bool] = False,
+        background_tasks: Optional[Any] = None,
         **kwargs: Any,
     ) -> Union[WorkflowRunOutput, Iterator[WorkflowRunOutputEvent]]:
         """Execute the workflow synchronously with optional streaming"""
         if self._has_async_db():
             raise Exception("`run()` is not supported with an async DB. Please use `arun()`.")
 
+        # Create a run_id for this specific run and register immediately for cancellation tracking
+        run_id = str(uuid4())
+        register_run(run_id)
+
         input = self._validate_input(input)
         if background:
             raise RuntimeError("Background execution is not supported for sync run()")
 
         self._set_debug()
 
-        run_id = str(uuid4())
-
         self.initialize_workflow()
         session_id, user_id = self._initialize_session(session_id=session_id, user_id=user_id)
 
@@ -3515,7 +3522,10 @@ class Workflow:
 
         # Initialize session state
         session_state = self._initialize_session_state(
-            session_state=session_state or {}, user_id=user_id, session_id=session_id, run_id=run_id
+            session_state=session_state if session_state is not None else {},
+            user_id=user_id,
+            session_id=session_id,
+            run_id=run_id,
         )
         # Update session state from DB
         session_state = self._load_session_state(session=workflow_session, session_state=session_state)
@@ -3592,6 +3602,7 @@ class Workflow:
                 workflow_run_response=workflow_run_response,
                 stream_events=stream_events,
                 run_context=run_context,
+                background_tasks=background_tasks,
                 **kwargs,
             )
         else:
@@ -3600,6 +3611,7 @@ class Workflow:
                 execution_input=inputs,  # type: ignore[arg-type]
                 workflow_run_response=workflow_run_response,
                 run_context=run_context,
+                background_tasks=background_tasks,
                 **kwargs,
             )
 
@@ -3620,6 +3632,7 @@ class Workflow:
         stream_intermediate_steps: Optional[bool] = None,
         background: Optional[bool] = False,
         websocket: Optional[WebSocket] = None,
+        background_tasks: Optional[Any] = None,
     ) -> WorkflowRunOutput: ...
 
     @overload
@@ -3639,6 +3652,7 @@ class Workflow:
         stream_intermediate_steps: Optional[bool] = None,
         background: Optional[bool] = False,
         websocket: Optional[WebSocket] = None,
+        background_tasks: Optional[Any] = None,
     ) -> AsyncIterator[WorkflowRunOutputEvent]: ...
 
     def arun(  # type: ignore
@@ -3657,6 +3671,7 @@ class Workflow:
         stream_intermediate_steps: Optional[bool] = False,
         background: Optional[bool] = False,
         websocket: Optional[WebSocket] = None,
+        background_tasks: Optional[Any] = None,
         **kwargs: Any,
     ) -> Union[WorkflowRunOutput, AsyncIterator[WorkflowRunOutputEvent]]:
         """Execute the workflow synchronously with optional streaming"""
@@ -3715,7 +3730,9 @@ class Workflow:
 
         self._set_debug()
 
+        # Create a run_id for this specific run and register immediately for cancellation tracking
         run_id = str(uuid4())
+        register_run(run_id)
 
         self.initialize_workflow()
         session_id, user_id = self._initialize_session(session_id=session_id, user_id=user_id)
@@ -3793,6 +3810,7 @@ class Workflow:
                 files=files,
                 session_state=session_state,
                 run_context=run_context,
+                background_tasks=background_tasks,
                 **kwargs,
             )
         else:
@@ -3805,6 +3823,7 @@ class Workflow:
                 files=files,
                 session_state=session_state,
                 run_context=run_context,
+                background_tasks=background_tasks,
                 **kwargs,
             )
 
@@ -4153,6 +4172,56 @@ class Workflow:
                             if hasattr(member, "workflow_id"):
                                 member.workflow_id = self.id
 
+    def propagate_run_hooks_in_background(self, run_in_background: bool = True) -> None:
+        """
+        Propagate _run_hooks_in_background setting to this workflow and all agents/teams in steps.
+
+        This method sets _run_hooks_in_background on the workflow and all agents/teams
+        within its steps, including nested teams and their members.
+
+        Args:
+            run_in_background: Whether hooks should run in background. Defaults to True.
+        """
+        self._run_hooks_in_background = run_in_background
+
+        if not self.steps or callable(self.steps):
+            return
+
+        steps_list = self.steps.steps if isinstance(self.steps, Steps) else self.steps
+
+        for step in steps_list:
+            self._propagate_hooks_to_step(step, run_in_background)
+
+    def _propagate_hooks_to_step(self, step: Any, run_in_background: bool) -> None:
+        """Recursively propagate _run_hooks_in_background to a step and its nested content."""
+        # Handle Step objects with active executor
+        if hasattr(step, "active_executor") and step.active_executor:
+            executor = step.active_executor
+            # If it's a team, use its propagation method
+            if hasattr(executor, "propagate_run_hooks_in_background"):
+                executor.propagate_run_hooks_in_background(run_in_background)
+            elif hasattr(executor, "_run_hooks_in_background"):
+                executor._run_hooks_in_background = run_in_background
+
+        # Handle agent/team directly on step
+        if hasattr(step, "agent") and step.agent:
+            if hasattr(step.agent, "_run_hooks_in_background"):
+                step.agent._run_hooks_in_background = run_in_background
+        if hasattr(step, "team") and step.team:
+            # Use team's method to propagate to all nested members
+            if hasattr(step.team, "propagate_run_hooks_in_background"):
+                step.team.propagate_run_hooks_in_background(run_in_background)
+            elif hasattr(step.team, "_run_hooks_in_background"):
+                step.team._run_hooks_in_background = run_in_background
+
+        # Handle nested primitives - check 'steps' and 'choices' attributes
+        for attr_name in ["steps", "choices"]:
+            if hasattr(step, attr_name):
+                attr_value = getattr(step, attr_name)
+                if attr_value and isinstance(attr_value, list):
+                    for nested_step in attr_value:
+                        self._propagate_hooks_to_step(nested_step, run_in_background)
+
     ###########################################################################
     # Telemetry functions
     ###########################################################################

{agno-2.3.4.dist-info → agno-2.3.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agno
-Version: 2.3.4
+Version: 2.3.6
 Summary: Agno: a lightweight library for building Multi-Agent Systems
 Author-email: Ashpreet Bedi <ashpreet@agno.com>
 Project-URL: homepage, https://agno.com
@@ -153,7 +153,7 @@ Requires-Dist: mcp>=1.9.2; extra == "mcp"
 Provides-Extra: mem0
 Requires-Dist: mem0ai; extra == "mem0"
 Provides-Extra: memori
-Requires-Dist: memorisdk; extra == "memori"
+Requires-Dist: memorisdk==2.3.3; extra == "memori"
 Provides-Extra: newspaper
 Requires-Dist: newspaper4k; extra == "newspaper"
 Requires-Dist: lxml_html_clean; extra == "newspaper"
@@ -381,6 +381,7 @@ Requires-Dist: agno[agui]; extra == "tests"
 Requires-Dist: agno[integration-tests]; extra == "tests"
 Requires-Dist: twine; extra == "tests"
 Requires-Dist: build; extra == "tests"
+Requires-Dist: grpcio==1.74.0; extra == "tests"
 Provides-Extra: integration-tests
 Requires-Dist: exa_py; extra == "integration-tests"
 Requires-Dist: ddgs; extra == "integration-tests"
@@ -411,15 +412,15 @@ Dynamic: license-file
 
 ## What is Agno?
 
-Agno is a multi-agent framework, runtime and control plane. Built for speed, privacy, and scale.
+Agno is an incredibly fast multi-agent framework, runtime and control plane.
 
-It provides a rich set of tools for building:
+It provides the complete stack for building, running and managing multi-agent systems:
 
-- **Agents** with memory, knowledge, session management, and advanced features like human-in-the-loop, guardrails, dynamic context management and best-in-class MCP support.
-- **Multi-Agent Teams** that operate autonomously under a team leader that maintains shared state and context. Perfect for use cases where the scope exceeds beyond a single agent.
-- **Step-based Workflows** for controlled, deterministic execution. Steps can be Agents, Teams, or regular python functions that run sequentially, in parallel, in loops, branches, or conditionally.
+- **Framework**: Build agents, multi-agent teams and workflows with memory, knowledge, state, guardrails, HITL, context compression, MCP, A2A and 100+ toolkits.
+- **AgentOS Runtime**: Run your multi-agent system in production with a secure, stateless runtime and ready to use integration endpoints.
+- **AgentOS Control Plane**: Test, monitor and manage AgentOS deployments across environments with full operational visibility.
 
-Agno also provides a ready-to-use FastAPI app (called the AgentOS) for serving your agents, teams and workflows in production. Stateless, horizontally scalable and designed for scale, the AgentOS gives you major head start in building your AI product.
+Checkout the full list of features [here](#features).
 
 ## Getting started
 
@@ -436,7 +437,7 @@ After that, checkout the [examples gallery](https://docs.agno.com/examples/use-c
 
 ## Example
 
-Here’s an example of an Agent that connects to an MCP server, manages conversation state in a database, is served using a FastAPI application that you can chat with using the [AgentOS UI](https://os.agno.com).
+Here's an example of an Agent that connects to an MCP server, manages conversation state in a database, is served using a FastAPI application that you can chat with using the [AgentOS UI](https://os.agno.com).
 
 ```python agno_agent.py
 from agno.agent import Agent
@@ -471,21 +472,21 @@ if __name__ == "__main__":
 
 ## AgentOS - Production Runtime for Multi-Agent Systems
 
-Building Agents is easy, running them is hard, and that's where the AgentOS comes in. AgentOS is a high-performance runtime for serving multi-agent systems in production. Key features include:
+Building Agents is easy, running them as a secure, scalable service is hard. AgentOS solves this by providing a high performance runtime for serving multi-agent systems in production. Key features include:
 
-1. **Pre-built FastAPI app**: AgentOS ships with a ready-to-use FastAPI app for orchestrating your agents, teams, and workflows. This gives you a major head start in building your AI product.
+1. **Pre-built FastAPI app**: AgentOS includes a ready-to-use FastAPI app for running your agents, teams and workflows. This gives you a significant head start when building an AI product.
 
-2. **Integrated Control Plane**: The [AgentOS UI](https://os.agno.com) connects directly to your runtime, letting you test, monitor, and manage your system in real time, giving you unmatched control over your system.
+2. **Integrated Control Plane**: The [AgentOS UI](https://os.agno.com) connects directly to your runtime, so you can test, monitor and manage your system in real time with full operational visibility.
 
-3. **Private by Design**: AgentOS runs entirely in your cloud, ensuring complete data privacy. No data ever leaves your system. This is ideal for security-conscious enterprises.
+3. **Private by Design**: AgentOS runs entirely in your cloud, ensuring complete data privacy. No data leaves your environment, making it ideal for security conscious enterprises..
 
-Here's what the [AgentOS UI](https://os.agno.com) looks like in action:
+When you run the example script shared above, you get a FastAPI app that you can connect to the [AgentOS UI](https://os.agno.com). Here's what it looks like in action:
 
 https://github.com/user-attachments/assets/feb23db8-15cc-4e88-be7c-01a21a03ebf6
 
 ## The Complete Agentic Solution
 
-For companies building agents, Agno provides the complete agentic solution:
+Agno provides the complete solution for companies building agentic systems:
 
 - The fastest framework for building agents, multi-agent teams and agentic workflows.
 - A ready-to-use FastAPI app that gets you building AI products on day one.
@@ -493,28 +494,32 @@ For companies building agents, Agno provides the complete agentic solution:
 
 Agno brings a novel architecture that no other framework provides, your AgentOS runs securely in your cloud, and the control plane connects directly to it from your browser. You don't need to send data to any external services or pay retention costs, you get complete privacy and control.
 
-## Designed for Agent Engineering
+## Features
 
-Agno is an incredibly feature-rich framework, designed for Agent Engineering. Here are some key features:
+Agno is an incredibly feature-rich framework purpose-built for Agent Engineering. Here are some key features:
 
 | **Category**                           | **Feature**                     | **Description**                                                                                                           |
 | -------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| **Core Intelligence**                  | **Model Agnostic**              | Works with any model provider so you can use your favorite LLMs.                                                          |
-|                                        | **Type Safe**                   | Enforce structured I/O through `input_schema` and `output_schema` for predictable, composable behavior.                   |
-|                                        | **Dynamic Context Engineering** | Inject variables, state, and retrieved data on the fly into context. Perfect for dependency-driven agents.                |
-| **Memory, Knowledge, and Persistence** | **Persistent Storage**          | Give your Agents, Teams, and Workflows a database to persist session history, state, and messages.                        |
-|                                        | **User Memory**                 | Built-in memory system that allows Agents to recall user-specific context across sessions.                                |
-|                                        | **Agentic RAG**                 | Connect to 20+ vector stores (called **Knowledge** in Agno) with hybrid search + reranking out of the box.                |
-|                                        | **Culture (Collective Memory)** | Shared knowledge that compounds across agents and time.                                                                   |
-| **Execution & Control**                | **Human-in-the-Loop**           | Native support for confirmations, manual overrides, and external tool execution.                                          |
+| **Foundational Principles**            | **Model Agnostic**              | Supports all model providers so you can choose the best model for your use case |
+|                                        | **Type Safe**                   | Enforces structured I/O through input_schema and output_schema for predictable and composable agent behavior. |
+|                                        | **Dynamic Context**             | Inject variables, state, and retrieved data at runtime into context. Compress, summarize and filter context to keep your Agents focused and efficient. |
+|                                        | **Designed for Scale**          | Designed around async execution and long-running tasks for high throughput agent workloads. |
+| **Memory, Knowledge, and Persistence** | **Persistent Storage**          | Give your Agents, Teams, and Workflows a database to persist session history, state, and messages. |
+|                                        | **User Memory**                 | Built in memory layer that helps agents recall user specific context across sessions. |
+|                                        | **Agentic RAG**                 | Connect to 20+ vector stores (called **Knowledge**) with hybrid search, reranking, and chunking out of the box. |
+|                                        | **Culture** | Shared long term collective memory that compounds across agents and time. |
+|                                        | **Ephemeral Context** | In memory scratchpad for short lived reasoning without polluting long term state. |
+| **Execution & Control**                | **Human-in-the-Loop**           | Native support for confirmations, approvals, manual overrides, and external actions. |
 |                                        | **Guardrails**                  | Built-in safeguards for validation, security, and prompt protection.                                                      |
-|                                        | **Agent Lifecycle Hooks**       | Pre- and post-hooks to validate or transform inputs and outputs.                                                          |
-|                                        | **MCP Integration**             | First-class support for the Model Context Protocol (MCP) to connect Agents with external systems.                         |
-|                                        | **Toolkits**                    | 100+ built-in toolkits with thousands of tools, ready for use across data, code, web, and enterprise APIs.                |
-| **Runtime & Evaluation**               | **Runtime**                     | Pre-built FastAPI based runtime with SSE compatible endpoints, ready for production on day 1.                             |
-|                                        | **Control Plane (UI)**          | Integrated interface to visualize, monitor, and debug agent activity in real time.                                        |
-|                                        | **Natively Multimodal**         | Agents can process and generate text, images, audio, video, and files.                                                    |
-|                                        | **Evals**                       | Measure your Agents' Accuracy, Performance, and Reliability.                                                              |
+|                                        | **Agent Lifecycle Hooks**       | Pre and post hooks to validate, enrich, or transform inputs and outputs. |
+|                                        | **MCP Integration**             | First-class support for the Model Context Protocol (MCP) to connect Agents with external systems. |
+|                                        | **A2A Integration**             | First-class support for the Agent to Agent communication protocol (A2A). |
+|                                        | **Toolkits**                    | 100+ built in toolkits with thousands of tools covering data, code, web, and enterprise APIs. |
+| **Runtime & Evaluation**               | **Runtime**                     | Prebuilt FastAPI runtime with SSE compatible endpoints. Production ready from day one. |
+|                                        | **Control Plane (UI)**          | Integrated interface to test, observe, and debug your agents, teams, and workflows in real time. |
+|                                        | **Natively Multimodal**         | Agents can process and generate text, images, audio, video, and files. |
+|                                        | **Evals**                       | Measure Accuracy, Performance, Latency, and Reliability across agents and workflows. |
+|                                        | **Durable Execution**           | Built in support for long running, resumable workflows. |
 | **Security & Privacy**                 | **Private by Design**           | Runs entirely in your cloud. The UI connects directly to your AgentOS from your browser, no data is ever sent externally. |
 |                                        | **Data Governance**             | Your data lives securely in your Agent database, no external data sharing or vendor lock-in.                              |
 |                                        | **Access Control**              | Role-based access (RBAC) and per-agent permissions to protect sensitive contexts and tools.                               |
@@ -544,7 +549,7 @@ At Agno, we optimize performance across 3 dimensions:
 
 1. **Agent performance:** We optimize static operations (instantiation, memory footprint) and runtime operations (tool calls, memory updates, history management).
 2. **System performance:** The AgentOS API is async by default and has a minimal memory footprint. The system is stateless and horizontally scalable, with a focus on preventing memory leaks. It handles parallel and batch embedding generation during knowledge ingestion, metrics collection in background tasks, and other system-level optimizations.
-3. **Agent reliability and accuracy:** Monitored through evals, which we’ll explore later.
+3. **Agent reliability and accuracy:** Monitored through evals, which we'll explore later.
 
 ### Agent Performance