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

xpander_sdk/modules/backend/frameworks/agno.py

@@ -1,10 +1,11 @@
 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
@@ -13,12 +14,14 @@ 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
 
@@ -219,6 +236,7 @@ async def build_agent_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"] = ""
@@ -227,23 +245,51 @@ def _configure_deep_planning_guidance(args: Dict[str, Any], agent: Agent, task:
             <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`)
-            4. **COMPLETE** task immediately after finishing it (`xpcomplete-agent-plan-item`)
-            5. **ASK** user for info if needed (`xpask-for-information`)
-            6. Repeat steps 3-5 until all tasks are done
+            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
+            #### **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
+            **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)
@@ -269,7 +315,7 @@ def _configure_deep_planning_guidance(args: Dict[str, Any], agent: Agent, task:
 
             ---
 
-            #### **2. xpget-agent-plan** - View Current Plan
+            #### **2. xpget_agent_plan** - View Current Plan
             **When to use**: Before deciding what to do next; to check progress
 
             **Returns**: 
@@ -280,25 +326,42 @@ def _configure_deep_planning_guidance(args: Dict[str, Any], agent: Agent, task:
 
             ---
 
-            #### **3. xpcomplete-agent-plan-item** - Mark Task Complete
-            **When to use**: **IMMEDIATELY** after finishing each task (NOT before!)
+            #### **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": {
-                "id": "task-uuid-from-plan"
+                "ids": ["35f56b8e-1427-4a5e-a1c0-57a4f7ec8e92", "8a3c4f12-9b7e-4d2a-b5c8-1f6e9a0d3b4c", "f2b9d1c7-3e8a-4b6f-9d2c-5a7e1f4b8c3d"]
             }
             }
             ```
-            **CRITICAL**: 
-            - Only mark complete AFTER work is actually done
-            - This is MANDATORY for progress tracking
-            - Get the task ID from `xpget-agent-plan` results
+            **🚨 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
+            #### **4. xpadd_new_agent_plan_item** - Add Discovered Task
             **When to use**: When you discover additional work needed during execution
 
             **How to use**:
@@ -312,7 +375,7 @@ def _configure_deep_planning_guidance(args: Dict[str, Any], agent: Agent, task:
             ```
             ---
 
-            #### **5. xpupdate-agent-plan-item** - Modify Existing Task
+            #### **5. xpupdate_agent_plan_item** - Modify Existing Task
             **When to use**: When task details change or need clarification
 
             **How to use**:
@@ -329,7 +392,7 @@ def _configure_deep_planning_guidance(args: Dict[str, Any], agent: Agent, task:
 
             ---
 
-            #### **6. xpdelete-agent-plan-item** - Remove Task
+            #### **6. xpdelete_agent_plan_item** - Remove Task
             **When to use**: When a task becomes unnecessary or redundant
 
             **How to use**:
@@ -342,8 +405,8 @@ def _configure_deep_planning_guidance(args: Dict[str, Any], agent: Agent, task:
             ```
             ---
 
-            #### **7. xpstart-execution-plan** - Start Plan Execution
-            **When to use**: Immediately after creating a plan with `xpcreate-agent-plan`
+            #### **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**:
@@ -361,9 +424,19 @@ def _configure_deep_planning_guidance(args: Dict[str, Any], agent: Agent, task:
 
             ---
 
-            #### **8. xpask-for-information** - Ask User a Question
-            **When to use**: When you need information from the user during plan execution
+            #### **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
@@ -375,10 +448,13 @@ def _configure_deep_planning_guidance(args: Dict[str, Any], agent: Agent, task:
             ```
 
             **What it does**:
-            - Sets `question_raised` flag to true
-            - Prints the question for the user
-            - Keeps enforcement active (does NOT pause execution)
-            - Returns waiting status
+            - 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!
 
             ---
 
@@ -386,19 +462,32 @@ def _configure_deep_planning_guidance(args: Dict[str, Any], agent: Agent, task:
 
             ✅ **DO:**
             - Create comprehensive plans with ALL necessary steps
-            - **START** the plan with `xpstart-execution-plan` after creating it
+            - **START** the plan with `xpstart_execution_plan` after creating it
             - Use descriptive, actionable task titles
             - Check plan before each action to stay oriented
-            - Mark tasks complete immediately after finishing them
-            - Ask for user information when needed with `xpask-for-information`
+            - **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:**
+            ❌ **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
-            - Forget to mark completed tasks
+            - 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.
 
             ---
 
@@ -407,7 +496,7 @@ def _configure_deep_planning_guidance(args: Dict[str, Any], agent: Agent, task:
             ```
             1. User: "Build a REST API for user management"
 
-            2. Call: xpcreate-agent-plan
+            2. Call: xpcreate_agent_plan
             tasks: [
                 {"title": "Design user schema"},
                 {"title": "Create database migration"},
@@ -416,27 +505,58 @@ def _configure_deep_planning_guidance(args: Dict[str, Any], agent: Agent, task:
                 {"title": "Write integration tests"}
             ]
 
-            3. Call: xpstart-execution-plan
+            3. Call: xpstart_execution_plan
             → Plan now started, enforcement enabled (if enforce=true)
 
-            4. Call: xpget-agent-plan
-            → See: Task 1 (ID: abc-123) - Design user schema - Not complete
+            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
+            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]
+            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!
 
-            7. Call: xpcomplete-agent-plan-item
-            id: "abc-123"
+            8. Call: xpget_agent_plan
+            → See: Task 1 ✓ complete, Task 2 (ID: 8a3c4f12-9b7e-4d2a-b5c8-1f6e9a0d3b4c) - Create database migration - Not complete
 
-            8. Call: xpget-agent-plan
-            → See: Task 1 ✓ complete, Task 2 next...
+            9. [DO THE WORK: Create migration file]
 
-            9. [Continue through remaining tasks]
+            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)**
+            
             ```
-            **Remember**: The plan is your roadmap. Check it often, update it as needed, and always mark tasks complete when done!
+            ❌ 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>
         """
         
@@ -452,7 +572,7 @@ def _configure_deep_planning_guidance(args: Dict[str, Any], agent: Agent, task:
         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:
+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.
 
@@ -667,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(
@@ -682,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:
@@ -773,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
@@ -837,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:

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 = 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"]