Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt

Use this file to discover all available pages before exploring further.

Decorators are how your Python module becomes a deployed agent worker. The platform dispatches incoming task events to your @on_task handler over SSE, calls @on_boot once at startup, runs @on_tool_* hooks around every tool invocation, and routes auth events through @on_auth_event.
DecoratorPurpose
@on_taskHandle incoming tasks. The primary entry point for any SDK-based agent.
@on_bootRun once at startup, before the SSE listener subscribes.
@on_shutdownRun once during graceful shutdown.
@on_auth_eventReceive MCP/OAuth authentication events as they happen.
@on_tool_beforeRun before any tool invocation.
@on_tool_afterRun after a successful tool invocation.
@on_tool_errorRun when a tool invocation raises.
For the tool-registration decorator, see @register_tool: it lives next to the tools API, since it constructs Tool objects rather than wiring runtime hooks.

​
Minimal worker

from xpander_sdk import Backend, on_task, on_boot, on_shutdown
from xpander_sdk.modules.tasks.sub_modules.task import Task
from agno.agent import Agent as AgnoAgent

backend = Backend()

@on_boot
async def boot():
    print("Worker starting…")

@on_shutdown
async def shutdown():
    print("Worker stopping…")

@on_task
async def handler(task: Task) -> Task:
    args = await backend.aget_args(
        agent_id=task.agent_id,
        agent_version=task.agent_version,
        task=task,
    )
    agno_agent = AgnoAgent(**args)
    result = await agno_agent.arun(input=task.to_message())
    task.result = result.content
    return task
Run this module: python worker.py: and the worker subscribes to the platform’s SSE stream, picks up tasks dispatched to its agent, runs them, and saves results. Tasks are auto-marked Completed (or Error on raise) and metrics are reported automatically when task.tokens is set.

​
Required environment

@on_task validates required env vars eagerly at import. Missing any of these raises ModuleException:
VariableRequired for
XPANDER_API_KEYAuthentication.
XPANDER_ORGANIZATION_IDRouting.
XPANDER_AGENT_IDWorker registration.
For local development without an org-managed agent, set these to your dev values.