> ## 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.
# Introduction
> Build in-product agents with the Python SDK and the xpander CLI
The Python SDK is in **preview**. It's for building in-product agents - agents you write in Python and embed in your own product - and agents built on an agent loop you run yourself (Agno, LangChain, OpenAI Agents, AWS Strands). To invoke or integrate xpander agents from an application, use the [REST API](/api-reference/invoke-api), which is stable and works from any language.
xpander is the governed runtime for enterprise AI agents. It runs the agents your teams already use, Claude Code, Codex, Cursor and OpenCode, and governs every action they take. There are two ways to work with it:
* **Xpander Chat** ([chat.xpander.ai](https://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
Agents created in Xpander Chat or through the API run on Claude Code, Codex or OpenCode by default. The SDK path is optional: it lets you run an agent loop of your own (Agno, LangChain and LangGraph, OpenAI Agents SDK, AWS Strands), create skills from private APIs, or embed xpander in your Python code. Anything you build in Xpander Chat is also available in code. In the SDK, skills are exposed as `tools`, the name the agent loops use for them.
## Install
You need all three steps. The CLI and SDK are separate packages with different runtimes: the CLI ships via npm, the SDK via pip.
```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
```
Python 3.12+ for the local dev server; the SDK needs Python 3.10 or newer (the wheel installs on 3.9 but fails to import).
10-minute scaffold-to-running-agent walkthrough. Start here once you're installed.
## When to use code
Xpander Chat covers most cases. Reach for the SDK when one of these applies:
* **Run a specific agent loop.** You're already invested in [Agno](/developers/frameworks/agno), [OpenAI Agents SDK](/developers/frameworks/openai-agents), [LangChain](/developers/frameworks/langchain), or [AWS Strands](/developers/frameworks/aws-strands).
* **Wrap a private API as a skill.** Decorate a Python function with [`@register_tool`](/developers/tools/custom-tools); 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
The SDK path splits into two halves:
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.
They talk through `Backend`, which fetches the agent and returns a dict ready to splat into your agent loop's `Agent` constructor.
```
┌─────────────────────────┐ ┌─────────────────────────────┐
│ 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 │
└─────────────────────────────┘
```
This split is why the SDK stays small and your code stays your code. There's no xpander-flavored wrapper around your agent loop. You instantiate the loop's own `Agent` class with arguments xpander provides.
## What you'll work with
A typical project pulls in three pieces:
* **Python SDK** (`xpander-sdk`): runtime classes (`Backend`, `Agents`, `Task`) and decorators (`@on_task`, `@register_tool`). The class-by-class breakdown lives in [Core Concepts](/developers/core-concepts).
* **CLI** (`xpander`): scaffolds projects, runs agents locally, manages auth. Every command is in the [CLI Reference](/developers/cli-reference/overview).
* **An agent loop**: [Agno](/developers/frameworks/agno) is the recommended path because the SDK does the most wiring for it. [OpenAI Agents SDK](/developers/frameworks/openai-agents), [LangChain](/developers/frameworks/langchain), and [AWS Strands](/developers/frameworks/aws-strands) are also supported; the [SDK integrations overview](/developers/frameworks) compares what's auto-wired vs. manual for each.
When you run `xpander agent new`, the CLI generates a starter project in your current directory. Here's what it creates:
```
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.
```
For most projects, `xpander_handler.py` is the only file you'll edit.
## What to read next
Scaffold a project, run the handler locally, send it a task.
The SDK class names mapped onto agents, tasks, threads, skills, and memory.
Pick an agent loop and see what xpander wires up for you.
Per-module class and method documentation.