agno 2.3.24__py3-none-any.whl → 2.3.25__py3-none-any.whl

agno/agent/agent.py

@@ -46,6 +46,7 @@ from agno.filters import FilterExpr
 from agno.guardrails import BaseGuardrail
 from agno.knowledge.knowledge import Knowledge
 from agno.knowledge.types import KnowledgeFilter
+from agno.learn.machine import LearningMachine
 from agno.media import Audio, File, Image, Video
 from agno.memory import MemoryManager
 from agno.models.base import Model
@@ -359,6 +360,12 @@ class Agent:
     # If True, resolve session_state, dependencies, and metadata in the user and system messages
     resolve_in_context: bool = True
 
+    # --- Learning Machine ---
+    # LearningMachine for unified learning capabilities
+    learning: Optional[Union[bool, LearningMachine]] = None
+    # Add learnings context to system prompt
+    add_learnings_to_context: bool = True
+
     # --- Extra Messages ---
     # A list of extra messages added after the system message and before the user message.
     # Use these for few-shot learning or to provide additional context to the Model.
@@ -527,6 +534,8 @@ class Agent:
         add_location_to_context: bool = False,
         timezone_identifier: Optional[str] = None,
         resolve_in_context: bool = True,
+        learning: Optional[Union[bool, LearningMachine]] = None,
+        add_learnings_to_context: bool = True,
         additional_input: Optional[List[Union[str, Dict, BaseModel, Message]]] = None,
         user_message_role: str = "user",
         build_user_context: bool = True,
@@ -656,6 +665,8 @@ class Agent:
         self.add_location_to_context = add_location_to_context
         self.timezone_identifier = timezone_identifier
         self.resolve_in_context = resolve_in_context
+        self.learning = learning
+        self.add_learnings_to_context = add_learnings_to_context
         self.additional_input = additional_input
         self.user_message_role = user_message_role
         self.build_user_context = build_user_context
@@ -705,6 +716,10 @@ class Agent:
         self.debug_level = debug_level
         self.telemetry = telemetry
 
+        # Internal use: _learning holds the resolved LearningMachine instance
+        # use get_learning_machine() to access it.
+        self._learning: Optional[LearningMachine] = None
+
         # If we are caching the agent session
         self._cached_session: Optional[AgentSession] = None
 
@@ -811,6 +826,49 @@ class Agent:
                 self.enable_user_memories or self.enable_agentic_memory or self.memory_manager is not None
             )
 
+    def _set_learning_machine(self) -> None:
+        """Initialize LearningMachine with agent's db and model.
+
+        Sets the internal _learning field without modifying the public learning field.
+
+        Handles:
+        - learning=True: Create default LearningMachine
+        - learning=False/None: Disabled
+        - learning=LearningMachine(...): Use provided, inject db/model/knowledge
+        """
+        # Handle learning=False or learning=None
+        if self.learning is None or self.learning is False:
+            self._learning = None
+            return
+
+        # Check db requirement
+        if self.db is None:
+            log_warning("Database not provided. LearningMachine not initialized.")
+            self._learning = None
+            return
+
+        # Handle learning=True: create default LearningMachine
+        if self.learning is True:
+            self._learning = LearningMachine(db=self.db, model=self.model, user_profile=True)
+            return
+
+        # Handle learning=LearningMachine(...): inject dependencies
+        if isinstance(self.learning, LearningMachine):
+            if self.learning.db is None:
+                self.learning.db = self.db
+            if self.learning.model is None:
+                self.learning.model = self.model
+            self._learning = self.learning
+
+    def get_learning_machine(self) -> Optional[LearningMachine]:
+        """Get the resolved LearningMachine instance.
+
+        Returns:
+            The LearningMachine instance if learning is enabled and initialized,
+            None otherwise.
+        """
+        return self._learning
+
     def _set_session_summary_manager(self) -> None:
         if self.enable_session_summaries and self.session_summary_manager is None:
             self.session_summary_manager = SessionSummaryManager(model=self.model)
@@ -871,6 +929,8 @@ class Agent:
             self._set_session_summary_manager()
         if self.compress_tool_results or self.compression_manager is not None:
             self._set_compression_manager()
+        if self.learning is not None and self.learning is not False:
+            self._set_learning_machine()
 
         log_debug(f"Agent ID: {self.id}", center=True)
 
@@ -1008,6 +1068,7 @@ class Agent:
         13. Cleanup and store the run response and session
         """
         memory_future = None
+        learning_future = None
         cultural_knowledge_future = None
 
         try:
@@ -1083,6 +1144,14 @@ class Agent:
                         existing_future=memory_future,
                     )
 
+                    # Start learning extraction as a background task (runs concurrently with the main execution)
+                    learning_future = self._start_learning_future(
+                        run_messages=run_messages,
+                        session=session,
+                        user_id=user_id,
+                        existing_future=learning_future,
+                    )
+
                     # Start cultural knowledge creation in background thread
                     cultural_knowledge_future = self._start_cultural_knowledge_future(
                         run_messages=run_messages,
@@ -1130,6 +1199,7 @@ class Agent:
                         wait_for_open_threads(
                             memory_future=memory_future,  # type: ignore
                             cultural_knowledge_future=cultural_knowledge_future,  # type: ignore
+                            learning_future=learning_future,  # type: ignore
                         )
 
                         return self._handle_agent_run_paused(
@@ -1164,6 +1234,7 @@ class Agent:
                     wait_for_open_threads(
                         memory_future=memory_future,  # type: ignore
                         cultural_knowledge_future=cultural_knowledge_future,  # type: ignore
+                        learning_future=learning_future,  # type: ignore
                     )
 
                     # 12. Create session summary
@@ -1251,6 +1322,8 @@ class Agent:
                 memory_future.cancel()
             if cultural_knowledge_future is not None and not cultural_knowledge_future.done():
                 cultural_knowledge_future.cancel()
+            if learning_future is not None and not learning_future.done():
+                learning_future.cancel()
 
             # Always disconnect connectable tools
             self._disconnect_connectable_tools()
@@ -1290,6 +1363,7 @@ class Agent:
         10. Cleanup and store the run response and session
         """
         memory_future = None
+        learning_future = None
         cultural_knowledge_future = None
 
         try:
@@ -1366,6 +1440,14 @@ class Agent:
                         existing_future=memory_future,
                     )
 
+                    # Start learning extraction as a background task (runs concurrently with the main execution)
+                    learning_future = self._start_learning_future(
+                        run_messages=run_messages,
+                        session=session,
+                        user_id=user_id,
+                        existing_future=learning_future,
+                    )
+
                     # Start cultural knowledge creation in background thread
                     cultural_knowledge_future = self._start_cultural_knowledge_future(
                         run_messages=run_messages,
@@ -1454,6 +1536,7 @@ class Agent:
                         yield from wait_for_thread_tasks_stream(
                             memory_future=memory_future,  # type: ignore
                             cultural_knowledge_future=cultural_knowledge_future,  # type: ignore
+                            learning_future=learning_future,  # type: ignore
                             stream_events=stream_events,
                             run_response=run_response,
                             events_to_skip=self.events_to_skip,
@@ -1493,6 +1576,7 @@ class Agent:
                     yield from wait_for_thread_tasks_stream(
                         memory_future=memory_future,  # type: ignore
                         cultural_knowledge_future=cultural_knowledge_future,  # type: ignore
+                        learning_future=learning_future,  # type: ignore
                         stream_events=stream_events,
                         run_response=run_response,
                     )
@@ -1643,6 +1727,8 @@ class Agent:
                 memory_future.cancel()
             if cultural_knowledge_future is not None and not cultural_knowledge_future.done():
                 cultural_knowledge_future.cancel()
+            if learning_future is not None and not learning_future.done():
+                learning_future.cancel()
 
             # Always disconnect connectable tools
             self._disconnect_connectable_tools()
@@ -1964,8 +2050,9 @@ class Agent:
         await aregister_run(run_context.run_id)
         log_debug(f"Agent Run Start: {run_response.run_id}", center=True)
 
-        cultural_knowledge_task = None
         memory_task = None
+        learning_task = None
+        cultural_knowledge_task = None
 
         # Set up retry logic
         num_attempts = self.retries + 1
@@ -2063,6 +2150,14 @@ class Agent:
                         existing_task=memory_task,
                     )
 
+                    # Start learning extraction as a background task
+                    learning_task = await self._astart_learning_task(
+                        run_messages=run_messages,
+                        session=agent_session,
+                        user_id=user_id,
+                        existing_task=learning_task,
+                    )
+
                     # Start cultural knowledge creation as a background task (runs concurrently with the main execution)
                     cultural_knowledge_task = await self._astart_cultural_knowledge_task(
                         run_messages=run_messages,
@@ -2114,7 +2209,9 @@ class Agent:
                     # We should break out of the run function
                     if any(tool_call.is_paused for tool_call in run_response.tools or []):
                         await await_for_open_threads(
-                            memory_task=memory_task, cultural_knowledge_task=cultural_knowledge_task
+                            memory_task=memory_task,
+                            cultural_knowledge_task=cultural_knowledge_task,
+                            learning_task=learning_task,
                         )
                         return await self._ahandle_agent_run_paused(
                             run_response=run_response, session=agent_session, user_id=user_id
@@ -2146,7 +2243,9 @@ class Agent:
 
                     # 14. Wait for background memory creation
                     await await_for_open_threads(
-                        memory_task=memory_task, cultural_knowledge_task=cultural_knowledge_task
+                        memory_task=memory_task,
+                        cultural_knowledge_task=cultural_knowledge_task,
+                        learning_task=learning_task,
                     )
 
                     # 15. Create session summary
@@ -2262,6 +2361,12 @@ class Agent:
                     await cultural_knowledge_task
                 except asyncio.CancelledError:
                     pass
+            if learning_task is not None and not learning_task.done():
+                learning_task.cancel()
+                try:
+                    await learning_task
+                except asyncio.CancelledError:
+                    pass
 
             # Always clean up the run tracking
             await acleanup_run(run_response.run_id)  # type: ignore
@@ -2306,6 +2411,7 @@ class Agent:
 
         memory_task = None
         cultural_knowledge_task = None
+        learning_task = None
 
         # 1. Read or create session. Reads from the database if provided.
         agent_session = await self._aread_or_create_session(session_id=session_id, user_id=user_id)
@@ -2411,6 +2517,14 @@ class Agent:
                         existing_task=memory_task,
                     )
 
+                    # Start learning extraction as a background task
+                    learning_task = await self._astart_learning_task(
+                        run_messages=run_messages,
+                        session=agent_session,
+                        user_id=user_id,
+                        existing_task=learning_task,
+                    )
+
                     # Start cultural knowledge creation as a background task (runs concurrently with the main execution)
                     cultural_knowledge_task = await self._astart_cultural_knowledge_task(
                         run_messages=run_messages,
@@ -2503,6 +2617,7 @@ class Agent:
                         async for item in await_for_thread_tasks_stream(
                             memory_task=memory_task,
                             cultural_knowledge_task=cultural_knowledge_task,
+                            learning_task=learning_task,
                             stream_events=stream_events,
                             run_response=run_response,
                         ):
@@ -2533,6 +2648,7 @@ class Agent:
                     async for item in await_for_thread_tasks_stream(
                         memory_task=memory_task,
                         cultural_knowledge_task=cultural_knowledge_task,
+                        learning_task=learning_task,
                         stream_events=stream_events,
                         run_response=run_response,
                         events_to_skip=self.events_to_skip,
@@ -2728,6 +2844,13 @@ class Agent:
                 except asyncio.CancelledError:
                     pass
 
+            if learning_task is not None and not learning_task.done():
+                learning_task.cancel()
+                try:
+                    await learning_task
+                except asyncio.CancelledError:
+                    pass
+
             # Always clean up the run tracking
             await acleanup_run(run_response.run_id)  # type: ignore
 
@@ -6252,6 +6375,93 @@ class Agent:
 
         return None
 
+    def _process_learnings(
+        self,
+        run_messages: RunMessages,
+        session: AgentSession,
+        user_id: Optional[str],
+    ) -> None:
+        """Process learnings from conversation (runs in background thread)."""
+        if self._learning is None:
+            return
+
+        try:
+            # Convert run messages to list format expected by LearningMachine
+            messages = run_messages.messages if run_messages else []
+
+            self._learning.process(
+                messages=messages,
+                user_id=user_id,
+                session_id=session.session_id if session else None,
+                agent_id=self.id,
+                team_id=self.team_id,
+            )
+            log_debug("Learning extraction completed.")
+        except Exception as e:
+            log_warning(f"Error processing learnings: {e}")
+
+    async def _astart_learning_task(
+        self,
+        run_messages: RunMessages,
+        session: AgentSession,
+        user_id: Optional[str],
+        existing_task: Optional[Task] = None,
+    ) -> Optional[Task]:
+        """Start learning extraction as async task.
+
+        Args:
+            run_messages: The run messages containing conversation.
+            session: The agent session.
+            user_id: The user ID for learning extraction.
+            existing_task: An existing task to cancel before starting a new one.
+
+        Returns:
+            A new learning task if conditions are met, None otherwise.
+        """
+        # Cancel any existing task from a previous retry attempt
+        if existing_task is not None and not existing_task.done():
+            existing_task.cancel()
+            try:
+                await existing_task
+            except CancelledError:
+                pass
+
+        # Create new task if learning is enabled
+        if self._learning is not None:
+            log_debug("Starting learning extraction as async task.")
+            return create_task(
+                self._aprocess_learnings(
+                    run_messages=run_messages,
+                    session=session,
+                    user_id=user_id,
+                )
+            )
+
+        return None
+
+    async def _aprocess_learnings(
+        self,
+        run_messages: RunMessages,
+        session: AgentSession,
+        user_id: Optional[str],
+    ) -> None:
+        """Async process learnings from conversation."""
+        if self._learning is None:
+            return
+
+        try:
+            messages = run_messages.messages if run_messages else []
+            await self._learning.aprocess(
+                messages=messages,
+                user_id=user_id,
+                session_id=session.session_id if session else None,
+                agent_id=self.id,
+                team_id=self.team_id,
+            )
+            log_debug("Learning extraction completed.")
+        except Exception as e:
+            log_warning(f"Error processing learnings: {e}")
+
     def _start_memory_future(
         self,
         run_messages: RunMessages,
@@ -6285,6 +6495,40 @@ class Agent:
 
         return None
 
+    def _start_learning_future(
+        self,
+        run_messages: RunMessages,
+        session: AgentSession,
+        user_id: Optional[str],
+        existing_future: Optional[Future] = None,
+    ) -> Optional[Future]:
+        """Start learning extraction in background thread.
+
+        Args:
+            run_messages: The run messages containing conversation.
+            session: The agent session.
+            user_id: The user ID for learning extraction.
+            existing_future: An existing future to cancel before starting a new one.
+
+        Returns:
+            A new learning future if conditions are met, None otherwise.
+        """
+        # Cancel any existing future from a previous retry attempt
+        if existing_future is not None and not existing_future.done():
+            existing_future.cancel()
+
+        # Create new future if learning is enabled
+        if self._learning is not None:
+            log_debug("Starting learning extraction in background thread.")
+            return self.background_executor.submit(
+                self._process_learnings,
+                run_messages=run_messages,
+                session=session,
+                user_id=user_id,
+            )
+
+        return None
+
     def _start_cultural_knowledge_future(
         self,
         run_messages: RunMessages,
@@ -6376,6 +6620,15 @@ class Agent:
         if self.enable_agentic_memory:
             agent_tools.append(self._get_update_user_memory_function(user_id=user_id, async_mode=False))
 
+        # Add learning machine tools
+        if self._learning is not None:
+            learning_tools = self._learning.get_tools(
+                user_id=user_id,
+                session_id=session.session_id if session else None,
+                agent_id=self.id,
+            )
+            agent_tools.extend(learning_tools)
+
         if self.enable_agentic_culture:
             agent_tools.append(self._get_update_cultural_knowledge_function(async_mode=False))
 
@@ -6485,6 +6738,18 @@ class Agent:
         if self.enable_agentic_memory:
             agent_tools.append(self._get_update_user_memory_function(user_id=user_id, async_mode=True))
 
+        # Add learning machine tools (async)
+        if self._learning is not None:
+            learning_tools = await self._learning.aget_tools(
+                user_id=user_id,
+                session_id=session.session_id if session else None,
+                agent_id=self.id,
+            )
+            agent_tools.extend(learning_tools)
+
+        if self.enable_agentic_culture:
+            agent_tools.append(self._get_update_cultural_knowledge_function(async_mode=True))
+
         if self.enable_agentic_state:
             agent_tools.append(Function(name="update_session_state", entrypoint=self._update_session_state_tool))
 
@@ -8097,12 +8362,22 @@ class Agent:
                 "You should ALWAYS prefer information from this conversation over the past summary.\n\n"
             )
 
-        # 3.3.12 Add the system message from the Model
+        # 3.3.12 then add learnings to the system prompt
+        if self._learning is not None and self.add_learnings_to_context:
+            learning_context = self._learning.build_context(
+                user_id=user_id,
+                session_id=session.session_id if session else None,
+                agent_id=self.id,
+            )
+            if learning_context:
+                system_message_content += learning_context + "\n"
+
+        # 3.3.13 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.13 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.14 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
@@ -8114,11 +8389,11 @@ class Agent:
         ):
             system_message_content += f"{get_json_output_prompt(output_schema)}"  # type: ignore
 
-        # 3.3.14 Add the response model format prompt if output_schema is provided (Pydantic only)
+        # 3.3.15 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.15 Add the session state to the system message
+        # 3.3.16 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"
 
@@ -8449,12 +8724,22 @@ class Agent:
                 "You should ALWAYS prefer information from this conversation over the past summary.\n\n"
             )
 
-        # 3.3.12 Add the system message from the Model
+        # 3.3.12 then add learnings to the system prompt
+        if self._learning is not None and self.add_learnings_to_context:
+            learning_context = await self._learning.abuild_context(
+                user_id=user_id,
+                session_id=session.session_id if session else None,
+                agent_id=self.id,
+            )
+            if learning_context:
+                system_message_content += learning_context + "\n"
+
+        # 3.3.13 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.13 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.14 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
@@ -8466,11 +8751,11 @@ class Agent:
         ):
             system_message_content += f"{get_json_output_prompt(output_schema)}"  # type: ignore
 
-        # 3.3.14 Add the response model format prompt if output_schema is provided (Pydantic only)
+        # 3.3.15 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.15 Add the session state to the system message
+        # 3.3.16 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)
 
@@ -11291,6 +11576,7 @@ class Agent:
             "has_memory": self.enable_user_memories is True
             or self.enable_agentic_memory is True
             or self.memory_manager is not None,
+            "has_learnings": self._learning is not None,
             "has_culture": self.enable_agentic_culture is True
             or self.update_cultural_knowledge is True
             or self.culture_manager is not None,