Quickstart

1. Created the agent in xpander’s control plane.
2. Run its handler locally against real prompts.

​

Prerequisites

• Node.js 20+ for the CLI.
• Python 3.12+ for the local dev server.
• An LLM provider key in your shell (OPENAI_API_KEY, ANTHROPIC_API_KEY, or whichever provider you’ll use). The agent runs against this key locally; in production, you can override it from the agent config.

​

1. Install and authenticate

1. The CLI ships via npm.
2. The SDK ships via pip.
3. login writes credentials that both the CLI and the SDK read.

# 1. CLI: creates agents, scaffolds projects, runs them locally
npm install -g xpander-cli

# 2. SDK: the runtime library you import in Python
pip install "xpander-sdk[agno]"

# 3. Auth: opens a browser, writes ~/.xpander/credentials
xpander login

# Optional: on CI or a machine without a browser, use this instead.
#           Paste an API key generated under Settings in the xpander app (https://chat.xpander.ai, or your self-hosted address).
xpander configure

​

2. Create the agent

1. It creates the agent in xpander’s control plane (giving it an ID, a default model, and an empty skill list).
2. It scaffolds the project files into the folder you point at.

# Create an agent named "my-first-agent" using the Agno agent loop
# and scaffold its files into the current directory.
xpander agent new \
    --name "my-first-agent" \
    --framework "agno" \
    --folder "."

xpander_handler.py        # Your @on_task entry point.
xpander_config.json       # Agent ID, framework selection, runtime settings.
agent_instructions.json   # Agent system prompt (edit this to change behavior).
requirements.txt          # Python dependencies.
.env                      # Prefilled with API key, org ID, and the new agent's ID.

# Use python3 explicitly so macOS doesn't fall back to system Python 2
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

​

3. Read the handler

from dotenv import load_dotenv
load_dotenv()

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

@on_task
async def handler(task: Task) -> Task:
    # 1. Fetch the agent's full configuration from xpander's control plane
    backend = Backend(configuration=task.configuration)
    agno_args = await backend.aget_args(task=task)

    # 2. Build Agno's own Agent class with that config
    agno_agent = Agent(**agno_args, debug_mode=True)

    # 3. Run the LLM loop with the task's input, files, and images
    result = await agno_agent.arun(
        input=task.to_message(),
        files=task.get_files(),
        images=task.get_images(),
    )

    # 4. Write the result back so xpander can store and display it
    task.result = result.content
    task.tokens = Tokens(
        prompt_tokens=result.metrics.input_tokens,
        completion_tokens=result.metrics.output_tokens,
    )
    task.used_tools = [t.tool_name for t in (result.tools or [])]
    return task

1. Backend(...).aget_args(task=task) calls the xpander control plane and returns a dict containing the full agent configuration: instructions, skills (passed to Agno as tools, the name agent loops use for them), model with credentials, knowledge bases, session storage, memory settings.
2. That dict gets splatted into agno.agent.Agent(...), which gives you a real Agno agent ready to run.
3. You run it with arun(), capture the output, and write it back to task.result.
4. The @on_task decorator stands up an HTTP server on port 59321 and subscribes to xpander’s task event stream, so any task created for this agent (from the API, Slack, Xpander Chat, anywhere) is routed to your handler.

​

4. Run it locally

# Boots the @on_task HTTP server and subscribes to xpander event stream
python3 xpander_handler.py

# Calls your handler exactly once with the prompt, prints the result, and exits
python3 xpander_handler.py --invoke --prompt "What can you do?"

# Same SSE subscription as `python3 xpander_handler.py`, plus dev tooling
xpander agent dev

1. A local URL you can chat with.
2. Once your dev process is running, every task created for this agent (REST API, Slack, Xpander Chat, MCP, any channel) is routed to your local handler, not just locally-initiated tests.
3. To iterate: edit xpander_handler.py, save, restart.

​

5. Customize the agent (Optional)

{
  "role": [
    "You are a customer support assistant for Acme.",
    "Always confirm the customer's account ID before taking any action."
  ],
  "goal": [
    "Resolve the customer's issue in as few turns as possible.",
    "Escalate to a human if the request involves a refund over $500."
  ],
  "general": "Be concise, professional, and friendly. Never invent policy details; if you don't know something, say so and offer to escalate."
}

1. Custom skills wrapped with @register_tool. See Custom skills.
2. Prebuilt skills from the skills catalog (Slack, Gmail, GitHub, and more). See Pre-built skills.
3. Knowledge bases for RAG. See Document Management.
4. Memory (session storage, user memories, agent memories). See Memory & State.
5. Skill hooks for logging, metrics, and guardrails around skill calls. See Skill hooks.
6. A different agent loop (OpenAI Agents SDK, LangChain, AWS Strands). See SDK integrations.

​

Troubleshooting

​

Next steps