agno 2.2.5__py3-none-any.whl → 2.2.7__py3-none-any.whl

agno/agent/agent.py

@@ -47,14 +47,15 @@ from agno.models.base import Model
 from agno.models.message import Message, MessageReferences
 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,
 )
@@ -94,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,
 )
@@ -262,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.
@@ -346,7 +349,7 @@ class Agent:
 
     # --- Agent Response Model Settings ---
     # Provide an input schema to validate the input
-    input_schema: Optional[Union[Type[BaseModel], type]] = None
+    input_schema: Optional[Type[BaseModel]] = None
     # Provide a response model to get the response as a Pydantic model
     output_schema: Optional[Type[BaseModel]] = None
     # Provide a secondary model to parse the response from the primary model
@@ -416,7 +419,7 @@ class Agent:
     def __init__(
         self,
         *,
-        model: Optional[Model] = None,
+        model: Optional[Union[Model, str]] = None,
         name: Optional[str] = None,
         id: Optional[str] = None,
         introduction: Optional[str] = None,
@@ -457,10 +460,10 @@ 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[Model] = None,
+        reasoning_model: Optional[Union[Model, str]] = None,
         reasoning_agent: Optional[Agent] = None,
         reasoning_min_steps: int = 1,
         reasoning_max_steps: int = 10,
@@ -488,12 +491,12 @@ class Agent:
         retries: int = 0,
         delay_between_retries: int = 1,
         exponential_backoff: bool = False,
-        parser_model: Optional[Model] = None,
+        parser_model: Optional[Union[Model, str]] = None,
         parser_model_prompt: Optional[str] = None,
-        input_schema: Optional[Union[Type[BaseModel], type]] = None,
+        input_schema: Optional[Type[BaseModel]] = None,
         output_schema: Optional[Type[BaseModel]] = None,
         parse_response: bool = True,
-        output_model: Optional[Model] = None,
+        output_model: Optional[Union[Model, str]] = None,
         output_model_prompt: Optional[str] = None,
         structured_outputs: Optional[bool] = None,
         use_json_mode: bool = False,
@@ -512,7 +515,7 @@ class Agent:
         debug_level: Literal[1, 2] = 1,
         telemetry: bool = True,
     ):
-        self.model = model
+        self.model = model  # type: ignore[assignment]
         self.name = name
         self.id = id
         self.introduction = introduction
@@ -578,7 +581,7 @@ class Agent:
         self.post_hooks = post_hooks
 
         self.reasoning = reasoning
-        self.reasoning_model = reasoning_model
+        self.reasoning_model = reasoning_model  # type: ignore[assignment]
         self.reasoning_agent = reasoning_agent
         self.reasoning_min_steps = reasoning_min_steps
         self.reasoning_max_steps = reasoning_max_steps
@@ -609,12 +612,12 @@ class Agent:
         self.retries = retries
         self.delay_between_retries = delay_between_retries
         self.exponential_backoff = exponential_backoff
-        self.parser_model = parser_model
+        self.parser_model = parser_model  # type: ignore[assignment]
         self.parser_model_prompt = parser_model_prompt
         self.input_schema = input_schema
         self.output_schema = output_schema
         self.parse_response = parse_response
-        self.output_model = output_model
+        self.output_model = output_model  # type: ignore[assignment]
         self.output_model_prompt = output_model_prompt
 
         self.structured_outputs = structured_outputs
@@ -658,6 +661,8 @@ class Agent:
         # Lazy-initialized shared thread pool executor for background tasks (memory, cultural knowledge, etc.)
         self._background_executor: Optional[Any] = None
 
+        self._get_models()
+
     @property
     def background_executor(self) -> Any:
         """Lazy initialization of shared thread pool executor for background tasks.
@@ -814,6 +819,16 @@ class Agent:
         """Return True if the db the agent is equipped with is an Async implementation"""
         return self.db is not None and isinstance(self.db, AsyncBaseDb)
 
+    def _get_models(self) -> None:
+        if self.model is not None:
+            self.model = get_model(self.model)
+        if self.reasoning_model is not None:
+            self.reasoning_model = get_model(self.reasoning_model)
+        if self.parser_model is not None:
+            self.parser_model = get_model(self.parser_model)
+        if self.output_model is not None:
+            self.output_model = get_model(self.output_model)
+
     def initialize_agent(self, debug_mode: Optional[bool] = None) -> None:
         self._set_default_model()
         self._set_debug(debug_mode=debug_mode)
@@ -900,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:
@@ -943,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,
@@ -957,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,
         )
@@ -1061,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)
@@ -1071,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,
                 )
@@ -1099,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)
@@ -1114,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:
@@ -1124,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,
@@ -1166,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,
@@ -1180,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
@@ -1198,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,
         )
@@ -1268,6 +1267,7 @@ class Agent:
                     tools=_tools,
                     response_format=response_format,
                     stream_events=stream_events,
+                    session_state=run_context.session_state,
                 ):
                     raise_if_cancelled(run_response.run_id)  # type: ignore
                     yield event
@@ -1284,6 +1284,7 @@ class Agent:
                     tools=_tools,
                     response_format=response_format,
                     stream_events=stream_events,
+                    session_state=run_context.session_state,
                 ):
                     raise_if_cancelled(run_response.run_id)  # type: ignore
                     if isinstance(event, RunContentEvent):
@@ -1303,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
@@ -1344,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,
@@ -1387,6 +1386,11 @@ class Agent:
                         store_events=self.store_events,
                     )
 
+            # Update run_response.session_state before creating RunCompletedEvent
+            # This ensures the event has the final state after 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"]
+
             # Create the run completed event
             completed_event = handle_event(  # type: ignore
                 create_run_completed_event(from_run_response=run_response),
@@ -1399,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
@@ -1430,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
@@ -1533,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)
@@ -1543,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
         )
 
@@ -1566,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
@@ -1583,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:
@@ -1612,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(
@@ -1625,7 +1637,8 @@ class Agent:
             agent_id=self.id,
             user_id=user_id,
             agent_name=self.name,
-            metadata=metadata,
+            metadata=run_context.metadata,
+            session_state=run_context.session_state,
             input=run_input,
         )
 
@@ -1647,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,
@@ -1666,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,
@@ -1727,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:
@@ -1771,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)
@@ -1790,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,
@@ -1807,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,
         )
@@ -1877,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
@@ -1909,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,
@@ -1944,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)
@@ -1960,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
 
@@ -1988,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,
@@ -2037,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)
@@ -2056,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,
@@ -2072,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,
         )
@@ -2148,6 +2158,7 @@ class Agent:
                     tools=_tools,
                     response_format=response_format,
                     stream_events=stream_events,
+                    session_state=run_context.session_state,
                 ):
                     raise_if_cancelled(run_response.run_id)  # type: ignore
                     yield event
@@ -2164,6 +2175,7 @@ class Agent:
                     tools=_tools,
                     response_format=response_format,
                     stream_events=stream_events,
+                    session_state=run_context.session_state,
                 ):
                     raise_if_cancelled(run_response.run_id)  # type: ignore
                     if isinstance(event, RunContentEvent):
@@ -2223,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,
@@ -2270,6 +2280,11 @@ class Agent:
                         store_events=self.store_events,
                     )
 
+            # Update run_response.session_state before creating RunCompletedEvent
+            # This ensures the event has the final state after all tool modifications
+            if agent_session.session_data is not None and "session_state" in agent_session.session_data:
+                run_response.session_state = agent_session.session_data["session_state"]
+
             # Create the run completed event
             completed_event = handle_event(
                 create_run_completed_event(from_run_response=run_response),
@@ -2282,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
@@ -2313,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()
@@ -2426,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
@@ -2440,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
         )
@@ -2487,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:
@@ -2498,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
 
@@ -2508,7 +2544,8 @@ class Agent:
             agent_id=self.id,
             user_id=user_id,
             agent_name=self.name,
-            metadata=metadata,
+            metadata=run_context.metadata,
+            session_state=run_context.session_state,
             input=run_input,
         )
 
@@ -2528,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,
                     )
@@ -2646,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,
@@ -2687,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,
@@ -2706,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
@@ -2774,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
@@ -2807,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,
@@ -2823,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,
@@ -2875,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,
@@ -2936,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,
                 )
@@ -2969,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)
@@ -2982,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:
@@ -2993,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]:
@@ -3016,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:
@@ -3042,6 +3076,7 @@ class Agent:
                 tools=tools,
                 response_format=response_format,
                 stream_events=stream_events,
+                session_state=run_context.session_state,
             ):
                 yield event
 
@@ -3072,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,
@@ -3110,6 +3143,11 @@ class Agent:
                         store_events=self.store_events,
                     )
 
+            # Update run_response.session_state before creating RunCompletedEvent
+            # This ensures the event has the final state after 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"]
+
             # Create the run completed event
             completed_event = handle_event(
                 create_run_completed_event(run_response),
@@ -3122,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
@@ -3147,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
@@ -3194,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,
@@ -3237,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
@@ -3268,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:
@@ -3283,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):
@@ -3290,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,
@@ -3307,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,
                     )
@@ -3357,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:
@@ -3392,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:
@@ -3430,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
@@ -3490,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
 
@@ -3499,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
@@ -3526,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)
@@ -3542,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:
@@ -3555,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]]:
@@ -3586,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)
@@ -3595,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:
@@ -3627,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
@@ -3742,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,
                 ):
@@ -3780,6 +3836,11 @@ class Agent:
                         store_events=self.store_events,
                     )
 
+            # Update run_response.session_state before creating RunCompletedEvent
+            # This ensures the event has the final state after all tool modifications
+            if agent_session.session_data is not None and "session_state" in agent_session.session_data:
+                run_response.session_state = agent_session.session_data["session_state"]
+
             # Create the run completed event
             completed_event = handle_event(
                 create_run_completed_event(run_response),
@@ -3792,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
@@ -3819,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()
@@ -3833,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,
@@ -3847,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,
         }
@@ -3902,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,
@@ -3919,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,
         }
@@ -3976,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,
@@ -3992,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)
@@ -4038,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,
@@ -4055,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)
@@ -4547,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,
@@ -4651,6 +4696,7 @@ class Agent:
         tools: Optional[List[Union[Function, dict]]] = None,
         response_format: Optional[Union[Dict, Type[BaseModel]]] = None,
         stream_events: bool = False,
+        session_state: Optional[Dict[str, Any]] = None,
     ) -> Iterator[RunOutputEvent]:
         self.model = cast(Model, self.model)
 
@@ -4683,6 +4729,7 @@ class Agent:
                 reasoning_state=reasoning_state,
                 parse_structured_output=self.should_parse_structured_output,
                 stream_events=stream_events,
+                session_state=session_state,
             )
 
         # Determine reasoning completed
@@ -4729,6 +4776,7 @@ class Agent:
         tools: Optional[List[Union[Function, dict]]] = None,
         response_format: Optional[Union[Dict, Type[BaseModel]]] = None,
         stream_events: bool = False,
+        session_state: Optional[Dict[str, Any]] = None,
     ) -> AsyncIterator[RunOutputEvent]:
         self.model = cast(Model, self.model)
 
@@ -4763,6 +4811,7 @@ class Agent:
                 reasoning_state=reasoning_state,
                 parse_structured_output=self.should_parse_structured_output,
                 stream_events=stream_events,
+                session_state=session_state,
             ):
                 yield event
 
@@ -4810,9 +4859,14 @@ class Agent:
         reasoning_state: Optional[Dict[str, Any]] = None,
         parse_structured_output: bool = False,
         stream_events: bool = False,
+        session_state: Optional[Dict[str, Any]] = None,
     ) -> Iterator[RunOutputEvent]:
-        if isinstance(model_response_event, tuple(get_args(RunOutputEvent))) or isinstance(
-            model_response_event, tuple(get_args(TeamRunOutputEvent))
+        from agno.run.workflow import WorkflowRunOutputEvent
+
+        if (
+            isinstance(model_response_event, tuple(get_args(RunOutputEvent)))
+            or isinstance(model_response_event, tuple(get_args(TeamRunOutputEvent)))
+            or isinstance(model_response_event, tuple(get_args(WorkflowRunOutputEvent)))
         ):
             if model_response_event.event == RunEvent.custom_event:  # type: ignore
                 model_response_event.agent_id = self.id  # type: ignore
@@ -4981,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:
@@ -5018,23 +5074,39 @@ class Agent:
 
             # If the model response is a tool_call_completed, update the existing tool call in the run_response
             elif model_response_event.event == ModelResponseEvent.tool_call_completed.value:
-                if model_response_event.updated_session_state is not None and session.session_data is not None:
-                    merge_dictionaries(
-                        session.session_data["session_state"],
-                        model_response_event.updated_session_state,
-                    )
+                if model_response_event.updated_session_state is not None:
+                    # update the session_state for RunOutput
+                    if session_state is not None:
+                        merge_dictionaries(session_state, model_response_event.updated_session_state)
+                    # update the DB session
+                    if session.session_data is not None and session.session_data.get("session_state") is not None:
+                        merge_dictionaries(
+                            session.session_data["session_state"], model_response_event.updated_session_state
+                        )
 
                 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
 
@@ -5251,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
@@ -5302,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:
@@ -5310,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,
                         )
                     )
 
@@ -5322,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,
@@ -5329,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()
 
@@ -5386,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:
@@ -5394,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,
                         )
                     )
 
@@ -5408,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]] = []
@@ -5515,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
@@ -5566,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}")
 
@@ -6477,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
@@ -6497,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
@@ -6516,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.
 
@@ -6530,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):
@@ -6543,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
@@ -6582,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):
@@ -6859,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.
 
@@ -6872,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):
@@ -6984,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(
@@ -7191,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
@@ -7208,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.
@@ -7227,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
 
@@ -7234,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,
@@ -7375,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:
@@ -7422,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:
@@ -7511,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,
             )
 
@@ -7585,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,
@@ -7624,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
@@ -7718,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,
             )
 
@@ -7967,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
@@ -8203,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
     ###########################################################################
@@ -8454,7 +8556,7 @@ class Agent:
                         store_events=self.store_events,
                     )
             else:
-                log_warning(
+                log_info(
                     f"Reasoning model: {reasoning_model.__class__.__name__} is not a native reasoning model, defaulting to manual Chain-of-Thought reasoning"
                 )
                 use_default_reasoning = True
@@ -8747,7 +8849,7 @@ class Agent:
                         store_events=self.store_events,
                     )
             else:
-                log_warning(
+                log_info(
                     f"Reasoning model: {reasoning_model.__class__.__name__} is not a native reasoning model, defaulting to manual Chain-of-Thought reasoning"
                 )
                 use_default_reasoning = True
@@ -10002,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)
 
@@ -10010,6 +10118,11 @@ class Agent:
         if run_response.metrics:
             run_response.metrics.stop_timer()
 
+        # Update run_response.session_state before saving
+        # This ensures RunOutput reflects all tool modifications
+        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(
             run_response=run_response,
@@ -10028,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)
@@ -10037,6 +10154,11 @@ class Agent:
         if run_response.metrics:
             run_response.metrics.stop_timer()
 
+        # Update run_response.session_state from session before saving
+        # This ensures RunOutput reflects all tool modifications
+        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(
             run_response=run_response,
@@ -10051,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:
@@ -10067,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,