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

xpander_sdk/consts/api_routes.py

@@ -35,6 +35,7 @@ and deleting resources.
     ListTasks = "/agent-execution/executions/history/{agent_id}"
     ListUserTasks = "/agent-execution/executions/history/user/{user_id}"
     GetTask = "/agent-execution/{task_id}/status"
+    GetTaskActivityLog = "/activity/{agent_id}/{task_id}"
     TaskCrud = "/agent-execution/{agent_or_task_id}"
     UpdateTask = "/agent-execution/{task_id}/update"
     ReportExternalTask = "/agent-execution/{agent_id}/report_task"

xpander_sdk/models/activity.py

@@ -0,0 +1,65 @@
+from datetime import datetime
+from enum import Enum
+from typing import Any, List, Literal, Optional, Union
+
+from xpander_sdk.models.events import ToolCallRequestReasoning
+from xpander_sdk.models.shared import XPanderSharedModel
+from xpander_sdk.models.user import User
+from xpander_sdk.modules.tools_repository.models.mcp import MCPOAuthGetTokenResponse
+
+class AgentActivityThreadMessageContent(XPanderSharedModel):
+    text: Optional[str] = None
+    files: Optional[List[str]] = []
+
+class AgentActivityThreadMessage(XPanderSharedModel):
+    id: str
+    created_at: datetime
+    role: Literal["user","agent"]
+    content: AgentActivityThreadMessageContent
+
+class AgentActivityThreadToolCall(XPanderSharedModel):
+    id: str
+    created_at: datetime
+    tool_name: str
+    payload: Any
+    is_error: Optional[bool] = False
+    reasoning: Optional[ToolCallRequestReasoning] = None
+    result: Optional[Any] = None
+
+class AgentActivityThreadReasoningType(str, Enum):
+    Think = "think"
+    Analyze = "analyze"
+
+class AgentActivityThreadReasoning(XPanderSharedModel):
+    id: str
+    created_at: datetime
+    type: AgentActivityThreadReasoningType
+    title: str
+    confidence: float
+    thought: Optional[str] = None
+    action: Optional[str] = None
+    result: Optional[str] = None
+    analysis: Optional[str] = None
+
+class AgentActivityThreadSubAgentTrigger(XPanderSharedModel):
+    id: str
+    created_at: datetime
+    agent_id: str
+    query: Optional[str] = None
+    files: Optional[List[str]] = []
+    reasoning: ToolCallRequestReasoning
+
+class AgentActivityThreadAuth(MCPOAuthGetTokenResponse):
+    id: str
+    created_at: datetime
+
+AgentActivityThreadMessageType = Union[AgentActivityThreadMessage, AgentActivityThreadToolCall, AgentActivityThreadReasoning, AgentActivityThreadSubAgentTrigger, AgentActivityThreadAuth]
+class AgentActivityThread(XPanderSharedModel):
+    id: str
+    created_at: datetime
+    messages: List[AgentActivityThreadMessageType]
+    user: Optional[User] = None
+
+class AgentActivityThreadListItem(XPanderSharedModel):
+    id: str
+    created_at: datetime

xpander_sdk/models/deep_planning.py

@@ -0,0 +1,18 @@
+from typing import List, Optional
+from .shared import XPanderSharedModel
+
+class DeepPlanningItem(XPanderSharedModel):
+    id: str
+    title: str
+    completed: Optional[bool] = False
+
+class DeepPlanning(XPanderSharedModel):
+    enabled: Optional[bool] = False
+    enforce: Optional[bool] = False
+    started: Optional[bool] = False
+    question_raised: Optional[bool] = False
+    tasks: Optional[List[DeepPlanningItem]] = []
+
+class PlanFollowingStatus(XPanderSharedModel):
+    can_finish: bool
+    uncompleted_tasks: Optional[List[DeepPlanningItem]] = []

xpander_sdk/models/events.py

@@ -68,3 +68,6 @@ class TaskUpdateEventType(str, Enum):
     # reasoning
     Think = "think"
     Analyze = "analyze"
+    
+    # deep planning
+    PlanUpdated = "plan_updated"

xpander_sdk/modules/agents/models/agent.py

@@ -383,7 +383,10 @@ class AgentGraphItem(BaseModel):
     llm_settings: Optional[List[AgentGraphItemLLMSettings]] = []
     is_first: Optional[bool] = False
 
-
+class LLMReasoningEffort(str, Enum):
+    Low = "low"
+    Medium = "medium"
+    High = "high"
 
 class AIAgentConnectivityDetailsA2AAuthType(str, Enum):
     NoAuth = "none"

xpander_sdk/modules/agents/sub_modules/agent.py

@@ -40,6 +40,7 @@ from xpander_sdk.modules.agents.models.agent import (
     AgentType,
     DatabaseConnectionString,
     LLMCredentials,
+    LLMReasoningEffort,
 )
 from xpander_sdk.modules.agents.models.knowledge_bases import AgentKnowledgeBase
 from xpander_sdk.modules.knowledge_bases.knowledge_bases_module import KnowledgeBases
@@ -151,6 +152,9 @@ class Agent(XPanderSharedModel):
             using_nemo: Optional[bool]
             model_provider: str
             model_name: str
+            llm_reasoning_effort: Optional[LLMReasoningEffort] = LLMReasoningEffort.Medium
+            deep_planning: Optional[bool] = False
+            enforce_deep_planning: Optional[bool] = False
             llm_api_base: Optional[str]
             webhook_url: Optional[str]
             created_at: Optional[datetime]
@@ -192,6 +196,9 @@ class Agent(XPanderSharedModel):
     using_nemo: Optional[bool] = False
     model_provider: str
     model_name: str
+    llm_reasoning_effort: Optional[LLMReasoningEffort] = LLMReasoningEffort.Medium
+    deep_planning: Optional[bool] = False
+    enforce_deep_planning: Optional[bool] = False
     llm_api_base: Optional[str] = None
     webhook_url: Optional[str] = None
     created_at: Optional[datetime] = None

xpander_sdk/modules/backend/frameworks/agno.py

@@ -8,7 +8,7 @@ from loguru import logger
 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
@@ -213,8 +213,244 @@ 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:
+        # add instructions guidance
+        if not "instructions" in args:
+            args["instructions"] = ""
+        
+        args["instructions"] += """\n
+            <important_planning_instructions>
+            ## **Deep Planning Tools - Essential for Multi-Step Tasks**
+
+            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
+
+            ---
+
+            ### **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-item** - Mark Task Complete
+            **When to use**: **IMMEDIATELY** after finishing each task (NOT before!)
+
+            **How to use**:
+            ```json
+            {
+            "body_params": {
+                "id": "task-uuid-from-plan"
+            }
+            }
+            ```
+            **CRITICAL**: 
+            - Only mark complete AFTER work is actually done
+            - This is MANDATORY for progress tracking
+            - Get the task ID from `xpget-agent-plan` results
+
+            ---
+
+            #### **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`)
+
+            ---
+
+            #### **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**: When you need information from the user during plan execution
+            **PREREQUISITE**: Plan must be started (running) first
+
+            **How to use**:
+            ```json
+            {
+            "body_params": {
+                "question": "What is the customer email address?"
+            }
+            }
+            ```
+
+            **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
+
+            ---
+
+            ### **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
+            - Mark tasks complete immediately after finishing them
+            - Ask for user information when needed with `xpask-for-information`
+            - Call plan tools **sequentially** (one at a time, never in parallel)
+
+            ❌ **DON'T:**
+            - Mark tasks complete before they're actually done
+            - 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
+
+            ---
+
+            ### **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: abc-123) - 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. Call: xpcomplete-agent-plan-item
+            id: "abc-123"
+
+            8. Call: xpget-agent-plan
+            → See: Task 1 ✓ complete, Task 2 next...
+
+            9. [Continue through remaining tasks]
+            ```
+            **Remember**: The plan is your roadmap. Check it often, update it as needed, and always mark tasks complete when done!
+            </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:
     """
@@ -278,6 +514,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
     
@@ -579,6 +819,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:
@@ -612,10 +853,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/utils/mcp_oauth.py

@@ -8,7 +8,7 @@ from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
 from xpander_sdk.modules.tools_repository.models.mcp import MCPOAuthGetTokenGenericResponse, MCPOAuthGetTokenResponse, MCPOAuthResponseType, MCPServerDetails
 
 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):
     client = APIClient(configuration=task.configuration)

xpander_sdk/modules/events/events_module.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import json as py_json
 import os
 import signal
 import sys
@@ -19,10 +20,12 @@ from typing import Any, Awaitable, Callable, Optional, Set, Union, List
 import httpx
 from httpx_sse import aconnect_sse
 from loguru import logger
+from pydantic import BaseModel
 
 from xpander_sdk.core.module_base import ModuleBase
 from xpander_sdk.exceptions.module_exception import ModuleException
 from xpander_sdk.models.configuration import Configuration
+from xpander_sdk.models.shared import OutputFormat
 from xpander_sdk.modules.agents.models.agent import SourceNodeType
 from xpander_sdk.modules.tasks.tasks_module import Tasks
 
@@ -327,6 +330,7 @@ class Events(ModuleBase):
         agent_worker: DeployedAsset,
         task: Task,
         on_execution_request: ExecutionRequestHandler,
+        retry_count: Optional[int] = 0,
     ) -> None:
         """
         Handle an incoming task execution request.
@@ -335,6 +339,7 @@ class Events(ModuleBase):
             agent_worker (DeployedAsset): The deployed asset (agent) to handle the task.
             task (Task): The task object containing execution details.
             on_execution_request (ExecutionRequestHandler): The handler function to process the task.
+            retry_count (Optional[int]): Current retry attempt count. Defaults to 0.
         """
         error = None
         try:
@@ -348,6 +353,25 @@ class Events(ModuleBase):
                     on_execution_request,
                     task,
                 )
+            
+            # Check if plan is complete, retry if not
+            plan_following_status = await task.aget_plan_following_status()
+            if not plan_following_status.can_finish:
+                # Check if we've exceeded max retries
+                if retry_count >= 2:  # 0, 1, 2 = 3 total attempts
+                    logger.warning(f"Failed to complete plan after {retry_count + 1} attempts. Remaining incomplete tasks.")
+                    return
+                
+                # Recursively call with incremented retry count
+                logger.info(f"Plan not complete, retrying (attempt {retry_count + 2}/3)")
+                await self.handle_task_execution_request(
+                    agent_worker,
+                    task,
+                    on_execution_request,
+                    retry_count=retry_count + 1
+                )
+                return
+            
         except Exception as e:
             logger.exception(f"Execution handler failed - {str(e)}")
             error = str(e)
@@ -364,6 +388,16 @@ class Events(ModuleBase):
             ):  # let the handler set the status, if not set - mark as completed
                 task.status = AgentExecutionStatus.Completed
 
+            # in case of structured output, return as stringified json
+            try:
+                if task.output_format == OutputFormat.Json:
+                    if isinstance(task.result, BaseModel):
+                        task.result = task.result.model_dump_json()
+                    if isinstance(task.result, dict) or isinstance(task.result, list):
+                        task.result = py_json.dumps(task.result)
+            except Exception:
+                pass
+            
             await task.asave()
             task.tokens = task_used_tokens
             task.used_tools = task_used_tools