xpander-sdk 2.0.145__tar.gz → 2.0.157__tar.gz

{xpander_sdk-2.0.145 → xpander_sdk-2.0.157}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.145
+Version: 2.0.157
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI
@@ -131,6 +131,11 @@ tasks = Tasks(configuration=config)
 task = await tasks.aget("task-id")
 await task.aset_status(AgentExecutionStatus.Running)
 await task.asave()
+
+# Retrieve task activity log
+activity_log = await task.aget_activity_log()
+for message in activity_log.messages:
+    print(f"{message.role}: {message.content.text}")
 ```
 
 ### 4. Tools Integration
@@ -287,6 +292,40 @@ async for event in task.aevents():
     print(f"Event Data: {event.data}")
 ```
 
+### Task Activity Monitoring
+
+```python
+from xpander_sdk import Task
+from xpander_sdk.models.activity import (
+    AgentActivityThreadMessage,
+    AgentActivityThreadToolCall,
+    AgentActivityThreadReasoning
+)
+
+# Load a completed task
+task = await Task.aload("task-id")
+
+# Get detailed activity log
+activity_log = await task.aget_activity_log()
+
+# Analyze messages between user and agent
+for message in activity_log.messages:
+    if isinstance(message, AgentActivityThreadMessage):
+        print(f"{message.role}: {message.content.text}")
+    elif isinstance(message, AgentActivityThreadToolCall):
+        # Tool call
+        print(f"Tool: {message.tool_name}")
+        print(f"Payload: {message.payload}")
+        print(f"Result: {message.result}")
+    elif isinstance(message, AgentActivityThreadReasoning):
+        # Reasoning step
+        print(f"Reasoning ({message.type}): {message.thought}")
+
+# Synchronous version
+task = Task.load("task-id")
+activity_log = task.get_activity_log()
+```
+
 ### Local Task Testing
 
 ```python
@@ -378,6 +417,93 @@ load_dotenv()
 config = Configuration()
 ```
 
+## 🏢 Self-Hosted Deployment
+
+If you're using a self-hosted xpander.ai deployment, configure the SDK to point to your Agent Controller endpoint.
+
+**Important**: Use the **Agent Controller API key** generated during Helm installation, not your xpander.ai cloud API key.
+
+### Configuration
+
+```bash
+# Set environment variables
+export XPANDER_API_KEY="your-agent-controller-api-key"  # From Helm installation
+export XPANDER_ORGANIZATION_ID="your-org-id"
+export XPANDER_BASE_URL="https://agent-controller.my-company.com"
+```
+
+Or configure explicitly:
+
+```python
+from xpander_sdk import Configuration
+
+config = Configuration(
+    api_key="your-agent-controller-api-key",  # From Helm installation
+    organization_id="your-org-id",
+    base_url="https://agent-controller.my-company.com"
+)
+```
+
+### Using with Agno Framework
+
+```python
+from xpander_sdk import Backend, Configuration
+from agno.agent import Agent
+
+# Configure for self-hosted
+config = Configuration(
+    api_key="your-agent-controller-api-key",  # From Helm installation
+    organization_id="your-org-id",
+    base_url="https://agent-controller.my-company.com"
+)
+
+# Initialize Backend with self-hosted config
+backend = Backend(configuration=config)
+
+# Create agent - it will use your self-hosted infrastructure
+agno_agent = Agent(**backend.get_args(agent_id="agent-123"))
+
+# Run agent
+result = await agno_agent.arun(
+    input="What can you help me with?",
+    stream=True
+)
+```
+
+### Complete Self-Hosted Example
+
+```python
+import asyncio
+from xpander_sdk import Configuration, Agent
+
+async def main():
+    # Configure for self-hosted deployment
+    config = Configuration(
+        api_key="your-agent-controller-api-key",  # From Helm installation
+        organization_id="your-org-id",
+        base_url="https://agent-controller.my-company.com"
+    )
+    
+    # Load agent from self-hosted deployment
+    agent = await Agent.aload("agent-123", configuration=config)
+    print(f"Agent: {agent.name}")
+    
+    # Create and execute task
+    task = await agent.acreate_task(
+        prompt="Analyze Q4 sales data",
+        file_urls=["https://example.com/sales-q4.csv"]
+    )
+    print(f"Task created: {task.id}")
+    print(f"Status: {task.status}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+**Important**: Make sure your `base_url` points to the Agent Controller endpoint (e.g., `https://agent-controller.{your-domain}`), not the root domain.
+
+📖 **Full Guide**: [Self-Hosted Configuration Documentation](https://docs.xpander.ai/api-reference/configuration/self-hosted)
+
 ## 🔄 Error Handling
 
 ```python
@@ -392,9 +518,9 @@ except ModuleException as e:
 ## 🤝 Contributing
 
 1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
+2. Create a feature branch (`git checkout -b feature/{base_branch}/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat/chore/fix: Add amazing feature'`)
+4. Push to the branch (`git push origin feature/{base_branch}/amazing-feature`)
 5. Open a Pull Request
 
 ## 📄 License

{xpander_sdk-2.0.145 → xpander_sdk-2.0.157}/README.md

@@ -82,6 +82,11 @@ tasks = Tasks(configuration=config)
 task = await tasks.aget("task-id")
 await task.aset_status(AgentExecutionStatus.Running)
 await task.asave()
+
+# Retrieve task activity log
+activity_log = await task.aget_activity_log()
+for message in activity_log.messages:
+    print(f"{message.role}: {message.content.text}")
 ```
 
 ### 4. Tools Integration
@@ -238,6 +243,40 @@ async for event in task.aevents():
     print(f"Event Data: {event.data}")
 ```
 
+### Task Activity Monitoring
+
+```python
+from xpander_sdk import Task
+from xpander_sdk.models.activity import (
+    AgentActivityThreadMessage,
+    AgentActivityThreadToolCall,
+    AgentActivityThreadReasoning
+)
+
+# Load a completed task
+task = await Task.aload("task-id")
+
+# Get detailed activity log
+activity_log = await task.aget_activity_log()
+
+# Analyze messages between user and agent
+for message in activity_log.messages:
+    if isinstance(message, AgentActivityThreadMessage):
+        print(f"{message.role}: {message.content.text}")
+    elif isinstance(message, AgentActivityThreadToolCall):
+        # Tool call
+        print(f"Tool: {message.tool_name}")
+        print(f"Payload: {message.payload}")
+        print(f"Result: {message.result}")
+    elif isinstance(message, AgentActivityThreadReasoning):
+        # Reasoning step
+        print(f"Reasoning ({message.type}): {message.thought}")
+
+# Synchronous version
+task = Task.load("task-id")
+activity_log = task.get_activity_log()
+```
+
 ### Local Task Testing
 
 ```python
@@ -329,6 +368,93 @@ load_dotenv()
 config = Configuration()
 ```
 
+## 🏢 Self-Hosted Deployment
+
+If you're using a self-hosted xpander.ai deployment, configure the SDK to point to your Agent Controller endpoint.
+
+**Important**: Use the **Agent Controller API key** generated during Helm installation, not your xpander.ai cloud API key.
+
+### Configuration
+
+```bash
+# Set environment variables
+export XPANDER_API_KEY="your-agent-controller-api-key"  # From Helm installation
+export XPANDER_ORGANIZATION_ID="your-org-id"
+export XPANDER_BASE_URL="https://agent-controller.my-company.com"
+```
+
+Or configure explicitly:
+
+```python
+from xpander_sdk import Configuration
+
+config = Configuration(
+    api_key="your-agent-controller-api-key",  # From Helm installation
+    organization_id="your-org-id",
+    base_url="https://agent-controller.my-company.com"
+)
+```
+
+### Using with Agno Framework
+
+```python
+from xpander_sdk import Backend, Configuration
+from agno.agent import Agent
+
+# Configure for self-hosted
+config = Configuration(
+    api_key="your-agent-controller-api-key",  # From Helm installation
+    organization_id="your-org-id",
+    base_url="https://agent-controller.my-company.com"
+)
+
+# Initialize Backend with self-hosted config
+backend = Backend(configuration=config)
+
+# Create agent - it will use your self-hosted infrastructure
+agno_agent = Agent(**backend.get_args(agent_id="agent-123"))
+
+# Run agent
+result = await agno_agent.arun(
+    input="What can you help me with?",
+    stream=True
+)
+```
+
+### Complete Self-Hosted Example
+
+```python
+import asyncio
+from xpander_sdk import Configuration, Agent
+
+async def main():
+    # Configure for self-hosted deployment
+    config = Configuration(
+        api_key="your-agent-controller-api-key",  # From Helm installation
+        organization_id="your-org-id",
+        base_url="https://agent-controller.my-company.com"
+    )
+    
+    # Load agent from self-hosted deployment
+    agent = await Agent.aload("agent-123", configuration=config)
+    print(f"Agent: {agent.name}")
+    
+    # Create and execute task
+    task = await agent.acreate_task(
+        prompt="Analyze Q4 sales data",
+        file_urls=["https://example.com/sales-q4.csv"]
+    )
+    print(f"Task created: {task.id}")
+    print(f"Status: {task.status}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+**Important**: Make sure your `base_url` points to the Agent Controller endpoint (e.g., `https://agent-controller.{your-domain}`), not the root domain.
+
+📖 **Full Guide**: [Self-Hosted Configuration Documentation](https://docs.xpander.ai/api-reference/configuration/self-hosted)
+
 ## 🔄 Error Handling
 
 ```python
@@ -343,9 +469,9 @@ except ModuleException as e:
 ## 🤝 Contributing
 
 1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
+2. Create a feature branch (`git checkout -b feature/{base_branch}/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat/chore/fix: Add amazing feature'`)
+4. Push to the branch (`git push origin feature/{base_branch}/amazing-feature`)
 5. Open a Pull Request
 
 ## 📄 License

{xpander_sdk-2.0.145 → xpander_sdk-2.0.157}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="xpander-sdk",
-    version="2.0.145",
+    version="2.0.157",
     author="xpanderAI",
     author_email="dev@xpander.ai",
     description="xpander.ai Backend-as-a-service for AI Agents - SDK",

{xpander_sdk-2.0.145 → xpander_sdk-2.0.157}/src/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-2.0.157/src/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-2.0.145 → xpander_sdk-2.0.157}/src/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-2.0.145 → xpander_sdk-2.0.157}/src/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,8 @@ class Agent(XPanderSharedModel):
             using_nemo: Optional[bool]
             model_provider: str
             model_name: str
+            llm_reasoning_effort: Optional[LLMReasoningEffort] = LLMReasoningEffort.Medium
+            deep_plan: Optional[bool] = False
             llm_api_base: Optional[str]
             webhook_url: Optional[str]
             created_at: Optional[datetime]
@@ -192,6 +195,8 @@ class Agent(XPanderSharedModel):
     using_nemo: Optional[bool] = False
     model_provider: str
     model_name: str
+    llm_reasoning_effort: Optional[LLMReasoningEffort] = LLMReasoningEffort.Medium
+    deep_plan: Optional[bool] = False
     llm_api_base: Optional[str] = None
     webhook_url: Optional[str] = None
     created_at: Optional[datetime] = None

{xpander_sdk-2.0.145 → xpander_sdk-2.0.157}/src/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
@@ -278,6 +278,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 +583,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,7 +617,8 @@ 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"
                 )
             )
 

{xpander_sdk-2.0.145 → xpander_sdk-2.0.157}/src/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)