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

xpander_sdk/modules/tools_repository/sub_modules/tool.py

@@ -41,6 +41,7 @@ from xpander_sdk.modules.tools_repository.utils.schemas import (
     schema_enforcement_block_and_descriptions,
 )
 from xpander_sdk.utils.event_loop import run_sync
+from xpander_sdk.modules.events.decorators.on_tool import ToolHooksRegistry
 
 
 class Tool(XPanderSharedModel):
@@ -376,6 +377,15 @@ class Tool(XPanderSharedModel):
             task_id=task_id,
         )
 
+        # Execute before hooks
+        await ToolHooksRegistry.execute_before_hooks(
+            tool=self,
+            payload=payload,
+            payload_extension=payload_extension,
+            tool_call_id=tool_call_id,
+            agent_version=agent_version
+        )
+
         try:
             if self.schema and payload:
                 try:
@@ -386,32 +396,43 @@ class Tool(XPanderSharedModel):
                     ) from validation_error
 
             if self.is_local:
-                await self.agraph_preflight_check(
-                    agent_id=agent_id,
-                    agent_version=agent_version,
-                    configuration=configuration,
-                    task_id=task_id,
-                )
-
                 if self.fn is None:
                     raise RuntimeError(
                         f"No local function provided for this tool ({self.id})."
                     )
 
                 result = await invoke_local_fn(fn=self.fn, payload=payload)
+                
+                await self.agraph_preflight_check(
+                    agent_id=agent_id,
+                    agent_version=agent_version,
+                    configuration=configuration,
+                    task_id=task_id,
+                    payload={"input": payload, "output": result.model_dump() if isinstance(result, BaseModel) else result}
+                )
+                
                 tool_invocation_result.result = result
                 tool_invocation_result.is_success = True
-                return tool_invocation_result
-
-            tool_invocation_result.result = await self.acall_remote_tool(
-                agent_id=agent_id,
-                agent_version=agent_version,
+            else:
+                tool_invocation_result.result = await self.acall_remote_tool(
+                    agent_id=agent_id,
+                    agent_version=agent_version,
+                    payload=payload,
+                    payload_extension=payload_extension,
+                    configuration=configuration,
+                    task_id=task_id,
+                )
+                tool_invocation_result.is_success = True
+            
+            # Execute after hooks on success
+            await ToolHooksRegistry.execute_after_hooks(
+                tool=self,
                 payload=payload,
                 payload_extension=payload_extension,
-                configuration=configuration,
-                task_id=task_id,
+                tool_call_id=tool_call_id,
+                agent_version=agent_version,
+                result=tool_invocation_result.result
             )
-            tool_invocation_result.is_success = True
 
         except Exception as e:
             tool_invocation_result.is_error = True
@@ -421,6 +442,16 @@ class Tool(XPanderSharedModel):
             else:
                 tool_invocation_result.status_code = 500
                 tool_invocation_result.result = str(e)
+            
+            # Execute error hooks on failure
+            await ToolHooksRegistry.execute_error_hooks(
+                tool=self,
+                payload=payload,
+                payload_extension=payload_extension,
+                tool_call_id=tool_call_id,
+                agent_version=agent_version,
+                error=e
+            )
 
         return tool_invocation_result
 

xpander_sdk/modules/tools_repository/tools_repository_module.py

@@ -16,7 +16,7 @@ from xpander_sdk.models.configuration import Configuration
 from xpander_sdk.models.shared import XPanderSharedModel
 from xpander_sdk.modules.tools_repository.sub_modules.tool import Tool
 from xpander_sdk.utils.event_loop import run_sync
-
+import json
 
 class ToolsRepository(XPanderSharedModel):
     """
@@ -51,7 +51,7 @@ class ToolsRepository(XPanderSharedModel):
     tools: List[Tool] = []
 
     agent_graph: Optional[Any] = None
-    is_async: Optional[bool] = False
+    is_async: Optional[bool] = True
 
     # Immutable registry for tools defined via decorator
     _local_tools: ClassVar[List[Tool]] = []
@@ -158,6 +158,10 @@ class ToolsRepository(XPanderSharedModel):
         fn_list = []
 
         for tool in self.list:
+            
+            # add json schema to the model doc
+            tool.schema.__doc__ = "Pay attention to the schema, dont miss. " + json.dumps(tool.schema.model_json_schema(mode="serialization"))
+            
             schema_cls: Type[BaseModel] = tool.schema
 
             # Create closure to capture tool and schema_cls

xpander_sdk/modules/tools_repository/utils/generic.py

@@ -38,6 +38,9 @@ def json_type_to_python(json_type: str, prop_schema: dict = None):
         item_type = json_type_to_python(items.get("type"), items)
         return List[item_type]
     
+    if isinstance(json_type, list) and len(json_type) > 1:
+        json_type = next((t for t in json_type if t != "null"), None)
+    
     return {
         "string": str,
         "integer": int,

xpander_sdk/utils/agents/compactization_agent.py

@@ -0,0 +1,257 @@
+from typing import TYPE_CHECKING, List, Union
+from agno.agent import Agent as AgnoAgent
+from loguru import logger
+import json
+from xpander_sdk.models.compactization import TaskCompactizationEvent, TaskCompactizationOutput, TaskCompactizationInput, TaskCompactizationRetryEvent
+from xpander_sdk.models.deep_planning import DeepPlanningItem
+from xpander_sdk.models.events import TaskUpdateEventType
+from xpander_sdk.models.frameworks import Framework
+from xpander_sdk.models.shared import Tokens
+from xpander_sdk.modules.agents.agents_module import Agents
+from xpander_sdk.modules.backend.backend_module import Backend
+from xpander_sdk.modules.backend.utils.mcp_oauth import push_event
+from xpander_sdk.modules.tasks.sub_modules.task import TaskUpdateEvent
+from xpander_sdk.utils.event_loop import run_sync
+
+if TYPE_CHECKING:
+    from xpander_sdk.modules.tasks.sub_modules.task import Task
+
+def run_task_compactization(message: str, task: "Task", uncompleted_tasks: List[DeepPlanningItem]) -> Union[str, TaskCompactizationOutput]:
+    try:
+        
+        # report retry event
+        try:
+            run_sync(
+                push_event(
+                    task=task,
+                    event=TaskCompactizationEvent(type="retry", data=TaskCompactizationRetryEvent(is_retry=True)),
+                    event_type=TaskUpdateEventType.TaskCompactization
+                )
+            )
+        except Exception as e:
+            pass
+        
+        # get agent to identify framework
+        agent = Agents(configuration=task.configuration).get(agent_id=task.agent_id,version=task.agent_version)
+        
+        # non agno, let the same agent handle it
+        if agent.framework != Framework.Agno:
+            return "\n".join([
+                "Task not finished, uncompleted tasks detected:",
+                f"Uncompleted tasks: {[task.model_dump_json() for task in uncompleted_tasks]}",
+                "You must complete tasks if fulfilled",
+                f"User's original request: \"{message}\""
+            ])
+        
+        # load backend args for consistency of model provider and settings
+        agno_args = Backend(configuration=agent.configuration).get_args(agent_id=agent.id, agent_version=agent.version, task=task)
+        
+        if agent.model_provider == "openai":
+            agno_args["model"].id = "gpt-5-mini"
+        
+        # create compacitzation agent
+        compactization_agent = AgnoAgent(
+            output_schema=TaskCompactizationOutput,
+            name="Task Compactization Agent",
+            model=agno_args.get("model"),
+            description="""
+                You are a system component that handles early/unapproved agent task exits.
+                
+                When an agent stops execution with uncompleted tasks, you analyze the state and generate a continuation prompt
+                that will be sent DIRECTLY to that agent to resume its work.
+                
+                Your output becomes the agent's next input - it must guide the agent to:
+                1. Continue from where it stopped (seamlessly, no restart)
+                2. Complete ALL remaining uncompleted tasks
+                3. Use correct tools (especially xpask_for_information for questions)
+                4. NOT expose internal orchestration (xp* tools, task IDs) to the user
+                
+                You are a bridge between system orchestration and agent execution.
+            """,
+            role="""
+                You are the **Compactization Agent** - a system component for handling early agent exits.
+                
+                **The Flow:**
+                1. Agent A (e.g., researcher) starts task and creates plan
+                2. Agent A executes but stops/exits early with uncompleted tasks
+                3. System detects uncompleted tasks and triggers YOU
+                4. You analyze Agent A's execution state and generate continuation guidance
+                5. Your output goes DIRECTLY to Agent A as its next prompt
+                6. Agent A resumes and completes remaining work
+                
+                **Your Mission:**
+                Generate a prompt that Agent A will receive to continue its work. This prompt must:
+                - Guide Agent A on what's been done and what remains
+                - Correct any protocol violations (e.g., asking questions without tool)
+                - Instruct Agent A to NOT expose internal xp* tools to the user
+                - Make Agent A's continuation feel seamless to the user
+                
+                You are NOT talking to the user. You are talking to Agent A.
+            """,
+            instructions="""
+            ## Your Role: Agent-to-Agent Handoff
+            
+            You are writing a message that will be sent TO the agent (Agent A) to continue its task.
+            
+            **Key Understanding:**
+            - Your `new_task_prompt` = The message Agent A will receive
+            - Agent A will see this message and continue working
+            - The user will see Agent A's response, not your message directly
+            - You must guide Agent A to work seamlessly without exposing internals
+            
+            ## Core Principles
+            
+            * **You are guiding Agent A**, not the user
+            * **Agent A must complete ALL uncompleted tasks** - tell it what remains
+            * **Stay factual** - Use "Unknown" for missing info
+            * **Preserve exact state** - Keep IDs, names, paths, outputs unchanged in context
+            * **Correct violations** - If Agent A asked questions without tool, tell it to use the tool
+            * **Hide orchestration** - Instruct Agent A to NOT mention xp* tools, task IDs, or internals to user
+            
+            ## What You Must Capture
+            
+            * **Tool call history.** For each tool: name/id, purpose, inputs (high-level), outputs (high-level), errors. Include plan tools (xpcreate_agent_plan, xpcomplete_agent_plan_item, etc.).
+            * **Artifacts and state.** All created files, IDs, URLs, variables, decisions, and configurations.
+            * **What worked / what didn't.** Successes, failures, blockers, missing info, wrong assumptions.
+            * **Task completion status.** For each uncompleted task: exact ID, title, and specific reason it's incomplete.
+            * **PROTOCOL VIOLATIONS.** Check if agent asked questions in response text AFTER calling xpstart_execution_plan (violates protocol).
+            
+            ## Detecting Protocol Violations
+            
+            If the agent's last message contains questions to the user AFTER the plan was started (after xpstart_execution_plan was called):
+            - This is a PROTOCOL VIOLATION
+            - The agent should have used xpask_for_information tool instead
+            
+            When violation is detected, you MUST make it SUPER CLEAR in BOTH output fields:
+            
+            **In `new_task_prompt`:**
+            - START with: "CRITICAL PROTOCOL VIOLATION DETECTED: You asked questions directly after starting the plan."
+            - Explicitly state: "You MUST use xpask_for_information tool to ask questions once plan is running."
+            - Include: "NEVER write questions in your response text after calling xpstart_execution_plan."
+            - Then provide the continuation instructions
+            
+            **In `task_context`:**
+            - Add a dedicated section at the TOP before section 1: "**PROTOCOL VIOLATION DETECTED**"
+            - State clearly: "Agent asked questions in response text after calling xpstart_execution_plan. This violates execution protocol."
+            - Remind: "Rule: After xpstart_execution_plan is called, questions MUST be asked using xpask_for_information tool, NOT written in response text."
+            
+            Signs of protocol violation in messages:
+            - Phrases like "Before I proceed", "I need clarification", "Please choose", "Which option"
+            - Questions written in response text after xpstart_execution_plan was called
+            
+            ## Continuation Prompt: Your Message TO Agent A
+            
+            Your `new_task_prompt` is what Agent A will read. Structure it as guidance TO the agent:
+            
+            1. **IF protocol violation:** "You asked questions without using xpask_for_information tool. Use the tool for questions."
+            2. **Orient Agent A:** "You were working on [task]. You've completed [X, Y, Z]."
+            3. **State what remains:** "You still need to complete: [list remaining work in plain language]."
+            4. **Guide next steps:** "Continue by: [step-by-step what to do next]."
+            5. **Hide internals instruction:** "Important: Do NOT mention xp* tools, task IDs, or internal workflow to the user. Present your work naturally."
+            6. **Enforce protocol:** "Mark each task complete immediately after finishing using xpcomplete_agent_plan_item."
+            7. **Natural tone:** "Continue your response to the user seamlessly, as if you never stopped."
+            
+            You are INSTRUCTING Agent A on how to continue, not writing the user-facing response yourself.
+            
+            ## Task Context Requirements
+            
+            Your `task_context` must:
+            1. **IF protocol violation detected:** Add "PROTOCOL VIOLATION DETECTED" section at the TOP before section 1
+            2. Follow the exact 9-heading structure specified in the output schema (or 10 if violation detected)
+            3. Be deterministic and parseable by downstream systems
+            4. Focus on actionable continuation steps in section 9 (NEXT ACTIONS)
+            5. Include task IDs for all uncompleted tasks
+            6. Emphasize that ALL tasks must be completed and marked complete
+            
+            ## Critical Rules
+            
+            ❌ **NEVER:**
+            - Suggest restarting or creating a new plan
+            - Mark tasks as complete that aren't actually done
+            - Invent details or speculate
+            - Write a "fresh start" prompt
+            
+            ✅ **ALWAYS:**
+            - Write as instructions TO Agent A (you're guiding it, not doing its work)
+            - Tell Agent A what it's done and what remains
+            - Instruct Agent A to complete remaining tasks
+            - Tell Agent A to use correct tools (xpask_for_information for questions)
+            - Instruct Agent A to hide xp* tools and internals from user
+            - Include technical details (task IDs, tool names) in task_context for Agent A's reference
+            - Correct any protocol violations Agent A made
+            """,
+            expected_output="""
+            Return a JSON object with exactly these two fields:
+
+            - new_task_prompt (string): Instructions TO Agent A for continuing its task.
+              
+              This message will be sent directly to Agent A. Write it as guidance:
+              
+              IF PROTOCOL VIOLATION:
+                "You asked questions without using xpask_for_information tool. Use the tool for questions after plan starts."
+              
+              Then:
+              "You were working on [task name]. You've completed [work done in plain language].
+              
+              You still need to complete: [list remaining uncompleted work naturally].
+              
+              Continue by: [specific steps for Agent A to take].
+              
+              IMPORTANT: When responding to the user, do NOT mention xp* tools, task IDs, or internal workflow.
+              Present your work naturally as if execution never stopped. The user should not see any interruption.
+              
+              Mark each task complete immediately after finishing using xpcomplete_agent_plan_item."
+
+            - task_context (string): Comprehensive context for continuation.
+              IF PROTOCOL VIOLATION DETECTED:
+                - Add section at TOP: "**PROTOCOL VIOLATION DETECTED**\nAgent asked questions in response text after calling xpstart_execution_plan. This violates execution protocol. Rule: After xpstart_execution_plan is called, questions MUST be asked using xpask_for_information tool, NOT written in response text.\n\n"
+              Then follow the EXACT 9-section structure defined in TaskCompactizationOutput.task_context.
+              Must be deterministic, actionable, and focused on completing ALL remaining tasks and marking them as completed.
+
+            Important:
+            - Do NOT invent details; write 'Unknown' when information is missing.
+            - Preserve exact IDs, names, file paths, numbers, and user phrasing.
+            - Final actions must include marking each remaining task as completed with the plan tools.
+            - IF protocol violation: Make it SUPER CLEAR in both fields that tool must be used for questions.
+            """
+        )
+        
+        session = agent.get_session(session_id=task.id)
+        
+        # run compactization
+        run_result = compactization_agent.run(
+            input=TaskCompactizationInput(
+                user_input=task.input,
+                agent_instructions=agent.instructions,
+                task_context_and_messages=json.dumps({"messages": [message.model_dump() for message in session.get_messages() if message.role != "system"]}),
+                uncompleted_tasks=uncompleted_tasks
+            )
+        )
+        
+        # reset old session
+        agent.delete_session(session_id=task.id)
+        
+        # report LLM Metrics
+        task.tokens = Tokens(
+            completion_tokens=run_result.metrics.output_tokens,
+            prompt_tokens=run_result.metrics.input_tokens
+        )
+        
+        task.report_metrics(configuration=task.configuration)
+        
+        # report compactization event
+        try:
+            run_sync(
+                push_event(
+                    task=task,
+                    event=TaskCompactizationEvent(type="summarization", data=run_result.content),
+                    event_type=TaskUpdateEventType.TaskCompactization
+                )
+            )
+        except Exception as e:
+            pass
+        
+        return run_result.content
+    except Exception as e:
+        logger.warning(f"Failed to run task compactization - {str(e)}")
+        return message

xpander_sdk/utils/generic.py

@@ -0,0 +1,5 @@
+from datetime import datetime, timezone
+
+
+def get_current_timestamp() -> str:
+    return datetime.now(timezone.utc).isoformat()

{xpander_sdk-2.0.144.dist-info → xpander_sdk-2.0.192.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.144
+Version: 2.0.192
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI
@@ -11,15 +11,16 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: python-dotenv
-Requires-Dist: packaging
-Requires-Dist: pydantic
-Requires-Dist: loguru
-Requires-Dist: httpx
-Requires-Dist: httpx_sse
-Requires-Dist: nest-asyncio
-Requires-Dist: strands-agents
-Requires-Dist: openai-agents
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: packaging>=25.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: httpx_sse>=0.4.3
+Requires-Dist: nest-asyncio>=1.6.0
+Requires-Dist: strands-agents>=1.20.0
+Requires-Dist: openai-agents>=0.6.4
+Requires-Dist: python-toon>=0.1.3
 Provides-Extra: agno
 Requires-Dist: agno; extra == "agno"
 Requires-Dist: sqlalchemy; extra == "agno"
@@ -47,7 +48,7 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# xpander.ai SDK
+# xpander.ai SDK 
 
 [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Documentation](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://docs.xpander.ai) [![PyPI Version](https://img.shields.io/pypi/v/xpander-sdk?label=PyPI)](https://pypi.org/project/xpander-sdk/) [![Downloads](https://pepy.tech/badge/xpander-sdk)](https://pepy.tech/project/xpander-sdk)
 
@@ -131,6 +132,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 +293,123 @@ async for event in task.aevents():
     print(f"Event Data: {event.data}")
 ```
 
+### Authentication Events Callback
+
+Handle authentication events in real-time. This callback is triggered only for authentication flows (e.g., MCP OAuth requiring user login).
+
+**You can use both approaches simultaneously** - decorated handlers will always be invoked, and you can also pass an explicit callback for additional handling.
+
+You can provide the callback in two ways:
+
+#### Option 1: Direct Function
+
+```python
+from xpander_sdk import Backend
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
+from agno.agent import Agent as AgnoAgent
+
+# Define event callback (async or sync)
+async def my_event_callback(agent: Agent, task: Task, event: TaskUpdateEvent):
+    """Called for authentication events only"""
+    # event.type will always be "auth_event"
+    print(f"Authentication required: {event.data}")
+    # Display login URL or handle OAuth flow
+
+# Get args with callback
+backend = Backend(configuration=config)
+args = await backend.aget_args(
+    agent_id="agent-123",
+    task=my_task,
+    auth_events_callback=my_event_callback
+)
+```
+
+#### Option 2: Decorator (Auto-registered)
+
+```python
+from xpander_sdk import Backend, on_auth_event
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
+from agno.agent import Agent as AgnoAgent
+
+# Use decorator - auto-registers globally
+@on_auth_event
+async def handle_auth(agent: Agent, task: Task, event: TaskUpdateEvent):
+    # event.type will always be "auth_event"
+    print(f"Authentication required for {agent.name}")
+    print(f"Auth data: {event.data}")
+
+# Decorated handler is automatically invoked - no need to pass it
+backend = Backend(configuration=config)
+args = await backend.aget_args(
+    agent_id="agent-123",
+    task=my_task
+)
+```
+
+#### Option 3: Combine Both
+
+```python
+from xpander_sdk import Backend, on_auth_event
+
+# Global handler for all auth events
+@on_auth_event
+async def log_auth(agent, task, event):
+    print(f"[GLOBAL] Auth event for {agent.name}")
+
+# Additional one-time handler
+async def custom_handler(agent, task, event):
+    print(f"[CUSTOM] Specific handling for this call")
+
+# Both handlers will be invoked
+args = await backend.aget_args(
+    agent_id="agent-123",
+    auth_events_callback=custom_handler  # Optional additional callback
+)
+
+# Use with Agno
+agno_agent = AgnoAgent(**args)
+result = await agno_agent.arun(
+    input="Process this data",
+    stream=True
+)
+```
+
+### Task Activity Monitoring
+
+```python
+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 +501,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 +602,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