agno 2.4.4__py3-none-any.whl → 2.4.6__py3-none-any.whl

agno/agent/agent.py

@@ -320,6 +320,8 @@ class Agent:
     # Add a tool that allows the Model to search the knowledge base (aka Agentic RAG)
     # Added only if knowledge is provided.
     search_knowledge: bool = True
+    # If True, add search_knowledge instructions to the system prompt
+    add_search_knowledge_instructions: bool = True
     # Add a tool that allows the Agent to update Knowledge.
     update_knowledge: bool = False
     # Add a tool that allows the Model to get the tool call history.
@@ -524,6 +526,7 @@ class Agent:
         reasoning_max_steps: int = 10,
         read_chat_history: bool = False,
         search_knowledge: bool = True,
+        add_search_knowledge_instructions: bool = True,
         update_knowledge: bool = False,
         read_tool_call_history: bool = False,
         send_media_to_model: bool = True,
@@ -661,6 +664,7 @@ class Agent:
 
         self.read_chat_history = read_chat_history
         self.search_knowledge = search_knowledge
+        self.add_search_knowledge_instructions = add_search_knowledge_instructions
         self.update_knowledge = update_knowledge
         self.read_tool_call_history = read_tool_call_history
         self.send_media_to_model = send_media_to_model
@@ -854,8 +858,9 @@ class Agent:
             return
 
         # Handle learning=True: create default LearningMachine
+        # Enables user_profile (structured fields) and user_memory (unstructured observations)
         if self.learning is True:
-            self._learning = LearningMachine(db=self.db, model=self.model, user_profile=True)
+            self._learning = LearningMachine(db=self.db, model=self.model, user_profile=True, user_memory=True)
             return
 
         # Handle learning=LearningMachine(...): inject dependencies
@@ -7431,6 +7436,10 @@ class Agent:
             config["enable_agentic_knowledge_filters"] = self.enable_agentic_knowledge_filters
         if self.add_knowledge_to_context:
             config["add_knowledge_to_context"] = self.add_knowledge_to_context
+        if not self.search_knowledge:
+            config["search_knowledge"] = self.search_knowledge
+        if self.add_search_knowledge_instructions:
+            config["add_search_knowledge_instructions"] = self.add_search_knowledge_instructions
         # Skip knowledge_retriever as it's a callable
         if self.references_format != "json":
             config["references_format"] = self.references_format
@@ -7481,8 +7490,6 @@ class Agent:
         # --- Default tools settings ---
         if self.read_chat_history:
             config["read_chat_history"] = self.read_chat_history
-        if not self.search_knowledge:
-            config["search_knowledge"] = self.search_knowledge
         if self.update_knowledge:
             config["update_knowledge"] = self.update_knowledge
         if self.read_tool_call_history:
@@ -7806,6 +7813,7 @@ class Agent:
             # --- Default tools settings ---
             read_chat_history=config.get("read_chat_history", False),
             search_knowledge=config.get("search_knowledge", True),
+            add_search_knowledge_instructions=config.get("add_search_knowledge_instructions", True),
             update_knowledge=config.get("update_knowledge", False),
             read_tool_call_history=config.get("read_tool_call_history", False),
             send_media_to_model=config.get("send_media_to_model", True),
@@ -8859,16 +8867,6 @@ class Agent:
         if self.name is not None and self.add_name_to_context:
             additional_information.append(f"Your name is: {self.name}.")
 
-        # 3.2.5 Add knowledge context using protocol's build_context
-        if self.knowledge is not None:
-            build_context_fn = getattr(self.knowledge, "build_context", None)
-            if callable(build_context_fn):
-                knowledge_context = build_context_fn(
-                    enable_agentic_filters=self.enable_agentic_knowledge_filters,
-                )
-                if knowledge_context:
-                    additional_information.append(knowledge_context)
-
         # 3.3 Build the default system message for the Agent.
         system_message_content: str = ""
         # 3.3.1 First add the Agent description if provided
@@ -9045,12 +9043,22 @@ class Agent:
             if learning_context:
                 system_message_content += learning_context + "\n"
 
-        # 3.3.13 Add the system message from the Model
+        # 3.3.13 then add search_knowledge instructions to the system prompt
+        if self.knowledge is not None and self.search_knowledge and self.add_search_knowledge_instructions:
+            build_context_fn = getattr(self.knowledge, "build_context", None)
+            if callable(build_context_fn):
+                knowledge_context = build_context_fn(
+                    enable_agentic_filters=self.enable_agentic_knowledge_filters,
+                )
+                if knowledge_context is not None:
+                    system_message_content += knowledge_context + "\n"
+
+        # 3.3.14 Add the system message from the Model
         system_message_from_model = self.model.get_system_message_for_model(tools)
         if system_message_from_model is not None:
             system_message_content += system_message_from_model
 
-        # 3.3.14 Add the JSON output prompt if output_schema is provided and the model does not support native structured outputs or JSON schema outputs
+        # 3.3.15 Add the JSON output prompt if output_schema is provided and the model does not support native structured outputs or JSON schema outputs
         # or if use_json_mode is True
         if (
             output_schema is not None
@@ -9062,11 +9070,11 @@ class Agent:
         ):
             system_message_content += f"{get_json_output_prompt(output_schema)}"  # type: ignore
 
-        # 3.3.15 Add the response model format prompt if output_schema is provided (Pydantic only)
+        # 3.3.16 Add the response model format prompt if output_schema is provided (Pydantic only)
         if output_schema is not None and self.parser_model is not None and not isinstance(output_schema, dict):
             system_message_content += f"{get_response_model_format_prompt(output_schema)}"
 
-        # 3.3.16 Add the session state to the system message
+        # 3.3.17 Add the session state to the system message
         if add_session_state_to_context and session_state is not None:
             system_message_content += f"\n<session_state>\n{session_state}\n</session_state>\n\n"
 
@@ -9196,24 +9204,6 @@ class Agent:
         if self.name is not None and self.add_name_to_context:
             additional_information.append(f"Your name is: {self.name}.")
 
-        # 3.2.5 Add knowledge context using protocol's build_context (async)
-        if self.knowledge is not None:
-            # Prefer async version if available for async databases
-            abuild_context_fn = getattr(self.knowledge, "abuild_context", None)
-            build_context_fn = getattr(self.knowledge, "build_context", None)
-            if callable(abuild_context_fn):
-                knowledge_context = await abuild_context_fn(
-                    enable_agentic_filters=self.enable_agentic_knowledge_filters,
-                )
-                if knowledge_context:
-                    additional_information.append(knowledge_context)
-            elif callable(build_context_fn):
-                knowledge_context = build_context_fn(
-                    enable_agentic_filters=self.enable_agentic_knowledge_filters,
-                )
-                if knowledge_context:
-                    additional_information.append(knowledge_context)
-
         # 3.3 Build the default system message for the Agent.
         system_message_content: str = ""
         # 3.3.1 First add the Agent description if provided
@@ -9393,12 +9383,30 @@ class Agent:
             if learning_context:
                 system_message_content += learning_context + "\n"
 
-        # 3.3.13 Add the system message from the Model
+        # 3.3.13 then add search_knowledge instructions to the system prompt
+        if self.knowledge is not None and self.search_knowledge and self.add_search_knowledge_instructions:
+            # Prefer async version if available for async databases
+            abuild_context_fn = getattr(self.knowledge, "abuild_context", None)
+            build_context_fn = getattr(self.knowledge, "build_context", None)
+            if callable(abuild_context_fn):
+                knowledge_context = await abuild_context_fn(
+                    enable_agentic_filters=self.enable_agentic_knowledge_filters,
+                )
+                if knowledge_context is not None:
+                    system_message_content += knowledge_context + "\n"
+            elif callable(build_context_fn):
+                knowledge_context = build_context_fn(
+                    enable_agentic_filters=self.enable_agentic_knowledge_filters,
+                )
+                if knowledge_context is not None:
+                    system_message_content += knowledge_context + "\n"
+
+        # 3.3.14 Add the system message from the Model
         system_message_from_model = self.model.get_system_message_for_model(tools)
         if system_message_from_model is not None:
             system_message_content += system_message_from_model
 
-        # 3.3.14 Add the JSON output prompt if output_schema is provided and the model does not support native structured outputs or JSON schema outputs
+        # 3.3.15 Add the JSON output prompt if output_schema is provided and the model does not support native structured outputs or JSON schema outputs
         # or if use_json_mode is True
         if (
             output_schema is not None
@@ -9410,11 +9418,11 @@ class Agent:
         ):
             system_message_content += f"{get_json_output_prompt(output_schema)}"  # type: ignore
 
-        # 3.3.15 Add the response model format prompt if output_schema is provided (Pydantic only)
+        # 3.3.16 Add the response model format prompt if output_schema is provided (Pydantic only)
         if output_schema is not None and self.parser_model is not None and not isinstance(output_schema, dict):
             system_message_content += f"{get_response_model_format_prompt(output_schema)}"
 
-        # 3.3.16 Add the session state to the system message
+        # 3.3.17 Add the session state to the system message
         if add_session_state_to_context and session_state is not None:
             system_message_content += self._get_formatted_session_state_for_system_message(session_state)
 

agno/db/surrealdb/models.py

@@ -48,7 +48,7 @@ def surrealize_dates(record: dict) -> dict:
         if isinstance(value, date):
             copy[key] = datetime.combine(value, datetime.min.time()).replace(tzinfo=timezone.utc)
         elif key in ["created_at", "updated_at"] and isinstance(value, (int, float)):
-            copy[key] = datetime.fromtimestamp(value).replace(tzinfo=timezone.utc)
+            copy[key] = datetime.fromtimestamp(value, tz=timezone.utc)
         elif key in ["created_at", "updated_at"] and isinstance(value, str):
             # Handle ISO string format - convert back to datetime object for SurrealDB
             try:

agno/knowledge/chunking/agentic.py

@@ -55,11 +55,7 @@ class AgenticChunking(ChunkingStrategy):
             chunk = remaining_text[:break_point].strip()
             meta_data = chunk_meta_data.copy()
             meta_data["chunk"] = chunk_number
-            chunk_id = None
-            if document.id:
-                chunk_id = f"{document.id}_{chunk_number}"
-            elif document.name:
-                chunk_id = f"{document.name}_{chunk_number}"
+            chunk_id = self._generate_chunk_id(document, chunk_number, chunk)
             meta_data["chunk_size"] = len(chunk)
             chunks.append(
                 Document(

agno/knowledge/chunking/code.py

@@ -82,7 +82,7 @@ class CodeChunking(ChunkingStrategy):
         for i, chunk in enumerate(chunks, 1):
             meta_data = document.meta_data.copy()
             meta_data["chunk"] = i
-            chunk_id = f"{document.id}_{i}" if document.id else None
+            chunk_id = self._generate_chunk_id(document, i, chunk.text)
             meta_data["chunk_size"] = len(chunk.text)
 
             chunked_documents.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk.text))

agno/knowledge/chunking/document.py

@@ -38,17 +38,10 @@ class DocumentChunking(ChunkingStrategy):
                 if current_chunk:
                     meta_data = chunk_meta_data.copy()
                     meta_data["chunk"] = chunk_number
-                    chunk_id = None
-                    if document.id:
-                        chunk_id = f"{document.id}_{chunk_number}"
-                    elif document.name:
-                        chunk_id = f"{document.name}_{chunk_number}"
-                    meta_data["chunk_size"] = len("\n\n".join(current_chunk))
-                    chunks.append(
-                        Document(
-                            id=chunk_id, name=document.name, meta_data=meta_data, content="\n\n".join(current_chunk)
-                        )
-                    )
+                    chunk_content = "\n\n".join(current_chunk)
+                    chunk_id = self._generate_chunk_id(document, chunk_number, chunk_content)
+                    meta_data["chunk_size"] = len(chunk_content)
+                    chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk_content))
                     chunk_number += 1
                     current_chunk = []
                     current_size = 0
@@ -70,18 +63,15 @@ class DocumentChunking(ChunkingStrategy):
                         if current_chunk:
                             meta_data = chunk_meta_data.copy()
                             meta_data["chunk"] = chunk_number
-                            chunk_id = None
-                            if document.id:
-                                chunk_id = f"{document.id}_{chunk_number}"
-                            elif document.name:
-                                chunk_id = f"{document.name}_{chunk_number}"
-                            meta_data["chunk_size"] = len(" ".join(current_chunk))
+                            chunk_content = " ".join(current_chunk)
+                            chunk_id = self._generate_chunk_id(document, chunk_number, chunk_content)
+                            meta_data["chunk_size"] = len(chunk_content)
                             chunks.append(
                                 Document(
                                     id=chunk_id,
                                     name=document.name,
                                     meta_data=meta_data,
-                                    content=" ".join(current_chunk),
+                                    content=chunk_content,
                                 )
                             )
                             chunk_number += 1
@@ -94,18 +84,11 @@ class DocumentChunking(ChunkingStrategy):
             else:
                 meta_data = chunk_meta_data.copy()
                 meta_data["chunk"] = chunk_number
-                chunk_id = None
-                if document.id:
-                    chunk_id = f"{document.id}_{chunk_number}"
-                elif document.name:
-                    chunk_id = f"{document.name}_{chunk_number}"
-                meta_data["chunk_size"] = len("\n\n".join(current_chunk))
+                chunk_content = "\n\n".join(current_chunk)
+                chunk_id = self._generate_chunk_id(document, chunk_number, chunk_content)
+                meta_data["chunk_size"] = len(chunk_content)
                 if current_chunk:
-                    chunks.append(
-                        Document(
-                            id=chunk_id, name=document.name, meta_data=meta_data, content="\n\n".join(current_chunk)
-                        )
-                    )
+                    chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk_content))
                     chunk_number += 1
                 current_chunk = [para]
                 current_size = para_size
@@ -113,15 +96,10 @@ class DocumentChunking(ChunkingStrategy):
         if current_chunk:
             meta_data = chunk_meta_data.copy()
             meta_data["chunk"] = chunk_number
-            chunk_id = None
-            if document.id:
-                chunk_id = f"{document.id}_{chunk_number}"
-            elif document.name:
-                chunk_id = f"{document.name}_{chunk_number}"
-            meta_data["chunk_size"] = len("\n\n".join(current_chunk))
-            chunks.append(
-                Document(id=chunk_id, name=document.name, meta_data=meta_data, content="\n\n".join(current_chunk))
-            )
+            chunk_content = "\n\n".join(current_chunk)
+            chunk_id = self._generate_chunk_id(document, chunk_number, chunk_content)
+            meta_data["chunk_size"] = len(chunk_content)
+            chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk_content))
 
         # Handle overlap if specified
         if self.overlap > 0:
@@ -131,11 +109,11 @@ class DocumentChunking(ChunkingStrategy):
                     # Add overlap from previous chunk
                     prev_text = chunks[i - 1].content[-self.overlap :]
                     meta_data = chunk_meta_data.copy()
-                    meta_data["chunk"] = chunk_number
-                    chunk_id = None
-                    if document.id:
-                        chunk_id = f"{document.id}_{chunk_number}"
+                    # Use the chunk's existing metadata and ID instead of stale chunk_number
+                    meta_data["chunk"] = chunks[i].meta_data["chunk"]
+                    chunk_id = chunks[i].id
                     meta_data["chunk_size"] = len(prev_text + chunks[i].content)
+
                     if prev_text:
                         overlapped_chunks.append(
                             Document(
@@ -145,6 +123,8 @@ class DocumentChunking(ChunkingStrategy):
                                 content=prev_text + chunks[i].content,
                             )
                         )
+                    else:
+                        overlapped_chunks.append(chunks[i])
                 else:
                     overlapped_chunks.append(chunks[i])
             chunks = overlapped_chunks

agno/knowledge/chunking/fixed.py

@@ -38,11 +38,7 @@ class FixedSizeChunking(ChunkingStrategy):
             chunk = content[start:end]
             meta_data = chunk_meta_data.copy()
             meta_data["chunk"] = chunk_number
-            chunk_id = None
-            if document.id:
-                chunk_id = f"{document.id}_{chunk_number}"
-            elif document.name:
-                chunk_id = f"{document.name}_{chunk_number}"
+            chunk_id = self._generate_chunk_id(document, chunk_number, chunk)
             meta_data["chunk_size"] = len(chunk)
             chunked_documents.append(
                 Document(

agno/knowledge/chunking/markdown.py

@@ -267,11 +267,7 @@ class MarkdownChunking(ChunkingStrategy):
                 for sub_chunk in sub_chunks:
                     meta_data = chunk_meta_data.copy()
                     meta_data["chunk"] = chunk_number
-                    chunk_id = None
-                    if document.id:
-                        chunk_id = f"{document.id}_{chunk_number}"
-                    elif document.name:
-                        chunk_id = f"{document.name}_{chunk_number}"
+                    chunk_id = self._generate_chunk_id(document, chunk_number, sub_chunk)
                     meta_data["chunk_size"] = len(sub_chunk)
 
                     chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=sub_chunk))
@@ -282,19 +278,12 @@ class MarkdownChunking(ChunkingStrategy):
             else:
                 meta_data = chunk_meta_data.copy()
                 meta_data["chunk"] = chunk_number
-                chunk_id = None
-                if document.id:
-                    chunk_id = f"{document.id}_{chunk_number}"
-                elif document.name:
-                    chunk_id = f"{document.name}_{chunk_number}"
-                meta_data["chunk_size"] = len("\n\n".join(current_chunk))
+                chunk_content = "\n\n".join(current_chunk)
+                chunk_id = self._generate_chunk_id(document, chunk_number, chunk_content)
+                meta_data["chunk_size"] = len(chunk_content)
 
                 if current_chunk:
-                    chunks.append(
-                        Document(
-                            id=chunk_id, name=document.name, meta_data=meta_data, content="\n\n".join(current_chunk)
-                        )
-                    )
+                    chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk_content))
                     chunk_number += 1
 
                 current_chunk = [section]
@@ -304,15 +293,10 @@ class MarkdownChunking(ChunkingStrategy):
         if current_chunk and not self.split_on_headings:
             meta_data = chunk_meta_data.copy()
             meta_data["chunk"] = chunk_number
-            chunk_id = None
-            if document.id:
-                chunk_id = f"{document.id}_{chunk_number}"
-            elif document.name:
-                chunk_id = f"{document.name}_{chunk_number}"
-            meta_data["chunk_size"] = len("\n\n".join(current_chunk))
-            chunks.append(
-                Document(id=chunk_id, name=document.name, meta_data=meta_data, content="\n\n".join(current_chunk))
-            )
+            chunk_content = "\n\n".join(current_chunk)
+            chunk_id = self._generate_chunk_id(document, chunk_number, chunk_content)
+            meta_data["chunk_size"] = len(chunk_content)
+            chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk_content))
 
         # Handle overlap if specified
         if self.overlap > 0:

agno/knowledge/chunking/recursive.py

@@ -46,9 +46,7 @@ class RecursiveChunking(ChunkingStrategy):
             chunk = self.clean_text(content[start:end])
             meta_data = chunk_meta_data.copy()
             meta_data["chunk"] = chunk_number
-            chunk_id = None
-            if document.id:
-                chunk_id = f"{document.id}_{chunk_number}"
+            chunk_id = self._generate_chunk_id(document, chunk_number, chunk)
             chunk_number += 1
             meta_data["chunk_size"] = len(chunk)
             chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk))

agno/knowledge/chunking/row.py

@@ -33,7 +33,8 @@ class RowChunking(ChunkingStrategy):
 
             if chunk_content:  # Skip empty rows
                 meta_data = document.meta_data.copy()
-                meta_data["row_number"] = start_index + i  # Preserve logical row numbering
-                chunk_id = f"{document.id}_row_{start_index + i}" if document.id else None
+                row_number = start_index + i
+                meta_data["row_number"] = row_number  # Preserve logical row numbering
+                chunk_id = self._generate_chunk_id(document, row_number, chunk_content, prefix="row")
                 chunks.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk_content))
         return chunks

agno/knowledge/chunking/semantic.py

@@ -160,7 +160,7 @@ class SemanticChunking(ChunkingStrategy):
         for i, chunk in enumerate(chunks, 1):
             meta_data = document.meta_data.copy()
             meta_data["chunk"] = i
-            chunk_id = f"{document.id}_{i}" if document.id else None
+            chunk_id = self._generate_chunk_id(document, i, chunk.text)
             meta_data["chunk_size"] = len(chunk.text)
 
             chunked_documents.append(Document(id=chunk_id, name=document.name, meta_data=meta_data, content=chunk.text))

agno/knowledge/chunking/strategy.py

@@ -1,3 +1,4 @@
+import hashlib
 from abc import ABC, abstractmethod
 from enum import Enum
 from typing import List, Optional
@@ -12,6 +13,24 @@ class ChunkingStrategy(ABC):
     def chunk(self, document: Document) -> List[Document]:
         raise NotImplementedError
 
+    def _generate_chunk_id(
+        self, document: Document, chunk_number: int, content: Optional[str] = None, prefix: Optional[str] = None
+    ) -> Optional[str]:
+        """Generate a deterministic ID for the chunk."""
+        suffix = f"_{prefix}_{chunk_number}" if prefix else f"_{chunk_number}"
+
+        if document.id:
+            return f"{document.id}{suffix}"
+        elif document.name:
+            return f"{document.name}{suffix}"
+        else:
+            # Hash the chunk content for a deterministic ID when no identifier exists
+            hash_source = content if content else document.content
+            if hash_source:
+                content_hash = hashlib.md5(hash_source.encode("utf-8")).hexdigest()[:12]  # nosec B324
+                return f"chunk_{content_hash}{suffix}"
+            return None
+
     async def achunk(self, document: Document) -> List[Document]:
         """Async version of chunk. Override for truly async implementations."""
         return self.chunk(document)