agno 2.2.13__py3-none-any.whl → 2.4.3__py3-none-any.whl

agno/run/agent.py

@@ -11,6 +11,7 @@ from agno.models.metrics import Metrics
 from agno.models.response import ToolExecution
 from agno.reasoning.step import ReasoningStep
 from agno.run.base import BaseRunOutputEvent, MessageReferences, RunStatus
+from agno.run.requirement import RunRequirement
 from agno.utils.log import logger
 from agno.utils.media import (
     reconstruct_audio_list,
@@ -54,8 +55,11 @@ class RunInput:
             return self.input_content.model_dump_json(exclude_none=True)
         elif isinstance(self.input_content, Message):
             return json.dumps(self.input_content.to_dict())
-        elif isinstance(self.input_content, list) and self.input_content and isinstance(self.input_content[0], Message):
-            return json.dumps([m.to_dict() for m in self.input_content])
+        elif isinstance(self.input_content, list):
+            try:
+                return json.dumps(self.to_dict().get("input_content"))
+            except Exception:
+                return str(self.input_content)
         else:
             return str(self.input_content)
 
@@ -70,22 +74,15 @@ class RunInput:
                 result["input_content"] = self.input_content.model_dump(exclude_none=True)
             elif isinstance(self.input_content, Message):
                 result["input_content"] = self.input_content.to_dict()
-
-            # Handle input_content provided as a list of Message objects
-            elif (
-                isinstance(self.input_content, list)
-                and self.input_content
-                and isinstance(self.input_content[0], Message)
-            ):
-                result["input_content"] = [m.to_dict() for m in self.input_content]
-
-            # Handle input_content provided as a list of dicts
-            elif (
-                isinstance(self.input_content, list) and self.input_content and isinstance(self.input_content[0], dict)
-            ):
-                for content in self.input_content:
-                    # Handle media input
-                    if isinstance(content, dict):
+            elif isinstance(self.input_content, list):
+                serialized_items: List[Any] = []
+                for item in self.input_content:
+                    if isinstance(item, Message):
+                        serialized_items.append(item.to_dict())
+                    elif isinstance(item, BaseModel):
+                        serialized_items.append(item.model_dump(exclude_none=True))
+                    elif isinstance(item, dict):
+                        content = dict(item)
                         if content.get("images"):
                             content["images"] = [
                                 img.to_dict() if isinstance(img, Image) else img for img in content["images"]
@@ -102,7 +99,11 @@ class RunInput:
                             content["files"] = [
                                 file.to_dict() if isinstance(file, File) else file for file in content["files"]
                             ]
-                result["input_content"] = self.input_content
+                        serialized_items.append(content)
+                    else:
+                        serialized_items.append(item)
+
+                result["input_content"] = serialized_items
             else:
                 result["input_content"] = self.input_content
 
@@ -152,9 +153,11 @@ class RunEvent(str, Enum):
 
     tool_call_started = "ToolCallStarted"
     tool_call_completed = "ToolCallCompleted"
+    tool_call_error = "ToolCallError"
 
     reasoning_started = "ReasoningStarted"
     reasoning_step = "ReasoningStep"
+    reasoning_content_delta = "ReasoningContentDelta"
     reasoning_completed = "ReasoningCompleted"
 
     memory_update_started = "MemoryUpdateStarted"
@@ -169,6 +172,12 @@ class RunEvent(str, Enum):
     output_model_response_started = "OutputModelResponseStarted"
     output_model_response_completed = "OutputModelResponseCompleted"
 
+    model_request_started = "ModelRequestStarted"
+    model_request_completed = "ModelRequestCompleted"
+
+    compression_started = "CompressionStarted"
+    compression_completed = "CompressionCompleted"
+
     custom_event = "CustomEvent"
 
 
@@ -273,11 +282,18 @@ class RunCompletedEvent(BaseAgentRunEvent):
 class RunPausedEvent(BaseAgentRunEvent):
     event: str = RunEvent.run_paused.value
     tools: Optional[List[ToolExecution]] = None
+    requirements: Optional[List[RunRequirement]] = None
 
     @property
     def is_paused(self):
         return True
 
+    @property
+    def active_requirements(self) -> List[RunRequirement]:
+        if not self.requirements:
+            return []
+        return [requirement for requirement in self.requirements if not requirement.is_resolved()]
+
 
 @dataclass
 class RunContinuedEvent(BaseAgentRunEvent):
@@ -339,6 +355,7 @@ class MemoryUpdateStartedEvent(BaseAgentRunEvent):
 @dataclass
 class MemoryUpdateCompletedEvent(BaseAgentRunEvent):
     event: str = RunEvent.memory_update_completed.value
+    memories: Optional[List[Any]] = None
 
 
 @dataclass
@@ -365,6 +382,14 @@ class ReasoningStepEvent(BaseAgentRunEvent):
     reasoning_content: str = ""
 
 
+@dataclass
+class ReasoningContentDeltaEvent(BaseAgentRunEvent):
+    """Event for streaming reasoning content chunks as they arrive."""
+
+    event: str = RunEvent.reasoning_content_delta.value
+    reasoning_content: str = ""  # The delta/chunk of reasoning content
+
+
 @dataclass
 class ReasoningCompletedEvent(BaseAgentRunEvent):
     event: str = RunEvent.reasoning_completed.value
@@ -388,6 +413,13 @@ class ToolCallCompletedEvent(BaseAgentRunEvent):
     audio: Optional[List[Audio]] = None  # Audio produced by the tool call
 
 
+@dataclass
+class ToolCallErrorEvent(BaseAgentRunEvent):
+    event: str = RunEvent.tool_call_error.value
+    tool: Optional[ToolExecution] = None
+    error: Optional[str] = None
+
+
 @dataclass
 class ParserModelResponseStartedEvent(BaseAgentRunEvent):
     event: str = RunEvent.parser_model_response_started.value
@@ -408,9 +440,53 @@ class OutputModelResponseCompletedEvent(BaseAgentRunEvent):
     event: str = RunEvent.output_model_response_completed.value
 
 
+@dataclass
+class ModelRequestStartedEvent(BaseAgentRunEvent):
+    """Event sent when a model request is about to be made"""
+
+    event: str = RunEvent.model_request_started.value
+    model: Optional[str] = None
+    model_provider: Optional[str] = None
+
+
+@dataclass
+class ModelRequestCompletedEvent(BaseAgentRunEvent):
+    """Event sent when a model request has completed"""
+
+    event: str = RunEvent.model_request_completed.value
+    model: Optional[str] = None
+    model_provider: Optional[str] = None
+    input_tokens: Optional[int] = None
+    output_tokens: Optional[int] = None
+    total_tokens: Optional[int] = None
+    time_to_first_token: Optional[float] = None
+    reasoning_tokens: Optional[int] = None
+    cache_read_tokens: Optional[int] = None
+    cache_write_tokens: Optional[int] = None
+
+
+@dataclass
+class CompressionStartedEvent(BaseAgentRunEvent):
+    """Event sent when tool result compression is about to start"""
+
+    event: str = RunEvent.compression_started.value
+
+
+@dataclass
+class CompressionCompletedEvent(BaseAgentRunEvent):
+    """Event sent when tool result compression has completed"""
+
+    event: str = RunEvent.compression_completed.value
+    tool_results_compressed: Optional[int] = None
+    original_size: Optional[int] = None
+    compressed_size: Optional[int] = None
+
+
 @dataclass
 class CustomEvent(BaseAgentRunEvent):
     event: str = RunEvent.custom_event.value
+    # tool_call_id for ToolExecution
+    tool_call_id: Optional[str] = None
 
     def __init__(self, **kwargs):
         # Store arbitrary attributes directly on the instance
@@ -434,6 +510,7 @@ RunOutputEvent = Union[
     PostHookCompletedEvent,
     ReasoningStartedEvent,
     ReasoningStepEvent,
+    ReasoningContentDeltaEvent,
     ReasoningCompletedEvent,
     MemoryUpdateStartedEvent,
     MemoryUpdateCompletedEvent,
@@ -441,10 +518,15 @@ RunOutputEvent = Union[
     SessionSummaryCompletedEvent,
     ToolCallStartedEvent,
     ToolCallCompletedEvent,
+    ToolCallErrorEvent,
     ParserModelResponseStartedEvent,
     ParserModelResponseCompletedEvent,
     OutputModelResponseStartedEvent,
     OutputModelResponseCompletedEvent,
+    ModelRequestStartedEvent,
+    ModelRequestCompletedEvent,
+    CompressionStartedEvent,
+    CompressionCompletedEvent,
     CustomEvent,
 ]
 
@@ -466,6 +548,7 @@ RUN_EVENT_TYPE_REGISTRY = {
     RunEvent.post_hook_completed.value: PostHookCompletedEvent,
     RunEvent.reasoning_started.value: ReasoningStartedEvent,
     RunEvent.reasoning_step.value: ReasoningStepEvent,
+    RunEvent.reasoning_content_delta.value: ReasoningContentDeltaEvent,
     RunEvent.reasoning_completed.value: ReasoningCompletedEvent,
     RunEvent.memory_update_started.value: MemoryUpdateStartedEvent,
     RunEvent.memory_update_completed.value: MemoryUpdateCompletedEvent,
@@ -473,10 +556,15 @@ RUN_EVENT_TYPE_REGISTRY = {
     RunEvent.session_summary_completed.value: SessionSummaryCompletedEvent,
     RunEvent.tool_call_started.value: ToolCallStartedEvent,
     RunEvent.tool_call_completed.value: ToolCallCompletedEvent,
+    RunEvent.tool_call_error.value: ToolCallErrorEvent,
     RunEvent.parser_model_response_started.value: ParserModelResponseStartedEvent,
     RunEvent.parser_model_response_completed.value: ParserModelResponseCompletedEvent,
     RunEvent.output_model_response_started.value: OutputModelResponseStartedEvent,
     RunEvent.output_model_response_completed.value: OutputModelResponseCompletedEvent,
+    RunEvent.model_request_started.value: ModelRequestStartedEvent,
+    RunEvent.model_request_completed.value: ModelRequestCompletedEvent,
+    RunEvent.compression_started.value: CompressionStartedEvent,
+    RunEvent.compression_completed.value: CompressionCompletedEvent,
     RunEvent.custom_event.value: CustomEvent,
 }
 
@@ -539,11 +627,20 @@ class RunOutput:
 
     status: RunStatus = RunStatus.running
 
+    # User control flow (HITL) requirements to continue a run when paused, in order of arrival
+    requirements: Optional[list[RunRequirement]] = None
+
     # === FOREIGN KEY RELATIONSHIPS ===
     # These fields establish relationships to parent workflow/step structures
     # and should be treated as foreign keys for data integrity
     workflow_step_id: Optional[str] = None  # FK: Points to StepOutput.step_id
 
+    @property
+    def active_requirements(self) -> list[RunRequirement]:
+        if not self.requirements:
+            return []
+        return [requirement for requirement in self.requirements if not requirement.is_resolved()]
+
     @property
     def is_paused(self):
         return self.status == RunStatus.paused
@@ -572,6 +669,7 @@ class RunOutput:
             and k
             not in [
                 "messages",
+                "metrics",
                 "tools",
                 "metadata",
                 "images",
@@ -586,6 +684,7 @@ class RunOutput:
                 "reasoning_steps",
                 "reasoning_messages",
                 "references",
+                "requirements",
             ]
         }
 
@@ -671,6 +770,9 @@ class RunOutput:
                 else:
                     _dict["tools"].append(tool)
 
+        if self.requirements is not None:
+            _dict["requirements"] = [req.to_dict() if hasattr(req, "to_dict") else req for req in self.requirements]
+
         if self.input is not None:
             _dict["input"] = self.input.to_dict()
 
@@ -717,6 +819,18 @@ class RunOutput:
         tools = data.pop("tools", [])
         tools = [ToolExecution.from_dict(tool) for tool in tools] if tools else None
 
+        # Handle requirements
+        requirements_data = data.pop("requirements", None)
+        requirements: Optional[List[RunRequirement]] = None
+        if requirements_data is not None:
+            requirements_list: List[RunRequirement] = []
+            for item in requirements_data:
+                if isinstance(item, RunRequirement):
+                    requirements_list.append(item)
+                elif isinstance(item, dict):
+                    requirements_list.append(RunRequirement.from_dict(item))
+            requirements = requirements_list if requirements_list else None
+
         images = reconstruct_images(data.pop("images", []))
         videos = reconstruct_videos(data.pop("videos", []))
         audio = reconstruct_audio_list(data.pop("audio", []))
@@ -771,6 +885,7 @@ class RunOutput:
             reasoning_steps=reasoning_steps,
             reasoning_messages=reasoning_messages,
             references=references,
+            requirements=requirements,
             **filtered_data,
         )
 

agno/run/base.py

@@ -1,6 +1,6 @@
 from dataclasses import asdict, dataclass
 from enum import Enum
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Type, Union
 
 from pydantic import BaseModel
 
@@ -18,10 +18,14 @@ class RunContext:
     session_id: str
     user_id: Optional[str] = None
 
+    workflow_id: Optional[str] = None
+    workflow_name: Optional[str] = None
+
     dependencies: Optional[Dict[str, Any]] = None
     knowledge_filters: Optional[Union[Dict[str, Any], List[FilterExpr]]] = None
     metadata: Optional[Dict[str, Any]] = None
     session_state: Optional[Dict[str, Any]] = None
+    output_schema: Optional[Union[Type[BaseModel], Dict[str, Any]]] = None
 
 
 @dataclass
@@ -49,6 +53,9 @@ class BaseRunOutputEvent:
                 "additional_input",
                 "session_summary",
                 "metrics",
+                "run_input",
+                "requirements",
+                "memories",
             ]
         }
 
@@ -133,6 +140,15 @@ class BaseRunOutputEvent:
         if hasattr(self, "session_summary") and self.session_summary is not None:
             _dict["session_summary"] = self.session_summary.to_dict()
 
+        if hasattr(self, "run_input") and self.run_input is not None:
+            _dict["run_input"] = self.run_input.to_dict()
+
+        if hasattr(self, "requirements") and self.requirements is not None:
+            _dict["requirements"] = [req.to_dict() if hasattr(req, "to_dict") else req for req in self.requirements]
+
+        if hasattr(self, "memories") and self.memories is not None:
+            _dict["memories"] = [mem.to_dict() if hasattr(mem, "to_dict") else mem for mem in self.memories]
+
         return _dict
 
     def to_json(self, separators=(", ", ": "), indent: Optional[int] = 2) -> str:
@@ -201,7 +217,39 @@ class BaseRunOutputEvent:
 
             data["session_summary"] = SessionSummary.from_dict(session_summary)
 
+        run_input = data.pop("run_input", None)
+        if run_input:
+            from agno.run.team import BaseTeamRunEvent
+
+            if issubclass(cls, BaseTeamRunEvent):
+                from agno.run.team import TeamRunInput
+
+                data["run_input"] = TeamRunInput.from_dict(run_input)
+            else:
+                from agno.run.agent import RunInput
+
+                data["run_input"] = RunInput.from_dict(run_input)
+
+                # Handle requirements
+
+        # Handle requirements
+        requirements_data = data.pop("requirements", None)
+        if requirements_data is not None:
+            from agno.run.requirement import RunRequirement
+
+            requirements_list: List[RunRequirement] = []
+            for item in requirements_data:
+                if isinstance(item, RunRequirement):
+                    requirements_list.append(item)
+                elif isinstance(item, dict):
+                    requirements_list.append(RunRequirement.from_dict(item))
+            data["requirements"] = requirements_list if requirements_list else None
+
         # Filter data to only include fields that are actually defined in the target class
+        # CustomEvent accepts arbitrary fields, so skip filtering for it
+        if cls.__name__ == "CustomEvent":
+            return cls(**data)
+
         from dataclasses import fields
 
         supported_fields = {f.name for f in fields(cls)}

agno/run/cancel.py

@@ -1,64 +1,37 @@
 """Run cancellation management."""
 
-import threading
 from typing import Dict
 
-from agno.exceptions import RunCancelledException
+from agno.run.cancellation_management.base import BaseRunCancellationManager
+from agno.run.cancellation_management.in_memory_cancellation_manager import InMemoryRunCancellationManager
 from agno.utils.log import logger
 
+# Global cancellation manager instance
+_cancellation_manager: BaseRunCancellationManager = InMemoryRunCancellationManager()
 
-class RunCancellationManager:
-    """Manages cancellation state for agent runs."""
-
-    def __init__(self):
-        self._cancelled_runs: Dict[str, bool] = {}
-        self._lock = threading.Lock()
-
-    def register_run(self, run_id: str) -> None:
-        """Register a new run as not cancelled."""
-        with self._lock:
-            self._cancelled_runs[run_id] = False
-
-    def cancel_run(self, run_id: str) -> bool:
-        """Cancel a run by marking it as cancelled.
-
-        Returns:
-            bool: True if run was found and cancelled, False if run not found.
-        """
-        with self._lock:
-            if run_id in self._cancelled_runs:
-                self._cancelled_runs[run_id] = True
-                logger.info(f"Run {run_id} marked for cancellation")
-                return True
-            else:
-                logger.warning(f"Attempted to cancel unknown run {run_id}")
-                return False
-
-    def is_cancelled(self, run_id: str) -> bool:
-        """Check if a run is cancelled."""
-        with self._lock:
-            return self._cancelled_runs.get(run_id, False)
-
-    def cleanup_run(self, run_id: str) -> None:
-        """Remove a run from tracking (called when run completes)."""
-        with self._lock:
-            if run_id in self._cancelled_runs:
-                del self._cancelled_runs[run_id]
-
-    def raise_if_cancelled(self, run_id: str) -> None:
-        """Check if a run should be cancelled and raise exception if so."""
-        if self.is_cancelled(run_id):
-            logger.info(f"Cancelling run {run_id}")
-            raise RunCancelledException(f"Run {run_id} was cancelled")
-
-    def get_active_runs(self) -> Dict[str, bool]:
-        """Get all currently tracked runs and their cancellation status."""
-        with self._lock:
-            return self._cancelled_runs.copy()
 
+def set_cancellation_manager(manager: BaseRunCancellationManager) -> None:
+    """Set a custom cancellation manager.
 
-# Global cancellation manager instance
-_cancellation_manager = RunCancellationManager()
+    Args:
+        manager: A BaseRunCancellationManager instance or subclass.
+
+    Example:
+        ```python
+        class MyCustomManager(BaseRunCancellationManager):
+            ....
+
+        set_cancellation_manager(MyCustomManager())
+        ```
+    """
+    global _cancellation_manager
+    _cancellation_manager = manager
+    logger.info(f"Cancellation manager set to {type(manager).__name__}")
+
+
+def get_cancellation_manager() -> BaseRunCancellationManager:
+    """Get the current cancellation manager instance."""
+    return _cancellation_manager
 
 
 def register_run(run_id: str) -> None:
@@ -66,16 +39,56 @@ def register_run(run_id: str) -> None:
     _cancellation_manager.register_run(run_id)
 
 
+async def aregister_run(run_id: str) -> None:
+    """Register a new run for cancellation tracking (async version)."""
+    await _cancellation_manager.aregister_run(run_id)
+
+
 def cancel_run(run_id: str) -> bool:
     """Cancel a run."""
     return _cancellation_manager.cancel_run(run_id)
 
 
+async def acancel_run(run_id: str) -> bool:
+    """Cancel a run (async version)."""
+    return await _cancellation_manager.acancel_run(run_id)
+
+
+def is_cancelled(run_id: str) -> bool:
+    """Check if a run is cancelled."""
+    return _cancellation_manager.is_cancelled(run_id)
+
+
+async def ais_cancelled(run_id: str) -> bool:
+    """Check if a run is cancelled (async version)."""
+    return await _cancellation_manager.ais_cancelled(run_id)
+
+
 def cleanup_run(run_id: str) -> None:
     """Clean up cancellation tracking for a completed run."""
     _cancellation_manager.cleanup_run(run_id)
 
 
+async def acleanup_run(run_id: str) -> None:
+    """Clean up cancellation tracking for a completed run (async version)."""
+    await _cancellation_manager.acleanup_run(run_id)
+
+
 def raise_if_cancelled(run_id: str) -> None:
     """Check if a run should be cancelled and raise exception if so."""
     _cancellation_manager.raise_if_cancelled(run_id)
+
+
+async def araise_if_cancelled(run_id: str) -> None:
+    """Check if a run should be cancelled and raise exception if so (async version)."""
+    await _cancellation_manager.araise_if_cancelled(run_id)
+
+
+def get_active_runs() -> Dict[str, bool]:
+    """Get all currently tracked runs and their cancellation status."""
+    return _cancellation_manager.get_active_runs()
+
+
+async def aget_active_runs() -> Dict[str, bool]:
+    """Get all currently tracked runs and their cancellation status (async version)."""
+    return await _cancellation_manager.aget_active_runs()

agno/run/cancellation_management/__init__.py

@@ -0,0 +1,9 @@
+from agno.run.cancellation_management.base import BaseRunCancellationManager
+from agno.run.cancellation_management.in_memory_cancellation_manager import InMemoryRunCancellationManager
+from agno.run.cancellation_management.redis_cancellation_manager import RedisRunCancellationManager
+
+__all__ = [
+    "BaseRunCancellationManager",
+    "InMemoryRunCancellationManager",
+    "RedisRunCancellationManager",
+]

agno/run/cancellation_management/base.py

@@ -0,0 +1,78 @@
+from abc import ABC, abstractmethod
+from typing import Dict
+
+
+class BaseRunCancellationManager(ABC):
+    """Manages cancellation state for agent runs.
+
+    This class can be extended to implement custom cancellation logic.
+    Use set_cancellation_manager() to replace the global instance with your own.
+    """
+
+    @abstractmethod
+    def register_run(self, run_id: str) -> None:
+        """Register a new run as not cancelled."""
+        pass
+
+    @abstractmethod
+    async def aregister_run(self, run_id: str) -> None:
+        """Register a new run as not cancelled (async version)."""
+        pass
+
+    @abstractmethod
+    def cancel_run(self, run_id: str) -> bool:
+        """Cancel a run by marking it as cancelled.
+
+        Returns:
+            bool: True if run was found and cancelled, False if run not found.
+        """
+        pass
+
+    @abstractmethod
+    async def acancel_run(self, run_id: str) -> bool:
+        """Cancel a run by marking it as cancelled (async version).
+
+        Returns:
+            bool: True if run was found and cancelled, False if run not found.
+        """
+        pass
+
+    @abstractmethod
+    def is_cancelled(self, run_id: str) -> bool:
+        """Check if a run is cancelled."""
+        pass
+
+    @abstractmethod
+    async def ais_cancelled(self, run_id: str) -> bool:
+        """Check if a run is cancelled (async version)."""
+        pass
+
+    @abstractmethod
+    def cleanup_run(self, run_id: str) -> None:
+        """Remove a run from tracking (called when run completes)."""
+        pass
+
+    @abstractmethod
+    async def acleanup_run(self, run_id: str) -> None:
+        """Remove a run from tracking (called when run completes) (async version)."""
+        pass
+
+    @abstractmethod
+    def raise_if_cancelled(self, run_id: str) -> None:
+        """Check if a run should be cancelled and raise exception if so."""
+        pass
+
+    @abstractmethod
+    async def araise_if_cancelled(self, run_id: str) -> None:
+        """Check if a run should be cancelled and raise exception if so (async version)."""
+        pass
+
+    @abstractmethod
+    def get_active_runs(self) -> Dict[str, bool]:
+        """Get all currently tracked runs and their cancellation status."""
+        pass
+
+    @abstractmethod
+    async def aget_active_runs(self) -> Dict[str, bool]:
+        """Get all currently tracked runs and their cancellation status (async version)."""
+        pass