Skip to main content

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.

The xpander.ai SDK is a typed Python client for the xpander.ai platform. It exposes six core modules (Backend, Agents, Tasks, ToolsRepository, KnowledgeBases, Events), plus a set of decorators (@on_task, @on_boot, @on_shutdown, @on_auth_event, @on_tool_*, @register_tool) for wiring your code into the agent runtime. Every method comes in two flavors: an async coroutine (e.g. aget, acreate_task) and a synchronous wrapper (get, create_task). Use the async forms in production; sync wrappers are convenient for scripts and notebooks.

​
Install

# Requires Python 3.9+
pip install xpander-sdk
For Agno (the recommended framework), install the optional extras:
pip install xpander-sdk[agno]

​
Authenticate

The SDK reads credentials from environment variables by default: 
export XPANDER_API_KEY="your-api-key"
export XPANDER_ORGANIZATION_ID="your-org-id"
# Optional:
export XPANDER_BASE_URL="https://inbound.xpander.ai"   # cloud default
export XPANDER_AGENT_ID="agent-123"                    # avoids passing agent_id everywhere
Or instantiate Configuration explicitly and pass it into any module: 
from xpander_sdk import Configuration, Agents

config = Configuration(
    api_key="your-api-key",
    organization_id="your-org-id",
)

agents = Agents(configuration=config)
See the Configuration reference for the full attribute list and self-hosted setup.

​
Initialize and call

import asyncio
from xpander_sdk import Agents

async def main():
    agents = Agents()                          # picks up env vars

    agent = await agents.aget("agent-123")     # load agent config
    task = await agent.acreate_task(
        prompt="Summarize the latest sales report",
        file_urls=["https://example.com/sales.csv"],
    )
    print(task.id, task.status)

asyncio.run(main())
For framework integration (Agno, OpenAI Agents, LangChain, Google ADK, AWS Strands), use Backend.aget_args() to resolve framework-specific kwargs from a stored agent configuration: 
from xpander_sdk import Backend
from agno.agent import Agent as AgnoAgent

backend = Backend()
args = await backend.aget_args(agent_id="agent-123")

agno_agent = AgnoAgent(**args)
result = await agno_agent.arun(input="Hello!")

​
Async vs sync

Every coroutine has a sync sibling: same parameters, blocks until complete:
AsyncSync
agents.aget(...)agents.get(...)
agent.acreate_task(...)agent.create_task(...)
task.aevents()task.events()
tools.aload_tool_by_id(...)tools.load_tool_by_id(...)
Async methods are coroutines: wrap them in async def and call with await. Sync wrappers internally call run_sync(), so don’t call them from inside an existing event loop (FastAPI, asyncio scripts): use the a* form there.

​
Self-hosted

Point base_url at your Agent Controller endpoint and use the API key generated during your Helm install: 
config = Configuration(
    api_key="agent-controller-api-key",
    organization_id="your-org-id",
    base_url="https://agent-controller.your-company.com",
)
The SDK auto-detects when the URL points at a self-hosted controller (agent-controller in the host or port 9016) and prefixes paths with the organization ID. See the Configuration reference for details.

​
Where to next

Backend

Resolve framework args, invoke agents directly, report external runs.

Agents

List, load, and interact with agents.

Tasks

Create, stream, and inspect task executions.

Decorators

@on_task, @on_boot, @on_shutdown, and tool hooks.