PyPI - agno - Versions diffs - 2.2.6__py3-none-any.whl → 2.2.8__py3-none-any.whl - Mend

agno 2.2.6py3-none-any.whl → 2.2.8py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

agno/agent/agent.py +430 -416
agno/api/os.py +1 -1
agno/culture/manager.py +9 -4
agno/guardrails/prompt_injection.py +1 -0
agno/knowledge/embedder/vllm.py +262 -0
agno/knowledge/knowledge.py +37 -5
agno/models/base.py +62 -54
agno/models/openai/chat.py +6 -5
agno/models/openai/responses.py +1 -58
agno/models/requesty/requesty.py +5 -2
agno/os/app.py +13 -12
agno/os/schema.py +11 -8
agno/run/__init__.py +6 -0
agno/run/base.py +18 -1
agno/run/team.py +11 -9
agno/team/team.py +258 -361
agno/tools/exa.py +21 -16
agno/tools/function.py +93 -16
agno/tools/mcp/mcp.py +8 -1
agno/tools/notion.py +14 -11
agno/utils/agent.py +78 -0
agno/utils/hooks.py +1 -1
agno/utils/models/claude.py +25 -8
agno/vectordb/redis/__init__.py +5 -0
agno/vectordb/redis/redisdb.py +687 -0
agno/workflow/agent.py +10 -9
agno/workflow/step.py +13 -2
agno/workflow/workflow.py +85 -53
{agno-2.2.6.dist-info → agno-2.2.8.dist-info}/METADATA +7 -3
{agno-2.2.6.dist-info → agno-2.2.8.dist-info}/RECORD +33 -30
{agno-2.2.6.dist-info → agno-2.2.8.dist-info}/WHEEL +0 -0
{agno-2.2.6.dist-info → agno-2.2.8.dist-info}/licenses/LICENSE +0 -0
{agno-2.2.6.dist-info → agno-2.2.8.dist-info}/top_level.txt +0 -0

agno/agent/agent.py CHANGED Viewed

@@ -49,13 +49,13 @@ from agno.models.metrics import Metrics
 from agno.models.response import ModelResponse, ModelResponseEvent, ToolExecution
 from agno.models.utils import get_model
 from agno.reasoning.step import NextAction, ReasoningStep, ReasoningSteps
+from agno.run import RunContext, RunStatus
 from agno.run.agent import (
     RunEvent,
     RunInput,
     RunOutput,
     RunOutputEvent,
 )
-from agno.run.base import RunStatus
 from agno.run.cancel import (
     cancel_run as cancel_run_global,
 )
@@ -95,7 +95,9 @@ from agno.utils.agent import (
     scrub_media_from_run_output,
     scrub_tool_results_from_run_output,
     set_session_name_util,
+    store_media_util,
     update_session_state_util,
+    validate_media_object_id,
     wait_for_background_tasks,
     wait_for_background_tasks_stream,
 )
@@ -263,9 +265,9 @@ class Agent:
     # --- Agent Hooks ---
     # Functions called right after agent-session is loaded, before processing starts
-    pre_hooks: Optional[Union[List[Callable[..., Any]], List[BaseGuardrail]]] = None
+    pre_hooks: Optional[List[Union[Callable[..., Any], BaseGuardrail]]] = None
     # Functions called after output is generated but before the response is returned
-    post_hooks: Optional[Union[List[Callable[..., Any]], List[BaseGuardrail]]] = None
+    post_hooks: Optional[List[Union[Callable[..., Any], BaseGuardrail]]] = None
     # --- Agent Reasoning ---
     # Enable reasoning by working through the problem step by step.
@@ -458,8 +460,8 @@ class Agent:
         tool_call_limit: Optional[int] = None,
         tool_choice: Optional[Union[str, Dict[str, Any]]] = None,
         tool_hooks: Optional[List[Callable]] = None,
-        pre_hooks: Optional[Union[List[Callable[..., Any]], List[BaseGuardrail]]] = None,
-        post_hooks: Optional[Union[List[Callable[..., Any]], List[BaseGuardrail]]] = None,
+        pre_hooks: Optional[List[Union[Callable[..., Any], BaseGuardrail]]] = None,
+        post_hooks: Optional[List[Union[Callable[..., Any], BaseGuardrail]]] = None,
         reasoning: bool = False,
         reasoning_model: Optional[Union[Model, str]] = None,
         reasoning_agent: Optional[Agent] = None,
@@ -913,16 +915,13 @@ class Agent:
     def _run(
         self,
         run_response: RunOutput,
+        run_context: RunContext,
         session: AgentSession,
-        session_state: Optional[Dict[str, Any]] = None,
         user_id: Optional[str] = None,
-        knowledge_filters: Optional[Dict[str, Any]] = None,
         add_history_to_context: Optional[bool] = None,
         add_dependencies_to_context: Optional[bool] = None,
         add_session_state_to_context: Optional[bool] = None,
-        metadata: Optional[Dict[str, Any]] = None,
         response_format: Optional[Union[Dict, Type[BaseModel]]] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
         debug_mode: Optional[bool] = None,
         **kwargs: Any,
     ) -> RunOutput:
@@ -956,9 +955,7 @@ class Agent:
                 hooks=self.pre_hooks,  # type: ignore
                 run_response=run_response,
                 run_input=run_input,
-                session_state=session_state,
-                dependencies=dependencies,
-                metadata=metadata,
+                run_context=run_context,
                 session=session,
                 user_id=user_id,
                 debug_mode=debug_mode,
@@ -970,36 +967,32 @@ class Agent:
         # 2. Determine tools for model
         processed_tools = self.get_tools(
             run_response=run_response,
+            run_context=run_context,
             session=session,
             user_id=user_id,
-            knowledge_filters=knowledge_filters,
         )
         _tools = self._determine_tools_for_model(
             model=self.model,
             processed_tools=processed_tools,
             run_response=run_response,
             session=session,
-            session_state=session_state,
-            dependencies=dependencies,
+            run_context=run_context,
         )
         # 3. Prepare run messages
         run_messages: RunMessages = self._get_run_messages(
             run_response=run_response,
+            run_context=run_context,
             input=run_input.input_content,
             session=session,
-            session_state=session_state,
             user_id=user_id,
             audio=run_input.audios,
             images=run_input.images,
             videos=run_input.videos,
             files=run_input.files,
-            knowledge_filters=knowledge_filters,
             add_history_to_context=add_history_to_context,
-            dependencies=dependencies,
             add_dependencies_to_context=add_dependencies_to_context,
             add_session_state_to_context=add_session_state_to_context,
-            metadata=metadata,
             tools=_tools,
             **kwargs,
         )
@@ -1074,7 +1067,7 @@ class Agent:
             # 8. Store media if enabled
             if self.store_media:
-                self._store_media(run_response, model_response)
+                store_media_util(run_response, model_response)
             # 9. Convert the response to the structured format if needed
             self._convert_response_to_structured_format(run_response)
@@ -1084,11 +1077,9 @@ class Agent:
                 post_hook_iterator = self._execute_post_hooks(
                     hooks=self.post_hooks,  # type: ignore
                     run_output=run_response,
+                    run_context=run_context,
                     session=session,
                     user_id=user_id,
-                    session_state=session_state,
-                    dependencies=dependencies,
-                    metadata=metadata,
                     debug_mode=debug_mode,
                     **kwargs,
                 )
@@ -1112,7 +1103,9 @@ class Agent:
             run_response.status = RunStatus.completed
             # 13. Cleanup and store the run response and session
-            self._cleanup_and_store(run_response=run_response, session=session, user_id=user_id)
+            self._cleanup_and_store(
+                run_response=run_response, session=session, run_context=run_context, user_id=user_id
+            )
             # Log Agent Telemetry
             self._log_agent_telemetry(session_id=session.session_id, run_id=run_response.run_id)
@@ -1127,7 +1120,9 @@ class Agent:
             run_response.status = RunStatus.cancelled
             # Cleanup and store the run response and session
-            self._cleanup_and_store(run_response=run_response, session=session, user_id=user_id)
+            self._cleanup_and_store(
+                run_response=run_response, session=session, run_context=run_context, user_id=user_id
+            )
             return run_response
         finally:
@@ -1137,15 +1132,12 @@ class Agent:
     def _run_stream(
         self,
         run_response: RunOutput,
+        run_context: RunContext,
         session: AgentSession,
-        session_state: Optional[Dict[str, Any]] = None,
         user_id: Optional[str] = None,
-        knowledge_filters: Optional[Dict[str, Any]] = None,
         add_history_to_context: Optional[bool] = None,
         add_dependencies_to_context: Optional[bool] = None,
         add_session_state_to_context: Optional[bool] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
         response_format: Optional[Union[Dict, Type[BaseModel]]] = None,
         stream_events: bool = False,
         yield_run_response: bool = False,
@@ -1179,9 +1171,7 @@ class Agent:
                 hooks=self.pre_hooks,  # type: ignore
                 run_response=run_response,
                 run_input=run_input,
-                session_state=session_state,
-                dependencies=dependencies,
-                metadata=metadata,
+                run_context=run_context,
                 session=session,
                 user_id=user_id,
                 debug_mode=debug_mode,
@@ -1193,17 +1183,16 @@ class Agent:
         # 2. Determine tools for model
         processed_tools = self.get_tools(
             run_response=run_response,
+            run_context=run_context,
             session=session,
             user_id=user_id,
-            knowledge_filters=knowledge_filters,
         )
         _tools = self._determine_tools_for_model(
             model=self.model,
             processed_tools=processed_tools,
             run_response=run_response,
             session=session,
-            session_state=session_state,
-            dependencies=dependencies,
+            run_context=run_context,
         )
         # 3. Prepare run messages
@@ -1211,18 +1200,15 @@ class Agent:
             run_response=run_response,
             input=run_input.input_content,
             session=session,
-            session_state=session_state,
+            run_context=run_context,
             user_id=user_id,
             audio=run_input.audios,
             images=run_input.images,
             videos=run_input.videos,
             files=run_input.files,
-            knowledge_filters=knowledge_filters,
             add_history_to_context=add_history_to_context,
-            dependencies=dependencies,
             add_dependencies_to_context=add_dependencies_to_context,
             add_session_state_to_context=add_session_state_to_context,
-            metadata=metadata,
             tools=_tools,
             **kwargs,
         )
@@ -1281,7 +1267,7 @@ class Agent:
                     tools=_tools,
                     response_format=response_format,
                     stream_events=stream_events,
-                    session_state=session_state,
+                    session_state=run_context.session_state,
                 ):
                     raise_if_cancelled(run_response.run_id)  # type: ignore
                     yield event
@@ -1298,7 +1284,7 @@ class Agent:
                     tools=_tools,
                     response_format=response_format,
                     stream_events=stream_events,
-                    session_state=session_state,
+                    session_state=run_context.session_state,
                 ):
                     raise_if_cancelled(run_response.run_id)  # type: ignore
                     if isinstance(event, RunContentEvent):
@@ -1318,7 +1304,7 @@ class Agent:
                     stream_events=stream_events,
                 ):
                     raise_if_cancelled(run_response.run_id)  # type: ignore
-                    yield event
+                    yield event  # type: ignore
             # Check for cancellation after model processing
             raise_if_cancelled(run_response.run_id)  # type: ignore
@@ -1359,9 +1345,7 @@ class Agent:
                 yield from self._execute_post_hooks(
                     hooks=self.post_hooks,  # type: ignore
                     run_output=run_response,
-                    session_state=session_state,
-                    dependencies=dependencies,
-                    metadata=metadata,
+                    run_context=run_context,
                     session=session,
                     user_id=user_id,
                     debug_mode=debug_mode,
@@ -1419,7 +1403,9 @@ class Agent:
             run_response.status = RunStatus.completed
             # 10. Cleanup and store the run response and session
-            self._cleanup_and_store(run_response=run_response, session=session, user_id=user_id)
+            self._cleanup_and_store(
+                run_response=run_response, session=session, run_context=run_context, user_id=user_id
+            )
             if stream_events:
                 yield completed_event  # type: ignore
@@ -1450,7 +1436,9 @@ class Agent:
             )
             # Cleanup and store the run response and session
-            self._cleanup_and_store(run_response=run_response, session=session, user_id=user_id)
+            self._cleanup_and_store(
+                run_response=run_response, session=session, run_context=run_context, user_id=user_id
+            )
         finally:
             # Always clean up the run tracking
             cleanup_run(run_response.run_id)  # type: ignore
@@ -1553,9 +1541,9 @@ class Agent:
         # Normalise hook & guardails
         if not self._hooks_normalised:
             if self.pre_hooks:
-                self.pre_hooks = normalize_hooks(self.pre_hooks)
+                self.pre_hooks = normalize_hooks(self.pre_hooks)  # type: ignore
             if self.post_hooks:
-                self.post_hooks = normalize_hooks(self.post_hooks)
+                self.post_hooks = normalize_hooks(self.post_hooks)  # type: ignore
             self._hooks_normalised = True
         session_id, user_id = self._initialize_session(session_id=session_id, user_id=user_id)
@@ -1563,7 +1551,7 @@ class Agent:
         # Initialize the Agent
         self.initialize_agent(debug_mode=debug_mode)
-        image_artifacts, video_artifacts, audio_artifacts, file_artifacts = self._validate_media_object_id(
+        image_artifacts, video_artifacts, audio_artifacts, file_artifacts = validate_media_object_id(
             images=images, videos=videos, audios=audio, files=files
         )
@@ -1586,12 +1574,22 @@ class Agent:
         )
         # Update session state from DB
         session_state = self._load_session_state(session=agent_session, session_state=session_state)
         # Determine runtime dependencies
-        run_dependencies = dependencies if dependencies is not None else self.dependencies
+        dependencies = dependencies if dependencies is not None else self.dependencies
+        # Initialize run context
+        run_context = RunContext(
+            run_id=run_id,
+            session_id=session_id,
+            user_id=user_id,
+            session_state=session_state,
+            dependencies=dependencies,
+        )
         # Resolve dependencies
-        if run_dependencies is not None:
-            self._resolve_run_dependencies(dependencies=run_dependencies)
+        if run_context.dependencies is not None:
+            self._resolve_run_dependencies(run_context=run_context)
         add_dependencies = (
             add_dependencies_to_context if add_dependencies_to_context is not None else self.add_dependencies_to_context
@@ -1603,12 +1601,9 @@ class Agent:
         )
         add_history = add_history_to_context if add_history_to_context is not None else self.add_history_to_context
-        # Initialize Knowledge Filters
-        effective_filters = knowledge_filters
         # When filters are passed manually
         if self.knowledge_filters or knowledge_filters:
-            effective_filters = self._get_effective_filters(knowledge_filters)
+            run_context.knowledge_filters = self._get_effective_filters(knowledge_filters)
         # Use stream override value when necessary
         if stream is None:
@@ -1632,11 +1627,8 @@ class Agent:
         self.model = cast(Model, self.model)
         # Merge agent metadata with run metadata
-        if self.metadata is not None:
-            if metadata is None:
-                metadata = self.metadata
-            else:
-                merge_dictionaries(metadata, self.metadata)
+        if self.metadata is not None and metadata is not None:
+            merge_dictionaries(metadata, self.metadata)
         # Create a new run_response for this attempt
         run_response = RunOutput(
@@ -1645,8 +1637,8 @@ class Agent:
             agent_id=self.id,
             user_id=user_id,
             agent_name=self.name,
-            metadata=metadata,
-            session_state=session_state,
+            metadata=run_context.metadata,
+            session_state=run_context.session_state,
             input=run_input,
         )
@@ -1668,15 +1660,12 @@ class Agent:
                 if stream:
                     response_iterator = self._run_stream(
                         run_response=run_response,
+                        run_context=run_context,
                         session=agent_session,
-                        session_state=session_state,
                         user_id=user_id,
-                        knowledge_filters=effective_filters,
                         add_history_to_context=add_history,
                         add_dependencies_to_context=add_dependencies,
                         add_session_state_to_context=add_session_state,
-                        metadata=metadata,
-                        dependencies=run_dependencies,
                         response_format=response_format,
                         stream_events=stream_events,
                         yield_run_response=yield_run_response,
@@ -1687,15 +1676,12 @@ class Agent:
                 else:
                     response = self._run(
                         run_response=run_response,
+                        run_context=run_context,
                         session=agent_session,
-                        session_state=session_state,
                         user_id=user_id,
-                        knowledge_filters=effective_filters,
                         add_history_to_context=add_history,
                         add_dependencies_to_context=add_dependencies,
                         add_session_state_to_context=add_session_state,
-                        metadata=metadata,
-                        dependencies=run_dependencies,
                         response_format=response_format,
                         debug_mode=debug_mode,
                         **kwargs,
@@ -1748,16 +1734,13 @@ class Agent:
     async def _arun(
         self,
         run_response: RunOutput,
+        run_context: RunContext,
         session_id: str,
-        session_state: Optional[Dict[str, Any]] = None,
         user_id: Optional[str] = None,
-        knowledge_filters: Optional[Dict[str, Any]] = None,
         add_history_to_context: Optional[bool] = None,
         add_dependencies_to_context: Optional[bool] = None,
         add_session_state_to_context: Optional[bool] = None,
-        metadata: Optional[Dict[str, Any]] = None,
         response_format: Optional[Union[Dict, Type[BaseModel]]] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
         debug_mode: Optional[bool] = None,
         **kwargs: Any,
     ) -> RunOutput:
@@ -1792,16 +1775,21 @@ class Agent:
         # 2. Update metadata and session state
         self._update_metadata(session=agent_session)
         # Initialize session state
-        session_state = self._initialize_session_state(
-            session_state=session_state or {}, user_id=user_id, session_id=session_id, run_id=run_response.run_id
+        run_context.session_state = self._initialize_session_state(
+            session_state=run_context.session_state or {},
+            user_id=user_id,
+            session_id=session_id,
+            run_id=run_response.run_id,
         )
         # Update session state from DB
-        if session_state is not None:
-            session_state = self._load_session_state(session=agent_session, session_state=session_state)
+        if run_context.session_state is not None:
+            run_context.session_state = self._load_session_state(
+                session=agent_session, session_state=run_context.session_state
+            )
         # 3. Resolve dependencies
-        if dependencies is not None:
-            await self._aresolve_run_dependencies(dependencies=dependencies)
+        if run_context.dependencies is not None:
+            await self._aresolve_run_dependencies(run_context=run_context)
         # 4. Execute pre-hooks
         run_input = cast(RunInput, run_response.input)
@@ -1811,10 +1799,8 @@ class Agent:
             pre_hook_iterator = self._aexecute_pre_hooks(
                 hooks=self.pre_hooks,  # type: ignore
                 run_response=run_response,
+                run_context=run_context,
                 run_input=run_input,
-                session_state=session_state,
-                dependencies=dependencies,
-                metadata=metadata,
                 session=agent_session,
                 user_id=user_id,
                 debug_mode=debug_mode,
@@ -1828,36 +1814,33 @@ class Agent:
         self.model = cast(Model, self.model)
         processed_tools = await self.aget_tools(
             run_response=run_response,
+            run_context=run_context,
             session=agent_session,
             user_id=user_id,
-            knowledge_filters=knowledge_filters,
         )
         _tools = self._determine_tools_for_model(
             model=self.model,
             processed_tools=processed_tools,
             run_response=run_response,
+            run_context=run_context,
             session=agent_session,
-            session_state=session_state,
-            dependencies=dependencies,
         )
         # 6. Prepare run messages
         run_messages: RunMessages = await self._aget_run_messages(
             run_response=run_response,
+            run_context=run_context,
             input=run_input.input_content,
             session=agent_session,
-            session_state=session_state,
             user_id=user_id,
             audio=run_input.audios,
             images=run_input.images,
             videos=run_input.videos,
             files=run_input.files,
-            knowledge_filters=knowledge_filters,
             add_history_to_context=add_history_to_context,
-            dependencies=dependencies,
             add_dependencies_to_context=add_dependencies_to_context,
             add_session_state_to_context=add_session_state_to_context,
-            metadata=metadata,
             tools=_tools,
             **kwargs,
         )
@@ -1898,6 +1881,7 @@ class Agent:
                 tool_call_limit=self.tool_call_limit,
                 response_format=response_format,
                 send_media_to_model=self.send_media_to_model,
+                run_response=run_response,
             )
             # Check for cancellation after model call
@@ -1930,16 +1914,14 @@ class Agent:
             # 12. Store media if enabled
             if self.store_media:
-                self._store_media(run_response, model_response)
+                store_media_util(run_response, model_response)
             # 13. Execute post-hooks (after output is generated but before response is returned)
             if self.post_hooks is not None:
                 async for _ in self._aexecute_post_hooks(
                     hooks=self.post_hooks,  # type: ignore
                     run_output=run_response,
-                    session_state=session_state,
-                    dependencies=dependencies,
-                    metadata=metadata,
+                    run_context=run_context,
                     session=agent_session,
                     user_id=user_id,
                     debug_mode=debug_mode,
@@ -1965,7 +1947,12 @@ class Agent:
             run_response.status = RunStatus.completed
             # 16. Cleanup and store the run response and session
-            await self._acleanup_and_store(run_response=run_response, session=agent_session, user_id=user_id)
+            await self._acleanup_and_store(
+                run_response=run_response,
+                session=agent_session,
+                run_context=run_context,
+                user_id=user_id,
+            )
             # Log Agent Telemetry
             await self._alog_agent_telemetry(session_id=agent_session.session_id, run_id=run_response.run_id)
@@ -1981,7 +1968,12 @@ class Agent:
             run_response.status = RunStatus.cancelled
             # Cleanup and store the run response and session
-            await self._acleanup_and_store(run_response=run_response, session=agent_session, user_id=user_id)
+            await self._acleanup_and_store(
+                run_response=run_response,
+                session=agent_session,
+                run_context=run_context,
+                user_id=user_id,
+            )
             return run_response
@@ -2009,15 +2001,12 @@ class Agent:
     async def _arun_stream(
         self,
         run_response: RunOutput,
+        run_context: RunContext,
         session_id: str,
-        session_state: Optional[Dict[str, Any]] = None,
         user_id: Optional[str] = None,
-        knowledge_filters: Optional[Dict[str, Any]] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
         add_history_to_context: Optional[bool] = None,
         add_dependencies_to_context: Optional[bool] = None,
         add_session_state_to_context: Optional[bool] = None,
-        metadata: Optional[Dict[str, Any]] = None,
         response_format: Optional[Union[Dict, Type[BaseModel]]] = None,
         stream_events: bool = False,
         yield_run_response: Optional[bool] = None,
@@ -2058,16 +2047,21 @@ class Agent:
         # 2. Update metadata and session state
         self._update_metadata(session=agent_session)
         # Initialize session state
-        session_state = self._initialize_session_state(
-            session_state=session_state or {}, user_id=user_id, session_id=session_id, run_id=run_response.run_id
+        run_context.session_state = self._initialize_session_state(
+            session_state=run_context.session_state or {},
+            user_id=user_id,
+            session_id=session_id,
+            run_id=run_response.run_id,
         )
         # Update session state from DB
-        if session_state is not None:
-            session_state = self._load_session_state(session=agent_session, session_state=session_state)
+        if run_context.session_state is not None:
+            run_context.session_state = self._load_session_state(
+                session=agent_session, session_state=run_context.session_state
+            )
         # 3. Resolve dependencies
-        if dependencies is not None:
-            await self._aresolve_run_dependencies(dependencies=dependencies)
+        if run_context.dependencies is not None:
+            await self._aresolve_run_dependencies(run_context=run_context)
         # 4. Execute pre-hooks
         run_input = cast(RunInput, run_response.input)
@@ -2077,11 +2071,9 @@ class Agent:
             pre_hook_iterator = self._aexecute_pre_hooks(
                 hooks=self.pre_hooks,  # type: ignore
                 run_response=run_response,
+                run_context=run_context,
                 run_input=run_input,
                 session=agent_session,
-                session_state=session_state,
-                dependencies=dependencies,
-                metadata=metadata,
                 user_id=user_id,
                 debug_mode=debug_mode,
                 **kwargs,
@@ -2093,36 +2085,33 @@ class Agent:
         self.model = cast(Model, self.model)
         processed_tools = await self.aget_tools(
             run_response=run_response,
+            run_context=run_context,
             session=agent_session,
             user_id=user_id,
-            knowledge_filters=knowledge_filters,
         )
         _tools = self._determine_tools_for_model(
             model=self.model,
             processed_tools=processed_tools,
             run_response=run_response,
+            run_context=run_context,
             session=agent_session,
-            session_state=session_state,
-            dependencies=dependencies,
         )
         # 6. Prepare run messages
         run_messages: RunMessages = await self._aget_run_messages(
             run_response=run_response,
+            run_context=run_context,
             input=run_input.input_content,
             session=agent_session,
-            session_state=session_state,
             user_id=user_id,
             audio=run_input.audios,
             images=run_input.images,
             videos=run_input.videos,
             files=run_input.files,
-            knowledge_filters=knowledge_filters,
             add_history_to_context=add_history_to_context,
-            dependencies=dependencies,
             add_dependencies_to_context=add_dependencies_to_context,
             add_session_state_to_context=add_session_state_to_context,
-            metadata=metadata,
             tools=_tools,
             **kwargs,
         )
@@ -2169,7 +2158,7 @@ class Agent:
                     tools=_tools,
                     response_format=response_format,
                     stream_events=stream_events,
-                    session_state=session_state,
+                    session_state=run_context.session_state,
                 ):
                     raise_if_cancelled(run_response.run_id)  # type: ignore
                     yield event
@@ -2186,7 +2175,7 @@ class Agent:
                     tools=_tools,
                     response_format=response_format,
                     stream_events=stream_events,
-                    session_state=session_state,
+                    session_state=run_context.session_state,
                 ):
                     raise_if_cancelled(run_response.run_id)  # type: ignore
                     if isinstance(event, RunContentEvent):
@@ -2246,9 +2235,7 @@ class Agent:
                 async for event in self._aexecute_post_hooks(
                     hooks=self.post_hooks,  # type: ignore
                     run_output=run_response,
-                    session_state=session_state,
-                    dependencies=dependencies,
-                    metadata=metadata,
+                    run_context=run_context,
                     session=agent_session,
                     user_id=user_id,
                     debug_mode=debug_mode,
@@ -2310,7 +2297,12 @@ class Agent:
             run_response.status = RunStatus.completed
             # 13. Cleanup and store the run response and session
-            await self._acleanup_and_store(run_response=run_response, session=agent_session, user_id=user_id)
+            await self._acleanup_and_store(
+                run_response=run_response,
+                session=agent_session,
+                run_context=run_context,
+                user_id=user_id,
+            )
             if stream_events:
                 yield completed_event  # type: ignore
@@ -2341,7 +2333,12 @@ class Agent:
             )
             # Cleanup and store the run response and session
-            await self._acleanup_and_store(run_response=run_response, session=agent_session, user_id=user_id)
+            await self._acleanup_and_store(
+                run_response=run_response,
+                session=agent_session,
+                run_context=run_context,
+                user_id=user_id,
+            )
         finally:
             # Always disconnect MCP tools
             await self._disconnect_mcp_tools()
@@ -2454,12 +2451,12 @@ class Agent:
         # 2. Validate input against input_schema if provided
         validated_input = self._validate_input(input)
-        # Normalise hook & guardails
+        # Normalise hooks & guardails
         if not self._hooks_normalised:
             if self.pre_hooks:
-                self.pre_hooks = normalize_hooks(self.pre_hooks, async_mode=True)
+                self.pre_hooks = normalize_hooks(self.pre_hooks, async_mode=True)  # type: ignore
             if self.post_hooks:
-                self.post_hooks = normalize_hooks(self.post_hooks, async_mode=True)
+                self.post_hooks = normalize_hooks(self.post_hooks, async_mode=True)  # type: ignore
             self._hooks_normalised = True
         # Initialize session
@@ -2468,12 +2465,12 @@ class Agent:
         # Initialize the Agent
         self.initialize_agent(debug_mode=debug_mode)
-        image_artifacts, video_artifacts, audio_artifacts, file_artifacts = self._validate_media_object_id(
+        image_artifacts, video_artifacts, audio_artifacts, file_artifacts = validate_media_object_id(
             images=images, videos=videos, audios=audio, files=files
         )
         # Resolve variables
-        run_dependencies = dependencies if dependencies is not None else self.dependencies
+        dependencies = dependencies if dependencies is not None else self.dependencies
         add_dependencies = (
             add_dependencies_to_context if add_dependencies_to_context is not None else self.add_dependencies_to_context
         )
@@ -2515,9 +2512,9 @@ class Agent:
         self.model = cast(Model, self.model)
         # Get knowledge filters
-        effective_filters = knowledge_filters
+        knowledge_filters = knowledge_filters
         if self.knowledge_filters or knowledge_filters:
-            effective_filters = self._get_effective_filters(knowledge_filters)
+            knowledge_filters = self._get_effective_filters(knowledge_filters)
         # Merge agent metadata with run metadata
         if self.metadata is not None:
@@ -2526,6 +2523,17 @@ class Agent:
             else:
                 merge_dictionaries(metadata, self.metadata)
+        # Initialize run context
+        run_context = RunContext(
+            run_id=run_id,
+            session_id=session_id,
+            user_id=user_id,
+            session_state=session_state,
+            dependencies=dependencies,
+            knowledge_filters=knowledge_filters,
+            metadata=metadata,
+        )
         # If no retries are set, use the agent's default retries
         retries = retries if retries is not None else self.retries
@@ -2536,8 +2544,8 @@ class Agent:
             agent_id=self.id,
             user_id=user_id,
             agent_name=self.name,
-            metadata=metadata,
-            session_state=session_state,
+            metadata=run_context.metadata,
+            session_state=run_context.session_state,
             input=run_input,
         )
@@ -2557,34 +2565,28 @@ class Agent:
                 if stream:
                     return self._arun_stream(  # type: ignore
                         run_response=run_response,
+                        run_context=run_context,
                         user_id=user_id,
                         response_format=response_format,
                         stream_events=stream_events,
                         yield_run_response=yield_run_response,
-                        dependencies=run_dependencies,
                         session_id=session_id,
-                        session_state=session_state,
-                        knowledge_filters=effective_filters,
                         add_history_to_context=add_history,
                         add_dependencies_to_context=add_dependencies,
                         add_session_state_to_context=add_session_state,
-                        metadata=metadata,
                         debug_mode=debug_mode,
                         **kwargs,
                     )  # type: ignore[assignment]
                 else:
                     return self._arun(  # type: ignore
                         run_response=run_response,
+                        run_context=run_context,
                         user_id=user_id,
                         response_format=response_format,
-                        dependencies=run_dependencies,
                         session_id=session_id,
-                        session_state=session_state,
-                        knowledge_filters=effective_filters,
                         add_history_to_context=add_history,
                         add_dependencies_to_context=add_dependencies,
                         add_session_state_to_context=add_session_state,
-                        metadata=metadata,
                         debug_mode=debug_mode,
                         **kwargs,
                     )
@@ -2675,7 +2677,7 @@ class Agent:
         self,
         run_response: Optional[RunOutput] = None,
         *,
-        run_id: Optional[str] = None,
+        run_id: Optional[str] = None,  # type: ignore
         updated_tools: Optional[List[ToolExecution]] = None,
         stream: Optional[bool] = None,
         stream_events: Optional[bool] = False,
@@ -2716,6 +2718,7 @@ class Agent:
             raise Exception("continue_run() is not supported with an async DB. Please use acontinue_arun() instead.")
         session_id = run_response.session_id if run_response else session_id
+        run_id: str = run_response.run_id if run_response else run_id  # type: ignore
         session_id, user_id = self._initialize_session(
             session_id=session_id,
@@ -2735,24 +2738,32 @@ class Agent:
         # Update session state from DB
         session_state = self._load_session_state(session=agent_session, session_state=session_state)
-        run_dependencies = dependencies if dependencies is not None else self.dependencies
+        dependencies = dependencies if dependencies is not None else self.dependencies
-        # Resolve dependencies
-        if run_dependencies is not None:
-            self._resolve_run_dependencies(dependencies=run_dependencies)
+        # Initialize run context
+        run_context = RunContext(
+            run_id=run_id,  # type: ignore
+            session_id=session_id,
+            user_id=user_id,
+            session_state=session_state,
+            dependencies=dependencies,
+        )
-        effective_filters = knowledge_filters
+        # Resolve dependencies
+        if run_context.dependencies is not None:
+            self._resolve_run_dependencies(run_context=run_context)
         # When filters are passed manually
-        if self.knowledge_filters or knowledge_filters:
-            effective_filters = self._get_effective_filters(knowledge_filters)
+        if self.knowledge_filters or run_context.knowledge_filters or knowledge_filters:
+            run_context.knowledge_filters = self._get_effective_filters(knowledge_filters)
         # Merge agent metadata with run metadata
+        run_context.metadata = metadata
         if self.metadata is not None:
-            if metadata is None:
-                metadata = self.metadata
+            if run_context.metadata is None:
+                run_context.metadata = self.metadata
             else:
-                merge_dictionaries(metadata, self.metadata)
+                merge_dictionaries(run_context.metadata, self.metadata)
         # If no retries are set, use the agent's default retries
         retries = retries if retries is not None else self.retries
@@ -2803,17 +2814,17 @@ class Agent:
         processed_tools = self.get_tools(
             run_response=run_response,
+            run_context=run_context,
             session=agent_session,
             user_id=user_id,
-            knowledge_filters=effective_filters,
         )
         _tools = self._determine_tools_for_model(
             model=self.model,
             processed_tools=processed_tools,
             run_response=run_response,
+            run_context=run_context,
             session=agent_session,
-            session_state=session_state,
-            dependencies=run_dependencies,
         )
         last_exception = None
@@ -2836,12 +2847,10 @@ class Agent:
                     response_iterator = self._continue_run_stream(
                         run_response=run_response,
                         run_messages=run_messages,
+                        run_context=run_context,
                         tools=_tools,
                         user_id=user_id,
                         session=agent_session,
-                        session_state=session_state,
-                        dependencies=run_dependencies,
-                        metadata=metadata,
                         response_format=response_format,
                         stream_events=stream_events,
                         debug_mode=debug_mode,
@@ -2852,12 +2861,10 @@ class Agent:
                     response = self._continue_run(
                         run_response=run_response,
                         run_messages=run_messages,
+                        run_context=run_context,
                         tools=_tools,
                         user_id=user_id,
                         session=agent_session,
-                        session_state=session_state,
-                        dependencies=run_dependencies,
-                        metadata=metadata,
                         response_format=response_format,
                         debug_mode=debug_mode,
                         **kwargs,
@@ -2904,11 +2911,9 @@ class Agent:
         self,
         run_response: RunOutput,
         run_messages: RunMessages,
+        run_context: RunContext,
         session: AgentSession,
         tools: List[Union[Function, dict]],
-        session_state: Optional[Dict[str, Any]] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
         user_id: Optional[str] = None,
         response_format: Optional[Union[Dict, Type[BaseModel]]] = None,
         debug_mode: Optional[bool] = None,
@@ -2965,18 +2970,16 @@ class Agent:
             # 5. Store media if enabled
             if self.store_media:
-                self._store_media(run_response, model_response)
+                store_media_util(run_response, model_response)
             # 6. Execute post-hooks
             if self.post_hooks is not None:
                 post_hook_iterator = self._execute_post_hooks(
                     hooks=self.post_hooks,  # type: ignore
                     run_output=run_response,
+                    run_context=run_context,
                     session=session,
                     user_id=user_id,
-                    session_state=session_state,
-                    dependencies=dependencies,
-                    metadata=metadata,
                     debug_mode=debug_mode,
                     **kwargs,
                 )
@@ -2998,7 +3001,9 @@ class Agent:
             run_response.status = RunStatus.completed
             # 8. Cleanup and store the run response and session
-            self._cleanup_and_store(run_response=run_response, session=session, user_id=user_id)
+            self._cleanup_and_store(
+                run_response=run_response, session=session, run_context=run_context, user_id=user_id
+            )
             # Log Agent Telemetry
             self._log_agent_telemetry(session_id=session.session_id, run_id=run_response.run_id)
@@ -3011,7 +3016,9 @@ class Agent:
             run_response.content = str(e)
             # Cleanup and store the run response and session
-            self._cleanup_and_store(run_response=run_response, session=session, user_id=user_id)
+            self._cleanup_and_store(
+                run_response=run_response, session=session, run_context=run_context, user_id=user_id
+            )
             return run_response
         finally:
@@ -3022,14 +3029,12 @@ class Agent:
         self,
         run_response: RunOutput,
         run_messages: RunMessages,
+        run_context: RunContext,
         session: AgentSession,
         tools: List[Union[Function, dict]],
-        session_state: Optional[Dict[str, Any]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
         user_id: Optional[str] = None,
         response_format: Optional[Union[Dict, Type[BaseModel]]] = None,
         stream_events: bool = False,
-        dependencies: Optional[Dict[str, Any]] = None,
         debug_mode: Optional[bool] = None,
         **kwargs,
     ) -> Iterator[RunOutputEvent]:
@@ -3045,8 +3050,8 @@ class Agent:
         """
         # 1. Resolve dependencies
-        if dependencies is not None:
-            self._resolve_run_dependencies(dependencies=dependencies)
+        if run_context.dependencies is not None:
+            self._resolve_run_dependencies(run_context=run_context)
         # Start the Run by yielding a RunContinued event
         if stream_events:
@@ -3071,7 +3076,7 @@ class Agent:
                 tools=tools,
                 response_format=response_format,
                 stream_events=stream_events,
-                session_state=session_state,
+                session_state=run_context.session_state,
             ):
                 yield event
@@ -3102,9 +3107,7 @@ class Agent:
                     hooks=self.post_hooks,  # type: ignore
                     run_output=run_response,
                     session=session,
-                    session_state=session_state,
-                    dependencies=dependencies,
-                    metadata=metadata,
+                    run_context=run_context,
                     user_id=user_id,
                     debug_mode=debug_mode,
                     **kwargs,
@@ -3157,7 +3160,9 @@ class Agent:
             run_response.status = RunStatus.completed
             # 5. Cleanup and store the run response and session
-            self._cleanup_and_store(run_response=run_response, session=session, user_id=user_id)
+            self._cleanup_and_store(
+                run_response=run_response, session=session, run_context=run_context, user_id=user_id
+            )
             if stream_events:
                 yield completed_event  # type: ignore
@@ -3182,7 +3187,9 @@ class Agent:
             )
             # Cleanup and store the run response and session
-            self._cleanup_and_store(run_response=run_response, session=session, user_id=user_id)
+            self._cleanup_and_store(
+                run_response=run_response, session=session, run_context=run_context, user_id=user_id
+            )
         finally:
             # Always clean up the run tracking
             cleanup_run(run_response.run_id)  # type: ignore
@@ -3229,7 +3236,7 @@ class Agent:
         self,
         run_response: Optional[RunOutput] = None,
         *,
-        run_id: Optional[str] = None,
+        run_id: Optional[str] = None,  # type: ignore
         updated_tools: Optional[List[ToolExecution]] = None,
         stream: Optional[bool] = None,
         stream_events: Optional[bool] = None,
@@ -3272,11 +3279,12 @@ class Agent:
             session_id=session_id,
             user_id=user_id,
         )
+        run_id: str = run_id or run_response.run_id if run_response else run_id  # type: ignore
         # Initialize the Agent
         self.initialize_agent(debug_mode=debug_mode)
-        run_dependencies = dependencies if dependencies is not None else self.dependencies
+        dependencies = dependencies if dependencies is not None else self.dependencies
         # If no retries are set, use the agent's default retries
         retries = retries if retries is not None else self.retries
@@ -3303,9 +3311,9 @@ class Agent:
         self.stream_events = self.stream_events or stream_events
         # Get knowledge filters
-        effective_filters = knowledge_filters
+        knowledge_filters = knowledge_filters
         if self.knowledge_filters or knowledge_filters:
-            effective_filters = self._get_effective_filters(knowledge_filters)
+            knowledge_filters = self._get_effective_filters(knowledge_filters)
         # Merge agent metadata with run metadata
         if self.metadata is not None:
@@ -3318,6 +3326,17 @@ class Agent:
         response_format = self._get_response_format()
         self.model = cast(Model, self.model)
+        # Initialize run context
+        run_context = RunContext(
+            run_id=run_id,  # type: ignore
+            session_id=session_id,
+            user_id=user_id,
+            session_state={},
+            dependencies=dependencies,
+            knowledge_filters=knowledge_filters,
+            metadata=metadata,
+        )
         last_exception = None
         num_attempts = retries + 1
         for attempt in range(num_attempts):
@@ -3325,15 +3344,13 @@ class Agent:
                 if stream:
                     return self._acontinue_run_stream(
                         run_response=run_response,
+                        run_context=run_context,
                         updated_tools=updated_tools,
-                        knowledge_filters=effective_filters,
                         run_id=run_id,
                         user_id=user_id,
                         session_id=session_id,
                         response_format=response_format,
-                        dependencies=run_dependencies,
                         stream_events=stream_events,
-                        metadata=metadata,
                         yield_run_response=yield_run_response,
                         debug_mode=debug_mode,
                         **kwargs,
@@ -3342,13 +3359,11 @@ class Agent:
                     return self._acontinue_run(  # type: ignore
                         session_id=session_id,
                         run_response=run_response,
+                        run_context=run_context,
                         updated_tools=updated_tools,
-                        knowledge_filters=effective_filters,
                         run_id=run_id,
                         user_id=user_id,
                         response_format=response_format,
-                        dependencies=run_dependencies,
-                        metadata=metadata,
                         debug_mode=debug_mode,
                         **kwargs,
                     )
@@ -3392,14 +3407,12 @@ class Agent:
     async def _acontinue_run(
         self,
         session_id: str,
+        run_context: RunContext,
         run_response: Optional[RunOutput] = None,
         updated_tools: Optional[List[ToolExecution]] = None,
-        knowledge_filters: Optional[Dict[str, Any]] = None,
         run_id: Optional[str] = None,
         user_id: Optional[str] = None,
         response_format: Optional[Union[Dict, Type[BaseModel]]] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
         debug_mode: Optional[bool] = None,
         **kwargs,
     ) -> RunOutput:
@@ -3427,18 +3440,20 @@ class Agent:
         agent_session = await self._aread_or_create_session(session_id=session_id, user_id=user_id)
         # 2. Resolve dependencies
-        if dependencies is not None:
-            await self._aresolve_run_dependencies(dependencies=dependencies)
+        if run_context.dependencies is not None:
+            await self._aresolve_run_dependencies(run_context=run_context)
         # 3. Update metadata and session state
         self._update_metadata(session=agent_session)
         # Initialize session state
-        session_state = self._initialize_session_state(
+        run_context.session_state = self._initialize_session_state(
             session_state={}, user_id=user_id, session_id=session_id, run_id=run_id
         )
         # Update session state from DB
-        if session_state is not None:
-            session_state = self._load_session_state(session=agent_session, session_state=session_state)
+        if run_context.session_state is not None:
+            run_context.session_state = self._load_session_state(
+                session=agent_session, session_state=run_context.session_state
+            )
         # 4. Prepare run response
         if run_response is not None:
@@ -3465,17 +3480,17 @@ class Agent:
         self.model = cast(Model, self.model)
         processed_tools = await self.aget_tools(
             run_response=run_response,
+            run_context=run_context,
             session=agent_session,
             user_id=user_id,
-            knowledge_filters=knowledge_filters,
         )
         _tools = self._determine_tools_for_model(
             model=self.model,
             processed_tools=processed_tools,
             run_response=run_response,
+            run_context=run_context,
             session=agent_session,
-            session_state=session_state,
-            dependencies=dependencies,
         )
         # 6. Prepare run messages
@@ -3525,7 +3540,7 @@ class Agent:
             # 11. Store media if enabled
             if self.store_media:
-                self._store_media(run_response, model_response)
+                store_media_util(run_response, model_response)
             raise_if_cancelled(run_response.run_id)  # type: ignore
@@ -3534,12 +3549,10 @@ class Agent:
                 async for _ in self._aexecute_post_hooks(
                     hooks=self.post_hooks,  # type: ignore
                     run_output=run_response,
+                    run_context=run_context,
                     session=agent_session,
                     user_id=user_id,
                     debug_mode=debug_mode,
-                    session_state=session_state,
-                    dependencies=dependencies,
-                    metadata=metadata,
                     **kwargs,
                 ):
                     pass
@@ -3561,7 +3574,12 @@ class Agent:
             run_response.status = RunStatus.completed
             # 14. Cleanup and store the run response and session
-            await self._acleanup_and_store(run_response=run_response, session=agent_session, user_id=user_id)
+            await self._acleanup_and_store(
+                run_response=run_response,
+                session=agent_session,
+                run_context=run_context,
+                user_id=user_id,
+            )
             # Log Agent Telemetry
             await self._alog_agent_telemetry(session_id=agent_session.session_id, run_id=run_response.run_id)
@@ -3577,7 +3595,12 @@ class Agent:
             run_response.status = RunStatus.cancelled
             # Cleanup and store the run response and session
-            await self._acleanup_and_store(run_response=run_response, session=agent_session, user_id=user_id)
+            await self._acleanup_and_store(
+                run_response=run_response,
+                session=agent_session,
+                run_context=run_context,
+                user_id=user_id,
+            )
             return run_response
         finally:
@@ -3590,16 +3613,14 @@ class Agent:
     async def _acontinue_run_stream(
         self,
         session_id: str,
+        run_context: RunContext,
         run_response: Optional[RunOutput] = None,
         updated_tools: Optional[List[ToolExecution]] = None,
-        knowledge_filters: Optional[Dict[str, Any]] = None,
         run_id: Optional[str] = None,
         user_id: Optional[str] = None,
         response_format: Optional[Union[Dict, Type[BaseModel]]] = None,
         stream_events: bool = False,
         yield_run_response: Optional[bool] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
         debug_mode: Optional[bool] = None,
         **kwargs,
     ) -> AsyncIterator[Union[RunOutputEvent, RunOutput]]:
@@ -3621,8 +3642,8 @@ class Agent:
         log_debug(f"Agent Run Continue: {run_response.run_id if run_response else run_id}", center=True)  # type: ignore
         # 1. Resolve dependencies
-        if dependencies is not None:
-            await self._aresolve_run_dependencies(dependencies=dependencies)
+        if run_context.dependencies is not None:
+            await self._aresolve_run_dependencies(run_context=run_context)
         # 2. Read existing session from db
         agent_session = await self._aread_or_create_session(session_id=session_id, user_id=user_id)
@@ -3630,12 +3651,14 @@ class Agent:
         # 3. Update session state and metadata
         self._update_metadata(session=agent_session)
         # Initialize session state
-        session_state = self._initialize_session_state(
+        run_context.session_state = self._initialize_session_state(
             session_state={}, user_id=user_id, session_id=session_id, run_id=run_id
         )
         # Update session state from DB
-        if session_state is not None:
-            session_state = self._load_session_state(session=agent_session, session_state=session_state)
+        if run_context.session_state is not None:
+            run_context.session_state = self._load_session_state(
+                session=agent_session, session_state=run_context.session_state
+            )
         # 4. Prepare run response
         if run_response is not None:
@@ -3662,17 +3685,17 @@ class Agent:
         self.model = cast(Model, self.model)
         processed_tools = await self.aget_tools(
             run_response=run_response,
+            run_context=run_context,
             session=agent_session,
             user_id=user_id,
-            knowledge_filters=knowledge_filters,
         )
         _tools = self._determine_tools_for_model(
             model=self.model,
             processed_tools=processed_tools,
             run_response=run_response,
+            run_context=run_context,
             session=agent_session,
-            session_state=session_state,
-            dependencies=dependencies,
         )
         # 6. Prepare run messages
@@ -3777,11 +3800,9 @@ class Agent:
                 async for event in self._aexecute_post_hooks(
                     hooks=self.post_hooks,  # type: ignore
                     run_output=run_response,
+                    run_context=run_context,
                     session=agent_session,
                     user_id=user_id,
-                    session_state=session_state,
-                    dependencies=dependencies,
-                    metadata=metadata,
                     debug_mode=debug_mode,
                     **kwargs,
                 ):
@@ -3832,7 +3853,9 @@ class Agent:
             run_response.status = RunStatus.completed
             # 10. Cleanup and store the run response and session
-            await self._acleanup_and_store(run_response=run_response, session=agent_session, user_id=user_id)
+            await self._acleanup_and_store(
+                run_response=run_response, session=agent_session, run_context=run_context, user_id=user_id
+            )
             if stream_events:
                 yield completed_event  # type: ignore
@@ -3859,7 +3882,12 @@ class Agent:
             )
             # Cleanup and store the run response and session
-            await self._acleanup_and_store(run_response=run_response, session=agent_session, user_id=user_id)
+            await self._acleanup_and_store(
+                run_response=run_response,
+                session=agent_session,
+                run_context=run_context,
+                user_id=user_id,
+            )
         finally:
             # Always disconnect MCP tools
             await self._disconnect_mcp_tools()
@@ -3873,9 +3901,7 @@ class Agent:
         run_response: RunOutput,
         run_input: RunInput,
         session: AgentSession,
-        session_state: Optional[Dict[str, Any]] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
+        run_context: RunContext,
         user_id: Optional[str] = None,
         debug_mode: Optional[bool] = None,
         **kwargs: Any,
@@ -3887,11 +3913,12 @@ class Agent:
         # Prepare all possible arguments once
         all_args = {
             "run_input": run_input,
+            "run_context": run_context,
             "agent": self,
             "session": session,
-            "session_state": session_state,
-            "dependencies": dependencies,
-            "metadata": metadata,
+            "session_state": run_context.session_state,
+            "dependencies": run_context.dependencies,
+            "metadata": run_context.metadata,
             "user_id": user_id,
             "debug_mode": debug_mode or self.debug_mode,
         }
@@ -3942,10 +3969,8 @@ class Agent:
         hooks: Optional[List[Callable[..., Any]]],
         run_response: RunOutput,
         run_input: RunInput,
+        run_context: RunContext,
         session: AgentSession,
-        session_state: Optional[Dict[str, Any]] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
         user_id: Optional[str] = None,
         debug_mode: Optional[bool] = None,
         **kwargs: Any,
@@ -3959,9 +3984,10 @@ class Agent:
             "run_input": run_input,
             "agent": self,
             "session": session,
-            "session_state": session_state,
-            "dependencies": dependencies,
-            "metadata": metadata,
+            "run_context": run_context,
+            "session_state": run_context.session_state,
+            "dependencies": run_context.dependencies,
+            "metadata": run_context.metadata,
             "user_id": user_id,
             "debug_mode": debug_mode or self.debug_mode,
         }
@@ -4016,9 +4042,7 @@ class Agent:
         hooks: Optional[List[Callable[..., Any]]],
         run_output: RunOutput,
         session: AgentSession,
-        session_state: Optional[Dict[str, Any]] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
+        run_context: RunContext,
         user_id: Optional[str] = None,
         debug_mode: Optional[bool] = None,
         **kwargs: Any,
@@ -4032,10 +4056,11 @@ class Agent:
             "run_output": run_output,
             "agent": self,
             "session": session,
+            "session_state": run_context.session_state,
+            "dependencies": run_context.dependencies,
+            "metadata": run_context.metadata,
             "user_id": user_id,
-            "session_state": session_state,
-            "dependencies": dependencies,
-            "metadata": metadata,
+            "run_context": run_context,
             "debug_mode": debug_mode or self.debug_mode,
         }
         all_args.update(kwargs)
@@ -4078,10 +4103,8 @@ class Agent:
         self,
         hooks: Optional[List[Callable[..., Any]]],
         run_output: RunOutput,
+        run_context: RunContext,
         session: AgentSession,
-        session_state: Optional[Dict[str, Any]] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
         user_id: Optional[str] = None,
         debug_mode: Optional[bool] = None,
         **kwargs: Any,
@@ -4095,10 +4118,11 @@ class Agent:
             "run_output": run_output,
             "agent": self,
             "session": session,
+            "run_context": run_context,
+            "session_state": run_context.session_state,
+            "dependencies": run_context.dependencies,
+            "metadata": run_context.metadata,
             "user_id": user_id,
-            "session_state": session_state,
-            "dependencies": dependencies,
-            "metadata": metadata,
             "debug_mode": debug_mode or self.debug_mode,
         }
         all_args.update(kwargs)
@@ -4587,25 +4611,6 @@ class Agent:
                 _t.requires_user_input = False
                 _t.answered = True
-    def _store_media(self, run_response: RunOutput, model_response: ModelResponse):
-        """Store media from model response in run_response for persistence"""
-        # Handle generated media fields from ModelResponse (generated media)
-        if model_response.images is not None:
-            for image in model_response.images:
-                self._add_image(image, run_response)  # Generated images go to run_response.images
-        if model_response.videos is not None:
-            for video in model_response.videos:
-                self._add_video(video, run_response)  # Generated videos go to run_response.videos
-        if model_response.audios is not None:
-            for audio in model_response.audios:
-                self._add_audio(audio, run_response)  # Generated audio go to run_response.audio
-        if model_response.files is not None:
-            for file in model_response.files:
-                self._add_file(file, run_response)  # Generated files go to run_response.files
     def _update_run_response(
         self,
         model_response: ModelResponse,
@@ -5030,7 +5035,9 @@ class Agent:
                     # Store media in run_response if store_media is enabled
                     if self.store_media:
                         for image in model_response_event.images:
-                            self._add_image(image, run_response)
+                            if run_response.images is None:
+                                run_response.images = []
+                            run_response.images.append(image)
             # Handle tool interruption events
             elif model_response_event.event == ModelResponseEvent.tool_call_paused.value:
@@ -5079,15 +5086,27 @@ class Agent:
                 if model_response_event.images is not None:
                     for image in model_response_event.images:
-                        self._add_image(image, run_response)
+                        if run_response.images is None:
+                            run_response.images = []
+                        run_response.images.append(image)
                 if model_response_event.videos is not None:
                     for video in model_response_event.videos:
-                        self._add_video(video, run_response)
+                        if run_response.videos is None:
+                            run_response.videos = []
+                        run_response.videos.append(video)
                 if model_response_event.audios is not None:
                     for audio in model_response_event.audios:
-                        self._add_audio(audio, run_response)
+                        if run_response.audio is None:
+                            run_response.audio = []
+                        run_response.audio.append(audio)
+                if model_response_event.files is not None:
+                    for file_obj in model_response_event.files:
+                        if run_response.files is None:
+                            run_response.files = []
+                        run_response.files.append(file_obj)
                 reasoning_step: Optional[ReasoningStep] = None
@@ -5304,12 +5323,16 @@ class Agent:
     def get_tools(
         self,
         run_response: RunOutput,
+        run_context: RunContext,
         session: AgentSession,
         user_id: Optional[str] = None,
         knowledge_filters: Optional[Dict[str, Any]] = None,
     ) -> List[Union[Toolkit, Callable, Function, Dict]]:
         agent_tools: List[Union[Toolkit, Callable, Function, Dict]] = []
+        # Consider both run_context.knowledge_filters and knowledge_filters (deprecated)
+        run_context.knowledge_filters = run_context.knowledge_filters or knowledge_filters
         # Add provided tools
         if self.tools is not None:
             # If not running in async mode, raise if any tool is async
@@ -5355,7 +5378,7 @@ class Agent:
                         self._search_knowledge_base_with_agentic_filters_function(
                             run_response=run_response,
                             async_mode=False,
-                            knowledge_filters=knowledge_filters,
+                            knowledge_filters=run_context.knowledge_filters,
                         )
                     )
                 else:
@@ -5363,7 +5386,7 @@ class Agent:
                         self._get_search_knowledge_base_function(
                             run_response=run_response,
                             async_mode=False,
-                            knowledge_filters=knowledge_filters,
+                            knowledge_filters=run_context.knowledge_filters,
                         )
                     )
@@ -5375,6 +5398,7 @@ class Agent:
     async def aget_tools(
         self,
         run_response: RunOutput,
+        run_context: RunContext,
         session: AgentSession,
         user_id: Optional[str] = None,
         knowledge_filters: Optional[Dict[str, Any]] = None,
@@ -5382,6 +5406,9 @@ class Agent:
     ) -> List[Union[Toolkit, Callable, Function, Dict]]:
         agent_tools: List[Union[Toolkit, Callable, Function, Dict]] = []
+        # Consider both run_context.knowledge_filters and knowledge_filters (deprecated)
+        run_context.knowledge_filters = run_context.knowledge_filters or knowledge_filters
         # Connect MCP tools
         await self._connect_mcp_tools()
@@ -5439,7 +5466,7 @@ class Agent:
                         self._search_knowledge_base_with_agentic_filters_function(
                             run_response=run_response,
                             async_mode=True,
-                            knowledge_filters=knowledge_filters,
+                            knowledge_filters=run_context.knowledge_filters,
                         )
                     )
                 else:
@@ -5447,7 +5474,7 @@ class Agent:
                         self._get_search_knowledge_base_function(
                             run_response=run_response,
                             async_mode=True,
-                            knowledge_filters=knowledge_filters,
+                            knowledge_filters=run_context.knowledge_filters,
                         )
                     )
@@ -5461,9 +5488,8 @@ class Agent:
         model: Model,
         processed_tools: List[Union[Toolkit, Callable, Function, Dict]],
         run_response: RunOutput,
+        run_context: RunContext,
         session: AgentSession,
-        session_state: Optional[Dict[str, Any]] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
     ) -> List[Union[Function, dict]]:
         _function_names = []
         _functions: List[Union[Function, dict]] = []
@@ -5568,8 +5594,9 @@ class Agent:
             for func in _functions:  # type: ignore
                 if isinstance(func, Function):
-                    func._session_state = session_state
-                    func._dependencies = dependencies
+                    func._run_context = run_context
+                    func._session_state = run_context.session_state
+                    func._dependencies = run_context.dependencies
                     func._images = joint_images
                     func._files = joint_files
                     func._audios = joint_audios
@@ -5619,49 +5646,70 @@ class Agent:
                 log_debug("Model does not support structured or JSON schema outputs.")
                 return json_response_format
-    def _resolve_run_dependencies(self, dependencies: Dict[str, Any]) -> None:
+    def _resolve_run_dependencies(self, run_context: RunContext) -> None:
         from inspect import iscoroutine, iscoroutinefunction, signature
         # Dependencies should already be resolved in run() method
         log_debug("Resolving dependencies")
-        if not isinstance(dependencies, dict):
-            log_warning("Dependencies is not a dict")
+        if not isinstance(run_context.dependencies, dict):
+            log_warning("Run dependencies are not a dict")
             return
-        for key, value in dependencies.items():
+        for key, value in run_context.dependencies.items():
             if iscoroutine(value) or iscoroutinefunction(value):
                 log_warning(f"Dependency {key} is a coroutine. Use agent.arun() or agent.aprint_response() instead.")
                 continue
             elif callable(value):
                 try:
                     sig = signature(value)
-                    result = value(agent=self) if "agent" in sig.parameters else value()
+                    # Build kwargs for the function
+                    kwargs: Dict[str, Any] = {}
+                    if "agent" in sig.parameters:
+                        kwargs["agent"] = self
+                    if "run_context" in sig.parameters:
+                        kwargs["run_context"] = run_context
+                    # Run the function
+                    result = value(**kwargs)
+                    # Carry the result in the run context
                     if result is not None:
-                        dependencies[key] = result
+                        run_context.dependencies[key] = result
                 except Exception as e:
                     log_warning(f"Failed to resolve dependencies for '{key}': {e}")
             else:
-                dependencies[key] = value
+                run_context.dependencies[key] = value
-    async def _aresolve_run_dependencies(self, dependencies: Dict[str, Any]) -> None:
+    async def _aresolve_run_dependencies(self, run_context: RunContext) -> None:
         from inspect import iscoroutine, iscoroutinefunction, signature
         log_debug("Resolving context (async)")
-        if not isinstance(dependencies, dict):
-            log_warning("Context is not a dict")
+        if not isinstance(run_context.dependencies, dict):
+            log_warning("Run dependencies are not a dict")
             return
-        for key, value in dependencies.items():
+        for key, value in run_context.dependencies.items():
             if not callable(value):
-                dependencies[key] = value
+                run_context.dependencies[key] = value
                 continue
             try:
                 sig = signature(value)
-                result = value(agent=self) if "agent" in sig.parameters else value()
+                # Build kwargs for the function
+                kwargs: Dict[str, Any] = {}
+                if "agent" in sig.parameters:
+                    kwargs["agent"] = self
+                if "run_context" in sig.parameters:
+                    kwargs["run_context"] = run_context
+                # Run the function
+                result = value(**kwargs)
                 if iscoroutine(result) or iscoroutinefunction(result):
-                    result = await result
-                dependencies[key] = result
+                    result = await result  # type: ignore
+                run_context.dependencies[key] = result
             except Exception as e:
                 log_warning(f"Failed to resolve context for '{key}': {e}")
@@ -6530,10 +6578,10 @@ class Agent:
     def _format_message_with_state_variables(
         self,
         message: Any,
-        user_id: Optional[str] = None,
         session_state: Optional[Dict[str, Any]] = None,
         dependencies: Optional[Dict[str, Any]] = None,
         metadata: Optional[Dict[str, Any]] = None,
+        user_id: Optional[str] = None,
     ) -> Any:
         """Format a message with the session state variables."""
         import re
@@ -6550,6 +6598,7 @@ class Agent:
             metadata or {},
             {"user_id": user_id} if user_id is not None else {},
         )
         converted_msg = deepcopy(message)
         for var_name in format_variables.keys():
             # Only convert standalone {var_name} patterns, not nested ones
@@ -6569,12 +6618,13 @@ class Agent:
     def get_system_message(
         self,
         session: AgentSession,
-        session_state: Optional[Dict[str, Any]] = None,
+        run_context: Optional[RunContext] = None,
         user_id: Optional[str] = None,
         tools: Optional[List[Union[Function, dict]]] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
         add_session_state_to_context: Optional[bool] = None,
+        session_state: Optional[Dict[str, Any]] = None,  # Deprecated
+        dependencies: Optional[Dict[str, Any]] = None,  # Deprecated
+        metadata: Optional[Dict[str, Any]] = None,  # Deprecated
     ) -> Optional[Message]:
         """Return the system message for the Agent.
@@ -6583,6 +6633,12 @@ class Agent:
         3. Build and return the default system message for the Agent.
         """
+        # Consider both run_context and session_state, dependencies, metadata (deprecated fields)
+        if run_context is not None:
+            session_state = run_context.session_state or session_state
+            dependencies = run_context.dependencies or dependencies
+            metadata = run_context.metadata or metadata
         # 1. If the system_message is provided, use that.
         if self.system_message is not None:
             if isinstance(self.system_message, Message):
@@ -6596,14 +6652,13 @@ class Agent:
                 if not isinstance(sys_message_content, str):
                     raise Exception("system_message must return a string")
-            # Format the system message with the session state variables
             if self.resolve_in_context:
                 sys_message_content = self._format_message_with_state_variables(
                     sys_message_content,
                     user_id=user_id,
+                    session_state=session_state,
                     dependencies=dependencies,
                     metadata=metadata,
-                    session_state=session_state,
                 )
             # type: ignore
@@ -6635,6 +6690,11 @@ class Agent:
                 if "session_state" in signature.parameters:
                     instruction_args["session_state"] = session_state or {}
+                # Check for run_context parameter
+                if "run_context" in signature.parameters:
+                    instruction_args["run_context"] = run_context or None
+                # Run the instructions function
                 _instructions = self.instructions(**instruction_args)
             if isinstance(_instructions, str):
@@ -6912,11 +6972,13 @@ class Agent:
     async def aget_system_message(
         self,
         session: AgentSession,
-        session_state: Optional[Dict[str, Any]] = None,
+        run_context: Optional[RunContext] = None,
         user_id: Optional[str] = None,
         tools: Optional[List[Union[Function, dict]]] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
+        add_session_state_to_context: Optional[bool] = None,
+        session_state: Optional[Dict[str, Any]] = None,  # Deprecated
+        dependencies: Optional[Dict[str, Any]] = None,  # Deprecated
+        metadata: Optional[Dict[str, Any]] = None,  # Deprecated
     ) -> Optional[Message]:
         """Return the system message for the Agent.
@@ -6925,6 +6987,12 @@ class Agent:
         3. Build and return the default system message for the Agent.
         """
+        # Consider both run_context and session_state, dependencies, metadata (deprecated fields)
+        if run_context is not None:
+            session_state = run_context.session_state or session_state
+            dependencies = run_context.dependencies or dependencies
+            metadata = run_context.metadata or metadata
         # 1. If the system_message is provided, use that.
         if self.system_message is not None:
             if isinstance(self.system_message, Message):
@@ -7037,7 +7105,7 @@ class Agent:
         # 3.2.5 Add information about agentic filters if enabled
         if self.knowledge is not None and self.enable_agentic_knowledge_filters:
-            valid_filters = getattr(self.knowledge, "valid_metadata_filters", None)
+            valid_filters = await self.knowledge.aget_valid_filters()
             if valid_filters:
                 valid_filters_str = ", ".join(valid_filters)
                 additional_information.append(
@@ -7244,7 +7312,7 @@ class Agent:
             system_message_content += f"{get_response_model_format_prompt(self.output_schema)}"
         # 3.3.15 Add the session state to the system message
-        if self.add_session_state_to_context and session_state is not None:
+        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)
         # Return the system message
@@ -7261,17 +7329,18 @@ class Agent:
         self,
         *,
         run_response: RunOutput,
+        run_context: Optional[RunContext] = None,
         session_state: Optional[Dict[str, Any]] = None,
+        dependencies: Optional[Dict[str, Any]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
         user_id: Optional[str] = None,
         input: Optional[Union[str, List, Dict, Message, BaseModel, List[Message]]] = None,
         audio: Optional[Sequence[Audio]] = None,
         images: Optional[Sequence[Image]] = None,
         videos: Optional[Sequence[Video]] = None,
         files: Optional[Sequence[File]] = None,
-        knowledge_filters: Optional[Dict[str, Any]] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
         add_dependencies_to_context: Optional[bool] = None,
-        metadata: Optional[Dict[str, Any]] = None,
+        knowledge_filters: Optional[Dict[str, Any]] = None,
         **kwargs: Any,
     ) -> Optional[Message]:
         """Return the user message for the Agent.
@@ -7280,6 +7349,13 @@ class Agent:
         2. If build_user_context is False or if the message is a list, return the message as is.
         3. Build the default user message for the Agent
         """
+        # Consider both run_context and session_state, dependencies, metadata, knowledge_filters (deprecated fields)
+        if run_context is not None:
+            session_state = run_context.session_state or session_state
+            dependencies = run_context.dependencies or dependencies
+            metadata = run_context.metadata or metadata
+            knowledge_filters = run_context.knowledge_filters or knowledge_filters
         # Get references from the knowledge base to use in the user message
         references = None
@@ -7287,7 +7363,7 @@ class Agent:
         if not self.build_user_context:
             return Message(
                 role=self.user_message_role or "user",
-                content=input,
+                content=input,  # type: ignore
                 images=None if not self.send_media_to_model else images,
                 audio=None if not self.send_media_to_model else audio,
                 videos=None if not self.send_media_to_model else videos,
@@ -7428,20 +7504,17 @@ class Agent:
         self,
         *,
         run_response: RunOutput,
+        run_context: RunContext,
         input: Union[str, List, Dict, Message, BaseModel, List[Message]],
         session: AgentSession,
-        session_state: Optional[Dict[str, Any]] = None,
         user_id: Optional[str] = None,
         audio: Optional[Sequence[Audio]] = None,
         images: Optional[Sequence[Image]] = None,
         videos: Optional[Sequence[Video]] = None,
         files: Optional[Sequence[File]] = None,
-        knowledge_filters: Optional[Dict[str, Any]] = None,
         add_history_to_context: Optional[bool] = None,
-        dependencies: Optional[Dict[str, Any]] = None,
         add_dependencies_to_context: Optional[bool] = None,
         add_session_state_to_context: Optional[bool] = None,
-        metadata: Optional[Dict[str, Any]] = None,
         tools: Optional[List[Union[Function, dict]]] = None,
         **kwargs: Any,
     ) -> RunMessages:
@@ -7475,11 +7548,12 @@ class Agent:
         # 1. Add system message to run_messages
         system_message = self.get_system_message(
             session=session,
-            session_state=session_state,
+            run_context=run_context,
+            session_state=run_context.session_state,
+            dependencies=run_context.dependencies,
+            metadata=run_context.metadata,
             user_id=user_id,
             tools=tools,
-            dependencies=dependencies,
-            metadata=metadata,
             add_session_state_to_context=add_session_state_to_context,
         )
         if system_message is not None:
@@ -7564,16 +7638,13 @@ class Agent:
         ):
             user_message = self._get_user_message(
                 run_response=run_response,
-                session_state=session_state,
+                run_context=run_context,
                 input=input,
                 audio=audio,
                 images=images,
                 videos=videos,
                 files=files,
-                knowledge_filters=knowledge_filters,
-                dependencies=dependencies,
                 add_dependencies_to_context=add_dependencies_to_context,
-                metadata=metadata,
                 **kwargs,
             )
@@ -7638,6 +7709,7 @@ class Agent:
         run_response: RunOutput,
         input: Union[str, List, Dict, Message, BaseModel, List[Message]],
         session: AgentSession,
+        run_context: Optional[RunContext] = None,
         session_state: Optional[Dict[str, Any]] = None,
         user_id: Optional[str] = None,
         audio: Optional[Sequence[Audio]] = None,
@@ -7677,17 +7749,25 @@ class Agent:
         )
         """
+        # Consider both run_context and session_state, dependencies, metadata (deprecated fields)
+        if run_context is not None:
+            session_state = run_context.session_state or session_state
+            dependencies = run_context.dependencies or dependencies
+            metadata = run_context.metadata or metadata
         # Initialize the RunMessages object (no media here - that's in RunInput now)
         run_messages = RunMessages()
         # 1. Add system message to run_messages
         system_message = await self.aget_system_message(
             session=session,
+            run_context=run_context,
             session_state=session_state,
             user_id=user_id,
             tools=tools,
             dependencies=dependencies,
             metadata=metadata,
+            add_session_state_to_context=add_session_state_to_context,
         )
         if system_message is not None:
             run_messages.system_message = system_message
@@ -7771,16 +7851,17 @@ class Agent:
         ):
             user_message = self._get_user_message(
                 run_response=run_response,
+                run_context=run_context,
                 session_state=session_state,
+                dependencies=dependencies,
+                metadata=metadata,
                 input=input,
                 audio=audio,
                 images=images,
                 videos=videos,
                 files=files,
                 knowledge_filters=knowledge_filters,
-                dependencies=dependencies,
                 add_dependencies_to_context=add_dependencies_to_context,
-                metadata=metadata,
                 **kwargs,
             )
@@ -8020,7 +8101,7 @@ class Agent:
         # Validate the filters against known valid filter keys
         if self.knowledge is not None:
-            valid_filters, invalid_keys = self.knowledge.validate_filters(filters)  # type: ignore
+            valid_filters, invalid_keys = await self.knowledge.async_validate_filters(filters)  # type: ignore
             # Warn about invalid filter keys
             if invalid_keys:  # type: ignore
@@ -8256,38 +8337,6 @@ class Agent:
         return metrics
-    ###########################################################################
-    # Handle images, videos and audio
-    ###########################################################################
-    def _add_image(self, image: Image, run_response: RunOutput) -> None:
-        """Add an image to both the agent's stateful storage and the current run response"""
-        # Add to run response
-        if run_response.images is None:
-            run_response.images = []
-        run_response.images.append(image)
-    def _add_video(self, video: Video, run_response: RunOutput) -> None:
-        """Add a video to both the agent's stateful storage and the current run response"""
-        # Add to run response
-        if run_response.videos is None:
-            run_response.videos = []
-        run_response.videos.append(video)
-    def _add_audio(self, audio: Audio, run_response: RunOutput) -> None:
-        """Add audio to both the agent's stateful storage and the current run response"""
-        # Add to run response
-        if run_response.audio is None:
-            run_response.audio = []
-        run_response.audio.append(audio)
-    def _add_file(self, file: File, run_response: RunOutput) -> None:
-        """Add file to both the agent's stateful storage and the current run response"""
-        # Add to run response
-        if run_response.files is None:
-            run_response.files = []
-        run_response.files.append(file)
     ###########################################################################
     # Reasoning
     ###########################################################################
@@ -10055,7 +10104,13 @@ class Agent:
         return effective_filters
-    def _cleanup_and_store(self, run_response: RunOutput, session: AgentSession, user_id: Optional[str] = None) -> None:
+    def _cleanup_and_store(
+        self,
+        run_response: RunOutput,
+        session: AgentSession,
+        run_context: Optional[RunContext] = None,
+        user_id: Optional[str] = None,
+    ) -> None:
         #  Scrub the stored run based on storage flags
         self._scrub_run_output_for_storage(run_response)
@@ -10063,10 +10118,10 @@ class Agent:
         if run_response.metrics:
             run_response.metrics.stop_timer()
-        # Update run_response.session_state from session before saving
+        # Update run_response.session_state before saving
         # This ensures RunOutput reflects all tool modifications
-        if session.session_data is not None and "session_state" in session.session_data:
-            run_response.session_state = session.session_data["session_state"]
+        if session.session_data is not None and run_context is not None and run_context.session_state is not None:
+            run_response.session_state = run_context.session_state
         # Optional: Save output to file if save_response_to_file is set
         self.save_run_response_to_file(
@@ -10086,7 +10141,11 @@ class Agent:
         self.save_session(session=session)
     async def _acleanup_and_store(
-        self, run_response: RunOutput, session: AgentSession, user_id: Optional[str] = None
+        self,
+        run_response: RunOutput,
+        session: AgentSession,
+        run_context: Optional[RunContext] = None,
+        user_id: Optional[str] = None,
     ) -> None:
         #  Scrub the stored run based on storage flags
         self._scrub_run_output_for_storage(run_response)
@@ -10097,8 +10156,8 @@ class Agent:
         # Update run_response.session_state from session before saving
         # This ensures RunOutput reflects all tool modifications
-        if session.session_data is not None and "session_state" in session.session_data:
-            run_response.session_state = session.session_data["session_state"]
+        if session.session_data is not None and run_context is not None and run_context.session_state is not None:
+            run_response.session_state = run_context.session_state
         # Optional: Save output to file if save_response_to_file is set
         self.save_run_response_to_file(
@@ -10114,7 +10173,14 @@ class Agent:
         # Calculate session metrics
         self._update_session_metrics(session=session, run_response=run_response)
-        # Save session to storage
+        # Update session state before saving the session
+        if run_context is not None and run_context.session_state is not None:
+            if session.session_data is not None:
+                session.session_data["session_state"] = run_context.session_state
+            else:
+                session.session_data = {"session_state": run_context.session_state}
+        # Save session to memory
         await self.asave_session(session=session)
     def _scrub_run_output_for_storage(self, run_response: RunOutput) -> None:
@@ -10130,58 +10196,6 @@ class Agent:
         if not self.store_history_messages:
             scrub_history_messages_from_run_output(run_response)
-    def _validate_media_object_id(
-        self,
-        images: Optional[Sequence[Image]] = None,
-        videos: Optional[Sequence[Video]] = None,
-        audios: Optional[Sequence[Audio]] = None,
-        files: Optional[Sequence[File]] = None,
-    ) -> tuple:
-        """Convert raw Image/Video/Audio objects - now unified, so just return as-is."""
-        # With unified classes, no conversion needed - just ensure IDs are set
-        image_list = None
-        if images:
-            image_list = []
-            for img in images:
-                # Ensure ID is set (validation should handle this, but double-check)
-                if not img.id:
-                    from uuid import uuid4
-                    img.id = str(uuid4())
-                image_list.append(img)
-        video_list = None
-        if videos:
-            video_list = []
-            for vid in videos:
-                if not vid.id:
-                    from uuid import uuid4
-                    vid.id = str(uuid4())
-                video_list.append(vid)
-        audio_list = None
-        if audios:
-            audio_list = []
-            for aud in audios:
-                if not aud.id:
-                    from uuid import uuid4
-                    aud.id = str(uuid4())
-                audio_list.append(aud)
-        file_list = None
-        if files:
-            file_list = []
-            for file in files:
-                if not file.id:
-                    from uuid import uuid4
-                    file.id = str(uuid4())
-                file_list.append(file)
-        return image_list, video_list, audio_list, file_list
     def cli_app(
         self,
         input: Optional[str] = None,

agno 2.2.6__py3-none-any.whl → 2.2.8__py3-none-any.whl

agno 2.2.6py3-none-any.whl → 2.2.8py3-none-any.whl