Frameworks Guide

• Schedule and list tasks - consistent task management
• Consume tools - from the catalog or custom
• Manage prompts - version-controlled system prompts
• Handle memory - PostgreSQL-backed state
• Deploy containers - K8s (cloud or self-hosted)

1. Create an agent (via Workbench, SDK, or API)
2. Use Backend().aget_args() to get framework-specific config
3. Initialize your framework with the returned args
4. Use @on_task to handle incoming tasks

• Multiple interfaces - Slack, Web UI, API, Agent-to-Agent (A2A)
• Retry mechanism - automatic retries on failure
• Auto-scaling - if unavailable, xpander schedules a new instance
• Observability - built-in logging and monitoring

​

Framework Examples

from xpander_sdk import Task, on_task, Backend, Configuration
from agno.agent import Agent

@on_task(
    Configuration(
        api_key="{XPANDER_API_KEY}",
        organization_id="{XPANDER_ORGANIZATION_ID}",
        agent_id="{XPANDER_AGENT_ID}"
    )
)
async def my_agent_handler(task: Task):
    # Initialize Agno with xpander's configuration
    backend = Backend(configuration=task.configuration)
    agno_agent = Agent(**await backend.aget_args(task=task))

    # Run the agent
    result = await agno_agent.arun(
        input=task.to_message(),
        files=task.get_files(),
        images=task.get_images()
    )
    task.result = result.content

    return task

​

Local Development

​

Option 1: CLI

# Install the xpander CLI
npm install -g xpander-cli

# Run agent locally - connects to xpander platform for tools, prompts, and task handling
xpander agent dev [agent-name]

• Web UI - https://<agent-name>.agents.xpander.ai
• API - curl -X POST https://api.xpander.ai/v1/agents/<agent-id>/invoke -H 'x-api-key: <key>' -d '{"input":{"text":"hi!"}}'
• SDK - Tasks().create(agent_id="...", input=...)
• CLI - xpander agent invoke [agent-name] "test message"

​

Option 2: Inline test task

from xpander_sdk import on_task, Configuration
from xpander_sdk.modules.tasks.models.task import AgentExecutionInput, LocalTaskTest

test_task = LocalTaskTest(
    input=AgentExecutionInput(text="Your test input here"),
)

@on_task(
    Configuration(
        api_key="{XPANDER_API_KEY}",
        organization_id="{XPANDER_ORGANIZATION_ID}",
        agent_id="{XPANDER_AGENT_ID}"
    ),
    test_task=test_task  # Runs immediately with this test input
)
async def my_agent_handler(task):
    # Your agent logic here
    ...

​

Deployment

# Deploy to xpander cloud
xpander deploy

# View logs
xpander agent logs [agent]

# Restart container
xpander agent restart [agent]

​

Next Steps