xpander-sdk 2.0.144__py3-none-any.whl → 2.0.192__py3-none-any.whl

xpander_sdk/modules/backend/frameworks/agno.py

@@ -1,24 +1,27 @@
 import asyncio
+import json
 import shlex
 from os import getenv, environ
 from typing import Any, Callable, Dict, List, Optional
 
 from loguru import logger
-
+from toon import encode as toon_encode
 from xpander_sdk import Configuration
 from xpander_sdk.models.shared import OutputFormat, ThinkMode
 from xpander_sdk.modules.agents.agents_module import Agents
-from xpander_sdk.modules.agents.models.agent import AgentGraphItemType
+from xpander_sdk.modules.agents.models.agent import AgentGraphItemType, LLMReasoningEffort
 from xpander_sdk.modules.agents.sub_modules.agent import Agent
 from xpander_sdk.modules.backend.utils.mcp_oauth import authenticate_mcp_server
 from xpander_sdk.modules.tasks.sub_modules.task import Task
 from xpander_sdk.modules.tools_repository.models.mcp import (
+    MCPOAuthGetTokenGenericResponse,
     MCPOAuthGetTokenResponse,
     MCPOAuthResponseType,
     MCPServerAuthType,
     MCPServerTransport,
     MCPServerType,
 )
+from xpander_sdk.modules.tools_repository.models.tool_invocation_result import ToolInvocationResult
 from xpander_sdk.modules.tools_repository.sub_modules.tool import Tool
 from xpander_sdk.modules.tools_repository.utils.schemas import build_model_from_schema
 from agno.agent import Agent as AgnoAgent
@@ -34,13 +37,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)
@@ -53,7 +57,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:
@@ -100,7 +104,7 @@ async def build_agent_args(
         # convert to members
         members = await asyncio.gather(
             *[
-                build_agent_args(xpander_agent=sub_agent, override=override, task=task)
+                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
             ]
         )
@@ -108,7 +112,7 @@ async def build_agent_args(
         args.update(
             {
                 "members": [
-                    AgnoAgent(**member) if "id" in member else AgnoTeam(**member)
+                    AgnoAgent(**member) if "members" not in member else AgnoTeam(**member)
                     for member in members
                 ],
                 "add_member_tools_to_context": True,
@@ -199,6 +203,19 @@ async def build_agent_args(
             except Exception:
                 pass
 
+        # try toon optimization if compression enabled
+        if xpander_agent and xpander_agent and xpander_agent.agno_settings and xpander_agent.agno_settings.tool_calls_compression and xpander_agent.agno_settings.tool_calls_compression.enabled and not function_name.startswith("xp"):
+            try:
+                if isinstance(result, ToolInvocationResult):
+                    json_result = json.loads(result.result) if isinstance(result.result, str) else result.result
+                    result.result = toon_encode(json_result)
+                elif hasattr(result, "content"):
+                    json_result = json.loads(result.content)
+                    result.content = toon_encode(json_result)
+            except Exception:
+                pass
+    
+        
         # Return the result
         return result
 
@@ -213,10 +230,349 @@ async def build_agent_args(
     if args["model"] and args["model"].id and args["model"].id.startswith("gpt-5"):
         del args["model"].temperature
     
+    # configure deep planning guidance
+    _configure_deep_planning_guidance(args=args, agent=xpander_agent, task=task)
     return args
 
+def _configure_deep_planning_guidance(args: Dict[str, Any], agent: Agent, task: Optional[Task]) -> None:
+    if args and agent and task and agent.deep_planning and task.deep_planning.enabled == True:
+        task.reload() # reload the task - get latest version
+        # add instructions guidance
+        if not "instructions" in args:
+            args["instructions"] = ""
+        
+        args["instructions"] += """\n
+            <important_planning_instructions>
+            ## **Deep Planning Tools - Essential for Multi-Step Tasks**
+
+            **ABSOLUTE RULE - READ THIS FIRST**:
+            
+            IF YOU ARE ABOUT TO WRITE A QUESTION TO THE USER, STOP AND CHECK:
+            - Did I call xpstart_execution_plan? 
+              - YES → Use xpask_for_information tool (DO NOT write the question in your response)
+              - NO → You can ask directly
+            
+            SIMPLE RULE:
+            - BEFORE calling xpstart_execution_plan: You CAN ask questions directly in your response
+            - AFTER calling xpstart_execution_plan: You are FORBIDDEN from writing questions - use xpask_for_information tool
+            
+            Once execution has started, writing things like "Before I proceed, I need to know..." or "I need clarification on..."
+            or "Please choose one of the following..." in your response text is STRICTLY PROHIBITED and will cause execution failures.
+            
+            MANDATORY CHECK BEFORE ASKING: Have I started the plan? YES = use tool | NO = can ask directly
+
+            When handling complex tasks with multiple steps, use these planning tools to track progress systematically.
+
+            ### **Core Workflow**
+            1. **CREATE** plan at the start (`xpcreate_agent_plan`)
+            2. **START** plan execution (`xpstart_execution_plan`) - MANDATORY to enable enforcement
+            3. **CHECK** plan before each action (`xpget_agent_plan`) - note the FULL UUID of the task you'll work on
+            4. **DO THE WORK** for one task
+            5. **COMPLETE** task IMMEDIATELY - call `xpcomplete_agent_plan_items` with the FULL UUID RIGHT AFTER finishing work (DO NOT DELAY!)
+            6. **ASK** user for info if needed (`xpask_for_information`) - MANDATORY if you need input or want to pause
+            7. Repeat steps 3-6 until all tasks are done
+            
+            **UUID REQUIREMENT**: All task IDs are full UUIDs (e.g., '35f56b8e-1427-4a5e-a1c0-57a4f7ec8e92'). You MUST use the exact complete UUID string from the plan when marking tasks complete.
+            
+            **CRITICAL RULES - ABSOLUTE REQUIREMENTS**: 
+            - Mark each task complete THE MOMENT you finish it - not later, not at the end, RIGHT AWAY!
+            - **CHECK BEFORE ASKING**: Did you call xpstart_execution_plan?
+              - If YES: Use xpask_for_information tool ONLY (never write questions in response)
+              - If NO: Can ask directly
+            - **AFTER plan starts: Writing questions in your response is FORBIDDEN** - violates execution protocol
+            - If you called xpstart_execution_plan and then write "I need clarification" or "Before I proceed" or "Please choose", you are VIOLATING THE PROTOCOL
+            - AFTER xpstart_execution_plan: The ONLY way to ask users questions is through `xpask_for_information` tool - ZERO EXCEPTIONS!
+
+            ---
+
+            ### **Tool Reference**
+
+            #### **1. xpcreate_agent_plan** - Create Initial Plan
+            **When to use**: At the very start of any multi-step task, ONLY if no plan exists yet
+            **Note**: After creating a plan, you MUST call `xpstart_execution_plan` to begin enforcement
+
+            **How to use**:
+            - Pass an array of task objects (NOT strings)
+            - Each task must have a `title` field with short, explanatory description
+            - Example format:
+            ```json
+            {
+            "body_params": {
+                "tasks": [
+                {"title": "Research API requirements"},
+                {"title": "Design data schema"},
+                {"title": "Implement endpoints"},
+                {"title": "Write tests"},
+                {"title": "Deploy to staging"}
+                ]
+            }
+            }
+            ```
+            **Important**: 
+            - Include ALL steps needed from start to finish
+            - Each title should be clear and actionable (3-6 words)
+            - Do NOT pass plain strings like `["Task 1", "Task 2"]` - must be objects!
+
+            ---
+
+            #### **2. xpget_agent_plan** - View Current Plan
+            **When to use**: Before deciding what to do next; to check progress
+
+            **Returns**: 
+            - All tasks with their IDs, titles, and completion status
+            - Use this to know what's done and what remains
+
+            **No parameters needed** - just call the tool
+
+            ---
+
+            #### **3. xpcomplete_agent_plan_items** - Mark Task(s) Complete
+            **When to use**: **IMMEDIATELY** after finishing one or more tasks (NOT before, NOT later, RIGHT NOW!)
+
+            **How to use**:
+            ```json
+            // Single task
+            {
+            "body_params": {
+                "ids": ["35f56b8e-1427-4a5e-a1c0-57a4f7ec8e92"]
+            }
+            }
+            
+            // Multiple tasks (when finishing related tasks together)
+            {
+            "body_params": {
+                "ids": ["35f56b8e-1427-4a5e-a1c0-57a4f7ec8e92", "8a3c4f12-9b7e-4d2a-b5c8-1f6e9a0d3b4c", "f2b9d1c7-3e8a-4b6f-9d2c-5a7e1f4b8c3d"]
+            }
+            }
+            ```
+            **🚨 CRITICAL - NON-NEGOTIABLE RULES**: 
+            - IDs must be the FULL UUID strings (e.g., '35f56b8e-1427-4a5e-a1c0-57a4f7ec8e92') from the plan's 'id' field
+            - Get these exact UUID strings from xpget_agent_plan before calling this tool
+            - Call THIS TOOL the INSTANT you finish task(s)
+            - Can mark single or multiple tasks complete in one call
+            - Use multiple FULL UUIDs when finishing related tasks at the same time
+            - DO NOT use shortened IDs, abbreviations, or partial UUIDs - must be complete UUID strings
+            - DO NOT postpone marking completion
+            - DO NOT be lazy - mark it complete RIGHT AFTER the work is done
+            - This is MANDATORY for progress tracking and continuation
+            - If you finish a task and don't mark it complete immediately, you are doing it WRONG
+            
+            **Pattern**: Finish work → Get task UUID from plan → IMMEDIATELY call xpcomplete_agent_plan_items with FULL UUID → Move to next task
+
+            ---
+
+            #### **4. xpadd_new_agent_plan_item** - Add Discovered Task
+            **When to use**: When you discover additional work needed during execution
+
+            **How to use**:
+            ```json
+            {
+            "body_params": {
+                "title": "Validate input schemas",
+                "completed": false
+            }
+            }
+            ```
+            ---
+
+            #### **5. xpupdate_agent_plan_item** - Modify Existing Task
+            **When to use**: When task details change or need clarification
+
+            **How to use**:
+            ```json
+            {
+            "body_params": {
+                "id": "task-uuid",
+                "title": "Updated description",
+                "completed": true
+            }
+            }
+            ```
+            (All fields optional except `id`)
+
+            ---
 
-def _load_llm_model(agent: Agent, override: Optional[Dict[str, Any]]) -> Any:
+            #### **6. xpdelete_agent_plan_item** - Remove Task
+            **When to use**: When a task becomes unnecessary or redundant
+
+            **How to use**:
+            ```json
+            {
+            "body_params": {
+                "id": "task-uuid"
+            }
+            }
+            ```
+            ---
+
+            #### **7. xpstart_execution_plan** - Start Plan Execution
+            **When to use**: Immediately after creating a plan with `xpcreate_agent_plan`
+            **CRITICAL**: Must be called to enable enforcement mode before executing tasks
+
+            **How to use**:
+            ```json
+            {
+            "body_params": {}
+            }
+            ```
+            **No parameters needed** - just call after plan creation
+
+            **What it does**:
+            - Marks plan as "started" 
+            - Enables enforcement mode if `enforce` flag is true
+            - Allows plan execution to proceed
+
+            ---
+
+            #### **8. xpask_for_information** - Ask User a Question
+            **When to use**: **MANDATORY AFTER PLAN STARTS** when you need ANY of the following:
+            - Information from the user
+            - Clarification on requirements
+            - Approval before proceeding
+            - To pause execution for user input
+            
+            **PREREQUISITE**: Plan must be started (running) first
+            
+            **CRITICAL RULE**: Once the plan has started, if you need user input or want to pause, you MUST use this tool.
+            DO NOT just respond with questions in your regular output after plan starts - that breaks execution flow!
+            
+            **NOTE**: BEFORE starting the plan (before xpstart_execution_plan), you CAN ask questions directly if needed.
+
+            **How to use**:
+            ```json
+            {
+            "body_params": {
+                "question": "What is the customer email address?"
+            }
+            }
+            ```
+
+            **What it does**:
+            - Properly pauses plan enforcement and sets `question_raised` flag
+            - Delivers question to the user through the correct channel
+            - Manages execution state for proper continuation
+            - Allows resuming execution after user responds
+            
+            **Why this matters**: Using this tool ensures execution can be properly continued with full context.
+            Just responding with a question will NOT pause execution correctly!
+
+            ---
+
+            ### **Best Practices**
+
+            ✅ **DO:**
+            - Create comprehensive plans with ALL necessary steps
+            - **START** the plan with `xpstart_execution_plan` after creating it
+            - Use descriptive, actionable task titles
+            - Check plan before each action to stay oriented
+            - **Always use FULL UUID strings when marking tasks complete** (e.g., '35f56b8e-1427-4a5e-a1c0-57a4f7ec8e92')
+            - **Get the exact UUID from xpget_agent_plan** - copy the full 'id' field value
+            - **Mark tasks complete THE INSTANT you finish them - NO DELAYS, NO EXCEPTIONS**
+            - **Can mark multiple tasks at once if finished together** (e.g., related tasks done simultaneously)
+            - **ALWAYS use `xpask_for_information` when you need user input or want to pause**
+            - Call plan tools **sequentially** (one at a time, never in parallel)
+            - Follow the pattern: DO WORK → GET UUID → MARK COMPLETE WITH FULL UUID → NEXT TASK
+
+            ❌ **DON'T - THESE ARE FORBIDDEN:**
+            - Mark tasks complete before they're actually done
+            - **Use shortened, partial, or abbreviated task IDs** - MUST use complete UUID strings!
+            - **Use made-up or guessed UUIDs** - MUST get exact UUID from xpget_agent_plan!
+            - **Be lazy and wait to mark tasks complete later** (FORBIDDEN!)
+            - **Postpone marking completion to batch at the end** (WRONG! Mark immediately when done!)
+            - **AFTER plan starts: NEVER write questions in your response text** ("Before I proceed...", "I need clarification...", etc.)
+            - **AFTER plan starts: NEVER respond with questions - ONLY use xpask_for_information tool** (ABSOLUTE RULE!)
+            - Pass plain string arrays - must be objects with `title` field
+            - Call plan tools in parallel with each other
+            - Skip checking the plan between major steps
+            - Postpone marking completion "until later" - there is no later, only NOW
+            
+            **REMEMBER**: Once execution started, any text like "I need to know", "Before I proceed", "I need clarification" means you MUST call xpask_for_information instead!
+            **EXCEPTION**: Before starting the plan, you CAN ask questions directly if needed for planning.
+
+            ---
+
+            ### **Example Complete Workflow**
+
+            ```
+            1. User: "Build a REST API for user management"
+
+            2. Call: xpcreate_agent_plan
+            tasks: [
+                {"title": "Design user schema"},
+                {"title": "Create database migration"},
+                {"title": "Implement CRUD endpoints"},
+                {"title": "Add authentication"},
+                {"title": "Write integration tests"}
+            ]
+
+            3. Call: xpstart_execution_plan
+            → Plan now started, enforcement enabled (if enforce=true)
+
+            4. Call: xpget_agent_plan
+            → See: Task 1 (ID: 35f56b8e-1427-4a5e-a1c0-57a4f7ec8e92) - Design user schema - Not complete
+
+            5. [Realize need user input] Call: xpask_for_information
+            question: "Which database should we use - PostgreSQL or MySQL?"
+            → question_raised=true, waiting for response
+
+            6. [After user responds, DO THE WORK: Design schema]
+
+            7. ⚠️ IMMEDIATELY Call: xpcomplete_agent_plan_items
+            ids: ["35f56b8e-1427-4a5e-a1c0-57a4f7ec8e92"]
+            → MARKED COMPLETE RIGHT AFTER FINISHING - NOT DELAYED! Used FULL UUID from plan!
+
+            8. Call: xpget_agent_plan
+            → See: Task 1 ✓ complete, Task 2 (ID: 8a3c4f12-9b7e-4d2a-b5c8-1f6e9a0d3b4c) - Create database migration - Not complete
+
+            9. [DO THE WORK: Create migration file]
+
+            10. ⚠️ IMMEDIATELY Call: xpcomplete_agent_plan_items
+            ids: ["8a3c4f12-9b7e-4d2a-b5c8-1f6e9a0d3b4c"]
+            → MARKED COMPLETE RIGHT AWAY! Used FULL UUID from plan!
+            
+            // Alternative: If tasks 3 and 4 are done together, can batch complete:
+            11a. [DO THE WORK: Implement endpoints AND add auth together]
+            11b. ⚠️ IMMEDIATELY Call: xpcomplete_agent_plan_items
+            ids: ["f2b9d1c7-3e8a-4b6f-9d2c-5a7e1f4b8c3d", "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"]
+            → Both marked complete at once! Used FULL UUIDs from plan!
+
+            12. [Continue this pattern: GET PLAN → DO WORK → MARK COMPLETE IMMEDIATELY → REPEAT]
+            ```
+            
+            ### **WRONG WAY - ANTI-PATTERN (DO NOT DO THIS)**
+            
+            ```
+            ❌ WRONG:
+            1. Call: xpcreate_agent_plan
+            2. Call: xpstart_execution_plan  ← PLAN IS NOW STARTED!
+            3. Respond: "Before I proceed, I need clarification on..."  ← WRONG! FORBIDDEN!
+            
+            ✅ CORRECT:
+            1. Call: xpcreate_agent_plan
+            2. Call: xpstart_execution_plan  ← PLAN IS NOW STARTED!
+            3. Call: xpask_for_information with question  ← CORRECT! Use the tool!
+            ```
+            
+            **KEY POINT**: Once you call `xpstart_execution_plan`, the execution mode changes.
+            You CANNOT write questions in your response anymore. You MUST use the tool.
+            
+            **Golden Rule**: FINISH TASK → MARK COMPLETE INSTANTLY → MOVE TO NEXT TASK. No delays, no batching, no "I'll do it later"!
+            </important_planning_instructions>
+        """
+        
+        # add the expected output guidance
+        if not "expected_output" in args:
+            args["expected_output"] = ""
+        args["expected_output"] += "\nAll planned tasks completed and marked as done."
+        
+        # add the plan to additional_context
+        if not "additional_context" in args:
+            args["additional_context"] = ""
+        
+        plan_str = task.deep_planning.model_dump_json() if task.deep_planning and task.deep_planning.enabled and len(task.deep_planning.tasks) != 0 else "No execution plan, please generate"
+        args["additional_context"] += f" \n Current execution plan: {plan_str}"
+
+def _load_llm_model(agent: Agent, override: Optional[Dict[str, Any]] = {}) -> Any:
     """
     Load and configure the appropriate LLM model based on the agent's provider configuration.
 
@@ -278,6 +634,10 @@ def _load_llm_model(agent: Agent, override: Optional[Dict[str, Any]]) -> Any:
             return env_llm_key or agent.llm_credentials.value
 
     llm_args = {}
+    
+    if agent.llm_reasoning_effort and agent.llm_reasoning_effort != LLMReasoningEffort.Medium and agent.model_name and "gpt-5" in agent.model_name.lower():
+        llm_args = { "reasoning_effort": agent.llm_reasoning_effort.value }
+    
     if agent.llm_api_base and len(agent.llm_api_base) != 0:
         llm_args["base_url"] = agent.llm_api_base
     
@@ -427,7 +787,7 @@ def _configure_tool_calls_compression(
         args["compression_manager"] = CompressionManager(
             compress_tool_results=True,
             compress_tool_results_limit=agent.agno_settings.tool_calls_compression.threshold,
-            compress_tool_call_instructions=agent.agno_settings.tool_calls_compression.instructions,
+            compress_tool_call_instructions="never compress ids, keep them full. "+(agent.agno_settings.tool_calls_compression.instructions if agent.agno_settings.tool_calls_compression.instructions else ""),
         )
 
 def _configure_agentic_memory(
@@ -442,7 +802,7 @@ def _configure_agentic_memory(
         args["memory_manager"] = MemoryManager(delete_memories=True,clear_memories=True)
         args["enable_agentic_memory"] = agent.agno_settings.agentic_memory
     
-    if agent_memories_enabled:
+    if agent_memories_enabled and not agent.is_a_team:
         args["add_culture_to_context"] = True
         
         if agent.agno_settings.agentic_culture:
@@ -533,7 +893,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
@@ -579,6 +939,7 @@ async def _resolve_agent_tools(agent: Agent, task: Optional[Task] = None) -> Lis
                     ),
                     include_tools=mcp.allowed_tools or None,
                     timeout_seconds=120,
+                    tool_name_prefix="mcp_tool"
                 )
             )
         elif mcp.url:
@@ -596,7 +957,9 @@ 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 auth_result and auth_result.data and isinstance(auth_result.data, MCPOAuthGetTokenGenericResponse) and auth_result.data.message:
+                    raise ValueError(f"MCP authentication failed: {auth_result.data.message}")
                 if not auth_result:
                     raise ValueError("MCP Server authentication failed")
                 if auth_result.type != MCPOAuthResponseType.TOKEN_READY:
@@ -612,10 +975,9 @@ async def _resolve_agent_tools(agent: Agent, task: Optional[Task] = None) -> Lis
                     transport=transport,
                     server_params=params_cls(url=mcp.url, headers=mcp.headers),
                     include_tools=mcp.allowed_tools or None,
-                    timeout_seconds=120
+                    timeout_seconds=120,
+                    tool_name_prefix="mcp_tool"
                 )
             )
 
-    return agent.tools.functions + await asyncio.gather(
-        *[mcp.__aenter__() for mcp in mcp_tools]
-    )
+    return agent.tools.functions + mcp_tools

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,57 +1,69 @@
 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 = 300 # 5 mintutes
+MAX_WAIT_FOR_LOGIN = 600 # 10 mintutes
 
-async def push_event(task: Task, event: TaskUpdateEvent):
+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=TaskUpdateEventType.AuthEvent,
-                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:
+async def get_token(mcp_server: MCPServerDetails, task: Task, user_id: str, return_result: Optional[bool] = False, generate_login_url: Optional[bool] = True) -> MCPOAuthGetTokenResponse:
     client = APIClient(configuration=task.configuration)
     result: MCPOAuthGetTokenResponse = await client.make_request(
         path=APIRoute.GetUserMCPAuthToken.format(agent_id=task.agent_id, user_id=user_id),
         method="POST",
+        query={"generate_login_url": generate_login_url},
         payload=mcp_server.model_dump(),
         model=MCPOAuthGetTokenResponse
     )
-    if result.type == MCPOAuthResponseType.TOKEN_READY:
+    if result.type == MCPOAuthResponseType.TOKEN_READY or return_result:
         return result
     
     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}")
         
         user_identifier = user_id if mcp_server.share_user_token_across_other_agents else f"{task.agent_id}_{user_id}"
         
-        client = APIClient(configuration=task.configuration)
-        result: MCPOAuthGetTokenResponse = await client.make_request(
-            path=APIRoute.GetUserMCPAuthToken.format(agent_id=task.agent_id, user_id=user_identifier),
-            method="POST",
-            payload=mcp_server.model_dump(),
-            model=MCPOAuthGetTokenResponse
-        )
+        result: MCPOAuthGetTokenResponse = await get_token(mcp_server=mcp_server, task=task, user_id=user_identifier, return_result=True)
         
         if not result:
             raise Exception("Invalid response")
@@ -59,7 +71,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)
+            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
@@ -68,12 +80,12 @@ async def authenticate_mcp_server(mcp_server: MCPServerDetails, task: Task, user
                 elapsed_time += POLLING_INTERVAL
                 
                 # Check for token
-                token_result = await get_token(mcp_server=mcp_server, task=task, user_id=user_identifier)
+                token_result = await get_token(mcp_server=mcp_server, task=task, user_id=user_identifier, generate_login_url=False)
                 if token_result and token_result.type == MCPOAuthResponseType.TOKEN_READY:
                     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)
+                    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 +95,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)
+            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/events/decorators/__init__.py

@@ -0,0 +1,3 @@
+from .on_tool import on_tool_before, on_tool_after, on_tool_error
+
+__all__ = ["on_tool_before", "on_tool_after", "on_tool_error"]