> ## 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.

# Overview

> Install the xpander.ai SDK, authenticate, and make your first call.

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

```bash theme={"dark"}
# Requires Python 3.9+
pip install xpander-sdk
```

<Note>
  For Agno (the recommended framework), install the optional extras:

  ```bash theme={"dark"}
  pip install xpander-sdk[agno]
  ```
</Note>

## Authenticate

The SDK reads credentials from environment variables by default:

```bash theme={"dark"}
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:

```python theme={"dark"}
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](/developers/sdk-reference/configuration) for the full attribute list and self-hosted setup.

## Initialize and call

```python theme={"dark"}
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:

```python theme={"dark"}
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:

| Async                         | Sync                         |
| ----------------------------- | ---------------------------- |
| `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:

```python theme={"dark"}
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](/developers/sdk-reference/configuration#self-hosted) for details.

## Where to next

<CardGroup cols={2}>
  <Card title="Backend" icon="server" href="/developers/sdk-reference/backend/overview">
    Resolve framework args, invoke agents directly, report external runs.
  </Card>

  <Card title="Agents" icon="robot" href="/developers/sdk-reference/agents/overview">
    List, load, and interact with agents.
  </Card>

  <Card title="Tasks" icon="play" href="/developers/sdk-reference/tasks/overview">
    Create, stream, and inspect task executions.
  </Card>

  <Card title="Decorators" icon="bolt" href="/developers/sdk-reference/decorators/overview">
    `@on_task`, `@on_boot`, `@on_shutdown`, and tool hooks.
  </Card>
</CardGroup>