chore: Release 1.5.5 (#3359)

# Changelog

## New Features:

- **Claude File Upload:** we can now upload a file to Anthropic directly
and then use it as an input to an agent.
- **Claude 4 code execution tool:** allows Claude to execute Python code
in a secure, sandboxed environment.
- **Prompt caching with Anthropic models:** allows resuming from
specific prefixes in your prompts. This approach significantly reduces
processing time and costs for repetitive tasks or prompts with
consistent elements.
- **Vercel v0 Model:** Added support for new Vercel v0 models and
cookbook examples.
- **Qdrant Hybrid Search support**
- **Markdown Knowledge Base**: Added native support for Markdown-based
knowledge bases.
- **AI/ML API platform integration**: introduces integration with [AI/ML
API](https://aimlapi.com/models/?utm_source=agno&utm_medium=github&utm_campaign=integration),
a platform providing AI/ML models. AI/ML API provides 300+ AI models
including Deepseek, Gemini, ChatGPT. The models run at enterprise-grade
rate limits and uptimes
- **Update pydantic and dataclass in function handling**: Now supports
class as input to a function

## Improvements:

- **Timeout handling for API calls in ExaTools class:**
- Timeout functionality to Exa API calls to prevent indefinite hanging
of search operations. The implementation uses
Python's `concurrent.futures` module to enforce timeouts on all Exa API
operations (search, get contents, find similar, and answer generation).
- This change addresses the issue where Exa search functions would hang
indefinitely, causing potential service disruptions and resource leaks.
- **Fetch messages from last n sessions:**
- A tool for the agent, something
like `get_previous_session_messages(number_of_sessions: int)` that
returns a list of messages that the agent can analyse
    - Switch on with `search_previous_sessions_history`
- **Redis Expiration**: Added expire key to set TTL on Redis keys.
-  **Add anthropic cache write to agent session metrics**: adds
cache_creation_input_tokens to agent session metrics, to allow for
tracking Anthropic cache write statistics

## Bug Fixes:

- **HF custom embedder:**
- It turns out that HF has changed some things on their API and they've
deprecated .post on their
InferenceClient()- https://discuss.huggingface.co/t/getting-error-attributeerror-inferenceclient-object-has-no-attribute-post/156682
- Also we can no longer use- `id: str =
"jinaai/jina-embeddings-v2-base-code"` as default, because these models
are no longer provided by the `HF Inference API`. Changed the default
to- `id: str = "intfloat/multilingual-e5-large"`
- **Add `role_map` for `OpenAIChat`:** This allows certain models that
don’t adhere to OpenAI’s role mapping to be used vir `OpenAILike`.
- **Use content hash as id in upsert: in pgvector** use reproducible
content_hash in upsert as id
- **Insert in vector db passes only last chunk meta_data:** insert in
vector db passes only last chunk meta_data. issue link-
https://discord.com/channels/965734768803192842/1219054452221153463/1376631140047130649
- **Remove argument sanitization**: a safer way to do this that won't
break arguments that shouldn't be sanitized
- **Handle async tools when running async agents on playground**: Fixes
a regression where using Agents with async tools (e.g. MCP tools) was
breaking in the Playground.

---------

Co-authored-by: Dirk Brand <dirkbrnd@gmail.com>

Author: 2 people

.github/workflows/test_on_release.yml

@@ -638,9 +638,10 @@ jobs:
         run: |
           ./scripts/dev_setup.sh
       - name: Run embedder tests
-        working-directory: libs/agno
+        working-directory: .
         run: |
-          python -m pytest ./tests/integration/embedder
+          source .venv/bin/activate
+          python -m pytest ./libs/agno/tests/integration/embedder
 
   test-knowledge:
     runs-on: ubuntu-latest
@@ -699,5 +700,4 @@ jobs:
         working-directory: .
         run: |
           source .venv/bin/activate
-          python -m pytest --ignore=./libs/agno/tests/integration/models --ignore=./libs/agno/tests/integration/agent --ignore=./libs/agno/tests/integration/knowledge --ignore=./libs/agno/tests/integration/teams 
-          --ignore=./libs/agno/tests/integration/embedder ./libs/agno/tests/integration
+          python -m pytest --ignore=./libs/agno/tests/integration/models --ignore=./libs/agno/tests/integration/agent --ignore=./libs/agno/tests/integration/knowledge --ignore=./libs/agno/tests/integration/teams --ignore=./libs/agno/tests/integration/embedder ./libs/agno/tests/integration

cookbook/agent_concepts/tool_concepts/custom_tools/complex_input_types.py

@@ -0,0 +1,88 @@
+"""
+This example shows how to use complex input types with tools.
+
+Recommendations:
+- Specify fields with descriptions, these will be used in the JSON schema sent to the model and will increase accuracy.
+- Try not to nest the structures too deeply, the model will have a hard time understanding them.
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import List, Optional
+
+from agno.agent import Agent
+from agno.tools.decorator import tool
+from pydantic import BaseModel, Field
+
+
+# Define Pydantic models for our tools
+class UserProfile(BaseModel):
+    """User profile information."""
+
+    name: str = Field(..., description="Full name of the user")
+    email: str = Field(..., description="Valid email address")
+    age: int = Field(..., ge=0, le=120, description="Age of the user")
+    interests: List[str] = Field(
+        default_factory=list, description="List of user interests"
+    )
+    created_at: datetime = Field(
+        default_factory=datetime.now, description="Account creation timestamp"
+    )
+
+
+class TaskPriority(str, Enum):
+    """Priority levels for tasks."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    URGENT = "urgent"
+
+
+class Task(BaseModel):
+    """Task information."""
+
+    title: str = Field(..., min_length=1, max_length=100, description="Task title")
+    description: Optional[str] = Field(None, description="Detailed task description")
+    priority: TaskPriority = Field(
+        default=TaskPriority.MEDIUM, description="Task priority level"
+    )
+    due_date: Optional[datetime] = Field(None, description="Task due date")
+    assigned_to: Optional[UserProfile] = Field(
+        None, description="User assigned to the task"
+    )
+
+
+# Custom tools using Pydantic models
+@tool
+def create_user(user_data: UserProfile) -> str:
+    """Create a new user profile with validated information."""
+    # In a real application, this would save to a database
+    return f"Created user profile for {user_data.name} with email {user_data.email}"
+
+
+@tool
+def create_task(task_data: Task) -> str:
+    """Create a new task with priority and assignment."""
+    # In a real application, this would save to a database
+    return f"Created task '{task_data.title}' with priority {task_data.priority}"
+
+
+# Create the agent
+agent = Agent(
+    name="task_manager",
+    description="An agent that manages users and tasks with proper validation",
+    tools=[create_user, create_task],
+)
+
+# Example usage
+if __name__ == "__main__":
+    # Example 1: Create a user
+    agent.print_response(
+        "Create a new user named John Doe with email john@example.com, age 30, and interests in Python and AI"
+    )
+
+    # Example 2: Create a task
+    agent.print_response(
+        "Create a high priority task titled 'Implement API endpoints' due tomorrow"
+    )

cookbook/examples/a2a/basic_agent/README.md

@@ -21,7 +21,7 @@ Basic Agno A2A Agent example that uses A2A to send and receive messages to/from
 4. Run the test client in a different terminal
 
    ```bash
-   python cookbook/examples/a2a/basic_agent/test_client.py
+   python cookbook/examples/a2a/basic_agent/client.py
    ```
 
 ## Notes

cookbook/examples/a2a/basic_agent/test_client.py renamed to cookbook/examples/a2a/basic_agent/client.py

@@ -6157,7 +6157,6 @@ def register_agent(self) -> None:
             if not self.session_id:
                 self.session_id = str(uuid4())
 
-            log_debug(f"Creating Agent on Platform: {self.name}, {self.agent_id}, {self.team_id}, {self.workflow_id}")
             create_agent(
                 agent=AgentCreate(
                     name=self.name,
@@ -6168,7 +6167,6 @@ def register_agent(self) -> None:
                     config=self.get_agent_config_dict(),
                 )
             )
-            log_debug(f"Agent created: {self.name}, {self.agent_id}, {self.team_id}, {self.workflow_id}")
         except Exception as e:
             log_warning(f"Could not create Agent: {e}")
 
@@ -6180,7 +6178,6 @@ async def _aregister_agent(self) -> None:
         from agno.api.agent import AgentCreate, acreate_agent
 
         try:
-            log_debug(f"Creating Agent on Platform: {self.name}, {self.agent_id}, {self.team_id},")
             await acreate_agent(
                 agent=AgentCreate(
                     name=self.name,
@@ -6193,7 +6190,6 @@ async def _aregister_agent(self) -> None:
             )
         except Exception as e:
             log_debug(f"Could not create Agent app: {e}")
-        log_debug(f"Agent app created: {self.name}, {self.agent_id}, {self.team_id},")
 
     def _log_agent_run(self, session_id: str, user_id: Optional[str] = None) -> None:
         self.set_monitoring()

libs/agno/agno/agent/agent.py

@@ -48,6 +48,7 @@ async def acreate_agent_run(run: AgentRunCreate, monitor: bool = False) -> None:
             )
         except Exception as e:
             log_debug(f"Could not create Agent run: {e}")
+    return
 
 
 def create_agent(agent: AgentCreate) -> None:
@@ -60,8 +61,11 @@ def create_agent(agent: AgentCreate) -> None:
                 ApiRoutes.AGENT_CREATE,
                 json=agent.model_dump(exclude_none=True),
             )
+
+            log_debug(f"Created Agent on Platform. ID: {agent.agent_id}")
         except Exception as e:
             log_debug(f"Could not create Agent: {e}")
+    return
 
 
 async def acreate_agent(agent: AgentCreate) -> None:
@@ -74,5 +78,7 @@ async def acreate_agent(agent: AgentCreate) -> None:
                 ApiRoutes.AGENT_CREATE,
                 json=agent.model_dump(exclude_none=True),
             )
+            log_debug(f"Created Agent on Platform. ID: {agent.agent_id}")
         except Exception as e:
             log_debug(f"Could not create Agent: {e}")
+    return

libs/agno/agno/api/agent.py

@@ -23,7 +23,7 @@
         ContentBlockDeltaEvent,
         ContentBlockStartEvent,
         ContentBlockStopEvent,
-        MessageDeltaEvent,
+        # MessageDeltaEvent, # Broken at the moment
         MessageStopEvent,
     )
     from anthropic.types import Message as AnthropicMessage
@@ -137,16 +137,16 @@ def _prepare_request_kwargs(
             Dict[str, Any]: The request keyword arguments.
         """
         request_kwargs = self.request_kwargs.copy()
-
-        if self.cache_system_prompt:
-            cache_control = (
-                {"type": "ephemeral", "ttl": "1h"}
-                if self.extended_cache_time is not None and self.extended_cache_time is True
-                else {"type": "ephemeral"}
-            )
-            request_kwargs["system"] = [{"text": system_message, "type": "text", "cache_control": cache_control}]
-        else:
-            request_kwargs["system"] = [{"text": system_message, "type": "text"}]
+        if system_message:
+            if self.cache_system_prompt:
+                cache_control = (
+                    {"type": "ephemeral", "ttl": "1h"}
+                    if self.extended_cache_time is not None and self.extended_cache_time is True
+                    else {"type": "ephemeral"}
+                )
+                request_kwargs["system"] = [{"text": system_message, "type": "text", "cache_control": cache_control}]
+            else:
+                request_kwargs["system"] = [{"text": system_message, "type": "text"}]
 
         if tools:
             request_kwargs["tools"] = self._format_tools_for_model(tools)
@@ -212,7 +212,6 @@ def invoke(
         try:
             chat_messages, system_message = format_messages(messages)
             request_kwargs = self._prepare_request_kwargs(system_message, tools)
-
             return self.get_client().messages.create(
                 model=self.id,
                 messages=chat_messages,  # type: ignore
@@ -473,7 +472,7 @@ def parse_provider_response(self, response: AnthropicMessage, **kwargs) -> Model
         return model_response
 
     def parse_provider_response_delta(
-        self, response: Union[ContentBlockDeltaEvent, ContentBlockStopEvent, MessageDeltaEvent]
+        self, response: Union[ContentBlockStartEvent, ContentBlockDeltaEvent, ContentBlockStopEvent, MessageStopEvent]
     ) -> ModelResponse:
         """
         Parse the Claude streaming response into ModelProviderResponse objects.
@@ -543,12 +542,12 @@ def parse_provider_response_delta(
                             DocumentCitation(document_title=citation.document_title, cited_text=citation.cited_text)
                         )
 
-            if response.message.usage is not None:
-                model_response.response_usage = {
-                    "cache_write_tokens": response.usage.cache_creation_input_tokens,
-                    "cached_tokens": response.usage.cache_read_input_tokens,
-                    "input_tokens": response.usage.input_tokens,
-                    "output_tokens": response.usage.output_tokens,
-                }
+        if hasattr(response, "usage") and response.usage is not None:
+            model_response.response_usage = {
+                "cache_write_tokens": response.usage.cache_creation_input_tokens or 0,
+                "cached_tokens": response.usage.cache_read_input_tokens or 0,
+                "input_tokens": response.usage.input_tokens or 0,
+                "output_tokens": response.usage.output_tokens or 0,
+            }
 
         return model_response

libs/agno/agno/models/anthropic/claude.py

@@ -56,20 +56,20 @@ def _add_usage_metrics_to_assistant_message(assistant_message: Message, response
 
     # Standard token metrics
     if isinstance(response_usage, dict):
-        if "input_tokens" in response_usage:
+        if "input_tokens" in response_usage and response_usage.get("input_tokens") is not None:
             assistant_message.metrics.input_tokens = response_usage.get("input_tokens", 0)
-        if "output_tokens" in response_usage:
+        if "output_tokens" in response_usage and response_usage.get("output_tokens") is not None:
             assistant_message.metrics.output_tokens = response_usage.get("output_tokens", 0)
-        if "prompt_tokens" in response_usage:
+        if "prompt_tokens" in response_usage and response_usage.get("prompt_tokens") is not None:
             assistant_message.metrics.input_tokens = response_usage.get("prompt_tokens", 0)
-        if "completion_tokens" in response_usage:
+        if "completion_tokens" in response_usage and response_usage.get("completion_tokens") is not None:
             assistant_message.metrics.output_tokens = response_usage.get("completion_tokens", 0)
-        if "total_tokens" in response_usage:
-            assistant_message.metrics.total_tokens = response_usage.get("total_tokens", 0)
-        if "cached_tokens" in response_usage:
+        if "cached_tokens" in response_usage and response_usage.get("cached_tokens") is not None:
             assistant_message.metrics.cached_tokens = response_usage.get("cached_tokens", 0)
-        if "cache_write_tokens" in response_usage:
+        if "cache_write_tokens" in response_usage and response_usage.get("cache_write_tokens") is not None:
             assistant_message.metrics.cache_write_tokens = response_usage.get("cache_write_tokens", 0)
+        if "total_tokens" in response_usage and response_usage.get("total_tokens") is not None:
+            assistant_message.metrics.total_tokens = response_usage.get("total_tokens", 0)
         else:
             assistant_message.metrics.total_tokens = (
                 assistant_message.metrics.input_tokens + assistant_message.metrics.output_tokens
@@ -92,6 +92,17 @@ def _add_usage_metrics_to_assistant_message(assistant_message: Message, response
         if hasattr(response_usage, "cache_write_tokens") and response_usage.cache_write_tokens is not None:
             assistant_message.metrics.cache_write_tokens = response_usage.cache_write_tokens
 
+    # If you didn't capture any total tokens
+    if not assistant_message.metrics.total_tokens:
+        if assistant_message.metrics.input_tokens is None:
+            assistant_message.metrics.input_tokens = 0
+        if assistant_message.metrics.output_tokens is None:
+            assistant_message.metrics.output_tokens = 0
+
+        assistant_message.metrics.total_tokens = (
+            assistant_message.metrics.input_tokens + assistant_message.metrics.output_tokens
+        )
+
     # Additional metrics (e.g., from Groq, Ollama)
     if isinstance(response_usage, dict) and "additional_metrics" in response_usage:
         assistant_message.metrics.additional_metrics = response_usage["additional_metrics"]

libs/agno/agno/models/base.py

@@ -19,7 +19,7 @@ class OpenAILike(OpenAIChat):
     name: str = "OpenAILike"
     api_key: Optional[str] = "not-provided"
 
-    role_map = {
+    default_role_map = {
         "system": "system",
         "user": "user",
         "assistant": "assistant",

libs/agno/agno/models/openai/like.py

@@ -34,6 +34,8 @@ def __init__(
                     self.instructions += "\n" + few_shot_examples
                 else:
                     self.instructions += "\n" + self.FEW_SHOT_EXAMPLES
+        else:
+            self.instructions = instructions
 
         # The knowledge to search
         self.knowledge: AgentKnowledge = knowledge
@@ -48,7 +50,7 @@ def __init__(
 
         super().__init__(
             name="knowledge_tools",
-            instructions=instructions,
+            instructions=self.instructions,
             add_instructions=add_instructions,
             tools=tools,
             **kwargs,