xpander-sdk 2.0.177__py3-none-any.whl → 2.0.179__py3-none-any.whl

xpander_sdk/__init__.py

@@ -17,6 +17,7 @@ For more information, visit: https://xpander.ai
 
 # Backend-related imports
 from .modules.backend.backend_module import Backend
+from .modules.backend.decorators.on_auth_event import on_auth_event
 
 # Agent-related imports
 from .modules.agents.agents_module import Agents, Agent, AgentsListItem
@@ -53,6 +54,7 @@ from .models.shared import OutputFormat, Tokens
 __all__ = [
     # xpander.ai Backend
     "Backend",
+    "on_auth_event",
     # Agent management
     "Agents",
     "Agent",

xpander_sdk/modules/backend/__init__.py

@@ -0,0 +1,8 @@
+"""
+Backend module for xpander.ai SDK.
+"""
+
+from .backend_module import Backend
+from .decorators.on_auth_event import on_auth_event
+
+__all__ = ["Backend", "on_auth_event"]

xpander_sdk/modules/backend/backend_module.py

@@ -231,6 +231,7 @@ class Backend(ModuleBase):
         override: Optional[Dict[str, Any]] = None,
         tools: Optional[List[Callable]] = None,
         is_async: Optional[bool] = True,
+        auth_events_callback: Optional[Callable] = None,
     ) -> Dict[str, Any]:
         """
         Asynchronously resolve runtime arguments for the specified agent.
@@ -243,6 +244,27 @@ class Backend(ModuleBase):
             override (Optional[Dict[str, Any]]): Optional overrides for final arguments.
             tools (Optional[List[Callable]]): Optional additional tools to be added to the agent arguments.
             is_async (Optional[bool]): Is in Async Context?.
+            auth_events_callback (Optional[Callable]): Optional callback function (async or sync) that will be called for authentication events only.
+                Used specifically for authentication events (e.g., MCP OAuth flows requiring user login).
+                The callback signature must be: callback(agent: Agent, task: Task, event: TaskUpdateEvent)
+                
+                Can be provided in two ways:
+                1. Direct function: Pass the function directly to this parameter
+                2. Decorator: Use @on_auth_event decorator and pass the decorated function
+                
+                Example (direct function):
+                    async def my_callback(agent, task, event):
+                        print(f"Auth required: {event.data}")
+                    args = await backend.aget_args(agent_id="...", auth_events_callback=my_callback)
+                
+                Example (decorator):
+                    from xpander_sdk import on_auth_event
+                    
+                    @on_auth_event
+                    async def handle_auth(agent, task, event):
+                        print(f"Auth required: {event.data}")
+                    
+                    args = await backend.aget_args(agent_id="...", auth_events_callback=handle_auth)
 
         Returns:
             Dict[str, Any]: Resolved argument dictionary to use with the agent.
@@ -267,7 +289,7 @@ class Backend(ModuleBase):
                 "or set via the 'XPANDER_AGENT_ID' environment variable."
             )
 
-        return await dispatch_get_args(agent=xpander_agent, task=task, override=override, tools=tools, is_async=is_async)
+        return await dispatch_get_args(agent=xpander_agent, task=task, override=override, tools=tools, is_async=is_async, auth_events_callback=auth_events_callback)
 
     def get_args(
         self,
@@ -277,6 +299,7 @@ class Backend(ModuleBase):
         task: Optional[Task] = None,
         override: Optional[Dict[str, Any]] = None,
         tools: Optional[List[Callable]] = None,
+        auth_events_callback: Optional[Callable] = None,
     ) -> Dict[str, Any]:
         """
         Synchronously resolve runtime arguments for the specified agent.
@@ -291,6 +314,27 @@ class Backend(ModuleBase):
             task (Optional[Task]): Optional Task object providing runtime input/output context.
             override (Optional[Dict[str, Any]]): Optional overrides for final arguments.
             tools (Optional[List[Callable]]): Optional additional tools to be added to the agent arguments.
+            auth_events_callback (Optional[Callable]): Optional callback function (async or sync) that will be called for authentication events only.
+                Used specifically for authentication events (e.g., MCP OAuth flows requiring user login).
+                The callback signature must be: callback(agent: Agent, task: Task, event: TaskUpdateEvent)
+                
+                Can be provided in two ways:
+                1. Direct function: Pass the function directly to this parameter
+                2. Decorator: Use @on_auth_event decorator and pass the decorated function
+                
+                Example (direct function):
+                    def my_callback(agent, task, event):
+                        print(f"Auth required: {event.data}")
+                    args = backend.get_args(agent_id="...", auth_events_callback=my_callback)
+                
+                Example (decorator):
+                    from xpander_sdk import on_auth_event
+                    
+                    @on_auth_event
+                    def handle_auth(agent, task, event):
+                        print(f"Auth required: {event.data}")
+                    
+                    args = backend.get_args(agent_id="...", auth_events_callback=handle_auth)
 
         Returns:
             Dict[str, Any]: Resolved argument dictionary to use with the agent.
@@ -306,7 +350,8 @@ class Backend(ModuleBase):
                 task=task,
                 override=override,
                 tools=tools,
-                is_async=False
+                is_async=False,
+                auth_events_callback=auth_events_callback
             )
         )
     

xpander_sdk/modules/backend/decorators/__init__.py

@@ -0,0 +1,7 @@
+"""
+Backend module decorators.
+"""
+
+from .on_auth_event import on_auth_event
+
+__all__ = ["on_auth_event"]

xpander_sdk/modules/backend/decorators/on_auth_event.py

@@ -0,0 +1,131 @@
+"""
+xpander_sdk.modules.backend.decorators.on_auth_event
+
+This module provides the `@on_auth_event` decorator, which allows developers to define
+authentication event handlers that respond to OAuth flows and authentication events.
+
+The decorator ensures that the registered function:
+- Accepts three parameters: agent (Agent), task (Task), and event (TaskUpdateEvent)
+- Handles authentication events (e.g., MCP OAuth flows requiring user login)
+- Can be either synchronous or asynchronous
+
+Execution Notes:
+- The handler is called when authentication events occur (e.g., OAuth login required)
+- The event.type will always be "auth_event"
+- The event.data contains authentication-specific information (e.g., OAuth login URL)
+- Use this for displaying authentication prompts, handling OAuth flows, etc.
+
+Example usage:
+--------------
+>>> from xpander_sdk import Backend, on_auth_event
+>>> 
+>>> # Define handler with decorator - auto-registers globally
+>>> @on_auth_event
+... async def handle_auth(agent, task, event):
+...     print(f"Authentication required for {agent.name}")
+...     print(f"Login URL: {event.data.get('auth_url')}")
+...     # Display authentication prompt to user
+>>> 
+>>> # Handler is automatically invoked when auth events occur
+>>> backend = Backend()
+>>> args = await backend.aget_args(agent_id="agent-123")  # handle_auth is called automatically
+"""
+
+from functools import wraps
+from inspect import iscoroutinefunction, signature
+from typing import Optional, Callable
+
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
+from xpander_sdk.modules.backend.events_registry import EventsRegistry, EventType
+
+
+def on_auth_event(_func: Optional[Callable] = None):
+    """
+    Decorator to register a handler for authentication events.
+
+    The decorated function is automatically registered globally and will be called
+    whenever authentication events occur during agent execution (e.g., MCP OAuth flows
+    requiring user login). The function:
+    - Must accept three parameters: agent (Agent), task (Task), event (TaskUpdateEvent)
+    - Can be either synchronous or asynchronous
+    - Receives only authentication events (event.type == "auth_event")
+    - Is invoked automatically - no need to pass it to aget_args/get_args
+
+    Args:
+        _func (Optional[Callable]):
+            The function to decorate (for direct usage like `@on_auth_event`).
+
+    Raises:
+        TypeError: If the decorated function does not have the correct parameters.
+
+    Example:
+        >>> @on_auth_event
+        ... async def handle_oauth_login(agent, task, event):
+        ...     print(f"Agent: {agent.name}")
+        ...     print(f"Task: {task.id}")
+        ...     print(f"Auth data: {event.data}")
+        ...     # Handle OAuth flow
+        
+        >>> @on_auth_event
+        ... def sync_auth_handler(agent, task, event):
+        ...     if 'auth_url' in event.data:
+        ...         print(f"Please visit: {event.data['auth_url']}")
+    """
+
+    def decorator(func: Callable) -> Callable:
+        sig = signature(func)
+        params = list(sig.parameters.keys())
+
+        # Validate function signature
+        if len(params) < 3:
+            raise TypeError(
+                f"Function '{func.__name__}' must accept 3 parameters: agent, task, event. "
+                f"Got {len(params)} parameters: {params}"
+            )
+
+        # Store the original function for later use
+        @wraps(func)
+        async def async_wrapper(agent: Agent, task: Task, event: TaskUpdateEvent):
+            return await func(agent, task, event)
+
+        @wraps(func)
+        def sync_wrapper(agent: Agent, task: Task, event: TaskUpdateEvent):
+            return func(agent, task, event)
+
+        wrapped = async_wrapper if iscoroutinefunction(func) else sync_wrapper
+        
+        # Mark the function as an auth event handler
+        wrapped._is_auth_event_handler = True
+        
+        # Register the handler in the singleton registry
+        registry = EventsRegistry()
+        registry.register_auth_event(wrapped)
+        
+        return wrapped
+
+    if _func and callable(_func):
+        return decorator(_func)
+
+    return decorator
+
+
+def get_registered_handlers():
+    """
+    Get all registered authentication event handlers.
+    
+    Returns:
+        list: List of registered handler functions.
+    """
+    registry = EventsRegistry()
+    return registry.get_auth_handlers()
+
+
+def clear_handlers():
+    """
+    Clear all registered authentication event handlers.
+    
+    Useful for testing or when you want to reset the handlers.
+    """
+    registry = EventsRegistry()
+    registry.clear(EventType.AUTH_EVENT)

xpander_sdk/modules/backend/events_registry.py

@@ -0,0 +1,172 @@
+"""
+Events Registry - Singleton pattern for managing event handlers and hooks.
+
+This registry supports multiple event types:
+- Authentication events (OAuth flows)
+- Tool call hooks (pre/post/error) - Coming soon
+"""
+
+from typing import Callable, List, Optional, Dict, Any
+from enum import Enum
+import asyncio
+
+
+class EventType(str, Enum):
+    """Supported event types in the backend module."""
+    AUTH_EVENT = "auth_event"
+    TOOL_PRE_CALL = "tool_pre_call"  # Future: before tool execution
+    TOOL_POST_CALL = "tool_post_call"  # Future: after successful tool execution
+    TOOL_ERROR = "tool_error"  # Future: when tool execution fails
+
+
+class EventsRegistry:
+    """
+    Singleton registry for managing event handlers and hooks.
+    
+    This registry maintains handlers for different event types and provides
+    methods to register, retrieve, and invoke them.
+    
+    Supported event types:
+    - AUTH_EVENT: Authentication events (e.g., MCP OAuth flows)
+    - TOOL_PRE_CALL: Before tool execution (future)
+    - TOOL_POST_CALL: After successful tool execution (future)
+    - TOOL_ERROR: When tool execution fails (future)
+    """
+    
+    _instance: Optional['EventsRegistry'] = None
+    _handlers: Dict[EventType, List[Callable]] = {}
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._handlers = {
+                EventType.AUTH_EVENT: [],
+                EventType.TOOL_PRE_CALL: [],
+                EventType.TOOL_POST_CALL: [],
+                EventType.TOOL_ERROR: [],
+            }
+        return cls._instance
+    
+    def register(self, event_type: EventType, handler: Callable) -> None:
+        """
+        Register an event handler for a specific event type.
+        
+        Args:
+            event_type (EventType): The type of event to handle.
+            handler (Callable): The handler function to register.
+        """
+        if event_type not in self._handlers:
+            self._handlers[event_type] = []
+        
+        if handler not in self._handlers[event_type]:
+            self._handlers[event_type].append(handler)
+    
+    def register_auth_event(self, handler: Callable) -> None:
+        """
+        Register an authentication event handler.
+        
+        Args:
+            handler (Callable): The handler function to register.
+        """
+        self.register(EventType.AUTH_EVENT, handler)
+    
+    def get_handlers(self, event_type: EventType) -> List[Callable]:
+        """
+        Get all registered handlers for a specific event type.
+        
+        Args:
+            event_type (EventType): The type of event.
+        
+        Returns:
+            List[Callable]: List of registered handler functions.
+        """
+        return self._handlers.get(event_type, []).copy()
+    
+    def get_auth_handlers(self) -> List[Callable]:
+        """
+        Get all registered authentication event handlers.
+        
+        Returns:
+            List[Callable]: List of registered auth handler functions.
+        """
+        return self.get_handlers(EventType.AUTH_EVENT)
+    
+    def clear(self, event_type: Optional[EventType] = None) -> None:
+        """
+        Clear registered handlers.
+        
+        Args:
+            event_type (Optional[EventType]): If provided, clear only handlers
+                for this event type. If None, clear all handlers.
+        """
+        if event_type:
+            if event_type in self._handlers:
+                self._handlers[event_type].clear()
+        else:
+            for handlers_list in self._handlers.values():
+                handlers_list.clear()
+    
+    async def invoke_handlers(self, event_type: EventType, *args, **kwargs) -> None:
+        """
+        Invoke all registered handlers for a specific event type.
+        
+        Args:
+            event_type (EventType): The type of event to invoke handlers for.
+            *args: Positional arguments to pass to handlers.
+            **kwargs: Keyword arguments to pass to handlers.
+        """
+        handlers = self._handlers.get(event_type, [])
+        
+        for handler in handlers:
+            try:
+                if asyncio.iscoroutinefunction(handler):
+                    await handler(*args, **kwargs)
+                else:
+                    handler(*args, **kwargs)
+            except Exception as e:
+                # Log error but continue with other handlers
+                from loguru import logger
+                logger.error(f"Error in {event_type.value} handler {handler.__name__}: {e}")
+    
+    async def invoke_auth_handlers(self, agent, task, event) -> None:
+        """
+        Invoke all registered authentication event handlers.
+        
+        Args:
+            agent: The Agent object associated with the task.
+            task: The Task object being executed.
+            event: The TaskUpdateEvent containing authentication event data.
+        """
+        await self.invoke_handlers(EventType.AUTH_EVENT, agent, task, event)
+    
+    def has_handlers(self, event_type: EventType) -> bool:
+        """
+        Check if any handlers are registered for a specific event type.
+        
+        Args:
+            event_type (EventType): The type of event.
+        
+        Returns:
+            bool: True if at least one handler is registered, False otherwise.
+        """
+        return len(self._handlers.get(event_type, [])) > 0
+    
+    def has_auth_handlers(self) -> bool:
+        """
+        Check if any authentication event handlers are registered.
+        
+        Returns:
+            bool: True if at least one auth handler is registered, False otherwise.
+        """
+        return self.has_handlers(EventType.AUTH_EVENT)
+    
+    @classmethod
+    def reset(cls) -> None:
+        """
+        Reset the singleton instance.
+        
+        Useful for testing to ensure a clean state.
+        """
+        if cls._instance is not None:
+            cls._instance.clear()
+            cls._instance = None

xpander_sdk/modules/backend/frameworks/agno.py

@@ -36,13 +36,14 @@ async def build_agent_args(
     override: Optional[Dict[str, Any]] = None,
     tools: Optional[List[Callable]] = None,
     is_async: Optional[bool] = True,
+    auth_events_callback: Optional[Callable] = None,
 ) -> Dict[str, Any]:
     model = _load_llm_model(agent=xpander_agent, override=override)
     args: Dict[str, Any] = {
         "id": xpander_agent.id,
         "store_events": True
     }
-
+    
     _configure_output(args=args, agent=xpander_agent, task=task)
     _configure_session_storage(args=args, agent=xpander_agent, task=task)
     _configure_agentic_memory(args=args, agent=xpander_agent, task=task)
@@ -55,7 +56,7 @@ async def build_agent_args(
     # Configure pre-hooks (guardrails, etc.)
     _configure_pre_hooks(args=args, agent=xpander_agent, model=model)
 
-    args["tools"] = await _resolve_agent_tools(agent=xpander_agent, task=task)
+    args["tools"] = await _resolve_agent_tools(agent=xpander_agent, task=task, auth_events_callback=auth_events_callback)
 
     
     if tools and len(tools) != 0:
@@ -102,7 +103,7 @@ async def build_agent_args(
         # convert to members
         members = await asyncio.gather(
             *[
-                build_agent_args(xpander_agent=sub_agent, override=override, task=task, is_async=is_async)
+                build_agent_args(xpander_agent=sub_agent, override=override, task=task, is_async=is_async, auth_events_callback=auth_events_callback)
                 for sub_agent in sub_agents
             ]
         )
@@ -891,7 +892,7 @@ def _configure_pre_hooks(args: Dict[str, Any], agent: Agent, model: Any) -> None
         args["pre_hooks"].append(openai_moderation_guardrail)
 
 
-async def _resolve_agent_tools(agent: Agent, task: Optional[Task] = None) -> List[Any]:
+async def _resolve_agent_tools(agent: Agent, task: Optional[Task] = None, auth_events_callback: Optional[Callable] = None) -> List[Any]:
     mcp_servers = agent.mcp_servers
     
     # combine task mcps and agent mcps
@@ -955,7 +956,7 @@ async def _resolve_agent_tools(agent: Agent, task: Optional[Task] = None) -> Lis
                 if not task.input.user or not task.input.user.id:
                     raise ValueError("MCP server with OAuth authentication detected but user id not set on the task (task.input.user.id)")
                 
-                auth_result: MCPOAuthGetTokenResponse = await authenticate_mcp_server(mcp_server=mcp,task=task,user_id=task.input.user.id)
+                auth_result: MCPOAuthGetTokenResponse = await authenticate_mcp_server(mcp_server=mcp,task=task,user_id=task.input.user.id, auth_events_callback=auth_events_callback)
                 if not auth_result:
                     raise ValueError("MCP Server authentication failed")
                 if auth_result.type != MCPOAuthResponseType.TOKEN_READY:

xpander_sdk/modules/backend/frameworks/dispatch.py

@@ -10,6 +10,7 @@ async def dispatch_get_args(
     override: Optional[Dict[str, Any]] = None,
     tools: Optional[List[Callable]] = None,
     is_async: Optional[bool] = True,
+    auth_events_callback: Optional[Callable] = None,
 ) -> Dict[str, Any]:
     """
     Dispatch to the correct framework-specific argument resolver.
@@ -20,6 +21,7 @@ async def dispatch_get_args(
         override (Optional[Dict[str, Any]]): Dict of override values.
         tools (Optional[List[Callable]]): Optional additional tools to be added to the agent arguments.
         is_async (Optional[bool]): Is in Async Context?.
+        auth_events_callback (Optional[Callable]): Optional callback function (async or sync) that receives (agent, task, event) for authentication events only.
 
     Returns:
         Dict[str, Any]: Arguments for instantiating the framework agent.
@@ -28,7 +30,7 @@ async def dispatch_get_args(
     match agent.framework:
         case Framework.Agno:
             from .agno import build_agent_args
-            return await build_agent_args(xpander_agent=agent, task=task, override=override, tools=tools, is_async=is_async)
+            return await build_agent_args(xpander_agent=agent, task=task, override=override, tools=tools, is_async=is_async, auth_events_callback=auth_events_callback)
         # case Framework.Langchain: # PLACEHOLDER
         #     from .langchain import build_agent_args
         #     return await build_agent_args(xpander_agent=agent, task=task, override=override)

xpander_sdk/modules/backend/utils/mcp_oauth.py

@@ -1,30 +1,47 @@
 import asyncio
 from datetime import datetime, timezone
+from typing import Callable, Optional
 from loguru import logger
 from xpander_sdk.consts.api_routes import APIRoute
 from xpander_sdk.core.xpander_api_client import APIClient
 from xpander_sdk.models.events import TaskUpdateEventType
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
 from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
 from xpander_sdk.modules.tools_repository.models.mcp import MCPOAuthGetTokenGenericResponse, MCPOAuthGetTokenResponse, MCPOAuthResponseType, MCPServerDetails
+from xpander_sdk.modules.backend.events_registry import EventsRegistry
 
 POLLING_INTERVAL = 1 # every 1s
 MAX_WAIT_FOR_LOGIN = 600 # 10 mintutes
 
-async def push_event(task: Task, event: TaskUpdateEvent, event_type: TaskUpdateEventType):
+async def push_event(task: Task, event: TaskUpdateEvent, event_type: TaskUpdateEventType, auth_events_callback: Optional[Callable] = None):
     client = APIClient(configuration=task.configuration)
+    
+    evt = TaskUpdateEvent(
+        task_id=task.id,
+        organization_id=task.organization_id,
+        time=datetime.now(timezone.utc).isoformat(),
+        type=event_type,
+        data=event
+    )
+    
     await client.make_request(
         path=APIRoute.PushExecutionEventToQueue.format(task_id=task.id),
         method="POST",
-        payload=[
-            TaskUpdateEvent(
-                task_id=task.id,
-                organization_id=task.organization_id,
-                time=datetime.now(timezone.utc).isoformat(),
-                type=event_type,
-                data=event
-                ).model_dump_safe()
-            ]
+        payload=[evt.model_dump_safe()]
     )
+    
+    # Invoke both explicit callback and registered handlers
+    # 1. Call explicit callback if provided
+    if auth_events_callback:
+        if asyncio.iscoroutinefunction(auth_events_callback):
+            await auth_events_callback(task.configuration.state.agent, task, evt)
+        else:
+            auth_events_callback(task.configuration.state.agent, task, evt)
+    
+    # 2. Always invoke registered handlers from EventsRegistry
+    registry = EventsRegistry()
+    if registry.has_auth_handlers():
+        await registry.invoke_auth_handlers(task.configuration.state.agent, task, evt)
 
 async def get_token(mcp_server: MCPServerDetails, task: Task, user_id: str) -> MCPOAuthGetTokenResponse:
     client = APIClient(configuration=task.configuration)
@@ -39,7 +56,7 @@ async def get_token(mcp_server: MCPServerDetails, task: Task, user_id: str) -> M
     
     return None
 
-async def authenticate_mcp_server(mcp_server: MCPServerDetails, task: Task, user_id: str) -> MCPOAuthGetTokenResponse:
+async def authenticate_mcp_server(mcp_server: MCPServerDetails, task: Task, user_id: str, auth_events_callback: Optional[Callable] = None) -> MCPOAuthGetTokenResponse:
     try:
         logger.info(f"Authenticating MCP Server {mcp_server.url}")
         
@@ -59,7 +76,7 @@ async def authenticate_mcp_server(mcp_server: MCPServerDetails, task: Task, user
         if result.type == MCPOAuthResponseType.LOGIN_REQUIRED:
             logger.info(f"Initiating login for MCP Server {mcp_server.url}")
             # Notify user about login requirement
-            await push_event(task=task, event=result, event_type=TaskUpdateEventType.AuthEvent)
+            await push_event(task=task, event=result, event_type=TaskUpdateEventType.AuthEvent, auth_events_callback=auth_events_callback)
             
             # Poll for token with timeout
             elapsed_time = 0
@@ -73,7 +90,7 @@ async def authenticate_mcp_server(mcp_server: MCPServerDetails, task: Task, user
                     logger.info(f"Successful login for MCP Server {mcp_server.url}")
                     redacted_token_result = MCPOAuthGetTokenResponse(**token_result.model_dump_safe())
                     redacted_token_result.data.access_token = "REDACTED"
-                    await push_event(task=task, event=redacted_token_result, event_type=TaskUpdateEventType.AuthEvent)
+                    await push_event(task=task, event=redacted_token_result, event_type=TaskUpdateEventType.AuthEvent, auth_events_callback=auth_events_callback)
                     return token_result
             
             # Timeout reached
@@ -83,7 +100,7 @@ async def authenticate_mcp_server(mcp_server: MCPServerDetails, task: Task, user
             logger.info(f"Token ready for MCP Server {mcp_server.url}")
             redacted_token_result = MCPOAuthGetTokenResponse(**result.model_dump_safe())
             redacted_token_result.data.access_token = "REDACTED"
-            await push_event(task=task, event=redacted_token_result, event_type=TaskUpdateEventType.AuthEvent)
+            await push_event(task=task, event=redacted_token_result, event_type=TaskUpdateEventType.AuthEvent, auth_events_callback=auth_events_callback)
         
         return result
     except Exception as e:

xpander_sdk/modules/tools_repository/sub_modules/tool.py

@@ -386,19 +386,21 @@ class Tool(XPanderSharedModel):
                     ) from validation_error
 
             if self.is_local:
-                await self.agraph_preflight_check(
-                    agent_id=agent_id,
-                    agent_version=agent_version,
-                    configuration=configuration,
-                    task_id=task_id,
-                )
-
                 if self.fn is None:
                     raise RuntimeError(
                         f"No local function provided for this tool ({self.id})."
                     )
 
                 result = await invoke_local_fn(fn=self.fn, payload=payload)
+                
+                await self.agraph_preflight_check(
+                    agent_id=agent_id,
+                    agent_version=agent_version,
+                    configuration=configuration,
+                    task_id=task_id,
+                    payload={"input": payload, "output": result.model_dump() if isinstance(result, BaseModel) else result}
+                )
+                
                 tool_invocation_result.result = result
                 tool_invocation_result.is_success = True
                 return tool_invocation_result

{xpander_sdk-2.0.177.dist-info → xpander_sdk-2.0.179.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.177
+Version: 2.0.179
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI
@@ -293,6 +293,89 @@ async for event in task.aevents():
     print(f"Event Data: {event.data}")
 ```
 
+### Authentication Events Callback
+
+Handle authentication events in real-time. This callback is triggered only for authentication flows (e.g., MCP OAuth requiring user login).
+
+**You can use both approaches simultaneously** - decorated handlers will always be invoked, and you can also pass an explicit callback for additional handling.
+
+You can provide the callback in two ways:
+
+#### Option 1: Direct Function
+
+```python
+from xpander_sdk import Backend
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
+from agno.agent import Agent as AgnoAgent
+
+# Define event callback (async or sync)
+async def my_event_callback(agent: Agent, task: Task, event: TaskUpdateEvent):
+    """Called for authentication events only"""
+    # event.type will always be "auth_event"
+    print(f"Authentication required: {event.data}")
+    # Display login URL or handle OAuth flow
+
+# Get args with callback
+backend = Backend(configuration=config)
+args = await backend.aget_args(
+    agent_id="agent-123",
+    task=my_task,
+    auth_events_callback=my_event_callback
+)
+```
+
+#### Option 2: Decorator (Auto-registered)
+
+```python
+from xpander_sdk import Backend, on_auth_event
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
+from agno.agent import Agent as AgnoAgent
+
+# Use decorator - auto-registers globally
+@on_auth_event
+async def handle_auth(agent: Agent, task: Task, event: TaskUpdateEvent):
+    # event.type will always be "auth_event"
+    print(f"Authentication required for {agent.name}")
+    print(f"Auth data: {event.data}")
+
+# Decorated handler is automatically invoked - no need to pass it
+backend = Backend(configuration=config)
+args = await backend.aget_args(
+    agent_id="agent-123",
+    task=my_task
+)
+```
+
+#### Option 3: Combine Both
+
+```python
+from xpander_sdk import Backend, on_auth_event
+
+# Global handler for all auth events
+@on_auth_event
+async def log_auth(agent, task, event):
+    print(f"[GLOBAL] Auth event for {agent.name}")
+
+# Additional one-time handler
+async def custom_handler(agent, task, event):
+    print(f"[CUSTOM] Specific handling for this call")
+
+# Both handlers will be invoked
+args = await backend.aget_args(
+    agent_id="agent-123",
+    auth_events_callback=custom_handler  # Optional additional callback
+)
+
+# Use with Agno
+agno_agent = AgnoAgent(**args)
+result = await agno_agent.arun(
+    input="Process this data",
+    stream=True
+)
+```
+
 ### Task Activity Monitoring
 
 ```python

{xpander_sdk-2.0.177.dist-info → xpander_sdk-2.0.179.dist-info}/RECORD

@@ -1,4 +1,4 @@
-xpander_sdk/__init__.py,sha256=subqRII3DHqi4FYdWS11fuliCXiOttOrd57m6zTW7pY,2671
+xpander_sdk/__init__.py,sha256=ETLxETELJT1j5Q4xL7sWC-Kz4FRps8IvLoYexNCDqcs,2760
 xpander_sdk/consts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/consts/api_routes.py,sha256=dKUruLanvprTxZO15fR4OWe6ck8JQ8y64XmUJxsbeJY,2278
 xpander_sdk/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -27,13 +27,16 @@ xpander_sdk/modules/agents/sub_modules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JC
 xpander_sdk/modules/agents/sub_modules/agent.py,sha256=ALAHTlzIt6Rpgz6wkkAfmJKsh8QYZ2WDbCiFMyUB6OU,36246
 xpander_sdk/modules/agents/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/modules/agents/utils/generic.py,sha256=XbG4OeHMQo4gVYCsasMlW_b8OoqS1xL3MlUZSjXivu0,81
-xpander_sdk/modules/backend/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xpander_sdk/modules/backend/backend_module.py,sha256=wYghMuNXEtXgoyMXBgbMhgE7wYcbRwXJcpEyybF30kA,18927
+xpander_sdk/modules/backend/__init__.py,sha256=-NjikuZgHBhOM9xHML2vKsG0ICX9S2RKHktrWaODCBE,171
+xpander_sdk/modules/backend/backend_module.py,sha256=A8NW5QqVy28O-E5eL1VU2iUHgtxyz7rFN7Ih0Jnv-TE,21713
+xpander_sdk/modules/backend/events_registry.py,sha256=d0V-lsz3I3G1QB643EM1i-a5oJCiHnEfqBY_SmN2WrE,5983
+xpander_sdk/modules/backend/decorators/__init__.py,sha256=ub9c8G0Ll6AuCvfcFB6rqR8iamMJxtcW7QjWw3WSkPU,106
+xpander_sdk/modules/backend/decorators/on_auth_event.py,sha256=Xt_x9nncujMcF_SgM5hG6M-iZ6B-rDS97EPmgZkGdMk,4715
 xpander_sdk/modules/backend/frameworks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xpander_sdk/modules/backend/frameworks/agno.py,sha256=6rBi-3wUPmSd5n1hFdhigjiLZ8jM5clLXaxwKiKxOWA,41159
-xpander_sdk/modules/backend/frameworks/dispatch.py,sha256=5dP4c37C42U53VjM2kkwIRwEw1i0IN3G0YESHH7J3OE,1557
+xpander_sdk/modules/backend/frameworks/agno.py,sha256=N5XCXIo81MRhg4GVtB5NofbXiu_EDJC_Av_rCabZA-Y,41394
+xpander_sdk/modules/backend/frameworks/dispatch.py,sha256=ht9hT5-cHATofQbWsbWeTARx51Hne3TNNNjw6KECRtA,1814
 xpander_sdk/modules/backend/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xpander_sdk/modules/backend/utils/mcp_oauth.py,sha256=slmrtpjGM__g7mkhvnY9yNRtGHS-fDcLH82rIkBKxkA,4527
+xpander_sdk/modules/backend/utils/mcp_oauth.py,sha256=K80bLjFW66TXm-wz5mbtZEeKjpeYr6ezhMFb5r3bhXA,5468
 xpander_sdk/modules/events/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/modules/events/events_module.py,sha256=DVlho7JxT6Jy8GeyuSakswmYwR18xqO2JcCJ-8Zc3s8,25317
 xpander_sdk/modules/events/decorators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -71,7 +74,7 @@ xpander_sdk/modules/tools_repository/models/__init__.py,sha256=47DEQpj8HBSa-_TIm
 xpander_sdk/modules/tools_repository/models/mcp.py,sha256=qGpaiXKiuXw6gAcK8CW6ek6FkZNbBxDXUf1PWF6Tenw,1863
 xpander_sdk/modules/tools_repository/models/tool_invocation_result.py,sha256=Dhowt_fv8v8xWv7xMRJxo6hA8DawXKbWIrsJFMpt5H4,447
 xpander_sdk/modules/tools_repository/sub_modules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xpander_sdk/modules/tools_repository/sub_modules/tool.py,sha256=YUf267PRXtctpPydpQTTnaO3aliSJwapM3WsdGG06Pw,22365
+xpander_sdk/modules/tools_repository/sub_modules/tool.py,sha256=ylSVfekQQd0vPCKXPWN67tlkyVT7R4WsSQtoEZcBETw,22521
 xpander_sdk/modules/tools_repository/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/modules/tools_repository/utils/generic.py,sha256=m9FRaVGzRUj23tB52rP9K4O-nTsMSt9iwMxMcYsqfiY,1770
 xpander_sdk/modules/tools_repository/utils/local_tools.py,sha256=zp5P8hVnRUJQb-w-2jCEMV5eUB_awmvYfY_rin5qvEw,1875
@@ -83,8 +86,8 @@ xpander_sdk/utils/generic.py,sha256=XrRj2-L8c0YWpfPdDyXE-pVL-6lKF9VpyZzKHQ4wuCc,
 xpander_sdk/utils/tools.py,sha256=lyFkq2yP7DxBkyXYVlnFRwDhQCvf0fZZMDm5fBycze4,1244
 xpander_sdk/utils/agents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/utils/agents/compactization_agent.py,sha256=pqaf7LVSyPFaeXU62dMPY6iQ160TFga1KJ0Kgu1dIgg,14449
-xpander_sdk-2.0.177.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-xpander_sdk-2.0.177.dist-info/METADATA,sha256=GkvjGLP9bKCx0eAFqpDmWBxc3ooZoizCbKHJRbd-cnw,15339
-xpander_sdk-2.0.177.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-xpander_sdk-2.0.177.dist-info/top_level.txt,sha256=UCjnxQpsMy5Zoe7lmRuVDO6DI2V_6PgRFfm4oizRbVs,12
-xpander_sdk-2.0.177.dist-info/RECORD,,
+xpander_sdk-2.0.179.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+xpander_sdk-2.0.179.dist-info/METADATA,sha256=6dcIt4ajwKjEFSmOUqg8MgzDwe7hXeEnckKXKAnxohc,17880
+xpander_sdk-2.0.179.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+xpander_sdk-2.0.179.dist-info/top_level.txt,sha256=UCjnxQpsMy5Zoe7lmRuVDO6DI2V_6PgRFfm4oizRbVs,12
+xpander_sdk-2.0.179.dist-info/RECORD,,