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

agno/run/base.py

@@ -1,17 +1,30 @@
 from dataclasses import asdict, dataclass
 from enum import Enum
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional, Type, Union
 
 from pydantic import BaseModel
 
+from agno.filters import FilterExpr
 from agno.media import Audio, Image, Video
 from agno.models.message import Citations, Message, MessageReferences
 from agno.models.metrics import Metrics
-from agno.models.response import ToolExecution
 from agno.reasoning.step import ReasoningStep
 from agno.utils.log import log_error
 
 
+@dataclass
+class RunContext:
+    run_id: str
+    session_id: str
+    user_id: 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[Type[BaseModel]] = None
+
+
 @dataclass
 class BaseRunOutputEvent:
     def to_dict(self) -> Dict[str, Any]:
@@ -35,7 +48,9 @@ class BaseRunOutputEvent:
                 "reasoning_steps",
                 "references",
                 "additional_input",
+                "session_summary",
                 "metrics",
+                "run_input",
             ]
         }
 
@@ -97,6 +112,8 @@ class BaseRunOutputEvent:
             _dict["content"] = self.content.model_dump(exclude_none=True)
 
         if hasattr(self, "tools") and self.tools is not None:
+            from agno.models.response import ToolExecution
+
             _dict["tools"] = []
             for tool in self.tools:
                 if isinstance(tool, ToolExecution):
@@ -105,6 +122,8 @@ class BaseRunOutputEvent:
                     _dict["tools"].append(tool)
 
         if hasattr(self, "tool") and self.tool is not None:
+            from agno.models.response import ToolExecution
+
             if isinstance(self.tool, ToolExecution):
                 _dict["tool"] = self.tool.to_dict()
             else:
@@ -113,6 +132,12 @@ class BaseRunOutputEvent:
         if hasattr(self, "metrics") and self.metrics is not None:
             _dict["metrics"] = self.metrics.to_dict()
 
+        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()
+
         return _dict
 
     def to_json(self, separators=(", ", ": "), indent: Optional[int] = 2) -> str:
@@ -135,6 +160,8 @@ class BaseRunOutputEvent:
     def from_dict(cls, data: Dict[str, Any]):
         tool = data.pop("tool", None)
         if tool:
+            from agno.models.response import ToolExecution
+
             data["tool"] = ToolExecution.from_dict(tool)
 
         images = data.pop("images", None)
@@ -173,7 +200,32 @@ class BaseRunOutputEvent:
         if metrics:
             data["metrics"] = Metrics(**metrics)
 
-        return cls(**data)
+        session_summary = data.pop("session_summary", None)
+        if session_summary:
+            from agno.session.summary import SessionSummary
+
+            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)
+
+        # Filter data to only include fields that are actually defined in the target class
+        from dataclasses import fields
+
+        supported_fields = {f.name for f in fields(cls)}
+        filtered_data = {k: v for k, v in data.items() if k in supported_fields}
+
+        return cls(**filtered_data)
 
     @property
     def is_paused(self):

agno/run/requirement.py

@@ -0,0 +1,181 @@
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from uuid import uuid4
+
+from agno.models.response import ToolExecution, UserInputField
+
+if TYPE_CHECKING:
+    pass
+
+
+@dataclass
+class RunRequirement:
+    """Requirement to complete a paused run (used in HITL flows)"""
+
+    tool_execution: Optional[ToolExecution] = None
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    # User confirmation
+    confirmation: Optional[bool] = None
+    confirmation_note: Optional[str] = None
+
+    # User input
+    user_input_schema: Optional[List[UserInputField]] = None
+
+    # External execution
+    external_execution_result: Optional[str] = None
+
+    def __init__(
+        self,
+        tool_execution: ToolExecution,
+        id: Optional[str] = None,
+        created_at: Optional[datetime] = None,
+    ):
+        self.id = id or str(uuid4())
+        self.tool_execution = tool_execution
+        self.user_input_schema = tool_execution.user_input_schema if tool_execution else None
+        self.created_at = created_at or datetime.now(timezone.utc)
+        self.confirmation = None
+        self.confirmation_note = None
+        self.external_execution_result = None
+
+    @property
+    def needs_confirmation(self) -> bool:
+        if self.confirmation is not None:
+            return False
+        if not self.tool_execution:
+            return False
+        if self.tool_execution.confirmed is True:
+            return True
+
+        return self.tool_execution.requires_confirmation or False
+
+    @property
+    def needs_user_input(self) -> bool:
+        if not self.tool_execution:
+            return False
+        if self.tool_execution.answered is True:
+            return False
+        if self.user_input_schema and not all(field.value is not None for field in self.user_input_schema):
+            return True
+
+        return self.tool_execution.requires_user_input or False
+
+    @property
+    def needs_external_execution(self) -> bool:
+        if not self.tool_execution:
+            return False
+        if self.external_execution_result is not None:
+            return True
+
+        return self.tool_execution.external_execution_required or False
+
+    def confirm(self):
+        if not self.needs_confirmation:
+            raise ValueError("This requirement does not require confirmation")
+        self.confirmation = True
+        if self.tool_execution:
+            self.tool_execution.confirmed = True
+
+    def reject(self):
+        if not self.needs_confirmation:
+            raise ValueError("This requirement does not require confirmation")
+        self.confirmation = False
+        if self.tool_execution:
+            self.tool_execution.confirmed = False
+
+    def set_external_execution_result(self, result: str):
+        if not self.needs_external_execution:
+            raise ValueError("This requirement does not require external execution")
+        self.external_execution_result = result
+        if self.tool_execution:
+            self.tool_execution.result = result
+
+    def update_tool(self):
+        if not self.tool_execution:
+            return
+        if self.confirmation is True:
+            self.tool_execution.confirmed = True
+        elif self.confirmation is False:
+            self.tool_execution.confirmed = False
+        else:
+            raise ValueError("This requirement does not require confirmation or user input")
+
+    def is_resolved(self) -> bool:
+        """Return True if the requirement has been resolved"""
+        return not self.needs_confirmation and not self.needs_user_input and not self.needs_external_execution
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to JSON-serializable dictionary for storage."""
+        _dict: Dict[str, Any] = {
+            "id": self.id,
+            "created_at": self.created_at.isoformat() if isinstance(self.created_at, datetime) else self.created_at,
+            "confirmation": self.confirmation,
+            "confirmation_note": self.confirmation_note,
+            "external_execution_result": self.external_execution_result,
+        }
+
+        if self.tool_execution is not None:
+            _dict["tool_execution"] = (
+                self.tool_execution.to_dict() if isinstance(self.tool_execution, ToolExecution) else self.tool_execution
+            )
+
+        if self.user_input_schema is not None:
+            _dict["user_input_schema"] = [f.to_dict() if hasattr(f, "to_dict") else f for f in self.user_input_schema]
+
+        return {k: v for k, v in _dict.items() if v is not None}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "RunRequirement":
+        """Reconstruct from stored dictionary."""
+        if data is None:
+            raise ValueError("RunRequirement.from_dict() requires a non-None dict")
+
+        # Handle tool_execution
+        tool_data = data.get("tool_execution")
+        tool_execution: Optional[ToolExecution] = None
+        if isinstance(tool_data, ToolExecution):
+            tool_execution = tool_data
+        elif isinstance(tool_data, dict):
+            tool_execution = ToolExecution.from_dict(tool_data)
+
+        # Handle created_at (ISO string or datetime)
+        created_at_raw = data.get("created_at")
+        created_at: Optional[datetime] = None
+        if isinstance(created_at_raw, datetime):
+            created_at = created_at_raw
+        elif isinstance(created_at_raw, str):
+            try:
+                created_at = datetime.fromisoformat(created_at_raw)
+            except ValueError:
+                created_at = None
+
+        # Build requirement - tool_execution is required by __init__
+        # For legacy data without tool_execution, create a minimal placeholder
+        if tool_execution is None:
+            tool_execution = ToolExecution(tool_name="unknown", tool_args={})
+
+        requirement = cls(
+            tool_execution=tool_execution,
+            id=data.get("id"),
+            created_at=created_at,
+        )
+
+        # Set optional fields
+        requirement.confirmation = data.get("confirmation")
+        requirement.confirmation_note = data.get("confirmation_note")
+        requirement.external_execution_result = data.get("external_execution_result")
+
+        # Handle user_input_schema
+        schema_raw = data.get("user_input_schema")
+        if schema_raw is not None:
+            rebuilt_schema: List[UserInputField] = []
+            for item in schema_raw:
+                if isinstance(item, UserInputField):
+                    rebuilt_schema.append(item)
+                elif isinstance(item, dict):
+                    rebuilt_schema.append(UserInputField.from_dict(item))
+            requirement.user_input_schema = rebuilt_schema if rebuilt_schema else None
+
+        return requirement

agno/run/team.py

@@ -12,7 +12,15 @@ from agno.models.response import ToolExecution
 from agno.reasoning.step import ReasoningStep
 from agno.run.agent import RunEvent, RunOutput, RunOutputEvent, run_output_event_from_dict
 from agno.run.base import BaseRunOutputEvent, MessageReferences, RunStatus
+from agno.run.requirement import RunRequirement
 from agno.utils.log import log_error
+from agno.utils.media import (
+    reconstruct_audio_list,
+    reconstruct_files,
+    reconstruct_images,
+    reconstruct_response_audio,
+    reconstruct_videos,
+)
 
 
 @dataclass
@@ -59,12 +67,39 @@ class TeamRunInput:
                 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):
+                        if content.get("images"):
+                            content["images"] = [
+                                img.to_dict() if isinstance(img, Image) else img for img in content["images"]
+                            ]
+                        if content.get("videos"):
+                            content["videos"] = [
+                                vid.to_dict() if isinstance(vid, Video) else vid for vid in content["videos"]
+                            ]
+                        if content.get("audios"):
+                            content["audios"] = [
+                                aud.to_dict() if isinstance(aud, Audio) else aud for aud in content["audios"]
+                            ]
+                        if content.get("files"):
+                            content["files"] = [
+                                file.to_dict() if isinstance(file, File) else file for file in content["files"]
+                            ]
+                result["input_content"] = self.input_content
             else:
                 result["input_content"] = self.input_content
 
@@ -82,21 +117,10 @@ class TeamRunInput:
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> "TeamRunInput":
         """Create TeamRunInput from dictionary"""
-        images = None
-        if data.get("images"):
-            images = [Image.model_validate(img_data) for img_data in data["images"]]
-
-        videos = None
-        if data.get("videos"):
-            videos = [Video.model_validate(vid_data) for vid_data in data["videos"]]
-
-        audios = None
-        if data.get("audios"):
-            audios = [Audio.model_validate(aud_data) for aud_data in data["audios"]]
-
-        files = None
-        if data.get("files"):
-            files = [File.model_validate(file_data) for file_data in data["files"]]
+        images = reconstruct_images(data.get("images"))
+        videos = reconstruct_videos(data.get("videos"))
+        audios = reconstruct_audio_list(data.get("audios"))
+        files = reconstruct_files(data.get("files"))
 
         return cls(
             input_content=data.get("input_content", ""), images=images, videos=videos, audios=audios, files=files
@@ -109,6 +133,7 @@ class TeamRunEvent(str, Enum):
     run_started = "TeamRunStarted"
     run_content = "TeamRunContent"
     run_intermediate_content = "TeamRunIntermediateContent"
+    run_content_completed = "TeamRunContentCompleted"
     run_completed = "TeamRunCompleted"
     run_error = "TeamRunError"
     run_cancelled = "TeamRunCancelled"
@@ -116,6 +141,9 @@ class TeamRunEvent(str, Enum):
     pre_hook_started = "TeamPreHookStarted"
     pre_hook_completed = "TeamPreHookCompleted"
 
+    post_hook_started = "TeamPostHookStarted"
+    post_hook_completed = "TeamPostHookCompleted"
+
     tool_call_started = "TeamToolCallStarted"
     tool_call_completed = "TeamToolCallCompleted"
 
@@ -126,6 +154,9 @@ class TeamRunEvent(str, Enum):
     memory_update_started = "TeamMemoryUpdateStarted"
     memory_update_completed = "TeamMemoryUpdateCompleted"
 
+    session_summary_started = "TeamSessionSummaryStarted"
+    session_summary_completed = "TeamSessionSummaryCompleted"
+
     parser_model_response_started = "TeamParserModelResponseStarted"
     parser_model_response_completed = "TeamParserModelResponseCompleted"
 
@@ -207,6 +238,11 @@ class IntermediateRunContentEvent(BaseTeamRunEvent):
     content_type: str = "str"
 
 
+@dataclass
+class RunContentCompletedEvent(BaseTeamRunEvent):
+    event: str = TeamRunEvent.run_content_completed.value
+
+
 @dataclass
 class RunCompletedEvent(BaseTeamRunEvent):
     event: str = TeamRunEvent.run_completed.value
@@ -226,6 +262,7 @@ class RunCompletedEvent(BaseTeamRunEvent):
     member_responses: List[Union["TeamRunOutput", RunOutput]] = field(default_factory=list)
     metadata: Optional[Dict[str, Any]] = None
     metrics: Optional[Metrics] = None
+    session_state: Optional[Dict[str, Any]] = None
 
 
 @dataclass
@@ -263,6 +300,18 @@ class PreHookCompletedEvent(BaseTeamRunEvent):
     run_input: Optional[TeamRunInput] = None
 
 
+@dataclass
+class PostHookStartedEvent(BaseTeamRunEvent):
+    event: str = TeamRunEvent.post_hook_started.value
+    post_hook_name: Optional[str] = None
+
+
+@dataclass
+class PostHookCompletedEvent(BaseTeamRunEvent):
+    event: str = TeamRunEvent.post_hook_completed.value
+    post_hook_name: Optional[str] = None
+
+
 @dataclass
 class MemoryUpdateStartedEvent(BaseTeamRunEvent):
     event: str = TeamRunEvent.memory_update_started.value
@@ -273,6 +322,17 @@ class MemoryUpdateCompletedEvent(BaseTeamRunEvent):
     event: str = TeamRunEvent.memory_update_completed.value
 
 
+@dataclass
+class SessionSummaryStartedEvent(BaseTeamRunEvent):
+    event: str = TeamRunEvent.session_summary_started.value
+
+
+@dataclass
+class SessionSummaryCompletedEvent(BaseTeamRunEvent):
+    event: str = TeamRunEvent.session_summary_completed.value
+    session_summary: Optional[Any] = None
+
+
 @dataclass
 class ReasoningStartedEvent(BaseTeamRunEvent):
     event: str = TeamRunEvent.reasoning_started.value
@@ -333,11 +393,17 @@ class OutputModelResponseCompletedEvent(BaseTeamRunEvent):
 class CustomEvent(BaseTeamRunEvent):
     event: str = TeamRunEvent.custom_event.value
 
+    def __init__(self, **kwargs):
+        # Store arbitrary attributes directly on the instance
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
 
 TeamRunOutputEvent = Union[
     RunStartedEvent,
     RunContentEvent,
     IntermediateRunContentEvent,
+    RunContentCompletedEvent,
     RunCompletedEvent,
     RunErrorEvent,
     RunCancelledEvent,
@@ -348,6 +414,8 @@ TeamRunOutputEvent = Union[
     ReasoningCompletedEvent,
     MemoryUpdateStartedEvent,
     MemoryUpdateCompletedEvent,
+    SessionSummaryStartedEvent,
+    SessionSummaryCompletedEvent,
     ToolCallStartedEvent,
     ToolCallCompletedEvent,
     ParserModelResponseStartedEvent,
@@ -362,16 +430,21 @@ TEAM_RUN_EVENT_TYPE_REGISTRY = {
     TeamRunEvent.run_started.value: RunStartedEvent,
     TeamRunEvent.run_content.value: RunContentEvent,
     TeamRunEvent.run_intermediate_content.value: IntermediateRunContentEvent,
+    TeamRunEvent.run_content_completed.value: RunContentCompletedEvent,
     TeamRunEvent.run_completed.value: RunCompletedEvent,
     TeamRunEvent.run_error.value: RunErrorEvent,
     TeamRunEvent.run_cancelled.value: RunCancelledEvent,
     TeamRunEvent.pre_hook_started.value: PreHookStartedEvent,
     TeamRunEvent.pre_hook_completed.value: PreHookCompletedEvent,
+    TeamRunEvent.post_hook_started.value: PostHookStartedEvent,
+    TeamRunEvent.post_hook_completed.value: PostHookCompletedEvent,
     TeamRunEvent.reasoning_started.value: ReasoningStartedEvent,
     TeamRunEvent.reasoning_step.value: ReasoningStepEvent,
     TeamRunEvent.reasoning_completed.value: ReasoningCompletedEvent,
     TeamRunEvent.memory_update_started.value: MemoryUpdateStartedEvent,
     TeamRunEvent.memory_update_completed.value: MemoryUpdateCompletedEvent,
+    TeamRunEvent.session_summary_started.value: SessionSummaryStartedEvent,
+    TeamRunEvent.session_summary_completed.value: SessionSummaryCompletedEvent,
     TeamRunEvent.tool_call_started.value: ToolCallStartedEvent,
     TeamRunEvent.tool_call_completed.value: ToolCallCompletedEvent,
     TeamRunEvent.parser_model_response_started.value: ParserModelResponseStartedEvent,
@@ -397,8 +470,19 @@ def team_run_output_event_from_dict(data: dict) -> BaseTeamRunEvent:
 class TeamRunOutput:
     """Response returned by Team.run() functions"""
 
+    run_id: Optional[str] = None
+    team_id: Optional[str] = None
+    team_name: Optional[str] = None
+    session_id: Optional[str] = None
+    parent_run_id: Optional[str] = None
+    user_id: Optional[str] = None
+
+    # Input media and messages from user
+    input: Optional[TeamRunInput] = None
+
     content: Optional[Any] = None
     content_type: str = "str"
+
     messages: Optional[List[Message]] = None
     metrics: Optional[Metrics] = None
     model: Optional[str] = None
@@ -406,12 +490,6 @@ class TeamRunOutput:
 
     member_responses: List[Union["TeamRunOutput", RunOutput]] = field(default_factory=list)
 
-    run_id: Optional[str] = None
-    team_id: Optional[str] = None
-    team_name: Optional[str] = None
-    session_id: Optional[str] = None
-    parent_run_id: Optional[str] = None
-
     tools: Optional[List[ToolExecution]] = None
 
     images: Optional[List[Image]] = None  # Images from member runs
@@ -421,14 +499,12 @@ class TeamRunOutput:
 
     response_audio: Optional[Audio] = None  # Model audio response
 
-    # Input media and messages from user
-    input: Optional[TeamRunInput] = None
-
     reasoning_content: Optional[str] = None
 
     citations: Optional[Citations] = None
     model_provider_data: Optional[Dict[str, Any]] = None
     metadata: Optional[Dict[str, Any]] = None
+    session_state: Optional[Dict[str, Any]] = None
 
     references: Optional[List[MessageReferences]] = None
     additional_input: Optional[List[Message]] = None
@@ -440,11 +516,20 @@ class TeamRunOutput:
 
     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
@@ -461,6 +546,7 @@ class TeamRunOutput:
             and k
             not in [
                 "messages",
+                "metrics",
                 "status",
                 "tools",
                 "metadata",
@@ -480,6 +566,9 @@ class TeamRunOutput:
         if self.events is not None:
             _dict["events"] = [e.to_dict() for e in self.events]
 
+        if self.metrics is not None:
+            _dict["metrics"] = self.metrics.to_dict() if isinstance(self.metrics, Metrics) else self.metrics
+
         if self.status is not None:
             _dict["status"] = self.status.value if isinstance(self.status, RunStatus) else self.status
 
@@ -598,23 +687,15 @@ class TeamRunOutput:
         if references is not None:
             references = [MessageReferences.model_validate(reference) for reference in references]
 
-        images = data.pop("images", [])
-        images = [Image.model_validate(image) for image in images] if images else None
-
-        videos = data.pop("videos", [])
-        videos = [Video.model_validate(video) for video in videos] if videos else None
-
-        audio = data.pop("audio", [])
-        audio = [Audio.model_validate(audio) for audio in audio] if audio else None
-
-        files = data.pop("files", [])
-        files = [File.model_validate(file) for file in files] if files else None
+        images = reconstruct_images(data.pop("images", []))
+        videos = reconstruct_videos(data.pop("videos", []))
+        audio = reconstruct_audio_list(data.pop("audio", []))
+        files = reconstruct_files(data.pop("files", []))
 
         tools = data.pop("tools", [])
         tools = [ToolExecution.from_dict(tool) for tool in tools] if tools else None
 
-        response_audio = data.pop("response_audio", None)
-        response_audio = Audio.model_validate(response_audio) if response_audio else None
+        response_audio = reconstruct_response_audio(data.pop("response_audio", None))
 
         input_data = data.pop("input", None)
         input_obj = None
@@ -628,6 +709,12 @@ class TeamRunOutput:
         citations = data.pop("citations", None)
         citations = Citations.model_validate(citations) if citations else None
 
+        # Filter data to only include fields that are actually defined in the TeamRunOutput dataclass
+        from dataclasses import fields
+
+        supported_fields = {f.name for f in fields(cls)}
+        filtered_data = {k: v for k, v in data.items() if k in supported_fields}
+
         return cls(
             messages=messages,
             metrics=metrics,
@@ -645,7 +732,7 @@ class TeamRunOutput:
             citations=citations,
             tools=tools,
             events=events,
-            **data,
+            **filtered_data,
         )
 
     def get_content_as_string(self, **kwargs) -> str: