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

agno/utils/events.py

@@ -5,8 +5,12 @@ from agno.models.message import Citations
 from agno.models.response import ToolExecution
 from agno.reasoning.step import ReasoningStep
 from agno.run.agent import (
+    CompressionCompletedEvent,
+    CompressionStartedEvent,
     MemoryUpdateCompletedEvent,
     MemoryUpdateStartedEvent,
+    ModelRequestCompletedEvent,
+    ModelRequestStartedEvent,
     OutputModelResponseCompletedEvent,
     OutputModelResponseStartedEvent,
     ParserModelResponseCompletedEvent,
@@ -16,6 +20,7 @@ from agno.run.agent import (
     PreHookCompletedEvent,
     PreHookStartedEvent,
     ReasoningCompletedEvent,
+    ReasoningContentDeltaEvent,
     ReasoningStartedEvent,
     ReasoningStepEvent,
     RunCancelledEvent,
@@ -33,10 +38,16 @@ from agno.run.agent import (
     SessionSummaryCompletedEvent,
     SessionSummaryStartedEvent,
     ToolCallCompletedEvent,
+    ToolCallErrorEvent,
     ToolCallStartedEvent,
 )
+from agno.run.requirement import RunRequirement
+from agno.run.team import CompressionCompletedEvent as TeamCompressionCompletedEvent
+from agno.run.team import CompressionStartedEvent as TeamCompressionStartedEvent
 from agno.run.team import MemoryUpdateCompletedEvent as TeamMemoryUpdateCompletedEvent
 from agno.run.team import MemoryUpdateStartedEvent as TeamMemoryUpdateStartedEvent
+from agno.run.team import ModelRequestCompletedEvent as TeamModelRequestCompletedEvent
+from agno.run.team import ModelRequestStartedEvent as TeamModelRequestStartedEvent
 from agno.run.team import OutputModelResponseCompletedEvent as TeamOutputModelResponseCompletedEvent
 from agno.run.team import OutputModelResponseStartedEvent as TeamOutputModelResponseStartedEvent
 from agno.run.team import ParserModelResponseCompletedEvent as TeamParserModelResponseCompletedEvent
@@ -46,6 +57,7 @@ from agno.run.team import PostHookStartedEvent as TeamPostHookStartedEvent
 from agno.run.team import PreHookCompletedEvent as TeamPreHookCompletedEvent
 from agno.run.team import PreHookStartedEvent as TeamPreHookStartedEvent
 from agno.run.team import ReasoningCompletedEvent as TeamReasoningCompletedEvent
+from agno.run.team import ReasoningContentDeltaEvent as TeamReasoningContentDeltaEvent
 from agno.run.team import ReasoningStartedEvent as TeamReasoningStartedEvent
 from agno.run.team import ReasoningStepEvent as TeamReasoningStepEvent
 from agno.run.team import RunCancelledEvent as TeamRunCancelledEvent
@@ -58,6 +70,7 @@ from agno.run.team import SessionSummaryCompletedEvent as TeamSessionSummaryComp
 from agno.run.team import SessionSummaryStartedEvent as TeamSessionSummaryStartedEvent
 from agno.run.team import TeamRunEvent, TeamRunInput, TeamRunOutput, TeamRunOutputEvent
 from agno.run.team import ToolCallCompletedEvent as TeamToolCallCompletedEvent
+from agno.run.team import ToolCallErrorEvent as TeamToolCallErrorEvent
 from agno.run.team import ToolCallStartedEvent as TeamToolCallStartedEvent
 from agno.session.summary import SessionSummary
 
@@ -136,7 +149,9 @@ def create_run_completed_event(from_run_response: RunOutput) -> RunCompletedEven
 
 
 def create_run_paused_event(
-    from_run_response: RunOutput, tools: Optional[List[ToolExecution]] = None
+    from_run_response: RunOutput,
+    tools: Optional[List[ToolExecution]] = None,
+    requirements: Optional[List[RunRequirement]] = None,
 ) -> RunPausedEvent:
     return RunPausedEvent(
         session_id=from_run_response.session_id,
@@ -144,6 +159,7 @@ def create_run_paused_event(
         agent_name=from_run_response.agent_name,  # type: ignore
         run_id=from_run_response.run_id,
         tools=tools,
+        requirements=requirements,
         content=from_run_response.content,
     )
 
@@ -157,23 +173,41 @@ def create_run_continued_event(from_run_response: RunOutput) -> RunContinuedEven
     )
 
 
-def create_team_run_error_event(from_run_response: TeamRunOutput, error: str) -> TeamRunErrorEvent:
+def create_team_run_error_event(
+    from_run_response: TeamRunOutput,
+    error: str,
+    error_type: Optional[str] = None,
+    error_id: Optional[str] = None,
+    additional_data: Optional[Dict[str, Any]] = None,
+) -> TeamRunErrorEvent:
     return TeamRunErrorEvent(
         session_id=from_run_response.session_id,
         team_id=from_run_response.team_id,  # type: ignore
         team_name=from_run_response.team_name,  # type: ignore
         run_id=from_run_response.run_id,
         content=error,
+        error_type=error_type,
+        error_id=error_id,
+        additional_data=additional_data,
     )
 
 
-def create_run_error_event(from_run_response: RunOutput, error: str) -> RunErrorEvent:
+def create_run_error_event(
+    from_run_response: RunOutput,
+    error: str,
+    error_type: Optional[str] = None,
+    error_id: Optional[str] = None,
+    additional_data: Optional[Dict[str, Any]] = None,
+) -> RunErrorEvent:
     return RunErrorEvent(
         session_id=from_run_response.session_id,
         agent_id=from_run_response.agent_id,  # type: ignore
         agent_name=from_run_response.agent_name,  # type: ignore
         run_id=from_run_response.run_id,
         content=error,
+        error_type=error_type,
+        error_id=error_id,
+        additional_data=additional_data,
     )
 
 
@@ -323,21 +357,27 @@ def create_team_memory_update_started_event(from_run_response: TeamRunOutput) ->
     )
 
 
-def create_memory_update_completed_event(from_run_response: RunOutput) -> MemoryUpdateCompletedEvent:
+def create_memory_update_completed_event(
+    from_run_response: RunOutput, memories: Optional[List[Any]] = None
+) -> MemoryUpdateCompletedEvent:
     return MemoryUpdateCompletedEvent(
         session_id=from_run_response.session_id,
         agent_id=from_run_response.agent_id,  # type: ignore
         agent_name=from_run_response.agent_name,  # type: ignore
         run_id=from_run_response.run_id,
+        memories=memories,
     )
 
 
-def create_team_memory_update_completed_event(from_run_response: TeamRunOutput) -> TeamMemoryUpdateCompletedEvent:
+def create_team_memory_update_completed_event(
+    from_run_response: TeamRunOutput, memories: Optional[List[Any]] = None
+) -> TeamMemoryUpdateCompletedEvent:
     return TeamMemoryUpdateCompletedEvent(
         session_id=from_run_response.session_id,
         team_id=from_run_response.team_id,  # type: ignore
         team_name=from_run_response.team_name,  # type: ignore
         run_id=from_run_response.run_id,
+        memories=memories,
     )
 
 
@@ -417,6 +457,19 @@ def create_reasoning_step_event(
     )
 
 
+def create_reasoning_content_delta_event(
+    from_run_response: RunOutput, reasoning_content: str
+) -> ReasoningContentDeltaEvent:
+    """Create an event for streaming reasoning content chunks."""
+    return ReasoningContentDeltaEvent(
+        session_id=from_run_response.session_id,
+        agent_id=from_run_response.agent_id,  # type: ignore
+        agent_name=from_run_response.agent_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        reasoning_content=reasoning_content,
+    )
+
+
 def create_team_reasoning_step_event(
     from_run_response: TeamRunOutput, reasoning_step: ReasoningStep, reasoning_content: str
 ) -> TeamReasoningStepEvent:
@@ -431,6 +484,19 @@ def create_team_reasoning_step_event(
     )
 
 
+def create_team_reasoning_content_delta_event(
+    from_run_response: TeamRunOutput, reasoning_content: str
+) -> TeamReasoningContentDeltaEvent:
+    """Create an event for streaming reasoning content chunks for Team."""
+    return TeamReasoningContentDeltaEvent(
+        session_id=from_run_response.session_id,
+        team_id=from_run_response.team_id,  # type: ignore
+        team_name=from_run_response.team_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        reasoning_content=reasoning_content,
+    )
+
+
 def create_reasoning_completed_event(
     from_run_response: RunOutput, content: Optional[Any] = None, content_type: Optional[str] = None
 ) -> ReasoningCompletedEvent:
@@ -511,6 +577,32 @@ def create_team_tool_call_completed_event(
     )
 
 
+def create_tool_call_error_event(
+    from_run_response: RunOutput, tool: ToolExecution, error: Optional[str] = None
+) -> ToolCallErrorEvent:
+    return ToolCallErrorEvent(
+        session_id=from_run_response.session_id,
+        agent_id=from_run_response.agent_id,  # type: ignore
+        agent_name=from_run_response.agent_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        tool=tool,
+        error=error,
+    )
+
+
+def create_team_tool_call_error_event(
+    from_run_response: TeamRunOutput, tool: ToolExecution, error: Optional[str] = None
+) -> TeamToolCallErrorEvent:
+    return TeamToolCallErrorEvent(
+        session_id=from_run_response.session_id,
+        team_id=from_run_response.team_id,  # type: ignore
+        team_name=from_run_response.team_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        tool=tool,
+        error=error,
+    )
+
+
 def create_run_output_content_event(
     from_run_response: RunOutput,
     content: Optional[Any] = None,
@@ -681,6 +773,150 @@ def create_team_output_model_response_completed_event(
     )
 
 
+def create_model_request_started_event(
+    from_run_response: RunOutput,
+    model: Optional[str] = None,
+    model_provider: Optional[str] = None,
+) -> ModelRequestStartedEvent:
+    return ModelRequestStartedEvent(
+        session_id=from_run_response.session_id,
+        agent_id=from_run_response.agent_id,  # type: ignore
+        agent_name=from_run_response.agent_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        model=model,
+        model_provider=model_provider,
+    )
+
+
+def create_model_request_completed_event(
+    from_run_response: RunOutput,
+    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,
+) -> ModelRequestCompletedEvent:
+    return ModelRequestCompletedEvent(
+        session_id=from_run_response.session_id,
+        agent_id=from_run_response.agent_id,  # type: ignore
+        agent_name=from_run_response.agent_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        model=model,
+        model_provider=model_provider,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        total_tokens=total_tokens,
+        time_to_first_token=time_to_first_token,
+        reasoning_tokens=reasoning_tokens,
+        cache_read_tokens=cache_read_tokens,
+        cache_write_tokens=cache_write_tokens,
+    )
+
+
+def create_team_model_request_started_event(
+    from_run_response: TeamRunOutput,
+    model: Optional[str] = None,
+    model_provider: Optional[str] = None,
+) -> TeamModelRequestStartedEvent:
+    return TeamModelRequestStartedEvent(
+        session_id=from_run_response.session_id,
+        team_id=from_run_response.team_id,  # type: ignore
+        team_name=from_run_response.team_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        model=model,
+        model_provider=model_provider,
+    )
+
+
+def create_team_model_request_completed_event(
+    from_run_response: TeamRunOutput,
+    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,
+) -> TeamModelRequestCompletedEvent:
+    return TeamModelRequestCompletedEvent(
+        session_id=from_run_response.session_id,
+        team_id=from_run_response.team_id,  # type: ignore
+        team_name=from_run_response.team_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        model=model,
+        model_provider=model_provider,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        total_tokens=total_tokens,
+        time_to_first_token=time_to_first_token,
+        reasoning_tokens=reasoning_tokens,
+        cache_read_tokens=cache_read_tokens,
+        cache_write_tokens=cache_write_tokens,
+    )
+
+
+def create_compression_started_event(
+    from_run_response: RunOutput,
+) -> CompressionStartedEvent:
+    return CompressionStartedEvent(
+        session_id=from_run_response.session_id,
+        agent_id=from_run_response.agent_id,  # type: ignore
+        agent_name=from_run_response.agent_name,  # type: ignore
+        run_id=from_run_response.run_id,
+    )
+
+
+def create_compression_completed_event(
+    from_run_response: RunOutput,
+    tool_results_compressed: Optional[int] = None,
+    original_size: Optional[int] = None,
+    compressed_size: Optional[int] = None,
+) -> CompressionCompletedEvent:
+    return CompressionCompletedEvent(
+        session_id=from_run_response.session_id,
+        agent_id=from_run_response.agent_id,  # type: ignore
+        agent_name=from_run_response.agent_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        tool_results_compressed=tool_results_compressed,
+        original_size=original_size,
+        compressed_size=compressed_size,
+    )
+
+
+def create_team_compression_started_event(
+    from_run_response: TeamRunOutput,
+) -> TeamCompressionStartedEvent:
+    return TeamCompressionStartedEvent(
+        session_id=from_run_response.session_id,
+        team_id=from_run_response.team_id,  # type: ignore
+        team_name=from_run_response.team_name,  # type: ignore
+        run_id=from_run_response.run_id,
+    )
+
+
+def create_team_compression_completed_event(
+    from_run_response: TeamRunOutput,
+    tool_results_compressed: Optional[int] = None,
+    original_size: Optional[int] = None,
+    compressed_size: Optional[int] = None,
+) -> TeamCompressionCompletedEvent:
+    return TeamCompressionCompletedEvent(
+        session_id=from_run_response.session_id,
+        team_id=from_run_response.team_id,  # type: ignore
+        team_name=from_run_response.team_name,  # type: ignore
+        run_id=from_run_response.run_id,
+        tool_results_compressed=tool_results_compressed,
+        original_size=original_size,
+        compressed_size=compressed_size,
+    )
+
+
 def handle_event(
     event: Union[RunOutputEvent, TeamRunOutputEvent],
     run_response: Union[RunOutput, TeamRunOutput],
@@ -688,9 +924,30 @@ def handle_event(
     store_events: bool = False,
 ) -> Union[RunOutputEvent, TeamRunOutputEvent]:
     # We only store events that are not run_response_content events
-    events_to_skip = [event.value for event in events_to_skip] if events_to_skip else []
-    if store_events and event.event not in events_to_skip:
+    _events_to_skip: List[str] = [event.value for event in events_to_skip] if events_to_skip else []
+    if store_events and event.event not in _events_to_skip:
         if run_response.events is None:
             run_response.events = []
         run_response.events.append(event)  # type: ignore
     return event
+
+
+def add_error_event(
+    error: RunErrorEvent,
+    events: Optional[List[RunOutputEvent]],
+):
+    if events is None:
+        events = []
+    events.append(error)
+
+    return events
+
+
+def add_team_error_event(
+    error: TeamRunErrorEvent,
+    events: Optional[List[Union[RunOutputEvent, TeamRunOutputEvent]]],
+):
+    if events is None:
+        events = []
+    events.append(error)
+    return events

agno/utils/hooks.py

@@ -1,14 +1,112 @@
+from copy import deepcopy
 from typing import Any, Callable, Dict, List, Optional, Union
 
+from agno.eval.base import BaseEval
 from agno.guardrails.base import BaseGuardrail
+from agno.hooks.decorator import HOOK_RUN_IN_BACKGROUND_ATTR
 from agno.utils.log import log_warning
 
+# Keys that should be deep copied for background hooks to prevent race conditions
+BACKGROUND_HOOK_COPY_KEYS = frozenset(
+    {"run_input", "run_context", "run_output", "session_state", "dependencies", "metadata"}
+)
 
-def normalize_hooks(
-    hooks: Optional[List[Union[Callable[..., Any], BaseGuardrail]]],
+
+def copy_args_for_background(args: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Create a copy of hook arguments for background execution.
+
+    This deep copies run_input, run_context, run_output, session_state, dependencies,
+    and metadata to prevent race conditions when hooks run in the background.
+
+    Args:
+        args: The original arguments dictionary
+
+    Returns:
+        A new dictionary with copied values for sensitive keys
+    """
+    copied_args = {}
+    for key, value in args.items():
+        if key in BACKGROUND_HOOK_COPY_KEYS and value is not None:
+            try:
+                copied_args[key] = deepcopy(value)
+            except Exception:
+                # If deepcopy fails (e.g., for non-copyable objects), use the original
+                log_warning(f"Could not deepcopy {key} for background hook, using original reference")
+                copied_args[key] = value
+        else:
+            copied_args[key] = value
+    return copied_args
+
+
+def should_run_hook_in_background(hook: Callable[..., Any]) -> bool:
+    """
+    Check if a hook function should run in background.
+
+    This checks for the _agno_run_in_background attribute set by the @hook decorator.
+
+    Args:
+        hook: The hook function to check
+
+    Returns:
+        True if the hook is decorated with @hook(run_in_background=True)
+    """
+    return getattr(hook, HOOK_RUN_IN_BACKGROUND_ATTR, False)
+
+
+def normalize_pre_hooks(
+    hooks: Optional[List[Union[Callable[..., Any], BaseGuardrail, BaseEval]]],
+    async_mode: bool = False,
+) -> Optional[List[Callable[..., Any]]]:
+    """Normalize pre-hooks to a list format.
+
+    Args:
+        hooks: List of hook functions, guardrails, or eval instances
+        async_mode: Whether to use async versions of methods
+    """
+    result_hooks: List[Callable[..., Any]] = []
+
+    if hooks is not None:
+        for hook in hooks:
+            if isinstance(hook, BaseGuardrail):
+                if async_mode:
+                    result_hooks.append(hook.async_check)
+                else:
+                    result_hooks.append(hook.check)
+            elif isinstance(hook, BaseEval):
+                # Extract pre_check method
+                method = hook.async_pre_check if async_mode else hook.pre_check
+
+                from functools import partial
+
+                wrapped = partial(method)
+                wrapped.__name__ = method.__name__  # type: ignore
+                setattr(wrapped, HOOK_RUN_IN_BACKGROUND_ATTR, getattr(hook, "run_in_background", False))
+                result_hooks.append(wrapped)
+            else:
+                # Check if the hook is async and used within sync methods
+                if not async_mode:
+                    import asyncio
+
+                    if asyncio.iscoroutinefunction(hook):
+                        raise ValueError(
+                            f"Cannot use {hook.__name__} (an async hook) with `run()`. Use `arun()` instead."
+                        )
+
+                result_hooks.append(hook)
+    return result_hooks if result_hooks else None
+
+
+def normalize_post_hooks(
+    hooks: Optional[List[Union[Callable[..., Any], BaseGuardrail, BaseEval]]],
     async_mode: bool = False,
 ) -> Optional[List[Callable[..., Any]]]:
-    """Normalize hooks to a list format"""
+    """Normalize post-hooks to a list format.
+
+    Args:
+        hooks: List of hook functions, guardrails, or eval instances
+        async_mode: Whether to use async versions of methods
+    """
     result_hooks: List[Callable[..., Any]] = []
 
     if hooks is not None:
@@ -18,6 +116,16 @@ def normalize_hooks(
                     result_hooks.append(hook.async_check)
                 else:
                     result_hooks.append(hook.check)
+            elif isinstance(hook, BaseEval):
+                # Extract post_check method
+                method = hook.async_post_check if async_mode else hook.post_check  # type: ignore[assignment]
+
+                from functools import partial
+
+                wrapped = partial(method)
+                wrapped.__name__ = method.__name__  # type: ignore
+                setattr(wrapped, HOOK_RUN_IN_BACKGROUND_ATTR, getattr(hook, "run_in_background", False))
+                result_hooks.append(wrapped)
             else:
                 # Check if the hook is async and used within sync methods
                 if not async_mode: