> ## 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.
# Quickstart
> Create an agent and run it locally. Entirely from the terminal. About 10 minutes.
This page builds an agent end-to-end from the command line. No app, no clicking. By the end, you'll have:
1. Created the agent in xpander's control plane.
2. Run its handler locally against real prompts.
If you'd rather start in Xpander Chat, the [User guide](/use) walks through the same flow inside Xpander Chat. Agents created there run on Claude Code, Codex or OpenCode by default; the SDK path on this page runs an Agno agent loop in your own process instead.
## 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
All three commands are required:
1. The CLI ships via npm.
2. The SDK ships via pip.
3. `login` writes credentials that both the CLI and the SDK read.
```bash theme={"dark"}
# 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
`xpander agent new` does two things at once:
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.
```bash theme={"dark"}
# 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 "."
```
Drop the flags to use the interactive wizard, which asks for the same three values one at a time.
When the command finishes, the current directory contains:
```
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.
```
Set up a virtual environment and install the dependencies:
```bash theme={"dark"}
# 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
The scaffolded `xpander_handler.py` is the canonical pattern for an xpander agent. Every example in the rest of these docs is a variation on this:
```python xpander_handler.py theme={"dark"}
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
```
Here's what's happening:
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
The simplest "just boot it" command, copy-paste with zero typing:
```bash theme={"dark"}
# Boots the @on_task HTTP server and subscribes to xpander event stream
python3 xpander_handler.py
```
Tasks created for this agent (from any channel) will route to your handler. Hit Ctrl+C to stop.
For a one-shot test with a specific prompt, no server:
```bash theme={"dark"}
# Calls your handler exactly once with the prompt, prints the result, and exits
python3 xpander_handler.py --invoke --prompt "What can you do?"
```
For an interactive dev session with extra CLI affordances (auto-reload prompts, log formatting):
```bash theme={"dark"}
# Same SSE subscription as `python3 xpander_handler.py`, plus dev tooling
xpander agent dev
```
What you get:
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.
**Routing cloud traffic to a local instance is a preview feature.**
When a local instance is running via `xpander agent dev`, it takes over and all tasks route to your locally running agent instead. Only one can be active at a time.
## 5. Customize the agent (Optional)
The agent created by the CLI starts blank: a default system prompt, no skills. Open `agent_instructions.json` to rewrite the role, goal, and general description; the next `xpander agent dev` syncs it to the control plane.
```json agent_instructions.json theme={"dark"}
{
"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."
}
```
`role` and `goal` are arrays so you can add or remove individual statements without rewriting the prompt. `general` is a free-form description that wraps around them.
Beyond that, each customization has its own page:
1. **Custom skills** wrapped with `@register_tool`. See [Custom skills](/developers/tools/custom-tools).
2. **Prebuilt skills** from the skills catalog (Slack, Gmail, GitHub, and more). See [Pre-built skills](/developers/tools/pre-built).
3. **Knowledge bases** for RAG. See [Document Management](/developers/knowledge/document-management).
4. **Memory** (session storage, user memories, agent memories). See [Memory & State](/developers/memory/session-storage).
5. **Skill hooks** for logging, metrics, and guardrails around skill calls. See [Skill hooks](/developers/tools/tool-hooks).
6. **A different agent loop** (OpenAI Agents SDK, LangChain, AWS Strands). See [SDK integrations](/developers/frameworks).
## Troubleshooting
The handler imports before `.env` is loaded. The scaffolded handler already includes `from dotenv import load_dotenv; load_dotenv()` at the top. If you wrote your own entry point, add it before any `xpander_sdk` import.
zsh expands the brackets. Quote the package name: `pip install "xpander-sdk[agno]"`.
Another `@on_task` process is running. Either kill it, or set a different port for this one: `XPANDER_STREAMING_PORT=59322 python xpander_handler.py`.
The `/invoke` endpoint requires the `x-api-key` header on every request. The CLI sets it for you; if you're using curl or Postman, set it explicitly to your `XPANDER_API_KEY`.
When a local dev instance is running, it takes over inbound traffic. If another instance holds the slot, run `xpander agent stop` first, then start `xpander agent dev` again.
`xpander agent invoke` posts to the agent's webhook and waits for a sync response. If your handler is taking more than \~30 seconds, the webhook times out even though the task keeps running on xpander. Check the task in Xpander Chat, or invoke through the async REST endpoint (`/v1/agents/{agent_id}/invoke/async`) for long-running tasks.
## Next steps
Things you can do now that you couldn't from Xpander Chat alone:
Wrap a private API as a skill with `@register_tool` instead of a REST skill from the catalog.
Run skills served over MCP that need filesystem or process access.
Warmup, graceful shutdown, and observability around skill calls.
The SDK class names and how they map to agents, tasks, threads, and memory.
What `Backend.aget_args()` actually wires up.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.