Quickstart

1. Created the agent in xpander’s control plane.
2. Run its handler locally against real prompts.
3. Deployed it as a container reachable through the REST API and any channel you wire up later.

​

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, deploys, streams logs
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 from https://app.xpander.ai/settings.
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 tool list).
2. It scaffolds the project files into the folder you point at.

# Create an agent named "my-first-agent" using the Agno framework
# 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, deployment settings.
agent_instructions.json   # Agent system prompt (edit this to change behavior).
requirements.txt          # Python dependencies.
Dockerfile                # Used by xpander agent deploy.
.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 the framework'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, tools, 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 the platform’s task event stream, so any task created for this agent (from the API, Slack, Agent Studio, anywhere) is routed to your handler.

​

4. Run it locally

# Boots the @on_task HTTP server and subscribes to the platform 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, Agent Studio 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 tools wrapped with @register_tool. See Custom Tools.
2. Prebuilt connectors from the catalog (Slack, Gmail, GitHub, 2,000+). See Pre-built Tools.
3. Knowledge bases for RAG. See Document Management.
4. Memory (session storage, user memories, agent memories). See Memory & State.
5. Tool hooks for logging, metrics, and guardrails around tool calls. See Tool Hooks.
6. A different framework (OpenAI Agents SDK, LangChain, AWS Strands). See Frameworks.

​

6. Deploy

# Uploads code, builds a Docker image, replaces the running container
xpander agent deploy

1. A new immutable version on every deploy (rolling back is one flag away).
2. Reachability through the REST API and every channel you enable.

# Hits the deployed agent and prints the response + round-trip time
xpander agent invoke "Run a quick health check"

# Streams logs from the deployed container
xpander agent logs

​

Troubleshooting

​

Next steps