agno 2.3.3__py3-none-any.whl → 2.3.5__py3-none-any.whl

agno/eval/accuracy.py

@@ -612,11 +612,14 @@ Remember: You must only compare the agent_output to the expected_output. The exp
         print_results: bool = True,
     ) -> Optional[AccuracyResult]:
         """Run the evaluation logic against the given answer, instead of generating an answer with the Agent"""
+        # Generate unique run_id for this execution (don't modify self.eval_id due to concurrency)
+        run_id = str(uuid4())
+
         set_log_level_to_debug() if self.debug_mode else set_log_level_to_info()
 
         self.result = AccuracyResult()
 
-        logger.debug(f"************ Evaluation Start: {self.eval_id} ************")
+        logger.debug(f"************ Evaluation Start: {run_id} ************")
 
         evaluator_agent = self.get_evaluator_agent()
         eval_input = self.get_eval_input()
@@ -721,7 +724,7 @@ Remember: You must only compare the agent_output to the expected_output. The exp
                 ),
             )
 
-        logger.debug(f"*********** Evaluation End: {self.eval_id} ***********")
+        logger.debug(f"*********** Evaluation End: {run_id} ***********")
         return self.result
 
     async def arun_with_output(
@@ -732,11 +735,14 @@ Remember: You must only compare the agent_output to the expected_output. The exp
         print_results: bool = True,
     ) -> Optional[AccuracyResult]:
         """Run the evaluation logic against the given answer, instead of generating an answer with the Agent"""
+        # Generate unique run_id for this execution (don't modify self.eval_id due to concurrency)
+        run_id = str(uuid4())
+
         set_log_level_to_debug() if self.debug_mode else set_log_level_to_info()
 
         self.result = AccuracyResult()
 
-        logger.debug(f"************ Evaluation Start: {self.eval_id} ************")
+        logger.debug(f"************ Evaluation Start: {run_id} ************")
 
         evaluator_agent = self.get_evaluator_agent()
         eval_input = self.get_eval_input()
@@ -820,7 +826,7 @@ Remember: You must only compare the agent_output to the expected_output. The exp
                 eval_input=log_eval_input,
             )
 
-        logger.debug(f"*********** Evaluation End: {self.eval_id} ***********")
+        logger.debug(f"*********** Evaluation End: {run_id} ***********")
         return self.result
 
     def _get_telemetry_data(self) -> Dict[str, Any]:

agno/eval/performance.py

@@ -498,13 +498,16 @@ class PerformanceEval:
         from rich.live import Live
         from rich.status import Status
 
+        # Generate unique run_id for this execution (don't modify self.eval_id due to concurrency)
+        run_id = str(uuid4())
+
         run_times = []
         memory_usages = []
         previous_snapshot = None
 
         self._set_log_level()
 
-        log_debug(f"************ Evaluation Start: {self.eval_id} ************")
+        log_debug(f"************ Evaluation Start: {run_id} ************")
 
         # Add a spinner while running the evaluations
         console = Console()
@@ -615,7 +618,7 @@ class PerformanceEval:
                 ),
             )
 
-        log_debug(f"*********** Evaluation End: {self.eval_id} ***********")
+        log_debug(f"*********** Evaluation End: {run_id} ***********")
         return self.result
 
     async def arun(
@@ -641,13 +644,16 @@ class PerformanceEval:
         from rich.live import Live
         from rich.status import Status
 
+        # Generate unique run_id for this execution (don't modify self.eval_id due to concurrency)
+        run_id = str(uuid4())
+
         run_times = []
         memory_usages = []
         previous_snapshot = None
 
         self._set_log_level()
 
-        log_debug(f"************ Evaluation Start: {self.eval_id} ************")
+        log_debug(f"************ Evaluation Start: {run_id} ************")
 
         # Add a spinner while running the evaluations
         console = Console()
@@ -758,7 +764,7 @@ class PerformanceEval:
                 ),
             )
 
-        log_debug(f"*********** Evaluation End: {self.eval_id} ***********")
+        log_debug(f"*********** Evaluation End: {run_id} ***********")
         return self.result
 
     def _get_telemetry_data(self) -> Dict[str, Any]:

agno/eval/reliability.py

@@ -4,6 +4,7 @@ from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
 from uuid import uuid4
 
 from agno.db.base import AsyncBaseDb, BaseDb
+from agno.run.team import TeamRunOutput
 
 if TYPE_CHECKING:
     from rich.console import Console
@@ -11,7 +12,6 @@ if TYPE_CHECKING:
 from agno.agent import RunOutput
 from agno.db.schemas.evals import EvalType
 from agno.eval.utils import async_log_eval, log_eval_run, store_result_in_file
-from agno.run.team import TeamRunOutput
 from agno.utils.log import logger
 
 
@@ -86,6 +86,9 @@ class ReliabilityEval:
         from rich.live import Live
         from rich.status import Status
 
+        # Generate unique run_id for this execution (don't modify self.eval_id due to concurrency)
+        run_id = str(uuid4())
+
         # Add a spinner while running the evaluations
         console = Console()
         with Live(console=console, transient=True) as live_log:
@@ -118,7 +121,7 @@ class ReliabilityEval:
                     if not tool_name:
                         continue
                     else:
-                        if tool_name not in self.expected_tool_calls:  # type: ignore
+                        if self.expected_tool_calls is not None and tool_name not in self.expected_tool_calls:
                             failed_tool_calls.append(tool_call.get("function", {}).get("name"))
                         else:
                             passed_tool_calls.append(tool_call.get("function", {}).get("name"))
@@ -183,7 +186,7 @@ class ReliabilityEval:
                 ),
             )
 
-        logger.debug(f"*********** Evaluation End: {self.eval_id} ***********")
+        logger.debug(f"*********** Evaluation End: {run_id} ***********")
         return self.result
 
     async def arun(self, *, print_results: bool = False) -> Optional[ReliabilityResult]:
@@ -199,6 +202,9 @@ class ReliabilityEval:
         from rich.live import Live
         from rich.status import Status
 
+        # Generate unique run_id for this execution (don't modify self.eval_id due to concurrency)
+        run_id = str(uuid4())
+
         # Add a spinner while running the evaluations
         console = Console()
         with Live(console=console, transient=True) as live_log:
@@ -223,15 +229,18 @@ class ReliabilityEval:
 
             failed_tool_calls = []
             passed_tool_calls = []
-            for tool_call in actual_tool_calls:  # type: ignore
-                tool_name = tool_call.get("function", {}).get("name")
-                if not tool_name:
-                    continue
-                else:
-                    if tool_name not in self.expected_tool_calls:  # type: ignore
-                        failed_tool_calls.append(tool_call.get("function", {}).get("name"))
+            if not actual_tool_calls:
+                failed_tool_calls = self.expected_tool_calls or []
+            else:
+                for tool_call in actual_tool_calls:  # type: ignore
+                    tool_name = tool_call.get("function", {}).get("name")
+                    if not tool_name:
+                        continue
                     else:
-                        passed_tool_calls.append(tool_call.get("function", {}).get("name"))
+                        if self.expected_tool_calls is not None and tool_name not in self.expected_tool_calls:
+                            failed_tool_calls.append(tool_call.get("function", {}).get("name"))
+                        else:
+                            passed_tool_calls.append(tool_call.get("function", {}).get("name"))
 
             self.result = ReliabilityResult(
                 eval_status="PASSED" if len(failed_tool_calls) == 0 else "FAILED",
@@ -244,7 +253,7 @@ class ReliabilityEval:
             store_result_in_file(
                 file_path=self.file_path_to_save_results,
                 name=self.name,
-                eval_id=self.eval_id,
+                eval_id=run_id,
                 result=self.result,
             )
 
@@ -293,7 +302,7 @@ class ReliabilityEval:
                 ),
             )
 
-        logger.debug(f"*********** Evaluation End: {self.eval_id} ***********")
+        logger.debug(f"*********** Evaluation End: {run_id} ***********")
         return self.result
 
     def _get_telemetry_data(self) -> Dict[str, Any]:

agno/exceptions.py

@@ -77,6 +77,17 @@ class AgnoError(Exception):
         return str(self.message)
 
 
+class ModelAuthenticationError(AgnoError):
+    """Raised when model authentication fails."""
+
+    def __init__(self, message: str, status_code: int = 401, model_name: Optional[str] = None):
+        super().__init__(message, status_code)
+        self.model_name = model_name
+
+        self.type = "model_authentication_error"
+        self.error_id = "model_authentication_error"
+
+
 class ModelProviderError(AgnoError):
     """Exception raised when a model provider returns an error."""
 

agno/hooks/__init__.py

@@ -0,0 +1,3 @@
+from agno.hooks.decorator import hook, should_run_in_background
+
+__all__ = ["hook", "should_run_in_background"]

agno/hooks/decorator.py

@@ -0,0 +1,164 @@
+from functools import wraps
+from typing import Any, Callable, TypeVar, Union, overload
+
+# Type variable for better type hints
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Attribute name used to mark hooks for background execution
+HOOK_RUN_IN_BACKGROUND_ATTR = "_agno_run_in_background"
+
+
+def _is_async_function(func: Callable) -> bool:
+    """
+    Check if a function is async, even when wrapped by decorators like @staticmethod.
+    Traverses the full wrapper chain to find the original function.
+    """
+    from inspect import iscoroutinefunction, unwrap
+
+    # First, try the standard inspect function on the wrapper
+    if iscoroutinefunction(func):
+        return True
+
+    # Use unwrap to traverse the full __wrapped__ chain to the original function
+    try:
+        original_func = unwrap(func)
+        if original_func is not func and iscoroutinefunction(original_func):
+            return True
+    except ValueError:
+        # unwrap raises ValueError if it hits a cycle
+        pass
+
+    # Check if the function has CO_COROUTINE flag in its code object
+    try:
+        if hasattr(func, "__code__") and func.__code__.co_flags & 0x80:  # CO_COROUTINE flag
+            return True
+    except (AttributeError, TypeError):
+        pass
+
+    return False
+
+
+@overload
+def hook() -> Callable[[F], F]: ...
+
+
+@overload
+def hook(
+    *,
+    run_in_background: bool = False,
+) -> Callable[[F], F]: ...
+
+
+@overload
+def hook(func: F) -> F: ...
+
+
+def hook(*args, **kwargs) -> Union[F, Callable[[F], F]]:
+    """Decorator to configure hook behavior.
+
+    Args:
+        run_in_background: If True, this hook will be scheduled as a FastAPI background task
+                          when background_tasks is available, regardless of the agent/team's
+                          run_hooks_in_background setting. This allows per-hook control over
+                          background execution.  This is only use-able when running with AgentOS.
+
+    Returns:
+        Union[F, Callable[[F], F]]: Decorated function or decorator
+
+    Examples:
+        @hook
+        def my_hook(run_output, agent):
+            # This runs normally (blocking)
+            process_output(run_output.content)
+
+        @hook()
+        def another_hook(run_output, agent):
+            # Same as above - runs normally
+            process_output(run_output.content)
+
+        @hook(run_in_background=True)
+        def my_background_hook(run_output, agent):
+            # This will run in the background when background_tasks is available
+            send_notification(run_output.content)
+
+        @hook(run_in_background=True)
+        async def my_async_background_hook(run_output, agent):
+            # Async hooks also supported
+            await send_async_notification(run_output.content)
+
+        agent = Agent(
+            model=OpenAIChat(id="gpt-4o"),
+            post_hooks=[my_hook, my_background_hook],
+        )
+    """
+    # Valid kwargs for the hook decorator
+    VALID_KWARGS = frozenset({"run_in_background"})
+
+    # Validate kwargs
+    invalid_kwargs = set(kwargs.keys()) - VALID_KWARGS
+    if invalid_kwargs:
+        raise ValueError(
+            f"Invalid hook configuration arguments: {invalid_kwargs}. Valid arguments are: {sorted(VALID_KWARGS)}"
+        )
+
+    def decorator(func: F) -> F:
+        run_in_background = kwargs.get("run_in_background", False)
+
+        # Preserve existing hook attributes from previously applied decorators
+        # Use OR logic: if any decorator sets run_in_background=True, it stays True
+        existing_run_in_background = should_run_in_background(func)
+        final_run_in_background = run_in_background or existing_run_in_background
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return func(*args, **kwargs)
+
+        @wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return await func(*args, **kwargs)
+
+        # Choose appropriate wrapper based on function type
+        if _is_async_function(func):
+            wrapper = async_wrapper
+        else:
+            wrapper = sync_wrapper
+
+        # Set the background execution attribute (combined from all decorators)
+        setattr(wrapper, HOOK_RUN_IN_BACKGROUND_ATTR, final_run_in_background)
+
+        return wrapper  # type: ignore
+
+    # Handle both @hook and @hook() cases
+    if len(args) == 1 and callable(args[0]) and not kwargs:
+        return decorator(args[0])
+
+    return decorator
+
+
+def should_run_in_background(hook_func: Callable) -> bool:
+    """
+    Check if a hook function is marked to run in background.
+    Traverses the wrapper chain to find the attribute when multiple decorators are stacked.
+
+    Args:
+        hook_func: The hook function to check
+
+    Returns:
+        True if the hook is decorated with @hook(run_in_background=True)
+    """
+    # Check the function directly first
+    if hasattr(hook_func, HOOK_RUN_IN_BACKGROUND_ATTR):
+        return getattr(hook_func, HOOK_RUN_IN_BACKGROUND_ATTR)
+
+    # Traverse the wrapper chain to find the attribute
+    current = hook_func
+    seen: set[int] = set()
+    while hasattr(current, "__wrapped__"):
+        if id(current) in seen:
+            break
+        seen.add(id(current))
+        current = current.__wrapped__
+        if hasattr(current, HOOK_RUN_IN_BACKGROUND_ATTR):
+            return getattr(current, HOOK_RUN_IN_BACKGROUND_ATTR)
+
+    return False

agno/knowledge/chunking/semantic.py

@@ -55,10 +55,10 @@ class SemanticChunking(ChunkingStrategy):
                     # Fallback to model id
                     params["embedding_model"] = getattr(self.embedder, "id", None) or "text-embedding-3-small"
 
-                self.chunker = SemanticChunker(**params)
+                self.chunker = SemanticChunker(**params)  # type: ignore
             except Exception:
                 # As a final fallback, use the original behavior
-                self.chunker = SemanticChunker(
+                self.chunker = SemanticChunker(  # type: ignore
                     embedding_model=getattr(self.embedder, "id", None) or "text-embedding-3-small",
                     chunk_size=self.chunk_size,
                     threshold=self.similarity_threshold,

agno/models/aimlapi/aimlapi.py

@@ -2,6 +2,7 @@ from dataclasses import dataclass, field
 from os import getenv
 from typing import Any, Dict, Optional
 
+from agno.exceptions import ModelAuthenticationError
 from agno.models.message import Message
 from agno.models.openai.like import OpenAILike
 
@@ -28,6 +29,22 @@ class AIMLAPI(OpenAILike):
     base_url: str = "https://api.aimlapi.com/v1"
     max_tokens: int = 4096
 
+    def _get_client_params(self) -> Dict[str, Any]:
+        """
+        Returns client parameters for API requests, checking for AIMLAPI_API_KEY.
+
+        Returns:
+            Dict[str, Any]: A dictionary of client parameters for API requests.
+        """
+        if not self.api_key:
+            self.api_key = getenv("AIMLAPI_API_KEY")
+            if not self.api_key:
+                raise ModelAuthenticationError(
+                    message="AIMLAPI_API_KEY not set. Please set the AIMLAPI_API_KEY environment variable.",
+                    model_name=self.name,
+                )
+        return super()._get_client_params()
+
     def _format_message(self, message: Message) -> Dict[str, Any]:
         """
         Minimal additional formatter that only replaces None with empty string.

agno/models/anthropic/claude.py

@@ -129,6 +129,7 @@ class Claude(Model):
 
     # Client parameters
     api_key: Optional[str] = None
+    auth_token: Optional[str] = None
     default_headers: Optional[Dict[str, Any]] = None
     timeout: Optional[float] = None
     http_client: Optional[Union[httpx.Client, httpx.AsyncClient]] = None
@@ -153,11 +154,15 @@ class Claude(Model):
         client_params: Dict[str, Any] = {}
 
         self.api_key = self.api_key or getenv("ANTHROPIC_API_KEY")
-        if not self.api_key:
-            log_error("ANTHROPIC_API_KEY not set. Please set the ANTHROPIC_API_KEY environment variable.")
+        self.auth_token = self.auth_token or getenv("ANTHROPIC_AUTH_TOKEN")
+        if not (self.api_key or self.auth_token):
+            log_error(
+                "ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN not set. Please set the ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN environment variable."
+            )
 
         # Add API key to client parameters
         client_params["api_key"] = self.api_key
+        client_params["auth_token"] = self.auth_token
         if self.timeout is not None:
             client_params["timeout"] = self.timeout
 
@@ -177,10 +182,6 @@ class Claude(Model):
         """
         # If model is in blacklist, it doesn't support structured outputs
         if self.id in self.NON_STRUCTURED_OUTPUT_MODELS:
-            log_warning(
-                f"Model '{self.id}' does not support structured outputs. "
-                "Structured output features will not be available for this model."
-            )
             return False
 
         # Check for legacy model patterns which don't support structured outputs
@@ -209,8 +210,14 @@ class Claude(Model):
             bool: True if structured outputs are in use
         """
         # Check for output_format usage
-        if response_format is not None and self._supports_structured_outputs():
-            return True
+        if response_format is not None:
+            if self._supports_structured_outputs():
+                return True
+            else:
+                log_warning(
+                    f"Model '{self.id}' does not support structured outputs. "
+                    "Structured output features will not be available for this model."
+                )
 
         # Check for strict tools
         if tools:
@@ -926,8 +933,8 @@ class Claude(Model):
         elif isinstance(response, (ContentBlockStopEvent, ParsedBetaContentBlockStopEvent)):
             if response.content_block.type == "tool_use":  # type: ignore
                 tool_use = response.content_block  # type: ignore
-                tool_name = tool_use.name
-                tool_input = tool_use.input
+                tool_name = tool_use.name  # type: ignore
+                tool_input = tool_use.input  # type: ignore
 
                 function_def = {"name": tool_name}
                 if tool_input:
@@ -937,7 +944,7 @@ class Claude(Model):
 
                 model_response.tool_calls = [
                     {
-                        "id": tool_use.id,
+                        "id": tool_use.id,  # type: ignore
                         "type": "function",
                         "function": function_def,
                     }
@@ -958,7 +965,7 @@ class Claude(Model):
             for block in response.message.content:  # type: ignore
                 # Handle text blocks for structured output parsing
                 if block.type == "text":
-                    accumulated_text += block.text
+                    accumulated_text += block.text  # type: ignore
 
                 # Handle citations
                 citations = getattr(block, "citations", None)

agno/models/aws/bedrock.py

@@ -5,7 +5,7 @@ from typing import Any, AsyncIterator, Dict, Iterator, List, Optional, Tuple, Ty
 
 from pydantic import BaseModel
 
-from agno.exceptions import AgnoError, ModelProviderError
+from agno.exceptions import ModelProviderError
 from agno.models.base import Model
 from agno.models.message import Message
 from agno.models.metrics import Metrics
@@ -102,9 +102,8 @@ class AwsBedrock(Model):
             self.client = AwsClient(service_name="bedrock-runtime", region_name=self.aws_region)
         else:
             if not self.aws_access_key_id or not self.aws_secret_access_key:
-                raise AgnoError(
-                    message="AWS credentials not found. Please set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables or provide a boto3 session.",
-                    status_code=400,
+                log_error(
+                    "AWS credentials not found. Please set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables or provide a boto3 session."
                 )
 
             self.client = AwsClient(

agno/models/aws/claude.py

@@ -7,7 +7,7 @@ from pydantic import BaseModel
 
 from agno.models.anthropic import Claude as AnthropicClaude
 from agno.utils.http import get_default_async_client, get_default_sync_client
-from agno.utils.log import log_debug, log_warning
+from agno.utils.log import log_debug, log_error, log_warning
 from agno.utils.models.claude import format_tools_for_model
 
 try:
@@ -79,6 +79,10 @@ class Claude(AnthropicClaude):
                     "aws_access_key": self.aws_access_key,
                     "aws_region": self.aws_region,
                 }
+        if not (self.aws_access_key or (self.aws_access_key and self.aws_secret_key)):
+            log_error(
+                "AWS credentials not found. Please either set the AWS_BEDROCK_API_KEY or AWS_ACCESS_KEY and AWS_SECRET_KEY environment variables."
+            )
 
         if self.timeout is not None:
             client_params["timeout"] = self.timeout

agno/models/azure/ai_foundry.py

@@ -136,9 +136,9 @@ class AzureAIFoundry(Model):
         self.azure_endpoint = self.azure_endpoint or getenv("AZURE_ENDPOINT")
 
         if not self.api_key:
-            raise ValueError("API key is required")
+            log_error("AZURE_API_KEY not set. Please set the AZURE_API_KEY environment variable.")
         if not self.azure_endpoint:
-            raise ValueError("Endpoint URL is required")
+            log_error("AZURE_ENDPOINT not set. Please set the AZURE_ENDPOINT environment variable.")
 
         base_params = {
             "endpoint": self.azure_endpoint,

agno/models/azure/openai_chat.py

@@ -4,6 +4,7 @@ from typing import Any, Dict, Optional
 
 import httpx
 
+from agno.exceptions import ModelAuthenticationError
 from agno.models.openai.like import OpenAILike
 from agno.utils.http import get_default_async_client, get_default_sync_client
 from agno.utils.log import log_warning
@@ -63,6 +64,13 @@ class AzureOpenAI(OpenAILike):
         self.api_key = self.api_key or getenv("AZURE_OPENAI_API_KEY")
         self.azure_endpoint = self.azure_endpoint or getenv("AZURE_OPENAI_ENDPOINT")
         self.azure_deployment = self.azure_deployment or getenv("AZURE_OPENAI_DEPLOYMENT")
+
+        if not self.api_key:
+            raise ModelAuthenticationError(
+                message="AZURE_OPENAI_API_KEY not set. Please set the AZURE_OPENAI_API_KEY environment variable.",
+                model_name=self.name,
+            )
+
         params_mapping = {
             "api_key": self.api_key,
             "api_version": self.api_version,