Introduction

• Xpander Chat (chat.xpander.ai on xpander cloud, your own domain when self-hosted): assemble an agent from approved skills, instructions and knowledge
• SDK + CLI: the same runtime, driven from Python

​

Install

# 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

​

When to use code

• Run a specific agent loop. You’re already invested in Agno, OpenAI Agents SDK, LangChain, or AWS Strands.
• Wrap a private API as a skill. Decorate a Python function with @register_tool; the SDK generates the JSON schema from your type hints. Example: a lookup_customer(id) skill that hits your internal billing service.
• Embed in an existing service. Run an agent inside code you already deploy (a FastAPI service, a cron job, a Slack bot) without standing up a separate process.
• Programmatic scale. Spawn many tasks at once. Example: backfill structured fields across 10k support tickets, or run an eval suite that compares two agent versions on a fixed prompt set.

​

How it fits together

1. The control plane (cloud or self-hosted) owns the agent’s identity: instructions, skills, model + credentials, knowledge bases, session storage.
2. Your process owns the execution loop: the agent loop that decides what to call and when.

┌─────────────────────────┐         ┌─────────────────────────────┐
│ xpander control plane   │         │ Your process                │
│ (cloud or self-hosted)  │         │                             │
│                         │         │ Backend.aget_args(...)      │
│ • Agent definition      │ ──────▶ │   returns agent-loop args   │
│ • Skills                │         │                             │
│ • Knowledge bases       │         │ AgnoAgent(**args)           │
│ • Model + credentials   │         │   runs the LLM loop         │
│ • Instructions          │         │                             │
│ • Postgres (sessions)   │ ◀────── │ @on_task receives a Task,   │
└─────────────────────────┘         │ writes task.result, returns │
                                    └─────────────────────────────┘

​

What you’ll work with

• Python SDK (xpander-sdk): runtime classes (Backend, Agents, Task) and decorators (@on_task, @register_tool). The class-by-class breakdown lives in Core Concepts.
• CLI (xpander): scaffolds projects, runs agents locally, manages auth. Every command is in the CLI Reference.
• An agent loop: Agno is the recommended path because the SDK does the most wiring for it. OpenAI Agents SDK, LangChain, and AWS Strands are also supported; the SDK integrations overview compares what’s auto-wired vs. manual for each.

xpander_handler.py     # Your @on_task handler. The entry point.
xpander_config.json    # Agent ID, framework selection.
agent_instructions.json
requirements.txt
.env                   # XPANDER_API_KEY, XPANDER_ORGANIZATION_ID, XPANDER_AGENT_ID.

​

What to read next